Menulis file kustomisasi untuk kotak dev

Artikel
04/12/2024

Dalam artikel ini, Anda mempelajari cara membuat dan menguji file kustomisasi untuk kotak dev Anda dengan menggunakan Visual Studio Code (VS Code) dan Dev Home.

Ada dua cara untuk menggunakan file kustomisasi di Microsoft Dev Box. Kustomisasi tim diterapkan secara otomatis saat pengembang mengonfigurasinya di kumpulan. Kustomisasi individual diterapkan saat pengguna membuat kotak dev.

Artikel ini membantu Anda menentukan tugas baru dalam file kustomisasi Anda, menerapkannya ke kotak dev Anda, dan menguji kustomisasi ini langsung di Visual Studio Code.

Penting

Fitur penyesuaian tim Dev Box saat ini dalam pratinjau. Untuk informasi selengkapnya tentang status pratinjau, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure. Dokumen mendefinisikan istilah hukum yang berlaku untuk fitur Azure yang dalam versi beta, dalam pratinjau, atau belum dirilis ke ketersediaan umum.

Prasyarat

Untuk menyelesaikan langkah-langkah dalam artikel ini, Anda harus:

Memiliki pusat pengembangan yang dikonfigurasi dengan definisi dev box, kumpulan dev box, dan proyek dev box sehingga Anda dapat membuat dev box.
Jadilah anggota grup keamanan Pengguna Dev Box untuk setidaknya satu proyek.
Memiliki katalog yang dilampirkan ke pusat pengembangan dengan tugas yang dapat Anda gunakan dalam file kustomisasi Anda. Jika Anda tidak memiliki katalog, lihat Menambahkan dan mengonfigurasi katalog dari GitHub atau Azure Repos.

Izin yang diperlukan untuk mengonfigurasi kustomisasi

Untuk melakukan tindakan yang diperlukan untuk membuat dan menerapkan kustomisasi ke kotak dev, Anda memerlukan izin berikut:

Perbuatan	Izin/Peran
Aktifkan katalog tingkat proyek untuk pusat pengembangan.	Insinyur platform dengan akses tulis pada langganan.
Aktifkan pengaturan sinkronisasi katalog untuk proyek.	Insinyur platform dengan akses tulis pada langganan.
Lampirkan katalog ke proyek.	Izin Admin Proyek atau Kontributor pada proyek.
Buat file kustomisasi.	Tidak ada yang ditentukan. Siapa pun dapat membuat file kustomisasi.
Gunakan portal pengembang untuk mengunggah dan menerapkan file YAML selama pembuatan kotak pengembangan.	Pengguna Dev Box.
Menambahkan tugas ke katalog.	Izin untuk menambahkan ke repositori yang menghosting katalog.

Apa itu file kustomisasi?

Kustomisasi Dev Box menggunakan file berformat YAML untuk menentukan daftar tugas yang akan diterapkan saat pengembang membuat kotak dev. Tugas-tugas ini bisa sesingkat menginstal paket, atau secanggih menjalankan serangkaian skrip yang kompleks untuk menyiapkan basis kode. Tugas mengidentifikasi katalog dan memberikan parameter seperti nama perangkat lunak yang akan diinstal. File kustomisasi kemudian tersedia untuk pengembang yang membuat dev box.

Contoh berikut menggunakan winget tugas untuk menginstal Visual Studio Code, dan git-clone tugas untuk mengkloning repositori:

# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
  - name: winget
    parameters:
      package: Microsoft.VisualStudioCode
      runAsUser: true
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
      directory: C:\Workspaces

Ada dua cara untuk menggunakan file kustomisasi: kustomisasi individual berlaku untuk satu kotak dev, dan kustomisasi tim berlaku untuk seluruh tim.

File kustomisasi individual

Berisi tugas yang diterapkan saat pengembang membuat kotak pengembangan.
Diunggah oleh pengembang selama pembuatan kotak pengembangan.

File kustomisasi tim

Berisi tugas yang diterapkan saat pengembang membuat kotak pengembangan.
Dibagikan di seluruh tim atau proyek.
Sertakan bidang yang menentukan gambar dasar.
Diberi nama imagedefinition.yaml.
Diunggah ke repositori yang menghosting katalog.
Digunakan secara otomatis saat pengembang membuat kotak dev dari kumpulan yang dikonfigurasi.

Penting

Definisi gambar hanya dapat menggunakan gambar marketplace Dev Box sebagai gambar dasar. Untuk mendapatkan daftar gambar yang dapat diakses pusat pengembangan Anda, gunakan perintah Azure CLI ini:

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

Membuat file kustomisasi

Anda dapat membuat dan mengelola file kustomisasi dengan menggunakan Visual Studio Code. Anda dapat menggunakan ekstensi Microsoft Dev Box di VISUAL Code untuk menemukan tugas di katalog terlampir dan menguji file kustomisasi.

