azure.yaml Reference

name: my-awesome-app  # Letters, numbers, dashes, underscores (1-64 chars)
name: cool_project-2024  # ✅ Perfect!
name: my project  # ❌ No spaces
name: ""  # ❌ Can't be empty

services:
  api:
    # Core properties
    language: TypeScript
    project: ./backend
    entrypoint: src/main.ts  # Entry file
    command: "tsx watch src/main.ts"  # Override default command
    type: http
    mode: daemon

    # Network
    ports:
      - "8080:8080"  # host:container
      - "127.0.0.1:9090:9090"  # bind to specific IP
      - "3000"  # auto-map to same port

    # Environment
    environment:
      - name: NODE_ENV
        value: development
      - name: DB_PASSWORD
        secret: MY_DB_SECRET  # Reference to secret

    # Or as object (simpler for non-secret values)
    # environment:
    #   NODE_ENV: development
    #   API_KEY: "abc123"

    # Dependencies
    uses:
      - postgres
      - redis

    # Health monitoring
    healthcheck:
      type: http
      path: /health
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

services:
  api:
    # Array format (supports secrets)
    environment:
      - name: NODE_ENV
        value: development
      - name: DB_PASSWORD
        secret: DB_SECRET  # Reference to secret

    # Object format (simpler, no secrets)
    environment:
      NODE_ENV: development
      API_URL: http://localhost:8080
      DEBUG: "true"

services:
  # HTTP health check (default for HTTP services)
  api:
    ports: ["8080"]
    healthcheck:
      type: http
      path: /health  # Default is /health
      interval: 30s
      timeout: 10s
      retries: 3

  # TCP health check - checks if port is listening
  database:
    image: postgres:16
    ports: ["5432"]
    healthcheck:
      type: tcp
      interval: 10s
      retries: 5

  # Process health check - verifies process is running
  worker:
    project: ./worker
    healthcheck:
      type: process
      interval: 15s

  # Output health check - watches stdout for pattern
  typescript-watcher:
    project: ./frontend
    command: tsc --watch
    mode: watch
    healthcheck:
      type: output
      pattern: "Found 0 errors\. Watching for file changes"
      timeout: 60s

  # Disable health check for build processes
  build-assets:
    project: ./assets
    command: npm run build
    mode: build
    healthcheck: false

  # Docker Compose style (cross-platform compatible)
  postgres:
    image: postgres:16
    healthcheck:
      test: "http://localhost:5432"  # Preferred
      # Or: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 40s

services:
  custom-app:
    image: myapp:latest  # Use existing image
    ports: ["8080"]

  built-app:
    docker:
      path: ./Dockerfile  # Path to Dockerfile
      context: .  # Build context
      platform: linux/amd64
      buildArgs:
        - NODE_VERSION=20
        - BUILD_ENV=production
      registry: myregistry.azurecr.io
      image: myapp
      tag: v1.0.0
    ports: ["8080"]

resources:
  # Azure Storage Account
  storage:
    type: Microsoft.Storage/storageAccounts

  # Azure Key Vault
  keyvault:
    type: Microsoft.KeyVault/vaults

  # SQL Server with dependency
  sqlserver:
    type: Microsoft.Sql/servers
    uses:
      - keyvault  # Depends on key vault

  # Existing resource (not provisioned by azd)
  existing-db:
    type: Microsoft.Sql/servers
    existing: true

reqs:
  # Simple version check
  - name: node
    minVersion: "20.0.0"

  # With installation URL override
  - name: python
    minVersion: "3.11"
    installUrl: "https://www.python.org/downloads/"

  # Check if tool is running (Docker daemon)
  - name: docker
    minVersion: "20.0.0"
    checkRunning: true
    installUrl: "https://docs.docker.com/desktop/"

  # Custom version check command
  - name: my-tool
    minVersion: "2.5.0"
    command: my-tool
    args: ["version"]
    versionPrefix: "v"  # Strip 'v' prefix
    versionField: 1  # Which field has version
    installUrl: "https://example.com/install"

  # Custom running check
  - name: kubernetes
    command: kubectl
    checkRunning: true
    runningCheckCommand: kubectl
    runningCheckArgs: ["cluster-info"]
    runningCheckExpected: "Kubernetes control plane"
    runningCheckExitCode: 0

