new-azd-service

Add azd Support to Existing Project

Convert an existing application or infrastructure project to use the Azure Developer CLI (azd).

What azd Needs

Every azd-compatible project requires:

1. An azure.yaml at the project root
2. An infra/ folder with a Bicep or Terraform entry point (main.bicep or main.tf)
3. Resources tagged with azd-env-name and azd-service-name for auto-discovery

Step 1 — Explore the Project

Read the project structure first:

• What services are defined? (API, web app, functions, containers)
• What language / runtime?
• What Azure resources already exist or are planned?
• Is IaC already written? If so, Bicep or Terraform?

Step 2 — Create azure.yaml

# azure.yaml
name: {project-name}

metadata:
  template: {project-name}@1.0.0   # optional

infra:
  provider: bicep           # bicep | terraform
  path: infra               # relative path to IaC folder
  module: main              # root module name

services:
  api:
    project: ./src/api      # path to service source
    language: dotnet        # dotnet | js | ts | python | java
    host: containerapp      # appservice | containerapp | function | staticwebapp | aks
    docker:
      path: ./src/api/Dockerfile

  web:                      # remove if no front-end
    project: ./src/web
    language: js
    host: staticwebapp
    dist: build

pipeline:
  provider: github          # github | azdo

hooks:
  preprovision:
    shell: pwsh
    run: ./scripts/Validate-Prerequisites.ps1
    continueOnError: false
  postdeploy:
    shell: pwsh
    run: ./scripts/Invoke-SmokeTest.ps1 -EnvironmentName ${AZURE_ENV_NAME}

Step 3 — Tag Resources for azd Discovery

In infra/modules/{service}.bicep, add azd tags alongside common tags:

param environmentName string
param serviceName string = 'api'     // must match services key in azure.yaml

resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  tags: union(commonTags, {
    'azd-env-name':     environmentName
    'azd-service-name': serviceName
  })
  ...
}