Edit

Azure Developer CLI's azure.yaml schema

  • Article

azd templates are blueprint repositories that include proof-of-concept application code, editor/IDE configurations, and infrastructure code written in Bicep or Terraform. These templates are intended to be modified and adapted for your specific application requirements and then used to get your application on Azure using the Azure Developer CLI (azd). The azure.yaml schema defines and describes the apps and types of Azure resources that are included in these templates.

Sample

Below is a generic example of an azure.yaml required for your azd template.

name: yourApp
metadata:
  template: yourApp@0.0.1-beta
services:
  web:
    project: ./src/web # path to your web project
    dist: build # relative path to service deployment artifacts
    language: js # one of the supported languages
    host: appservice # one of the supported Azure services

Compare with the azure.yaml from our ToDo NodeJs Mongo template:

name: todo-nodejs-mongo
metadata:
  template: todo-nodejs-mongo@0.0.1-beta
services:
  web:
    project: ./src/web
    dist: build
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

Property descriptions

Element Name Required Description
name Y (string) Name of the application.
resourceGroup N (string) Name of the Azure resource group. When specified, will override the resource group name used for infrastructure provisioning.
metadata N (object) See metadata properties for more details.
infra N (object) Provides extra configuration for Azure infrastructure provisioning. See infra properties for more details.
services Y (object) Definition of services that comprise the application. See services properties for more details.
pipeline N (object) Definition of continuous integration pipeline. See pipeline properties for more details.
hooks N 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.
requiredVersions N A range of supported versions of azd for this project. If the version of azd is outside this range, the project will fail to load. Optional (allows all versions if absent). Example: >= 0.6.0-beta.3

metadata properties

Element Name Required Description Example
template N (string) Identifier of the template from which the application was created. todo-nodejs-mongo@0.0.1-beta

infra properties

Element Name Required Description Example
provider N (string) The infrastructure provider for the application's Azure resources. (Default: bicep). See the Terraform sample below. bicep, terraform
path N (string) The relative folder path to the location containing Azure provisioning templates for the specified provider. (Default: infra).
module N (string) The name of the default module withing the Azure provisioning templates. (Default: main).

Terraform as IaC provider sample

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 properties

Element Name Required Description Example
resourceName N (string) Name of the Azure resource that implements the service. If not specified, azd will look for a resource by azd-env-name and azd-service-name tags. If not found, it will look for a resource name constructed from the current environment name, concatenated with the service name (<environment-name><resource-name>). prodapi
project Y (string) Path to the service source code directory.
host Y (string) Type of Azure resource used for service implementation. If omitted, App Service will be assumed. appservice, containerapp, function, staticwebapp, aks (only for projects deployable via kubectl apply -f), springapp (when enabled - learn more about alpha features)
language Y (string) Service implementation language. dotnet, csharp, fsharp, py, python, js, ts, java
module Y (string) Path of the infrastructure module used to deploy the service relative to the root infra folder. If omitted, the CLI will assume the module name is the same as the service name.
dist Y (string) Relative path to the service deployment artifacts. The CLI will use files under this path to create the deployment artifact (.zip file). If omitted, all files under the service project directory will be included. build
docker N Only applicable when host is containerapp. Can't contain extra properties. See the custom Docker sample below. path (string): Path to the Dockerfile. Default: ./Dockerfile; context (string): The docker build context. When specified, overrides default context. Default: .; platform (string): The platform target. Default: amd64
k8s N The Azure Kubernetes Service (AKS) configuration options. See the AKS sample below. deploymentPath (string): Optional. The relative path from the service path to the k8s deployment manifests. When set, it will override the default deployment path location for k8s deployment manifests. Default: manifests; namespace (string): Optional. The k8s namespace of the deployed resources. When specified, a new k8s namespace will be created if it does not already exist. Default: Project name; deployment (object): See deployment properties; service (object): See service properties; ingress (object): See ingress properties.
hooks N Service level hooks. Hooks should match service event names prefixed with pre or post depending on when the script should execute. 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.

Docker options sample

In the following example, we declare Docker options for a container app.

name: yourApp-aca
metadata:
    template: yourApp-aca@0.0.1-beta
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
    docker:
      path: ./Dockerfile
      context: ../
  web:
    project: ./src/web
    language: js
    host: containerapp

AKS deployment properties

Element Name Required Description Example
name N (string) Optional. The name of the k8s deployment resource to use during deployment. Used during deployment to ensure if the k8s deployment rollout has been completed. If not set, will search for a deployment resource in the same namespace that contains the service name. Default: Service name api

AKS service properties

Element Name Required Description Example
name N (string) Optional. The name of the k8s service resource to use as the default service endpoint. Used when determining endpoints for the default service resource. If not set, will search for a deployment resource in the same namespace that contains the service name. (Default: Service name) api

AKS ingress properties

Element Name Required Description Example
name N (string) Optional. The name of the k8s ingress resource to use as the default service endpoint. Used when determining endpoints for the default ingress resource. If not set, will search for a deployment resource in the same namespace that contains the service name. Default: Service name api
relativePath N (string) Optional. The relative path to the service from the root of your ingress controller. When set, will be appended to the root of your ingress resource path.

AKS sample with service level hooks

metadata:
  template: todo-nodejs-mongo-aks@0.0.1-beta
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}

pipeline properties

Element Name Required Description Example
provider N (string) The pipeline provider to be used for continuous integration. (Default: github). github, azdo

Azure Pipelines (AzDo) as a CI/CD pipeline sample

name: yourApp
services:  
  web:    
    project: src/web
    dist: build
    language: js
    host: appservice
pipeline: 
  provider: azdo

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