hooks:
  # Simple pre-run hook
  prerun:
    run: npm install
    shell: sh

  # Post-run notification
  postrun:
    run: echo "🚀 All services are running!"
    shell: sh
    continueOnError: true  # Don't fail if hook fails

  # Pre-stop hook (drain connections before shutdown)
  prestop:
    run: echo "Draining connections..."
    shell: sh
    continueOnError: true

  # Post-stop cleanup
  poststop:
    run: ./scripts/cleanup.sh
    shell: bash

  # Platform-specific hooks
  prerun:
    windows:
      run: .\scripts\setup.ps1
      shell: pwsh
    posix:
      run: ./scripts/setup.sh
      shell: bash

logs:
  # Filter out noisy logs
  filters:
    exclude:
      - "npm warn"
      - "Debugger listening on"
      - "ExperimentalWarning"

  # Override log levels
  classifications:
    - text: "DEPRECATED"
      level: warning
    - text: "fatal"
      level: error
    - text: "panic"
      level: error

# Project-level: Configure polling behavior
logs:
  analytics:
    pollingInterval: 30s    # How often to refresh Azure logs (default: 30s)
    defaultTimespan: PT15M  # Time range for queries (ISO 8601 duration, default: PT15M)

# Service-level: Specify Log Analytics tables
services:
  web:
    host: appservice
    path: ./src/web
    logs:
      analytics:
        table: AppServiceConsoleLogs  # App Service standard table

  api:
    host: containerapp
    path: ./src/api
    logs:
      analytics:
        table: ContainerAppConsoleLogs_CL  # Container Apps custom log table

  functions:
    host: functions
    path: ./src/functions
    logs:
      analytics:
        table: FunctionAppLogs  # Functions standard table

# Advanced: Custom KQL query (yaml-only, not exposed in dashboard UI)
  worker:
    host: functions
    path: ./src/worker
    logs:
      analytics:
        query: |
          FunctionAppLogs
          | where FunctionName == "ProcessQueue"
          | where TimeGenerated > ago(15m)
          | where Level == "Error"
          | order by TimeGenerated desc

# Global test configuration
test:
  parallel: true  # Run service tests in parallel
  failFast: false  # Continue even if a test fails
  outputDir: ./test-results
  outputFormat: junit  # default, json, junit, github
  coverage:
    enabled: true
    threshold: 80  # Fail if coverage < 80%
    exclude:
      - "**/vendor/**"
      - "**/test/**"

services:
  api:
    test:
      # Unit tests
      unit:
        command: npm test
        path: tests/unit
        pattern: "*.test.ts"
        timeout: 5m
        env:
          NODE_ENV: test

      # Integration tests
      integration:
        command: npm run test:integration
        path: tests/integration
        timeout: 10m

      # End-to-end tests
      e2e:
        command: npm run test:e2e
        path: tests/e2e
        timeout: 15m

      # Service-specific coverage
      coverage:
        enabled: true
        threshold: 85
        exclude:
          - "**/*.test.ts"
          - "**/mocks/**"

infra:
  provider: bicep  # or 'terraform'
  path: ./infra  # Default: infra
  module: main  # Default: main

# Terraform example
infra:
  provider: terraform
  path: ./infrastructure
  module: main

pipeline:
  provider: github  # or 'azdo' for Azure DevOps

  # Variables from azd environment to pass to pipeline
  variables:
    - AZURE_ENV_NAME
    - AZURE_LOCATION

  # Secrets from azd environment to pass to pipeline
  secrets:
    - AZURE_SUBSCRIPTION_ID
    - DATABASE_PASSWORD

resourceGroup: my-custom-rg-name  # Supports environment variable substitution

requiredVersions:
  azd: ">= 0.6.0-beta.3"
  extensions:
    azure-app: ">=1.0.0"
    my-extension: "~2.0.0"  # Supports semver constraints

infra:
  provider: bicep  # or terraform
  path: infra  # Path to infrastructure code (default: infra)
  module: main  # Main module name (bicep) or path (terraform)

pipeline:
  provider: github  # or azdo (Azure DevOps)
  variables:
    NODE_ENV: production
  secrets:
    - API_KEY
    - DATABASE_URL

