Azure Developer CLI schema reference

The azure.yaml file is the configuration file for Azure Developer CLI (azd) projects. Place it in the root of your project to define the services, Azure resources, infrastructure, hooks, and CI/CD pipeline that make up your application. When you run commands like azd up, azd provision, or azd deploy, the CLI reads this file to understand your app's structure and how to deploy it to Azure.

This article is a complete reference for the azure.yaml schema. For getting started with azd templates, see Azure Developer CLI templates overview.

Sample

The following is a generic example of an azure.yaml file for an azd template. For a real-world example, see the azure.yaml from the ToDo NodeJs Mongo template:

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

Top-level properties

name

(string, required) The application name. Only lowercase letters, numbers, and hyphens (-) are allowed. The name must start and end with a letter or number. Minimum length: 2 characters.

name: my-app

resourceGroup

(string) Name of the Azure resource group. When specified, overrides the resource group name used for infrastructure provisioning. Supports environment variable substitution. Must be between 3 and 64 characters.

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

metadata

(object) Metadata about the application template.

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

infra

(object) Provides additional configuration for Azure infrastructure provisioning.

infra.layers

(array of objects) Defines provisioning layers for Azure infrastructure. Each layer represents an independent unit of provisioning.

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

Terraform as IaC provider sample

To use Terraform instead of Bicep, set the provider to terraform. For more information, see Use Terraform as an IaC provider.

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

(object) Definition of services that comprise the application. Each key is a service name, and the value is a service configuration object.

Service properties

Host types

The host property determines the type of Azure resource used for service implementation and controls which other properties are valid.

ai.endpoint config

(object, required when host is ai.endpoint) Provides additional configuration for Azure AI online endpoint deployment.

AI component config

AI deployment config

Inherits all properties from AI component config, plus:

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

docker

(object) Docker configuration for a service. Only applicable for hosts that support containers (containerapp, aks, ai.endpoint, azure.ai.agent).

k8s

(object) Azure Kubernetes Service (AKS) configuration options. Only valid when host is aks.

Deployment config

Service config

Ingress config

Helm config

repositories array items:

releases array items:

Kustomize config

Service hooks

Service level hooks execute during service lifecycle events. Hooks should match service event names prefixed with pre or post. When specifying paths, they should be relative to the service path. See Customize your Azure Developer CLI workflows using command and event hooks for more details.

Supported service hooks: prerestore, postrestore, prebuild, postbuild, prepackage, postpackage, prepublish, postpublish, predeploy, postdeploy.

Each hook uses the Hook definition format.

Service samples

Container Apps with Docker options

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

Container Apps from a prebuilt image

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

AKS with service level hooks

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

(object) Definition of Azure resources used by the application. Each key is a resource name, and the value is a resource configuration object. Resources can be referenced by services through the uses property.

Common resource properties

Resource types

The type property determines the kind of Azure resource and controls which additional properties are available.

host.appservice properties

runtime object:

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

host.containerapp properties

ai.openai.model properties

model object:

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

ai.project properties

models array items:

sku object:

ai.search properties

db.cosmos properties

containers array items:

messaging.eventhubs properties

messaging.servicebus properties

storage properties

keyvault properties

Resources sample

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

(object) Definition of continuous integration pipeline.

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

hooks

(object) Command level hooks. Hooks should match azd command names prefixed with pre or post depending on when the script should execute. When specifying paths, they should be relative to the project path. See Customize your Azure Developer CLI workflows using command and event hooks for more details.

Supported command hooks: preprovision, postprovision, preinfracreate, postinfracreate, preinfradelete, postinfradelete, predown, postdown, preup, postup, prepackage, postpackage, prepublish, postpublish, predeploy, postdeploy, prerestore, postrestore.

Each hook uses the Hook definition format.

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

Hook definition

A hook can be a single hook object or an array of hook objects. Each hook object has the following properties:

Hook executor configuration

The config property accepts different properties depending on the kind value.

JavaScript and TypeScript (js, ts) config

Python config

.NET (dotnet) config

Shell (sh, pwsh) config

Shell executors don't currently support config properties.

Hook samples

Platform-specific hooks

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

Python hook with kind

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

Multiple hooks for a single event

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

requiredVersions

(object) Provides additional configuration for required versions of azd and extensions.

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

state

(object) Provides additional configuration for state management.

state.remote

Azure Blob Storage config

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

platform

(object) Provides additional configuration for platform-specific features such as Azure Dev Center.

Dev Center config

Available when type is devcenter:

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

workflows

(object) Provides additional configuration for workflows such as overriding azd up behavior.

Workflow steps

The up workflow accepts a steps array (or can be specified directly as an array). Each step runs an azd command.

Configure workflow step order

The following azure.yaml file changes the default behavior of azd up to move the azd package step after the azd provision step. Use this approach in scenarios where you need to know the URLs of resources during the build or packaging process.

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

cloud

(object) Provides additional configuration for deploying to sovereign clouds such as Azure Government. The default cloud is AzureCloud.

cloud:
  name: AzureUSGovernment

Request help

For information on how to file a bug, request help, or propose a new feature for the Azure Developer CLI, please visit the troubleshooting and support page.

Next steps

• Customize workflows using command and event hooks
• Azure Developer CLI templates overview
• Use Terraform as an IaC provider
• Manage environment variables