1# AZD Deploy Recipe
2 
3Deploy to Azure using Azure Developer CLI (azd).
4 
5> 💡 **Note:** azd supports both Bicep and Terraform as IaC providers. The deployment workflow is identical regardless of which you use.
6 
7## Prerequisites
8 
9- `azd` CLI installed → Run `mcp_azure_mcp_extension_cli_install` with `cli-type: azd` if needed
10- `.azure/deployment-plan.md` exists with status `Validated`
11- `azure.yaml` exists and validated
12- Infrastructure files exist (Bicep: `infra/main.bicep`, Terraform: `infra/*.tf`)
13- **AZD environment configured** → Done in azure-validate
14- **Subscription and location confirmed** → See [Pre-deploy Checklist](../../pre-deploy-checklist.md)
15 
16## Workflow
17 
18| Step | Task | Command |
19|------|------|---------|
20| 1 | **Verify environment** | `azd env get-values` — Confirm AZURE_SUBSCRIPTION_ID and AZURE_LOCATION set |
21| 2 | **Provision infrastructure** | `azd provision --no-prompt` |
22| 3 | **RBAC health check** *(Container Apps + ACR only)* | After provisioning, verify `AcrPull` role has propagated before deploying — see [Pre-Deploy Checklist](../../pre-deploy-checklist.md#container-apps--acr--pre-deploy-rbac-health-check) |
23| 4 | **Deploy application** | `azd deploy --no-prompt` |
24| 5 | **Post-Deploy** | [Post-Deployment Steps](post-deployment.md) — If using SQL + managed identity |
25| 6 | **Verify** | See [Verification](verify.md) |
26| 7 | **Report** | Present deployed endpoint URLs to the user — see [Verification](verify.md) Step 3 |
27 
28> ⚠️ **Important:** For Container Apps that use a managed identity to pull from ACR, always run `azd provision` and `azd deploy` as **separate steps** (not `azd up`) and complete the RBAC health check between them. This ensures the managed identity `AcrPull` role assignment has propagated before the Container App revision attempts to pull the image.
29 
30> ⚠️ **Important:** For .NET Aspire projects or projects using azd "limited mode" (no explicit `infra/` folder), verify that `azd provision` populated all required environment variables. If `azd deploy` fails with errors about missing `AZURE_CONTAINER_REGISTRY_ENDPOINT`, `AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID`, or `MANAGED_IDENTITY_CLIENT_ID`, see [Error Handling](errors.md#missing-container-registry-variables) for the resolution.
31 
32## Common Mistakes
33 
34| ❌ Wrong | Why It Fails |
35|----------|-------------|
36| `azd up --location eastus2` | `--location` is not a valid flag for `azd up` |
37| `azd up` without `azd env new` | Prompts for input, fails with `--no-prompt` |
38| `mkdir .azure` then `azd env new --no-prompt` | Creates env folder structure incorrectly |
39| Setting AZURE_LOCATION without checking RG | "Invalid resource group location" if RG exists elsewhere |
40| Ignoring `azd-service-name` tag conflicts in same RG | "found '2' resources tagged with..." error |
41| `language: html` or `language: static` | Not valid - use `language: js` with `dist: .` for static sites |
42 
43## Deployment Commands
44 
45> ⚠️ `azd up` takes 5-15 min. Run with output **streamed visibly to the user** — do NOT run silently or suppress output. The user must see provisioning progress in real time.
46 
47### Full Deployment
48 
49Provisions infrastructure AND deploys application:
50 
51```bash
52azd up --no-prompt
53```
54 
55### Infrastructure Only
56 
57```bash
58azd provision --no-prompt
59```
60 
61### Application Only
62 
63Deploy code to existing infrastructure:
64 
65```bash
66azd deploy --no-prompt
67```
68 
69### Single Service
70 
71```bash
72azd deploy api --no-prompt
73```
74 
75## References
76 
77- [Pre-deploy Checklist](../../pre-deploy-checklist.md) — **REQUIRED**
78- [Post-Deployment Steps](post-deployment.md) — SQL + managed identity setup
79- [Azure Functions Deployment](functions-deploy.md)
80- [Verification](verify.md)
81- [Error Handling](errors.md)
82