Azd Deployment for Azure

Deploy containerized applications to Azure Container Apps using Azure Developer CLI (azd). Use when setting up azd projects, writing azure.yaml configuration, creating Bicep infrastructure for Container Apps, configuring remote builds with ACR, implementing idempotent deployments, managing environment variables across local/.azure/Bicep, or troubleshooting azd up failures. Triggers on requests for azd configuration, Container Apps deployment, multi-service deployments, and infrastructure-as-code with Bicep.

Security Scan

The skill's instructions broadly match an azd/Azure Container Apps deployment workflow, but there are notable inconsistencies and risky patterns you should review before installing (missing declared tool requirements, conflicting guidance around ACR credentials, and hooks that run privileged az commands).

Purpose & Capability

The name/description match the SKILL.md content (azd, azure.yaml, Bicep, Container Apps). However the manifest declares no required binaries or credentials even though the runtime instructions depend on azd and az and on an authenticated Azure context. The skill also has no public source/homepage which reduces transparency.

Instruction Scope

The SKILL.md instructions stay within deployment / infra territory: init, env management, provision/deploy, Bicep patterns, and hook scripts. Hooks run arbitrary shell/az commands (creating role assignments, listing resources); this is expected for postprovision tasks but grants the hook scripts broad ability to alter Azure resources.

Install Mechanism

This is an instruction-only skill (no install spec, no code files to execute). That lowers disk/execution risk — the security surface is the instructions themselves and the environment where the agent runs them.

Credentials

The skill does not declare required env vars/credentials but uses many Azure-related variables (AZURE_OPENAI_ENDPOINT, AZURE_SEARCH_ENDPOINT, AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, outputs like BACKEND_PRINCIPAL_ID). More importantly, some included Bicep patterns enable ACR admin credentials and call containerRegistry.listCredentials()/listCredentials().passwords[0].value to place registry credentials into secrets — this is inconsistent with other parts of the docs that recommend managed identity and is a sensitive, high-privilege pattern. Hooks that run az role assignment create require privileges and can grant rights to deployed identities.

Persistence & Privilege

The skill does not request persistent platform-level privileges (always:false) and does not modify other skills' config. Its operations are limited to creating/modifying Azure resources in the user's subscription (expected for a deployment skill).

What to consider before installing

Before installing or using this skill, be aware: (1) It assumes azd and az are available and that you have an authenticated Azure session — the manifest doesn't declare those requirements. Install/run only where you control the Azure subscription and tooling. (2) Review all hook scripts and Bicep templates yourself — hooks run arbitrary az commands and can assign roles; ensure they don't grant more privileges than you intend. (3) The Bicep examples include a pattern that enables ACR admin credentials and injects registry credentials into container secrets — avoid this in production; prefer managed identity or Key Vault secret references. (4) Because the skill's source/homepage is unknown, exercise extra caution: run initial deployments in a sandbox subscription, inspect the generated .azure/<env>/.env files and Bicep output, and confirm RBAC changes before applying them. If you want to proceed, require explicit confirmation before running any hook that performs role assignments or prints credential values.

Azure Developer CLI (azd) Container Apps Deployment

Deploy containerized frontend + backend applications to Azure Container Apps with remote builds, managed identity, and idempotent infrastructure.

Quick Start

# Initialize and deploy
azd auth login
azd init                    # Creates azure.yaml and .azure/ folder
azd env new <env-name>      # Create environment (dev, staging, prod)
azd up                      # Provision infra + build + deploy

Core File Structure

project/
├── azure.yaml              # azd service definitions + hooks
├── infra/
│   ├── main.bicep          # Root infrastructure module
│   ├── main.parameters.json # Parameter injection from env vars
│   └── modules/
│       ├── container-apps-environment.bicep
│       └── container-app.bicep
├── .azure/
│   ├── config.json         # Default environment pointer
│   └── <env-name>/
│       ├── .env            # Environment-specific values (azd-managed)
│       └── config.json     # Environment metadata
└── src/
    ├── frontend/Dockerfile
    └── backend/Dockerfile

azure.yaml Configuration

Minimal Configuration

name: azd-deployment
services:
  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Full Configuration with Hooks

name: azd-deployment
metadata:
  template: my-project@1.0.0

infra:
  provider: bicep
  path: ./infra

azure:
  location: eastus2

services:
  frontend:
    project: ./src/frontend
    language: ts
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

