azure.yaml Schema

June 30, 2026 · View on GitHub

The azure.yaml file is the project configuration file for the Azure Developer CLI. It lives at the root of your project and declares services, infrastructure, and lifecycle hooks.

Overview

name: my-project
metadata:
  template: my-org/my-template
services:
  web:
    project: ./src/web
    language: js
    host: appservice
  api:
    project: ./src/api
    language: python
    host: containerapp

Top-Level Properties

Property	Type	Description
`name`	string	Required. Project name used for resource naming
`metadata`	object	Template metadata (origin template, version)
`resourceGroup`	string	Override the default resource group name
`services`	map	Service definitions keyed by service name
`pipeline`	object	CI/CD pipeline configuration
`hooks`	map	Project-level lifecycle hooks
`infra`	object	Infrastructure provider configuration
`state`	object	Remote state backend configuration
`resources`	map	Azure resource definitions
`requiredVersions`	object	Version constraints for azd and extensions
`platform`	object	Platform-specific configuration
`workflows`	object	Workflow configuration
`cloud`	object	Cloud environment configuration

Service Properties

Property	Type	Description
`project`	string	Relative path to the service source directory
`language`	string	Service language (`dotnet`, `csharp`, `fsharp`, `py`, `js`, `ts`, `java`, `docker`, `custom`)
`host`	string	Required. Hosting target (`appservice`, `containerapp`, `function`, `staticwebapp`, `aks`, etc.)
`module`	string	Bicep module path for the service's infrastructure
`hooks`	map	Service-level lifecycle hooks
`docker`	object	Docker build configuration
`image`	string	Container image (alternative to `project` for pre-built images)
`dist`	string	Path to pre-built distribution directory
`resourceName`	string	Override the Azure resource name
`k8s`	object	Kubernetes-specific configuration
`config`	object	Service-specific configuration
`resourceGroup`	string	Override the resource group for this service
`apiVersion`	string	API version for the hosting target
`env`	map	Environment variables passed to the service
`uses`	list	Service dependencies
`remoteBuild`	boolean	Enable remote build (e.g., for Azure Functions)

Hooks

Hooks run user-defined scripts at lifecycle points:

hooks:
  preprovision:
    kind: sh
    run: ./scripts/setup.sh
  postdeploy:
    kind: sh
    run: ./scripts/smoke-test.sh

Available hook points (each supports pre and post prefixes):

Command hooks (project-level): build, deploy, down, package, provision, publish, restore, up
Service lifecycle hooks (service-level): restore, build, package, publish, deploy

For example, preprovision runs before provisioning, postdeploy runs after deployment. Service-level hooks are defined under a service's hooks section in azure.yaml and apply only to that service.

JSON Schema

The full JSON schema for azure.yaml is maintained in the schemas/ directory and published for editor validation.

Host-Specific Notes

App Service (`host: appservice`)

App Service supports two deployment modes:

Zip deploy (default): When language is set to a non-Docker language (e.g., python, js, dotnet), azd builds the code, creates a zip archive, and deploys it via the Kudu zip deploy API.
Container deploy: When language: docker is set, azd builds the container image, pushes it to ACR, and updates the site's linuxFxVersion. Currently Linux App Service only. Your infrastructure (bicep/terraform) must configure ACR access (e.g., managed identity ACR pull, identity assignment) before deploying. azd only updates the image reference at deploy time.

Note: Container deployment supports both language: docker (with a Dockerfile) and polyglot containerization (e.g., language: python with docker.path pointing to a Dockerfile). You can also use a pre-built image: without local source.

Example container deployment:

services:
  web:
    project: ./src/web
    language: docker
    host: appservice
    docker:
      path: ./Dockerfile