Referensi skema CLI Pengembang Azure

File azure.yaml adalah file konfigurasi untuk proyek Azure Developer CLI (azd). Letakkan di akar proyek Anda untuk menentukan layanan, sumber daya Azure, infrastruktur, kait, dan alur CI/CD yang membentuk aplikasi Anda. Saat Anda menjalankan perintah seperti azd up, , azd provisionatau azd deploy, CLI membaca file ini untuk memahami struktur aplikasi Anda dan cara menyebarkannya ke Azure.

Artikel ini adalah referensi lengkap untuk skema azure.yaml. Untuk memulai azd templat, lihat Gambaran umum templat Azure Developer CLI.

Contoh

Berikut ini adalah contoh azure.yaml umum file untuk azd templat. Untuk contoh dunia nyata, lihat azure.yaml dari templat ToDo NodeJs Mongo:

name: yourApp
metadata:
  template: yourApp@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Properti tingkat atas

name

(string, diperlukan) Nama aplikasi. Hanya huruf kecil, angka, dan tanda hubung (-) yang diizinkan. Nama harus dimulai dan diakhir dengan huruf atau angka. Panjang minimum: 2 karakter.

name: my-app

resourceGroup

(string) Nama grup sumber daya Azure. Jika ditentukan, ambil alih nama grup sumber daya yang digunakan untuk provisi infrastruktur. Mendukung substitusi variabel lingkungan. Harus antara 3 dan 64 karakter.

resourceGroup: rg-my-app-${AZURE_ENV_NAME}

metadata

(objek) Metadata tentang templat aplikasi.

metadata:
  template: todo-nodejs-mongo@0.0.1-beta

infra

(objek) Menyediakan konfigurasi tambahan untuk provisi infrastruktur Azure.

infra.layers

(array objek) Menentukan lapisan provisi untuk infrastruktur Azure. Setiap lapisan mewakili unit provisi independen.

infra:
  provider: bicep
  layers:
    - name: core
      path: ./infra/core
    - name: services
      path: ./infra/services
      dependsOn:
        - core
      hooks:
        postprovision:
          shell: sh
          run: ./scripts/post-provision.sh

Terraform sebagai sampel penyedia IaC

Untuk menggunakan Terraform alih-alih Bicep, atur ke providerterraform. Untuk informasi selengkapnya, lihat Menggunakan Terraform sebagai penyedia IaC.

name: yourApp-terraform
metadata:
  template: yourApp-terraform@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice
infra:
  provider: terraform

services

(objek) Definisi layanan yang terdiri dari aplikasi. Setiap kunci adalah nama layanan, dan nilainya adalah objek konfigurasi layanan.

Properti layanan

Jenis host

Properti host menentukan jenis sumber daya Azure yang digunakan untuk implementasi dan kontrol layanan mana properti lain yang valid.

ai.endpoint Config

(objek, diperlukan saat host adalah ai.endpoint) Menyediakan konfigurasi tambahan untuk penyebaran titik akhir online Azure AI.

Konfigurasi komponen AI

Konfigurasi penyebaran AI

Mewarisi semua properti dari konfigurasi komponen AI, ditambah:

services:
  myendpoint:
    project: ./src/endpoint
    host: ai.endpoint
    config:
      workspace: my-ai-project
      deployment:
        path: ./deployment
        environment:
          MODEL_NAME: ${AZURE_OPENAI_MODEL}

docker

(objek) Konfigurasi Docker untuk layanan. Hanya berlaku untuk host yang mendukung kontainer (appservice, , containerapp, aksai.endpoint, azure.ai.agent).

k8s

(objek) Opsi konfigurasi Azure Kubernetes Service (AKS). Hanya valid ketika host adalah aks.

Konfigurasi penyebaran

Konfigurasi layanan

Konfigurasi Ingress

Konfigurasi Helm

repositories item array:

releases item array:

Kustomisasi konfigurasi

host Microsoft Foundry

Host azure.ai.agent dan host sumber daya Foundry deklaratif (microsoft.foundry, , azure.ai.project, azure.ai.connectionazure.ai.toolbox, azure.ai.skill, dan azure.ai.routine) bekerja dengan sumber daya Microsoft Foundry. Host azure.ai.agent menyebarkan kode aplikasi yang Anda buat project dari folder, sementara host deklaratif tidak melibatkan kode apa pun yang Anda buat. Setiap host deklaratif menjelaskan sumber daya Foundry pendukung yang azd menyediakan dan mengonfigurasi. Tidak seperti ai.endpoint, yang menumpuk pengaturan di bawah config, host ini mendefinisikan properti khusus host mereka sebagai saudara kandung datar dari host. Setiap properti host berasal dari azd skema ekstensi daripada skema inti azure.yaml , sehingga ekstensi harus diinstal agar properti dapat divalidasi. Untuk host deklaratif, kunci layanan adalah nama sumber daya (misalnya, koneksi, kotak alat, keterampilan, atau nama rutin).