Buat kotak dev (atau gunakan kotak dev yang sudah ada) untuk pengujian.
Pada kotak dev pengujian, instal Visual Studio Code lalu instal ekstensi Dev Box.
Unduh contoh file kustomisasi YAML dari repositori sampel dan buka di Visual Studio Code.
Temukan tugas yang tersedia di katalog dengan menggunakan palet perintah. Pilih Tampilkan>Kotak Dev Palet>Perintah: Cantumkan Tugas yang Tersedia Untuk Kotak Dev Ini.
Uji kustomisasi di Visual Studio Code dengan menggunakan palet perintah. Pilih Tampilkan>Kotak Dev Palet>Perintah: Terapkan Tugas Kustomisasi.
File kustomisasi segera berjalan dan menerapkan tugas yang ditentukan ke kotak pengembangan pengujian Anda. Periksa perubahan, dan periksa terminal Visual Studio Code untuk setiap kesalahan atau peringatan yang dihasilkan selama eksekusi tugas.
Saat file kustomisasi berhasil dijalankan, unggah ke katalog Anda.

Mengkloning repositori privat dengan menggunakan file kustomisasi

Anda dapat menggunakan rahasia dari brankas kunci Azure di kustomisasi YAML Anda untuk mengkloning repositori privat, atau dengan tugas kustom apa pun yang Anda buat yang memerlukan token akses. Dalam file kustomisasi tim, Anda dapat menggunakan token akses pribadi (PAT) yang disimpan dalam brankas kunci untuk mengakses repositori privat.

Menggunakan rahasia brankas kunci dalam file kustomisasi tim

Untuk mengkloning repositori privat, simpan PAT Anda sebagai rahasia brankas kunci, dan gunakan saat Anda memanggil git-clone tugas dalam penyesuaian Anda.

Untuk mengonfigurasi rahasia brankas kunci untuk digunakan dalam kustomisasi YAML Anda:

Pastikan identitas terkelola proyek pusat pengembangan Anda memiliki peran Pembaca Key Vault dan peran Pengguna Rahasia Key Vault di brankas kunci Anda.
Berikan peran Pengguna Rahasia Key Vault untuk rahasia brankas kunci kepada setiap pengguna atau grup pengguna yang harus dapat menggunakan rahasia selama penyesuaian kotak dev. Pengguna atau grup yang diberikan peran harus menyertakan identitas terkelola untuk pusat dev, akun pengguna Anda sendiri, dan pengguna atau grup apa pun yang membutuhkan rahasia selama penyesuaian kotak dev.

Untuk informasi selengkapnya, lihat:

Anda dapat mereferensikan rahasia dalam kustomisasi YAML Anda dalam format berikut, yang menggunakan git-clone tugas sebagai contoh:

$schema: "1.0"
tasks:
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
      directory: C:\Workspaces
      pat: '{{KEY_VAULT_SECRET_URI}}'

Menggunakan rahasia brankas kunci dalam file kustomisasi individual

Jika Anda ingin mengkloning repositori Azure Repos privat dari file kustomisasi individual, Anda tidak perlu mengonfigurasi rahasia di Azure Key Vault. Sebagai gantinya, Anda dapat menggunakan {{ado}} atau {{ado://your-ado-organization-name}} sebagai parameter. Parameter ini mengambil token akses atas nama Anda saat Anda membuat kotak dev. Token akses memiliki izin baca-saja ke repositori Anda.

Tugas git-clone dalam katalog mulai cepat menggunakan token akses untuk mengkloning repositori Anda. Berikut contohnya:

tasks:
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
      directory: C:\Workspaces
      pat: '{{ado://YOUR_ADO_ORG}}'

Pusat pengembangan Anda memerlukan akses ke brankas kunci Anda. Pusat dev tidak mendukung tag layanan, jadi jika brankas kunci Anda dirahasiakan, Anda harus mengizinkan layanan Microsoft tepercaya untuk melewati firewall.

Untuk mempelajari cara mengizinkan layanan Microsoft tepercaya melewati firewall, lihat Mengonfigurasi pengaturan jaringan Azure Key Vault.

Kustomisasi kotak dev Anda dengan menggunakan file Konfigurasi WinGet yang ada

Konfigurasi WinGet mengambil pendekatan config-as-code untuk menentukan set unik perangkat lunak dan pengaturan konfigurasi yang diperlukan untuk membuat lingkungan Windows Anda dalam status siap kode. Anda juga dapat menggunakan file konfigurasi ini untuk menyiapkan kotak dev, dengan menggunakan tugas WinGet yang disertakan dalam katalog mulai cepat yang disediakan Microsoft.

Contoh berikut menunjukkan file kustomisasi kotak dev yang memanggil file WinGet Desired State Configuration (DSC) yang ada:

tasks:
    - name: winget
      parameters:
          configure: "projectConfiguration.dsc.yaml"

Untuk mempelajari lebih lanjut, lihat Konfigurasi WinGet.

Jadikan file kustomisasi Anda tersedia untuk kumpulan kotak dev dengan menamainya imagedefinition.yaml dan dengan mengunggahnya ke repositori yang menghosting katalog Anda. Saat membuat kumpulan kotak dev, Anda dapat memilih file kustomisasi dari katalog untuk diterapkan ke kotak dev di kumpulan.

Bagikan melalui