1# AZD Recipe
2 
3Azure Developer CLI workflow for preparing Azure deployments.
4 
5## When to Use
6 
7- New projects, multi-service apps, want `azd up`
8- Need environment management, auto-generated CI/CD
9- Team prefers simplified deployment workflow
10 
11> 💡 **Tip:** azd supports both Bicep and Terraform as IaC providers. Choose based on your team's expertise and requirements.
12 
13## IaC Provider Options
14 
15| Provider | Use When |
16|----------|----------|
17| **Bicep** (default) | Azure-only, no existing IaC, want simplest setup |
18| **Terraform** | Multi-cloud IaC, existing TF expertise, want azd simplicity |
19 
20**For Terraform with azd:** See [terraform.md](terraform.md)
21 
22## Before Generation
23 
24**REQUIRED: Research best practices before generating any files.**
25 
26### Check for Existing Codebase Patterns
27 
28**⚠️ CRITICAL: For existing codebases with special patterns, use `azd init --from-code -e <environment-name>` instead of manual generation.**
29 
30| Pattern | Detection | Action |
31|---------|-----------|--------|
32| **.NET Aspire** | `*.AppHost.csproj` or `Aspire.Hosting` package | Use `azd init --from-code -e <environment-name>` → [aspire.md](../../aspire.md) |
33| **Existing azure.yaml** | `azure.yaml` present | MODIFY mode - update existing config |
34| **New project** | No azure.yaml, no special patterns | Manual generation (steps below) |
35 
36> 💡 **Note:** The `-e <environment-name>` flag is **required** when running `azd init --from-code` in non-interactive environments (agents, CI/CD pipelines). Without it, the command will fail with a prompt error.
37 
38### References for Manual Generation
39 
40| Artifact | Reference |
41|----------|-----------|
42| azure.yaml | [Schema Guide](azure-yaml.md) |
43| .NET Aspire projects | [Aspire Guide](../../aspire.md) |
44| Terraform with azd | [Terraform Guide](terraform.md) |
45| AZD IAC rules | [IAC Rules](iac-rules.md) |
46| Azure Functions templates | [Templates](../../services/functions/templates/README.md) |
47| Bicep best practices | `mcp_bicep_get_bicep_best_practices` |
48| Bicep resource schema | `mcp_bicep_get_az_resource_type_schema` |
49| Azure Verified Modules | `mcp_bicep_list_avm_metadata` + [AVM module order](iac-rules.md#avm-module-selection-order-mandatory) |
50| Terraform best practices | `mcp_azure_mcp_azureterraformbestpractices` |
51| Dockerfiles | [Docker Guide](docker.md) |
52 
53## Generation Steps
54 
55### For Bicep (default)
56 
57| # | Artifact | Reference |
58|---|----------|-----------|
59| 1 | azure.yaml | [Schema Guide](azure-yaml.md) |
60| 2 | Application code | Entry points, health endpoints, config |
61| 3 | Dockerfiles | [Docker Guide](docker.md) (if containerized) |
62| 4 | Infrastructure | `./infra/main.bicep` + modules per [IAC Rules](iac-rules.md) |
63 
64### For Terraform
65 
66| # | Artifact | Reference |
67|---|----------|-----------|
68| 1 | azure.yaml with `infra.provider: terraform` | [Terraform Guide](terraform.md) |
69| 2 | Application code | Entry points, health endpoints, config |
70| 3 | Dockerfiles | [Docker Guide](docker.md) (if containerized) |
71| 4 | Terraform files | `./infra/*.tf` per [Terraform Guide](terraform.md) |
72 
73## Outputs
74 
75### For Bicep
76 
77| Artifact | Path |
78|----------|------|
79| azure.yaml | `./azure.yaml` |
80| App Code | `src/<service>/*` |
81| Dockerfiles | `src/<service>/Dockerfile` (if containerized) |
82| Infrastructure | `./infra/` (Bicep files) |
83 
84### For Terraform
85 
86| Artifact | Path |
87|----------|------|
88| azure.yaml | `./azure.yaml` (with `infra.provider: terraform`) |
89| App Code | `src/<service>/*` |
90| Dockerfiles | `src/<service>/Dockerfile` (if containerized) |
91| Infrastructure | `./infra/` (Terraform files) |
92 
93## References
94 
95- [.NET Aspire Projects](../../aspire.md)
96- [azure.yaml Schema](azure-yaml.md)
97- [.NET Aspire Apps](aspire.md)
98- [Terraform with AZD](terraform.md)
99- [Docker Configuration](docker.md)
100- [IAC Rules](iac-rules.md)
101 
102## Next
103 
104→ Update `.azure/deployment-plan.md` → **azure-validate**
105