Menjelajahi dan mengedit file templat CLI Pengembang Azure

Templat Azure Developer CLI (azd) adalah repositori standar dengan aset konfigurasi dan infrastruktur yang memungkinkan azd untuk menyediakan dan menyebarkan proyek. Baik Anda membangun templat baru atau mulai dari yang sudah ada, Anda tetap bertanggung jawab untuk meninjau dan memelihara filenya seiring berkembangnya proyek.

Artikel ini menjelaskan cara memeriksa dan mengedit file templat utama. Untuk deskripsi konseptual tentang struktur lengkap, lihat templat CLI Pengembang Azure.

Artikel ini menggunakan templat hello-azd sebagai contoh standar sehingga Anda dapat melihat apa yang dilakukan setiap file dalam proyek nyata. Konsep yang sama berlaku untuk templat yang Anda hasilkan untuk aplikasi Anda sendiri. Untuk mengikuti, inisialisasi templat dalam direktori kosong:

azd init --template hello-azd

Templat hello-azd men-deploy aplikasi C# terkontainerisasi ke Azure Container Apps dan memprovisikan sumber daya Azure pendukung melalui Bicep. Struktur folder yang digunakan adalah seperti berikut, di mana setiap aset utama sesuai dengan bagian dalam artikel ini:

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   ├── app/                  # Application-specific modules
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

Struktur yang tepat bervariasi menurut proyek, dan azure.yaml mengidentifikasi jalur yang azd menggunakan. Bagian berikut ini menjelaskan cara mengedit setiap aset.

Sebelum membuat perubahan yang substansial, terapkan atau simpan versi templat yang diketahui baik. Tinjau semua perubahan untuk kredensial yang disematkan, sumber daya yang tidak perlu, izin berlebihan, paparan jaringan, tingkat layanan, dan nilai khusus lingkungan.

Menjelajahi azure.yaml

File azure.yaml menentukan proyek dan memberi tahu cara memprovisikan azd infrastruktur, mengemas kode aplikasi, dan menyebarkan setiap layanan. Ini dapat menentukan layanan, pengaturan infrastruktur, kait, alur kerja, dan perilaku proyek lainnya.

hello-azd Templat mendefinisikan satu layanan bernama aca:

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Setiap properti memberi tahu azd cara menangani layanan:

• aca adalah nama layanan. azdmenggunakannya untuk mencocokkan layanan dengan sumber daya Azure yang menghostingnya. Untuk informasi selengkapnya, lihat Mengonfigurasi penemuan layanan.
• project: ./src menunjuk ke kode sumber aplikasi yang azd mengemas dan menyebarkan.
• language: csharp mengidentifikasi bahasa aplikasi.
• host: containerapp memberi tahu azd untuk menyebarkan layanan ke Azure Container Apps.
• docker membangun gambar kontainer dari Dockerfile dalam src direktori.
• remoteBuild memberi tahu azd untuk menggunakan Azure Container Registry (ACR) guna membangun image kontainer.

Menambahkan definisi layanan

Tambahkan entri di bawah services untuk setiap aplikasi tambahan yang azd harus disebarkan. Definisi layanan menentukan direktori sumber, bahasa, dan target hosting Azure. Misalnya, untuk menjelaskan proyek API baru:

services:
  api:
    project: ./src/api
    language: csharp
    host: appservice

Saat Anda memindahkan kode aplikasi, perbarui jalur yang project sesuai. Saat Anda mengubah arsitektur hosting, perbarui definisi layanan dan infrastruktur yang menyediakan host.

Untuk semua properti yang tersedia dan nilai yang azure.yaml didukung, lihat skema.

Kode sumber

Sumber aplikasi bersifat opsional. Templat dengan aplikasi yang dapat disebarkan sering mengatur kode sumber di src bawah direktori, tetapi Anda tidak perlu menggunakan nama folder atau tata letak tertentu. Properti project untuk setiap layanan di azure.yaml memberi tahu azd di mana kode sumbernya berada.

Di hello-azd, aca layanan menetapkan project: ./src, sehingga azd mengemas aplikasi C# di src direktori dan menyebarkannya ke Azure Container Apps. Karena layanan juga menetapkan konfigurasi docker, azd membangun citra kontainer dari Dockerfile di direktori src sebelum penerapan.