state:
  remote:
    backend: AzureBlobStorage
    config:
      accountName: mystorageaccount
      containerName: tfstate  # Optional, defaults to project name
      endpoint: blob.core.windows.net  # Optional

platform:
  type: devcenter
  config:
    name: my-dev-center
    project: my-dev-center-project
    catalog: my-catalog
    environmentDefinition: my-env-def
    environmentType: dev

workflows:
  up:
    steps:
      - azd: package --all
      - azd: provision
      - azd: deploy --all

# Or as array shorthand:
# workflows:
#   up:
#     - azd: package --all
#     - azd: provision
#     - azd: deploy --all

cloud:
  name: AzureUSGovernment  # AzureCloud (default), AzureChinaCloud, AzureUSGovernment

services:
  api:
    host: containerapp  # Required: appservice, containerapp, function, springapp, staticwebapp, aks, ai.endpoint
    project: ./api

    # Deployment configuration
    resourceGroup: custom-rg  # Override default resource group
    resourceName: my-api-instance  # Override resource name discovery
    module: api-module  # Infrastructure module for this service
    dist: ./dist  # Path to deployment artifacts

    # API version for deployment
    apiVersion: "2023-05-01"  # Container App API version

    # AKS-specific configuration
    k8s:
      deploymentPath: manifests  # Path to k8s manifests
      namespace: production  # K8s namespace
      deployment:
        name: api-deployment
      service:
        name: api-service
      ingress:
        name: api-ingress
        relativePath: /api

    # Service hooks (in addition to global hooks)
    hooks:
      predeploy:
        run: npm run build
        shell: sh
      postdeploy:
        run: echo "Deployed successfully!"
        shell: sh
      prerestore:
        run: npm install
      postrestore:
        run: echo "Restored dependencies"
      prebuild:
        run: npm run lint
      postbuild:
        run: echo "Build complete"
      prepackage:
        run: npm run test
      postpackage:
        run: echo "Package ready"

resources:
  # Storage Account
  storage:
    type: storage
    containers:  # Optional: containers to create
      - uploads
      - backups

  # Cosmos DB
  cosmosdb:
    type: db.cosmos
    containers:
      - name: users
        partitionKeys: ["/id"]
      - name: orders
        partitionKeys: ["/customerId", "/region"]

  # Event Hubs
  eventhubs:
    type: messaging.eventhubs
    hubs:  # Hubs to create
      - telemetry
      - logs

  # Service Bus
  servicebus:
    type: messaging.servicebus
    queues:
      - orders
      - notifications
    topics:
      - events

  # App Service host resource
  webapp:
    type: host.appservice
    port: 80
    runtime:
      stack: node
      version: "20-lts"
    startupCommand: "npm start"
    env:
      - name: NODE_ENV
        value: production

  # Container App host resource
  api-host:
    type: host.containerapp
    port: 8080
    env:
      - name: LOG_LEVEL
        value: info
      - name: DB_PASSWORD
        secret: DB_PASSWORD_SECRET

  # AI/ML Resources
  openai:
    type: ai.openai.model
    model:
      name: gpt-4
      version: "0613"

  ai-project:
    type: ai.project
    models:
      - name: gpt-4o
        version: "2024-05-13"
        format: OpenAI
        sku:
          name: GlobalStandard
          usageName: OpenAI.GlobalStandard.gpt-4o
          capacity: 10

  search:
    type: ai.search

  # Database resources
  postgres:
    type: db.postgres

  mysql:
    type: db.mysql

  redis:
    type: db.redis

  mongodb:
    type: db.mongo

  # Key Vault
  vault:
    type: keyvault

name: epic-fullstack-app

# 🎯 Global test configuration
test:
  parallel: true
  coverage:
    enabled: true
    threshold: 80

# 📋 Prerequisites
reqs:
  - name: node
    minVersion: "20.0.0"
  - name: docker
    checkRunning: true
  - name: python
    minVersion: "3.11"

# 🪝 Lifecycle hooks
hooks:
  prerun:
    run: echo "🚀 Starting up..."
    shell: sh
  postrun:
    run: echo "✨ Ready to code!"
    shell: sh
  prestop:
    run: echo "⏹️ Shutting down..."
    shell: sh
    continueOnError: true
  poststop:
    run: echo "🧹 Cleanup complete!"
    shell: sh

