plan-forge azd.instructions.md

Azure Developer CLI (azd) Best Practices

Required Structure

Every azd-compatible project requires:

project-root/
├── azure.yaml              ← service definition (required)
├── infra/                  ← IaC files (default; change with infra.path)
│   ├── main.bicep          ← or main.tf for Terraform
│   ├── main.parameters.json
│   └── modules/
├── .azure/                 ← azd environment state (git-ignored)
└── src/                    ← application source code (optional for pure infra)

azure.yaml

# azure.yaml — maps app services to provisioned Azure resources
name: myapp                       # must match infra resource naming

metadata:
  template: [email protected]           # optional: template origin tracking

# Infrastructure provider (default: bicep)
infra:
  provider: bicep                 # bicep | terraform
  path: infra                     # relative path to IaC files (default: infra)
  module: main                    # root module filename without extension (default: main)

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

  web:
    project: ./src/web
    language: js
    host: staticwebapp
    dist: build                   # relative path to built artifacts

# Pipeline provider (default: github)
pipeline:
  provider: github                # github | azdo

Terraform Variant

name: myapp-terraform
infra:
  provider: terraform
  path: infra
services:
  api:
    project: ./src/api
    language: dotnet
    host: containerapp

Required Resource Tags for azd Auto-Discovery

When resourceName is NOT set in azure.yaml, azd discovers resources by tags:

// In your Bicep module — tag resources so azd can find them
resource containerApp 'Microsoft.App/containerApps@2026-01-01' = {
  tags: union(commonTags, {
    'azd-env-name':     environmentName   // ← required for azd discovery
    'azd-service-name': 'api'             // ← must match service key in azure.yaml
  })
}