hooks:
  preprovision:
    shell: sh
    run: |
      echo "Before provisioning..."
      
  postprovision:
    shell: sh
    run: |
      echo "After provisioning - set up RBAC, etc."
      
  postdeploy:
    shell: sh
    run: |
      echo "Frontend: ${SERVICE_FRONTEND_URI}"
      echo "Backend: ${SERVICE_BACKEND_URI}"

Key azure.yaml Options

Option	Description
remoteBuild: true	Build images in Azure Container Registry (recommended)
context: .	Docker build context relative to project path
host: containerapp	Deploy to Azure Container Apps
infra.provider: bicep	Use Bicep for infrastructure

Environment Variables Flow

Three-Level Configuration

1. Local .env - For local development only
2. .azure/<env>/.env - azd-managed, auto-populated from Bicep outputs
3. main.parameters.json - Maps env vars to Bicep parameters

Parameter Injection Pattern

// infra/main.parameters.json
{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION=eastus2}" },
    "azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
  }
}

Syntax: ${VAR_NAME} or ${VAR_NAME=default_value}

Setting Environment Variables

# Set for current environment
azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"

# Set during init
azd env new prod
azd env set AZURE_OPENAI_ENDPOINT "..." 

Bicep Output → Environment Variable

// In main.bicep - outputs auto-populate .azure/<env>/.env
output SERVICE_FRONTEND_URI string = frontend.outputs.uri
output SERVICE_BACKEND_URI string = backend.outputs.uri
output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId

Idempotent Deployments

Why azd up is Idempotent

1. Bicep is declarative - Resources reconcile to desired state
2. Remote builds tag uniquely - Image tags include deployment timestamp
3. ACR reuses layers - Only changed layers upload

Preserving Manual Changes

Custom domains added via Portal can be lost on redeploy. Preserve with hooks:

hooks:
  preprovision:
    shell: sh
    run: |
      # Save custom domains before provision
      if az containerapp show --name "$FRONTEND_NAME" -g "$RG" &>/dev/null; then
        az containerapp show --name "$FRONTEND_NAME" -g "$RG" \
          --query "properties.configuration.ingress.customDomains" \
          -o json > /tmp/domains.json
      fi

  postprovision:
    shell: sh
    run: |
      # Verify/restore custom domains
      if [ -f /tmp/domains.json ]; then
        echo "Saved domains: $(cat /tmp/domains.json)"
      fi

Handling Existing Resources

// Reference existing ACR (don't recreate)
resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
  name: containerRegistryName
}

// Set customDomains to null to preserve Portal-added domains
customDomains: empty(customDomainsParam) ? null : customDomainsParam

Container App Service Discovery

Internal HTTP routing between Container Apps in same environment:

// Backend reference in frontend env vars
env: [
  {
    name: 'BACKEND_URL'
    value: 'http://ca-backend-${resourceToken}'  // Internal DNS
  }
]

Frontend nginx proxies to internal URL:

location /api {
    proxy_pass $BACKEND_URL;
}

Managed Identity & RBAC

Enable System-Assigned Identity

resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  identity: {
    type: 'SystemAssigned'
  }
}

output principalId string = containerApp.identity.principalId

Post-Provision RBAC Assignment

hooks:
  postprovision:
    shell: sh
    run: |
      PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
      
      # Azure OpenAI access
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --assignee-principal-type ServicePrincipal \
        --role "Cognitive Services OpenAI User" \
        --scope "$OPENAI_RESOURCE_ID" 2>/dev/null || true
      
      # Azure AI Search access
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --role "Search Index Data Reader" \
        --scope "$SEARCH_RESOURCE_ID" 2>/dev/null || true

Common Commands

# Environment management
azd env list                        # List environments
azd env select <name>               # Switch environment
azd env get-values                  # Show all env vars
azd env set KEY value               # Set variable

# Deployment
azd up                              # Full provision + deploy
azd provision                       # Infrastructure only
azd deploy                          # Code deployment only
azd deploy --service backend        # Deploy single service

# Debugging
azd show                            # Show project status
az containerapp logs show -n <app> -g <rg> --follow  # Stream logs

Reference Files

• Bicep patterns: See references/bicep-patterns.md for Container Apps modules
• Troubleshooting: See references/troubleshooting.md for common issues
• azure.yaml schema: See references/azure-yaml-schema.md for full options

Critical Reminders

1. Always use remoteBuild: true - Local builds fail on M1/ARM Macs deploying to AMD64
2. Bicep outputs auto-populate .azure/<env>/.env - Don't manually edit
3. Use azd env set for secrets - Not main.parameters.json defaults
4. Service tags (azd-service-name) - Required for azd to find Container Apps
5. || true in hooks - Prevent RBAC "already exists" errors from failing deploy