# 📊 Global logging
logs:
  filters:
    exclude:
      - "npm warn"
      - "Debugger listening"
  classifications:
    - text: "error"
      level: error
    - text: "warning"
      level: warning
  analytics:
    pollingInterval: "10s"
    defaultTimespan: "30m"

# 🎭 Services
services:
  # Next.js frontend
  web:
    language: TypeScript
    project: ./frontend
    ports: ["3000"]
    environment:
      - name: NEXT_PUBLIC_API_URL
        value: http://localhost:8000
      - name: NEXT_PUBLIC_ANALYTICS_ID
        secret: ANALYTICS_SECRET
    uses:
      - api
    healthcheck:
      path: /api/health
      interval: 10s
    test:
      unit:
        command: npm test
        coverage:
          threshold: 85

  # FastAPI backend
  api:
    language: Python
    project: ./backend
    entrypoint: main.py
    ports: ["8000"]
    environment:
      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app
      REDIS_URL: redis://localhost:6379
    uses:
      - postgres
      - redis
    healthcheck:
      path: /health
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s
    logs:
      analytics:
        tables:
          - ContainerAppConsoleLogs_CL
    test:
      unit:
        command: pytest tests/
        path: tests
      integration:
        command: pytest tests/integration/

  # Background worker
  worker:
    language: Python
    project: ./worker
    type: process
    environment:
      QUEUE_URL: redis://localhost:6379
    uses:
      - redis
    healthcheck:
      type: process
      interval: 30s

  # TypeScript build watcher
  build-types:
    project: ./shared
    command: tsc --watch --preserveWatchOutput
    mode: watch
    healthcheck:
      type: output
      pattern: "Found 0 errors"
      timeout: 60s

  # PostgreSQL database
  postgres:
    image: postgres:16
    ports: ["5432"]
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app
    healthcheck:
      type: tcp
      interval: 10s
      retries: 5

  # Redis cache
  redis:
    image: redis:7-alpine
    ports: ["6379"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s

  # Azurite for Azure Storage emulation
  azurite:
    image: mcr.microsoft.com/azure-storage/azurite
    ports:
      - "10000:10000"  # Blob
      - "10001:10001"  # Queue
      - "10002:10002"  # Table

# ☁️ Azure Resources
resources:
  storage:
    type: Microsoft.Storage/storageAccounts
  keyvault:
    type: Microsoft.KeyVault/vaults
  appinsights:
    type: Microsoft.Insights/components

# Property Quick Reference

## Root Properties (All)
### Required
- name - Application name (required)

### Development (azd app)
- services - Service definitions
- reqs - Prerequisites
- hooks - Lifecycle hooks (prerun, postrun, prestop, poststop)
- logs - Logging configuration
- test - Testing configuration

### Deployment (azd)
- resources - Azure resources
- infra - Infrastructure config (Bicep/Terraform)
- pipeline - CI/CD configuration
- resourceGroup - Override resource group
- requiredVersions - Version constraints
- state - Remote state management
- platform - Dev Center integration
- workflows - Custom command workflows
- cloud - Sovereign cloud selection
- metadata - Custom metadata

## Service Properties
### Core (azd app)
- language - Programming language
- project - Project directory
- entrypoint - Entry file
- command - Run command override
- type - http|tcp|process|container
- mode - daemon|watch|build|task

### Network & Containers
- ports - Port mappings
- image - Docker image
- docker - Build configuration
- environment - Env variables

### Dependencies & Health
- uses - Service/resource dependencies
- healthcheck - Health monitoring

### Configuration (azd app)
- logs - Service logging config
- test - Service test config

### Deployment (azd)
- host - Azure service type (required for deployment)
- resourceGroup - Service resource group
- resourceName - Override resource name
- apiVersion - API version
- module - Infrastructure module
- dist - Deployment artifacts path
- k8s - Kubernetes configuration
- config - Host-specific config
- hooks - Service lifecycle hooks

## Resource Properties
- type - Resource type (required)
- uses - Dependencies
- existing - Is existing resource
- [type-specific] - Container arrays, SKU config, etc.

metadata:
  template: todo-nodejs-mongo@0.0.1-beta
  author: Azure Samples
  description: Full-stack application with Node.js and MongoDB
  customField: any-value-you-want