Referencia del esquema de la CLI para desarrolladores de Azure

El azure.yaml archivo es el archivo de configuración de los proyectos de la CLI para desarrolladores de Azure (azd). Colóquelo en la raíz del proyecto para definir los servicios, los recursos de Azure, la infraestructura, los enlaces y la canalización de CI/CD que componen la aplicación. Al ejecutar comandos como azd up, azd provisiono azd deploy, la CLI lee este archivo para comprender la estructura de la aplicación y cómo implementarlo en Azure.

Este artículo es una referencia completa para el esquema azure.yaml. Para empezar a trabajar con azd plantillas, consulte Introducción a las plantillas de la CLI para desarrolladores de Azure.

Muestra

A continuación se muestra un ejemplo genérico de un azure.yaml archivo para una azd plantilla. Para ver un ejemplo real, consulte el azure.yaml elemento de la plantilla de Mongo toDo NodeJs:

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

Propiedades de nivel superior

name

(string, required) Nombre de la aplicación. Solo se permiten letras minúsculas, números y guiones (-). debe empezar y terminar con una letra o un número. Longitud mínima: 2 caracteres.

name: my-app

resourceGroup

(cadena) Nombre del grupo de recursos de Azure. Cuando se especifica, invalida el nombre del grupo de recursos usado para el aprovisionamiento de infraestructura. Admite la sustitución de variables de entorno. Debe tener entre 3 y 64 caracteres.

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

metadata

(objeto) Metadatos sobre la plantilla de aplicación.

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

infra

(objeto) Proporciona configuración adicional para el aprovisionamiento de la infraestructura de Azure.

infra.layers

(matriz de objetos) Define las capas de aprovisionamiento para la infraestructura de Azure. Cada capa representa una unidad independiente de aprovisionamiento.

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

Ejemplo de proveedor de Terraform como IaC

Para usar Terraform en lugar de Bicep, establezca en providerterraform. Para obtener más información, consulte Uso de Terraform como proveedor 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) Definición de servicios que componen la aplicación. Cada clave es un nombre de servicio y el valor es un objeto de configuración de servicio.

Propiedades del servicio

Tipos de host

La host propiedad determina el tipo de recurso de Azure que se usa para la implementación del servicio y los controles que otras propiedades son válidas.

ai.endpoint configuración

(object, required when host is ai.endpoint) Proporciona configuración adicional para la implementación de puntos de conexión en línea de Azure AI.

Configuración de componentes de IA

Configuración de implementación de IA

Hereda todas las propiedades de la configuración del componente de IA, además 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) Configuración de Docker para un servicio. Solo se aplica a los hosts que admiten contenedores (containerapp, aks, ai.endpoint, azure.ai.agent).

k8s

(objeto) Opciones de configuración de Azure Kubernetes Service (AKS). Solo es válido cuando host es aks.

Configuración de implementación

Configuración del servicio

Configuración de entrada

Configuración de Helm

repositories elementos de matriz:

releases elementos de matriz:

Configuración de Kustomize

Enlaces de servicio

Los enlaces de nivel de servicio se ejecutan durante los eventos del ciclo de vida del servicio. Los enlaces deben coincidir con los nombres de eventos de servicio prefijos con pre o post. Al especificar rutas de acceso, deben ser relativas a la ruta de acceso del servicio. Consulte Personalización de los flujos de trabajo de la CLI para desarrolladores de Azure mediante enlaces de comandos y eventos para más información.

Enlaces de servicio admitidos: prerestore, postrestore, prebuild, prepackagepostpackageprepublishpostbuild, postpublish, predeploy, . postdeploy

Cada enlace usa el formato de definición de enlace .

Ejemplos de servicio

Aplicaciones de contenedor con opciones de 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

Aplicaciones de contenedor a partir de una imagen precompilada

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

AKS con enlaces de nivel de servicio

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) Definición de los recursos de Azure usados por la aplicación. Cada clave es un nombre de recurso y el valor es un objeto de configuración de recursos. Los servicios pueden hacer referencia a los recursos a través de la uses propiedad .

Propiedades de recursos comunes

Tipos de recursos

La type propiedad determina el tipo de recurso de Azure y controla qué propiedades adicionales están disponibles.

propiedades de host.appservice

runtime objeto:

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

propiedades de host.containerapp

propiedades de ai.openai.model

model objeto:

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

propiedades de ai.project

models elementos de matriz:

sku objeto:

propiedades de ai.search

propiedades de db.cosmos

containers elementos de matriz:

propiedades de messaging.eventhubs

propiedades de messaging.servicebus

propiedades de storage

propiedades de keyvault

Ejemplo 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) Definición de la canalización de integración continua.

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

hooks

(objeto) Enlaces de nivel de comando. Los enlaces deben coincidir con azd nombres de comando prefijos con pre o post en función de cuándo se debe ejecutar el script. Al especificar rutas de acceso, deben ser relativas a la ruta de acceso del proyecto. Consulte Personalización de los flujos de trabajo de la CLI para desarrolladores de Azure mediante enlaces de comandos y eventos para más información.

Enlaces de comandos admitidos: , , , , postdeployprepublishpostpublishpostrestoreprerestorepostpackagepredeploypredownpostdownpostupprepackagepreinfradeletepreuppostinfracreatepostinfradeletepreinfracreatepostprovisionpreprovision

Cada enlace usa el formato de definición de enlace .

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

Definición de enlace

Un enlace puede ser un solo objeto de enlace o una matriz de objetos de enlace. Cada objeto de enlace tiene las siguientes propiedades:

Configuración del ejecutor de enlace

La config propiedad acepta propiedades diferentes en función del kind valor.

Configuración de JavaScript y TypeScript (js, ts)

Configuración de Python

Configuración de .NET (dotnet)

Configuración de Shell (sh, pwsh)

Los ejecutores de shell no admiten config actualmente propiedades.

Ejemplos de enlace

Enlaces específicos de la plataforma

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

Enlace de Python con tipo

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

Varios enlaces para un único evento

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

requiredVersions

(objeto) Proporciona configuración adicional para las versiones necesarias de azd y extensiones.

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

state

(objeto) Proporciona configuración adicional para la administración de estados.

state.remote

Configuración de Azure Blob Storage

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

platform

(objeto) Proporciona configuración adicional para características específicas de la plataforma, como el Centro de desarrollo de Azure.

Configuración del Centro de desarrollo

Disponible cuando type es devcenter:

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

workflows

(objeto) Proporciona una configuración adicional para los flujos de trabajo, como el comportamiento de invalidación azd up .

Pasos del flujo de trabajo

El up flujo de trabajo acepta una steps matriz (o se puede especificar directamente como una matriz). Cada paso ejecuta un azd comando.

Configuración del orden de pasos de flujo de trabajo

El siguiente azure.yaml archivo cambia el comportamiento predeterminado de azd up para mover el azd package paso después del azd provision paso. Use este enfoque en escenarios en los que necesite conocer las direcciones URL de los recursos durante el proceso de compilación o empaquetado.

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) Proporciona una configuración adicional para la implementación en nubes soberanas, como Azure Government. La nube predeterminada es AzureCloud.

cloud:
  name: AzureUSGovernment

Solicitar ayuda

Para obtener información sobre cómo archivar un error, solicitar ayuda o proponer una nueva característica para la CLI para desarrolladores de Azure, visite la página solución de problemas y soporte técnico.

Pasos siguientes

• Personalización de flujos de trabajo mediante enlaces de comandos y eventos
• Introducción a las plantillas de la CLI para desarrolladores de Azure
• Uso de Terraform como proveedor de IaC
• Administración de variables de entorno