azure.ai.agent Config

(properti di tingkat layanan, kapan host ) azure.ai.agent Konfigurasikan agen Microsoft Foundry yang dihosting. Layanan ini juga memerlukan project. Kumpulan properti lengkap ditentukan oleh azure.ai.agent skema ekstensi.

Penyebaran model agen

Setiap item di deployments upsert penyebaran model.

Konfigurasi kode agen

Ketika codeConfiguration ada, agen disebarkan dari sumber (ZIP) alih-alih gambar kontainer.

Sumber daya kontainer agen

Objek container menetapkan sumber daya komputasi melalui objek berlapis resources .

services:
  myagent:
    project: ./src/agent
    host: azure.ai.agent
    language: python
    name: support-agent
    displayName: Support Agent
    kind: hosted
    env:
      LOG_LEVEL: info
    deployments:
      - name: gpt-4o
        model:
          name: gpt-4o
          format: OpenAI
          version: "2024-08-06"
        sku:
          name: GlobalStandard
          capacity: 50
    codeConfiguration:
      runtime: python_3_12
      entryPoint: main.py
      dependencyResolution: remote_build
    container:
      resources:
        cpu: "1"
        memory: 2Gi

Host Microsoft Foundry lainnya

Host deklaratif berikut mengambil propertinya dari azd skema ekstensi. Anda tidak membuat atau menyebarkan kode untuk mereka. Masing-masing mendeklarasikan sumber daya Foundry pendukung yang azd menyediakan. Kunci layanan adalah nama sumber daya. Untuk kumpulan properti lengkap, lihat skema setiap host.

services:
  # Foundry project that owns model deployments
  project:
    host: azure.ai.project
    deployments:
      - name: gpt-4o
        model:
          name: gpt-4o
          format: OpenAI
          version: "2024-08-06"
        sku:
          name: GlobalStandard
          capacity: 50
  # Connection referenced by tools (service key is the connection name)
  my-search:
    host: azure.ai.connection
    uses:
      - project
    category: CognitiveSearch
    target: https://my-search.search.windows.net
    authType: ApiKey

Pengait layanan

Kait tingkat layanan dijalankan selama peristiwa siklus hidup layanan. Hook harus cocok dengan nama peristiwa layanan yang diawali dengan pre atau post. Saat menentukan jalur, jalur tersebut harus relatif terhadap jalur layanan. Lihat Mengkustomisasi alur kerja Azure Developer CLI Anda menggunakan perintah dan kait peristiwa untuk detail selengkapnya.

Kait layanan yang didukung: prerestore, , postrestore, prebuildpostbuild, prepackage, postpackage, prepublish, postpublish, predeploy. postdeploy

Setiap hook menggunakan format definisi Hook .

Sampel layanan

Aplikasi Kontainer dengan opsi Docker

services:
  api:
    project: ./src/api
    language: js
    host: containerapp
    docker:
      path: ./Dockerfile
      context: ../
  web:
    project: ./src/web
    language: js
    host: containerapp
    docker:
      remoteBuild: true

Aplikasi Kontainer dari gambar bawaan

services:
  api:
    image: myregistry.azurecr.io/myapp:latest
    host: containerapp

AKS dengan kait tingkat layanan

services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: aks
    hooks:
      postdeploy:
        shell: sh
        run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}
  api:
    project: ./src/api
    language: js
    host: aks
    k8s:
      ingress:
        relativePath: api
    hooks:
      postdeploy:
        shell: sh
        run: azd env set REACT_APP_API_BASE_URL ${SERVICE_API_ENDPOINT_URL}

resources

(objek) Definisi sumber daya Azure yang digunakan oleh aplikasi. Setiap kunci adalah nama sumber daya, dan nilainya adalah objek konfigurasi sumber daya. Sumber daya dapat dirujuk oleh layanan melalui uses properti .

Properti sumber daya umum

Jenis sumber daya

Properti type menentukan jenis sumber daya Azure dan kontrol properti tambahan mana yang tersedia.

properti host.appservice

runtime Objek:

resources:
  web:
    type: host.appservice
    port: 8080
    runtime:
      stack: node
      version: 22-lts
    uses:
      - db

properti host.containerapp

properti ai.openai.model

model Objek:

resources:
  chatModel:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"

properti ai.project

models item array:

sku Objek:

properti ai.search

properti db.cosmos

containers item array:

properti messaging.eventhubs

