Azd Deployment

1---
2name: azd-deployment
3description: 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.
4---
5 
6# Azure Developer CLI (azd) Container Apps Deployment
7 
8Deploy containerized frontend + backend applications to Azure Container Apps with remote builds, managed identity, and idempotent infrastructure.
9 
10## Quick Start
11 
12```bash
13# Initialize and deploy
14azd auth login
15azd init                    # Creates azure.yaml and .azure/ folder
16azd env new <env-name>      # Create environment (dev, staging, prod)
17azd up                      # Provision infra + build + deploy
18```
19 
20## Core File Structure
21 
22```
23project/
24├── azure.yaml              # azd service definitions + hooks
25├── infra/
26│   ├── main.bicep          # Root infrastructure module
27│   ├── main.parameters.json # Parameter injection from env vars
28│   └── modules/
29│       ├── container-apps-environment.bicep
30│       └── container-app.bicep
31├── .azure/
32│   ├── config.json         # Default environment pointer
33│   └── <env-name>/
34│       ├── .env            # Environment-specific values (azd-managed)
35│       └── config.json     # Environment metadata
36└── src/
37    ├── frontend/Dockerfile
38    └── backend/Dockerfile
39```
40 
41## azure.yaml Configuration
42 
43### Minimal Configuration
44 
45```yaml
46name: azd-deployment
47services:
48  backend:
49    project: ./src/backend
50    language: python
51    host: containerapp
52    docker:
53      path: ./Dockerfile
54      remoteBuild: true
55```
56 
57### Full Configuration with Hooks
58 
59```yaml
60name: azd-deployment
61metadata:
62  template: my-project@1.0.0
63 
64infra:
65  provider: bicep
66  path: ./infra
67 
68azure:
69  location: eastus2
70 
71services:
72  frontend:
73    project: ./src/frontend
74    language: ts
75    host: containerapp
76    docker:
77      path: ./Dockerfile
78      context: .
79      remoteBuild: true
80 
81  backend:
82    project: ./src/backend
83    language: python
84    host: containerapp
85    docker:
86      path: ./Dockerfile
87      context: .
88      remoteBuild: true
89 
90hooks:
91  preprovision:
92    shell: sh
93    run: |
94      echo "Before provisioning..."
95      
96  postprovision:
97    shell: sh
98    run: |
99      echo "After provisioning - set up RBAC, etc."
100      
101  postdeploy:
102    shell: sh
103    run: |
104      echo "Frontend: ${SERVICE_FRONTEND_URI}"
105      echo "Backend: ${SERVICE_BACKEND_URI}"
106```
107 
108### Key azure.yaml Options
109 
110| Option | Description |
111|--------|-------------|
112| `remoteBuild: true` | Build images in Azure Container Registry (recommended) |
113| `context: .` | Docker build context relative to project path |
114| `host: containerapp` | Deploy to Azure Container Apps |
115| `infra.provider: bicep` | Use Bicep for infrastructure |
116 
117## Environment Variables Flow
118 
119### Three-Level Configuration
120 
1211. **Local `.env`** - For local development only
1222. **`.azure/<env>/.env`** - azd-managed, auto-populated from Bicep outputs
1233. **`main.parameters.json`** - Maps env vars to Bicep parameters
124 
125### Parameter Injection Pattern
126 
127```json
128// infra/main.parameters.json
129{
130  "parameters": {
131    "environmentName": { "value": "${AZURE_ENV_NAME}" },
132    "location": { "value": "${AZURE_LOCATION=eastus2}" },
133    "azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
134  }
135}
136```
137 
138Syntax: `${VAR_NAME}` or `${VAR_NAME=default_value}`
139 
140### Setting Environment Variables
141 
142```bash
143# Set for current environment
144azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
145azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"
146 
147# Set during init
148azd env new prod
149azd env set AZURE_OPENAI_ENDPOINT "..." 
150```
151 
152### Bicep Output → Environment Variable
153 
154```bicep
155// In main.bicep - outputs auto-populate .azure/<env>/.env
156output SERVICE_FRONTEND_URI string = frontend.outputs.uri
157output SERVICE_BACKEND_URI string = backend.outputs.uri
158output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId
159```
160 
161## Idempotent Deployments
162 
163### Why azd up is Idempotent
164 
1651. **Bicep is declarative** - Resources reconcile to desired state
1662. **Remote builds tag uniquely** - Image tags include deployment timestamp
1673. **ACR reuses layers** - Only changed layers upload
168 
169### Preserving Manual Changes
170 
171Custom domains added via Portal can be lost on redeploy. Preserve with hooks:
172 
173```yaml
174hooks:
175  preprovision:
176    shell: sh
177    run: |
178      # Save custom domains before provision
179      if az containerapp show --name "$FRONTEND_NAME" -g "$RG" &>/dev/null; then
180        az containerapp show --name "$FRONTEND_NAME" -g "$RG" \
181          --query "properties.configuration.ingress.customDomains" \
182          -o json > /tmp/domains.json
183      fi
184 
185  postprovision:
186    shell: sh
187    run: |
188      # Verify/restore custom domains
189      if [ -f /tmp/domains.json ]; then
190        echo "Saved domains: $(cat /tmp/domains.json)"
191      fi
192```
193 
194### Handling Existing Resources
195 
196```bicep
197// Reference existing ACR (don't recreate)
198resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
199  name: containerRegistryName
200}
201 
202// Set customDomains to null to preserve Portal-added domains
203customDomains: empty(customDomainsParam) ? null : customDomainsParam
204```
205 
206## Container App Service Discovery
207 
208Internal HTTP routing between Container Apps in same environment:
209 
210```bicep
211// Backend reference in frontend env vars
212env: [
213  {
214    name: 'BACKEND_URL'
215    value: 'http://ca-backend-${resourceToken}'  // Internal DNS
216  }
217]
218```
219 
220Frontend nginx proxies to internal URL:
221```nginx
222location /api {
223    proxy_pass $BACKEND_URL;
224}
225```
226 
227## Managed Identity & RBAC
228 
229### Enable System-Assigned Identity
230 
231```bicep
232resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
233  identity: {
234    type: 'SystemAssigned'
235  }
236}
237 
238output principalId string = containerApp.identity.principalId
239```
240 
241### Post-Provision RBAC Assignment
242 
243```yaml
244hooks:
245  postprovision:
246    shell: sh
247    run: |
248      PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
249      
250      # Azure OpenAI access
251      az role assignment create \
252        --assignee-object-id "$PRINCIPAL_ID" \
253        --assignee-principal-type ServicePrincipal \
254        --role "Cognitive Services OpenAI User" \
255        --scope "$OPENAI_RESOURCE_ID" 2>/dev/null || true
256      
257      # Azure AI Search access
258      az role assignment create \
259        --assignee-object-id "$PRINCIPAL_ID" \
260        --role "Search Index Data Reader" \
261        --scope "$SEARCH_RESOURCE_ID" 2>/dev/null || true
262```
263 
264## Common Commands
265 
266```bash
267# Environment management
268azd env list                        # List environments
269azd env select <name>               # Switch environment
270azd env get-values                  # Show all env vars
271azd env set KEY value               # Set variable
272 
273# Deployment
274azd up                              # Full provision + deploy
275azd provision                       # Infrastructure only
276azd deploy                          # Code deployment only
277azd deploy --service backend        # Deploy single service
278 
279# Debugging
280azd show                            # Show project status
281az containerapp logs show -n <app> -g <rg> --follow  # Stream logs
282```
283 
284## Reference Files
285 
286- **Bicep patterns**: See [references/bicep-patterns.md](references/bicep-patterns.md) for Container Apps modules
287- **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md) for common issues
288- **azure.yaml schema**: See [references/azure-yaml-schema.md](references/azure-yaml-schema.md) for full options
289 
290## Critical Reminders
291 
2921. **Always use `remoteBuild: true`** - Local builds fail on M1/ARM Macs deploying to AMD64
2932. **Bicep outputs auto-populate .azure/<env>/.env** - Don't manually edit
2943. **Use `azd env set` for secrets** - Not main.parameters.json defaults
2954. **Service tags (`azd-service-name`)** - Required for azd to find Container Apps
2965. **`|| true` in hooks** - Prevent RBAC "already exists" errors from failing deploy
297