Referência de esquema da CLI do Desenvolvedor do Azure

O azure.yaml arquivo é o arquivo de configuração para projetos da CLI do Desenvolvedor do Azure (azd). Coloque-o na raiz do projeto para definir os serviços, os recursos do Azure, a infraestrutura, os ganchos e o pipeline de CI/CD que compõem seu aplicativo. Quando você executa comandos como azd up, azd provisionou azd deploy, a CLI lê este arquivo para entender a estrutura do aplicativo e como implantá-lo no Azure.

Este artigo é uma referência completa para o esquema azure.yaml. Para começar a azd usar modelos, consulte a visão geral dos modelos da CLI do Desenvolvedor do Azure.

Amostra

Veja a seguir um exemplo genérico de um azure.yaml arquivo para um azd modelo. Para obter um exemplo do mundo real, consulte o azure.yamlmodelo do 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

Propriedades de nível superior

name

(cadeia de caracteres, obrigatório) O nome do aplicativo. Somente letras minúsculas, números e hifens (-) são permitidos. O nome deve começar e terminar com uma letra ou um número. Comprimento mínimo: 2 caracteres.

name: my-app

resourceGroup

(cadeia de caracteres) Nome do grupo de recursos do Azure. Quando especificado, substitui o nome do grupo de recursos usado para provisionamento de infraestrutura. Dá suporte à substituição de variável de ambiente. Deve ter entre 3 e 64 caracteres.

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

metadata

(objeto) Metadados sobre o modelo de aplicativo.

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

infra

(objeto) Fornece configuração adicional para provisionamento de infraestrutura do Azure.

infra.layers

(matriz de objetos) Define as camadas de provisionamento para a infraestrutura do Azure. Cada camada representa uma unidade independente de provisionamento.

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

Exemplo de provedor Terraform como IaC

Para usar o Terraform em vez de Bicep, defina como providerterraform. Para obter mais informações, consulte Usar o Terraform como um provedor de 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

(objeto) Definição de serviços que compõem o aplicativo. Cada chave é um nome de serviço e o valor é um objeto de configuração de serviço.

Propriedades de serviço

Tipos de host

A host propriedade determina o tipo de recurso do Azure usado para implementação de serviço e controla quais outras propriedades são válidas.

ai.endpoint Configuração

(object, required when host is ai.endpoint) Fornece configuração adicional para a implantação de ponto de extremidade online de IA do Azure.

Configuração do componente de IA

Configuração de implantação de IA

Herda todas as propriedades da configuração do componente de IA, além de:

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

docker

(objeto) Configuração do Docker para um serviço. Aplicável somente a hosts que dão suporte a contêineres (containerapp, , aks, ai.endpoint). azure.ai.agent

k8s

(objeto) Opções de configuração do AKS (Serviço de Kubernetes do Azure). Somente válido quando host for aks.

Configuração de implantação

Configuração de serviço

Configuração de entrada

Configuração do Helm

repositories itens de matriz:

releases itens de matriz:

Configuração de Kustomize

Ganchos de serviço

Ganchos de nível de serviço são executados durante eventos do ciclo de vida do serviço. Os ganchos devem corresponder aos nomes de eventos de serviço prefixados com pre ou post. Ao especificar caminhos, eles devem ser relativos ao caminho do serviço. Consulte Personalizar seus fluxos de trabalho da CLI do Desenvolvedor do Azure usando comando e ganchos de evento para obter mais detalhes.

Ganchos de serviço com suporte: prerestore, , postrestore, prebuild, postbuild, prepackage, postpackage, , prepublish, postpublish, , , predeploy. postdeploy

Cada gancho usa o formato de definição do Gancho .

Exemplos de serviço

Aplicativos de contêiner com opções do 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

Aplicativos de contêiner de uma imagem predefinida

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

AKS com ganchos de nível de serviço

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