properti messaging.servicebus

properti storage

properti keyvault

Sampel sumber daya

resources:
  db:
    type: db.postgres
  cache:
    type: db.redis
  chatModel:
    type: ai.openai.model
    model:
      name: gpt-4o
      version: "2024-08-06"
  web:
    type: host.containerapp
    port: 3100
    uses:
      - db
      - chatModel

pipeline

(objek) Definisi alur integrasi berkelanjutan.

pipeline:
  provider: azdo
  variables:
    - CUSTOM_SETTING
  secrets:
    - API_KEY

hooks

(objek) Kait tingkat perintah. Hook harus cocok dengan nama perintah azd yang diawali dengan pre atau post tergantung kapan skrip harus dijalankan. Saat menentukan jalur, jalur tersebut harus relatif terhadap jalur proyek. Lihat Mengkustomisasi alur kerja Azure Developer CLI Anda menggunakan perintah dan kait peristiwa untuk detail selengkapnya.

Kait perintah yang didukung: preprovision, , postprovision, preinfracreate, postinfracreatepreinfradelete, postinfradelete, predown, postdown, preup, postupprepackage, postpackage, prepublish, , postpublish, predeploy, postdeploy, , prerestore. postrestore

Setiap hook menggunakan format definisi Hook .

hooks:
  preprovision:
    shell: sh
    run: ./scripts/setup.sh
  postdeploy:
    shell: sh
    run: azd env set APP_URL ${SERVICE_WEB_ENDPOINT_URL}

Definisi hook

Kait bisa menjadi objek kait tunggal atau array objek kait. Setiap objek kait memiliki properti berikut:

Konfigurasi pelaksana hook

Properti config menerima properti yang berbeda tergantung pada nilainya kind .

Konfigurasi JavaScript dan TypeScript (js, ts)

Konfigurasi Python

Konfigurasi .NET (dotnet)

Konfigurasi Shell (sh, pwsh)

Eksekutor Shell saat ini tidak mendukung config properti.

Sampel hook

Kait khusus platform

hooks:
  preprovision:
    windows:
      shell: pwsh
      run: ./scripts/setup.ps1
    posix:
      shell: sh
      run: ./scripts/setup.sh

Kait Python dengan jenis

hooks:
  postprovision:
    kind: python
    run: ./scripts/seed-data.py
    dir: ./scripts
    config:
      virtualEnvName: .venv

Beberapa kait untuk satu peristiwa

hooks:
  postprovision:
    - shell: sh
      run: ./scripts/step1.sh
    - shell: sh
      run: ./scripts/step2.sh

requiredVersions

(objek) Menyediakan konfigurasi tambahan untuk versi azd ekstensi dan yang diperlukan.

requiredVersions:
  azd: ">= 0.6.0-beta.3"
  extensions:
    azure.ai.agents: ">=1.0.0"
    my-extension: latest

state

(objek) Menyediakan konfigurasi tambahan untuk manajemen status.

state.remote

Konfigurasi Azure Blob Storage

state:
  remote:
    backend: AzureBlobStorage
    config:
      accountName: mystorageaccount
      containerName: azd-state

platform

(objek) Menyediakan konfigurasi tambahan untuk fitur khusus platform seperti Azure Dev Center.

Konfigurasi Dev Center

Tersedia ketika type adalah devcenter:

platform:
  type: devcenter
  config:
    name: my-devcenter
    project: my-project
    catalog: my-catalog
    environmentDefinition: my-env-def
    environmentType: dev

workflows

(objek) Menyediakan konfigurasi tambahan untuk alur kerja seperti perilaku penimpaan azd up .

Langkah-langkah alur kerja

up Alur kerja menerima steps array (atau dapat ditentukan langsung sebagai array). Setiap langkah menjalankan azd perintah.

Mengonfigurasi urutan langkah alur kerja

File berikut azure.yaml mengubah perilaku azd up default untuk memindahkan azd package langkah setelah langkah.azd provision Gunakan pendekatan ini dalam skenario di mana Anda perlu mengetahui URL sumber daya selama proses build atau pengemasan.

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
workflows:
  up:
    steps:
      - azd: provision
      - azd: package
      - azd: deploy --all

cloud

(objek) Menyediakan konfigurasi tambahan untuk menyebarkan ke sovereign cloud seperti Azure Government. Cloud defaultnya adalah AzureCloud.

cloud:
  name: AzureUSGovernment

Minta bantuan

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

Langkah berikutnya

• Sesuaikan alur kerja menggunakan perintah dan event hook
• Gambaran umum templat Azure Developer CLI
• Menggunakan Terraform sebagai penyedia IaC
• Mengelola variabel lingkungan