azure.yaml Schema

July 31, 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 for code-based 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

Function App (`host: function`)

Function Apps support code and container deployment:

Zip deploy (default): When no container configuration is present, azd builds the Function project, creates a zip archive, and deploys it through the Function App deployment API. The top-level remoteBuild property applies only to this mode.
Container deploy: Configure language: docker, set docker.path for a non-Docker language, or provide a pre-built image. azd builds or resolves the image, publishes it to ACR when needed, and updates the Function App's linuxFxVersion.

Container-based Function infrastructure must configure a Linux Function App, an initial DOCKER| image reference, and registry pull access before deployment. These settings remain the responsibility of Bicep or Terraform. If the provisioned Function App and the service disagree about the deployment mode, azd fails before attempting an incompatible upload and identifies the configuration mismatch.

Unlike App Service, Function Apps always deploy to the main site. Deployment slots are not part of the Function App workflow, so AZD_DEPLOY_{SERVICE}_SLOT_NAME has no effect and azd never prompts for a slot.

Example TypeScript container deployment:

services:
  function:
    project: ./src/function
    language: ts
    host: function
    docker:
      path: ./Dockerfile