1# AZD with Terraform
2 
3Use Azure Developer CLI (azd) with Terraform as the infrastructure provider.
4 
5## When to Use
6 
7Choose azd+Terraform when you want:
8- **Terraform's multi-cloud capabilities** with **azd's deployment simplicity**
9- Existing Terraform expertise but want `azd up` convenience
10- Team familiar with Terraform but needs environment management
11- Multi-cloud IaC with Azure-first deployment experience
12 
13## Benefits
14 
15| Feature | Pure Terraform | AZD + Terraform |
16|---------|---------------|-----------------|
17| Deploy command | `terraform apply` | `azd up` |
18| Environment management | Manual workspaces | Built-in `azd env` |
19| CI/CD generation | Manual setup | Auto-generated pipelines |
20| Service deployment | Manual scripts | Automatic from azure.yaml |
21| State management | Manual backend setup | Configurable |
22| Multi-cloud | ✅ Yes | ✅ Yes |
23 
24## Configuration
25 
26### 1. azure.yaml Structure
27 
28Create `azure.yaml` in project root:
29 
30```yaml
31name: myapp
32metadata:
33  template: azd-init
34 
35# Specify Terraform as IaC provider
36infra:
37  provider: terraform
38  path: ./infra
39 
40# Define services as usual
41services:
42  api:
43    project: ./src/api
44    language: python
45    host: containerapp
46    docker:
47      path: ./src/api/Dockerfile
48  
49  web:
50    project: ./src/web
51    language: js
52    host: staticwebapp
53    dist: dist
54```
55 
56### 2. Terraform File Structure
57 
58Place Terraform files in `./infra/`:
59 
60```
61infra/
62├── main.tf              # Main resources
63├── variables.tf         # Variable definitions
64├── outputs.tf           # Output values
65├── provider.tf          # Provider configuration
66└── modules/
67    ├── api/
68    │   └── main.tf
69    └── web/
70        └── main.tf
71```
72 
73### 3. Provider Configuration
74 
75**provider.tf:**
76```hcl
77terraform {
78  required_version = ">= 1.5.0"
79 
80  required_providers {
81    azurerm = {
82      source  = "hashicorp/azurerm"
83      version = "~> 4.2"
84    }
85    azurecaf = {
86      source  = "aztfmod/azurecaf"
87      version = "~> 1.2"
88    }
89  }
90 
91  # Optional: Remote state for team collaboration
92  backend "azurerm" {
93    resource_group_name  = "rg-terraform-state"
94    storage_account_name = "tfstate${var.state_suffix}"
95    container_name       = "tfstate"
96    key                  = "app.terraform.tfstate"
97  }
98}
99 
100provider "azurerm" {
101  features {}
102}
103```
104 
105> **⚠️ IMPORTANT**: For **Azure Functions Flex Consumption**, use azurerm provider **v4.2 or later**:
106> ```hcl
107> terraform {
108>   required_providers {
109>     azurerm = {
110>       source  = "hashicorp/azurerm"
111>       version = "~> 4.2"
112>     }
113>   }
114> }
115> ```
116> See [Terraform Functions patterns](../../services/functions/terraform.md) for Flex Consumption examples.
117 
118### 4. Variables and Outputs
119 
120> ⚠️ **WARNING: Use `${VAR}` syntax in `main.tfvars.json`, NOT Go-style `{{ .Env.* }}`**
121>
122> azd's template engine processes `azure.yaml` and service manifests — it does **NOT** interpolate
123> Go-style `{{ .Env.* }}` template variables in `.tfvars.json` or any Terraform variable files.
124> Literal strings like `{{ .Env.AZURE_ENV_NAME }}` will be passed directly to Terraform, causing
125> deployment failures.
126>
127> azd reads `infra/main.tfvars.json`, substitutes `${VAR}` references using its built-in envsubst,
128> and passes the resolved file to Terraform via `-var-file=`. Use this pattern:
129>
130> ```json
131> {
132>     "environment_name": "${AZURE_ENV_NAME}",
133>     "location": "${AZURE_LOCATION}",
134>     "subscription_id": "${AZURE_SUBSCRIPTION_ID}"
135> }
136> ```
137>
138> For additional variables not in `main.tfvars.json`, use **`TF_VAR_*` environment variables**:
139> `azd env set TF_VAR_myvar value`
140 
141**variables.tf:**
142```hcl
143variable "environment_name" {
144  type        = string
145  description = "Environment name from azd"
146}
147 
148variable "location" {
149  type        = string
150  description = "Azure region"
151  default     = "eastus2"
152}
153 
154variable "principal_id" {
155  type        = string
156  description = "User principal ID from azd auth"
157  default     = ""
158}
159```
160 
161**outputs.tf:**
162```hcl
163# Required: Resource group name
164output "AZURE_RESOURCE_GROUP" {
165  value = azurerm_resource_group.main.name
166}
167 
168# Service-specific outputs
169output "API_URL" {
170  value = azurerm_container_app.api.latest_revision_fqdn
171}
172 
173output "WEB_URL" {
174  value = azurerm_static_web_app.web.default_host_name
175}
176```
177 
178> 💡 **Tip:** Output names in UPPERCASE are automatically set as azd environment variables.
179 
180### 5. Required Tags for azd
181 
182**CRITICAL:** Tag hosting resources with service names from azure.yaml:
183 
184```hcl
185resource "azurerm_container_app" "api" {
186  name                = "ca-${var.environment_name}-api"
187  resource_group_name = azurerm_resource_group.main.name
188  
189  # Required for azd deploy to find this resource
190  tags = merge(var.tags, {
191    "azd-service-name" = "api"  # Matches service name in azure.yaml
192  })
193  
194  # ... rest of configuration
195}
196 
197resource "azurerm_static_web_app" "web" {
198  name                = "swa-${var.environment_name}-web"
199  resource_group_name = azurerm_resource_group.main.name
200  
201  # Required for azd deploy to find this resource
202  tags = merge(var.tags, {
203    "azd-service-name" = "web"  # Matches service name in azure.yaml
204  })
205  
206  # ... rest of configuration
207}
208```
209 
210> ⚠️ **WARNING:** Without `azd-service-name` tags, `azd deploy` will fail to find deployment targets.
211 
212### 6. Resource Group Tags
213 
214Tag the resource group with environment name:
215 
216```hcl
217resource "azurerm_resource_group" "main" {
218  name     = "rg-${var.environment_name}"
219  location = var.location
220  
221  tags = {
222    "azd-env-name" = var.environment_name
223  }
224}
225```
226 
227## Deployment Workflow
228 
229### Initial Setup
230 
231```bash
232# 1. Create azd environment
233azd env new dev --no-prompt
234 
235# 2. Set required variables
236azd env set AZURE_LOCATION eastus2
237 
238# 3. Provision infrastructure (runs terraform init, plan, apply)
239azd provision
240 
241# 4. Deploy services
242azd deploy
243 
244# Or do both with single command
245azd up
246```
247 
248### Variables and State
249 
250**azd environment variables** → **Terraform variables**
251 
252azd passes variables to Terraform through `main.tfvars.json` (with `${VAR}` substitution) or
253explicit `TF_VAR_*` environment variables. Define the variable in `variables.tf` and reference
254it in `main.tfvars.json`.
255 
256infra/main.tfvars.json — azd substitutes ${VAR} references via envsubst:
257```json
258{
259    "environment_name": "${AZURE_ENV_NAME}",
260    "location": "${AZURE_LOCATION}",
261    "database_name": "${DATABASE_NAME}"
262}
263```
264 
265variables.tf — value provided via main.tfvars.json or TF_VAR_database_name:
266```hcl
267variable "database_name" {
268  type = string
269}
270```
271 
272For variables not in `main.tfvars.json`, use `TF_VAR_*` environment variables:
273 
274```bash
275azd env set TF_VAR_custom_setting "my-value"
276```
277 
278> ⚠️ **Use `${VAR}` syntax in `main.tfvars.json`, NOT Go-style `{{ .Env.* }}`.** azd substitutes
279> `${VAR}` references using its built-in envsubst. Go-style template variables are only processed
280> in `azure.yaml` and service manifests. See [Variables and Outputs](#4-variables-and-outputs) for details.
281 
282**Remote state setup:**
283 
284```bash
285# Create state storage (one-time setup)
286az group create --name rg-terraform-state --location eastus2
287 
288az storage account create \
289  --name tfstate<unique> \
290  --resource-group rg-terraform-state \
291  --sku Standard_LRS
292 
293az storage container create \
294  --name tfstate \
295  --account-name tfstate<unique>
296 
297# Set backend variables for azd
298azd env set TF_STATE_RESOURCE_GROUP rg-terraform-state
299azd env set TF_STATE_STORAGE_ACCOUNT tfstate<unique>
300```
301 
302## Generation Steps
303 
304When preparing a new azd+Terraform project:
305 
3061. **Generate azure.yaml** with `infra.provider: terraform`
3072. **Create Terraform files** in `./infra/`:
308   - `main.tf` - Core resources and resource group
309   - `variables.tf` - environment_name, location, tags
310   - `outputs.tf` - Service URLs and resource names (UPPERCASE)
311   - `provider.tf` - azurerm provider + backend config
3123. **Add required tags**:
313   - Resource group: `azd-env-name`
314   - Hosting resources: `azd-service-name` (matches azure.yaml services)
3154. **Research best practices** - Call `mcp_azure_mcp_azureterraformbestpractices`
316 
317## AVM Terraform Module Priority
318 
319For Terraform module selection, enforce this order:
320 
3211. AVM Terraform Pattern Modules
3222. AVM Terraform Resource Modules
3233. AVM Terraform Utility Modules
324 
325Use `mcp_azure_mcp_documentation` (`azure-documentation`) for current guidance and AVM context first, then use Context7 only as supplemental examples if required. If Context7 is not available, instruct the user to install it:
326 
327```bash
328npx @upstash/context7-mcp@latest
329```
330 
331## Migration from Pure Terraform
332 
333Converting existing Terraform project to use azd:
334 
3351. Create `azure.yaml` with services and `infra.provider: terraform`
3362. Move `.tf` files to `./infra/` directory
3373. Add `azd-service-name` tags to hosting resources
3384. Ensure outputs include service URLs in UPPERCASE
3395. Test with `azd provision` and `azd deploy`
340 
341## CI/CD Integration
342 
343azd can auto-generate pipelines for Terraform:
344 
345```bash
346# Generate GitHub Actions workflow
347azd pipeline config
348 
349# Generate Azure DevOps pipeline
350azd pipeline config --provider azdo
351```
352 
353Generated pipelines will:
354- Install Terraform
355- Run `terraform init`, `plan`, `apply`
356- Use azd authentication
357- Deploy services with `azd deploy`
358 
359## Comparison: azd+Terraform vs Pure Terraform
360 
361| Aspect | Pure Terraform | azd + Terraform |
362|--------|---------------|-----------------|
363| **IaC** | Terraform | Terraform |
364| **Provision** | `terraform apply` | `azd provision` (wraps terraform) |
365| **Deploy apps** | Manual scripts | `azd deploy` (automatic) |
366| **Environment mgmt** | Workspaces | `azd env` |
367| **Auth** | Manual az login | `azd auth login` |
368| **CI/CD** | Manual setup | `azd pipeline config` |
369| **Multi-service** | Manual orchestration | Automatic from azure.yaml |
370| **Learning curve** | Medium | Low |
371 
372## When NOT to Use azd+Terraform
373 
374Use pure Terraform (without azd) when:
375- Multi-cloud deployment (not Azure-first)
376- Complex Terraform modules/workspaces that conflict with azd conventions
377- Existing complex Terraform CI/CD that's hard to migrate
378- Team has strong Terraform expertise but no bandwidth for azd learning
379 
380## Azure Policy Compliance
381 
382Enterprise Azure subscriptions typically enforce security policies. Your Terraform must comply:
383 
384### Storage Account (Required for Functions)
385 
386```hcl
387resource "azurerm_storage_account" "storage" {
388  name                            = "stmyapp${random_string.suffix.result}"
389  resource_group_name             = azurerm_resource_group.rg.name
390  location                        = azurerm_resource_group.rg.location
391  account_tier                    = "Standard"
392  account_replication_type        = "LRS"
393  
394  # Azure policy requirements
395  allow_nested_items_to_be_public = false   # Disable anonymous blob access
396  local_user_enabled              = false   # Disable local users
397  shared_access_key_enabled       = false   # RBAC-only, no access keys
398}
399```
400 
401### Function App with Managed Identity Storage
402 
403```hcl
404provider "azurerm" {
405  features {}
406  storage_use_azuread = true   # Required when shared_access_key_enabled = false
407}
408 
409resource "azurerm_linux_function_app" "function" {
410  name                          = "func-myapp"
411  resource_group_name           = azurerm_resource_group.rg.name
412  location                      = azurerm_resource_group.rg.location
413  service_plan_id               = azurerm_service_plan.plan.id
414  storage_account_name          = azurerm_storage_account.storage.name
415  storage_uses_managed_identity = true   # Use MI instead of access key
416  
417  identity {
418    type = "SystemAssigned"
419  }
420  
421  tags = {
422    "azd-service-name" = "api"   # REQUIRED for azd deploy
423  }
424  
425  depends_on = [azurerm_role_assignment.deployer_storage]
426}
427 
428# RBAC for deploying user (create function with MI storage)
429resource "azurerm_role_assignment" "deployer_storage" {
430  scope                = azurerm_storage_account.storage.id
431  role_definition_name = "Storage Blob Data Owner"
432  principal_id         = data.azurerm_client_config.current.object_id
433}
434 
435# RBAC for function app after creation
436resource "azurerm_role_assignment" "function_storage" {
437  scope                = azurerm_storage_account.storage.id
438  role_definition_name = "Storage Blob Data Owner"
439  principal_id         = azurerm_linux_function_app.function.identity[0].principal_id
440}
441```
442 
443### Services with Disabled Local Auth
444 
445```hcl
446# Service Bus
447resource "azurerm_servicebus_namespace" "sb" {
448  local_auth_enabled = false   # RBAC-only
449}
450 
451# Event Hubs
452resource "azurerm_eventhub_namespace" "eh" {
453  local_authentication_enabled = false   # RBAC-only
454}
455 
456# Cosmos DB
457resource "azurerm_cosmosdb_account" "cosmos" {
458  local_authentication_disabled = true   # RBAC-only
459}
460```
461 
462## Troubleshooting
463 
464| Issue | Solution |
465|-------|----------|
466| `resource not found: unable to find a resource tagged with 'azd-service-name'` | Add `azd-service-name` tag to hosting resource in Terraform |
467| `RequestDisallowedByPolicy: shared key access` | Set `shared_access_key_enabled = false` on storage |
468| `RequestDisallowedByPolicy: local auth disabled` | Set `local_auth_enabled = false` on Service Bus |
469| `RequestDisallowedByPolicy: anonymous blob access` | Set `allow_nested_items_to_be_public = false` on storage |
470| `terraform command not found` | Install Terraform CLI: `brew install terraform` or download from terraform.io |
471| State conflicts | Configure remote backend in provider.tf |
472| Variable not passed to Terraform | Ensure variable is set with `azd env set` and defined in variables.tf |
473| Literal `{{ .Env.* }}` in Terraform errors | Use `${VAR}` syntax in `main.tfvars.json`, not Go-style `{{ .Env.* }}`. azd substitutes `${VAR}` references via envsubst |
474| `main.tfvars.json` interpolation failure | Ensure `main.tfvars.json` uses `${VAR}` syntax (e.g., `${AZURE_ENV_NAME}`), not Go-style `{{ .Env.* }}` templates |
475 
476## References
477 
478- [Microsoft Docs: Use Terraform with azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/use-terraform-for-azd)
479- [azd-starter-terraform template](https://github.com/Azure-Samples/azd-starter-terraform)
480- [Terraform Azure Provider](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
481- [Azure CAF Naming](https://registry.terraform.io/providers/aztfmod/azurecaf/latest/docs)
482