azdmendukung host Node.js, Python, .NET, Java, dan Go on yang didukung Azure. Templat juga dapat menyebarkan kontainer. Untuk kombinasi bahasa, kerangka kerja, dan host saat ini, lihat Bahasa dan lingkungan yang didukung.

Edit kode sumber seperti yang Anda lakukan di repositori aplikasi apa pun. Jika Anda menambahkan layanan atau memindahkan direktori sumbernya, perbarui definisi layanannya azure.yaml . Jika aplikasi memerlukan sumber daya Azure baru, perbarui infrastruktur dan teruskan titik akhir atau nama sumber daya yang diperlukan ke aplikasi melalui konfigurasi.

Mengubah direktori sumber layanan

Misalnya, jika Anda memindahkan aplikasi hello-azd dari src ke src/app, perbarui nilai project dari layanan aca:

services:
  aca:
    project: ./src/app
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

File infrastruktur

infra Direktori berisi file Bicep atau Terraform yang menentukan sumber daya Azure untuk templat. Dalam hello-azd, infra direktori menggunakan Bicep dan menyertakan aset kunci berikut:

• main.bicep adalah titik masuk penyebaran standar yang azd berjalan untuk menyediakan sumber daya.
• main.parameters.json memasok nilai parameter untuk main.bicep.
• app berisi modul khusus untuk aplikasi.
• core berisi modul yang dapat digunakan kembali untuk sumber daya umum, seperti penyimpanan dan hosting.

Cara main.bicep berjalan selama azd up

Saat Anda menjalankan azd up, fase penyediaan menerapkan infra/main.bicep. Di hello-azd, main.bicep menargetkan cakupan langganan, membuat grup sumber daya, lalu memanggil modul untuk menyediakan sumber daya yang dibutuhkan aplikasi:

targetScope = 'subscription'

// Create a storage account
module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: rg
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    allowSharedKeyAccess: false
    containers: [ { name: 'attachments' } ]
    tables: [ { name: 'tickets' } ]
  }
}

// Container app for the 'aca' service
module web 'app/app.bicep' = {
  name: serviceName
  scope: rg
  params: {
    // ...
    serviceName: serviceName
  }
}

File main.bicep ini memprovisikan identitas terkelola yang ditetapkan pengguna, akun Azure Storage, lingkungan dan registri Azure Container Apps, serta aplikasi kontainer yang meng-host layanan aca. Ini juga menetapkan peran yang memungkinkan identitas terkelola mengakses penyimpanan. Modul menyimpan setiap sumber daya dalam filenya sendiri sehingga main.bicep tetap dapat dibaca.

Menambahkan sumber daya ke main.bicep

Tambahkan deklarasi sumber daya langsung ke infra/main.bicep untuk sumber daya sederhana atau satu kali. Pisahkan sumber daya ke dalam modul Bicep terpisah jika akan digunakan kembali, jika suatu sumber daya memerlukan beberapa sumber daya terkait, atau agar main.bicep tetap mudah dibaca. Seperti hello-azd, banyak templat mengelompokkan modul yang dapat digunakan kembali di bawah infra/core.

Untuk sumber daya Azure umum, lebih suka Modul Terverifikasi Azure daripada menulis modul dari awal. Modul terverifikasi dikelola oleh Microsoft, mengikuti praktik terbaik untuk keamanan dan keandalan, serta mengurangi jumlah kode infrastruktur yang perlu Anda pertahankan di dalam templat.

Untuk panduan lengkap yang menambahkan sumber daya baru ke hello-azd, lihat Memperluas templat.

Berkas main.parameters.json memetakan nilai yang dikelola oleh azd ke parameter Bicep. hello-azd Templat menggunakan parameter berikut:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

Setiap entri mengaitkan parameter Bicep dengan nilai yang dikelola oleh azd di lingkungan, seperti nama lingkungan, lokasi, dan prinsipal yang menjalankan deployment. Gunakan main.parameters.json untuk nilai yang bervariasi menurut lingkungan atau penyebaran, seperti nama lingkungan, lokasi, atau nama sumber daya yang azd dihasilkan. Pertahankan nilai stabil yang tidak berubah di antara lingkungan sebagai default parameter atau literal di main.bicep. Pendekatan ini membuat Bicep yang sama tetap dapat digunakan kembali di berbagai lingkungan tanpa perlu mengeditnya untuk setiap penerapan.