(objeto) Definição de recursos do Azure usados pelo aplicativo. Cada chave é um nome de recurso e o valor é um objeto de configuração de recurso. Os recursos podem ser referenciados por serviços por meio da uses propriedade.

Propriedades comuns do recurso

Tipos de recursos

A type propriedade determina o tipo de recurso do Azure e controla quais propriedades adicionais estão disponíveis.

propriedades de host.appservice

runtime Objeto:

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

propriedades de host.containerapp

propriedades de ai.openai.model

model Objeto:

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

propriedades de ai.project

models itens de matriz:

sku Objeto:

propriedades de ai.search

propriedades de db.cosmos

containers itens de matriz:

propriedades de messaging.eventhubs

propriedades de messaging.servicebus

propriedades de storage

propriedades de keyvault

Exemplo de recursos

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

(objeto) Definição de pipeline de integração contínua.

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

hooks

(objeto) Ganchos de nível de comando. Os ganchos devem corresponder azd nomes de comando prefixados com pre ou post dependendo de quando o script deve ser executado. Ao especificar caminhos, eles devem ser relativos ao caminho do projeto. Consulte Personalizar seus fluxos de trabalho da CLI do Desenvolvedor do Azure usando comando e ganchos de evento para obter mais detalhes.

Ganchos de comando com suporte: preprovision, , postprovision, preinfracreate, postinfracreate, preinfradelete, postinfradelete, , postdownpredown, preup, , postup, prepackage, , postpackage, , prepublish, postpublish, , predeploy, postdeploy, , prerestore, postrestore.

Cada gancho usa o formato de definição do Gancho .

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

Definição de gancho

Um gancho pode ser um único objeto de gancho ou uma matriz de objetos de gancho. Cada objeto de gancho tem as seguintes propriedades:

Configuração do executor do gancho

A config propriedade aceita propriedades diferentes dependendo do kind valor.

Configuração de JavaScript e TypeScript (js, ts)

Configuração do Python

Configuração do .NET (dotnet)

Configuração do Shell (sh, pwsh)

Atualmente, os executores de shell não dão suporte config a propriedades.

Exemplos de gancho

Ganchos específicos da plataforma

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

Gancho do Python com tipo

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

Vários ganchos para um único evento

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

requiredVersions

(objeto) Fornece configuração adicional para versões azd e extensões necessárias.

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

state

(objeto) Fornece configuração adicional para o gerenciamento de estado.

state.remote

Configuração do Armazenamento de Blobs do Azure

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

platform

(objeto) Fornece configuração adicional para recursos específicos da plataforma, como o Centro de Desenvolvimento do Azure.

Configuração do Centro de Desenvolvimento

Disponível quando type for devcenter:

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

workflows

(objeto) Fornece configuração adicional para fluxos de trabalho, como o comportamento de substituição azd up .

Etapas do fluxo de trabalho

O up fluxo de trabalho aceita uma steps matriz (ou pode ser especificado diretamente como uma matriz). Cada etapa executa um azd comando.

Configurar a ordem da etapa do fluxo de trabalho

O arquivo a seguir azure.yaml altera o comportamento padrão de azd up mover a azd package etapa após a azd provision etapa. Use essa abordagem em cenários em que você precisa saber as URLs dos recursos durante o processo de build ou empacotamento.

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

cloud

(objeto) Fornece configuração adicional para implantação em nuvens soberanas, como o Azure Governamental. A nuvem padrão é AzureCloud.

cloud:
  name: AzureUSGovernment

Solicitar ajuda

Para obter informações sobre como arquivar um bug, solicitar ajuda ou propor um novo recurso para a CLI do Desenvolvedor do Azure, visite a página solução de problemas e suporte.

Próximas etapas

• Personalizar fluxos de trabalho usando comando e ganchos de evento
• Visão geral dos modelos da CLI do Desenvolvedor do Azure
• Usar o Terraform como um provedor de IaC
• Gerenciar variáveis de ambiente