Saat Anda menambahkan atau mengedit infrastruktur:

• Menjaga lingkungan konfigurasi sumber daya tetap independen. Gunakan parameter dan azd nilai lingkungan alih-alih menyematkan ID langganan, nama sumber daya, lokasi, atau kredensial.
• Gunakan output aman untuk nilai sensitif, dan jangan mengekspos rahasia sebagai output penyebaran teks biasa.
• Terapkan penugasan peran dengan hak istimewa seminimal mungkin pada identitas terkelola.
• Jaga agar definisi layanan selaras dengan sumber daya yang ditargetkan azure.yaml .
• Tinjau efek tingkat layanan, batas penskalaan, redundansi, dan pengaturan retensi pada biaya.

Untuk panduan bahasa dan modul Bicep, lihat dokumentasi Bicep. Untuk templat berbasis Terraform, lihat Menggunakan Terraform dengan Azure Developer CLI.

Mengonfigurasi penemuan layanan

Secara default, azd menemukan sumber daya Azure untuk layanan dengan menemukan sumber daya yang tagnya azd-service-name cocok dengan nama layanan di azure.yaml. Jika Anda mengganti nama layanan, perbarui tag sumber daya yang sesuai atau konfigurasikan nama sumber daya secara eksplisit di azure.yaml.

Misalnya, dalam hello-azdaca nama layanan cocok dengan azd-service-name tag pada sumber daya aplikasi kontainer. Definisi azure.yaml layanan menetapkan nama:

services:
  aca:
    project: ./src
    language: csharp
    host: containerapp

Modul aplikasi kontainer dalam infra/app/app.bicep menerapkan tag yang cocok:

tags: union(tags, { 'azd-service-name': serviceName })

Mengonfigurasi jalur infrastruktur nonstandar

Bagian infraazure.yaml mengidentifikasi penyedia infrastruktur dan titik masuk. Nilai-nilai ini bersifat opsional saat Anda menggunakan tata letak Bicep default, tetapi mendeklarasikannya dapat membuat tata letak yang tidak standar lebih mudah dipahami:

infra:
  provider: bicep
  path: infra
  module: main

Konfigurasi lingkungan

Direktori .azure berisi status dan nilai lingkungan lokal yang dibuat oleh azd, seperti langganan yang dipilih, lokasi, nama sumber daya, dan hasil deployment. Perlakukan direktori ini sebagai status lokal daripada aset templat yang dapat digunakan kembali. Jangan meng-commit file environment yang berisi rahasia atau nilai khusus untuk environment tertentu.

Tambahkan output infrastruktur

Saat Anda menjalankan azd provision untuk menyebarkan Bicep, ia mengambil output dari titik masuk infrastruktur sebagai azd nilai lingkungan. Tambahkan output untuk titik akhir sumber daya, nama sumber daya, dan ID klien identitas terkelola yang dibutuhkan layanan aplikasi atau kait. Misalnya, hello-azd menghasilkan registri kontainer dan detail identitas terkelola dari main.bicep:

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

Jangan keluarkan rahasia saat identitas terkelola atau referensi Key Vault dapat menyediakan akses sebagai gantinya. Setelah penyediaan, periksa nilai yang ditangkap dengan menjalankan azd env get-values.

Untuk informasi selengkapnya, lihat Mengelola variabel lingkungan.

Menguji perubahan Anda

Jalankan azd up untuk menyediakan infrastruktur dan menyebarkan layanan aplikasi apa pun:

azd up

Jika Anda ingin berbagi templat, inisialisasikan di direktori yang bersih dan sebarkan dengan lingkungan baru. Pengujian ini membantu mengidentifikasi file lokal, nilai cache, atau asumsi khusus lingkungan yang bukan bagian dari templat.

Konten terkait

• Gambaran umum pengembangan templat
• Mulai dengan templat baru
• Mulai dari templat yang sudah ada
• Perluas templat
• azd up Menjelajahi alur kerja

Minta bantuan

Untuk informasi tentang cara mengajukan bug, meminta bantuan, atau mengusulkan fitur baru untuk Azure Developer CLI, silakan kunjungi halaman troubleshooting dan dukungan.