1# Container Apps Terraform Patterns
2 
3> **⚠️ Container Registry Naming:** ACR names must be alphanumeric only (5-50 characters). Use Terraform's `replace()` function when constructing the value passed to `azurecaf_name`, or otherwise strip hyphens manually.
4 
5> **⚠️ Two-Phase Deployment (Mandatory):** To avoid the chicken-and-egg problem where Terraform tries to create a Container App referencing an ACR image that doesn't exist yet:
6> - **Phase 1 (`terraform apply`):** Deploy ACR and Container App with a **public placeholder image** and **no `registry` block**.
7> - **Phase 2 (post-apply CLI):** Build/push the app image to ACR, configure the registry/identity link, then update the Container App image.
8>
9> This mirrors the [Bicep two-phase pattern](bicep.md). Without it, `terraform apply` fails with `ContainerAppOperationError` because the image doesn't exist in ACR yet.
10 
11> **⚠️ ACR Authentication — Managed Identity Only:** Do **not** use `admin_enabled = true` on `azurerm_container_registry` or add a `registry` block with `username`/`password_secret_name` to the Container App. Admin credentials are a security risk and leak secrets into Terraform state. Always use **managed identity** with an `AcrPull` role assignment, and configure the registry link via `az containerapp registry set --identity system` in Phase 2.
12 
13## Phase 1: Container App Resource (No Registry Block)
14 
15```hcl
16# Placeholder image allows provisioning before the app image exists in ACR.
17# No registry block in Terraform during Phase 1 — the registry/identity link is
18# configured via CLI after provisioning (see Phase 2 below).
19# Do NOT add a registry block with username/password_secret_name — use managed identity.
20resource "azurerm_container_app" "api" {
21  name                         = azurecaf_name.container_app.result
22  container_app_environment_id = azurerm_container_app_environment.env.id
23  resource_group_name          = azurerm_resource_group.rg.name
24  revision_mode                = "Single"
25 
26  identity {
27    type = "SystemAssigned"
28  }
29 
30  tags = merge(var.tags, {
31    "azd-service-name" = "api"
32  })
33 
34  template {
35    min_replicas = 1
36    max_replicas = 3
37 
38    container {
39      name   = "api"
40      image  = "mcr.microsoft.com/azuredocs/containerapps-helloworld:latest"
41      cpu    = 0.25
42      memory = "0.5Gi"
43    }
44  }
45 
46  ingress {
47    external_enabled = true
48    target_port      = 8080
49 
50    traffic_weight {
51      latest_revision = true
52      percentage      = 100
53    }
54  }
55 
56  # Phase 2 updates the image and configures the registry/identity link via CLI.
57  # Prevent Terraform from reverting those changes on subsequent applies.
58  # Do NOT add a registry block here — use `az containerapp registry set --identity system`.
59  lifecycle {
60    ignore_changes = [
61      template[0].container[0].image,
62      registry,
63    ]
64  }
65}
66```
67 
68## AcrPull Role Assignment
69 
70Deploy the `AcrPull` role assignment as a **separate resource** that depends on the Container App (to read its system-assigned identity principal ID). Neither the ACR nor the Container App depends on this resource, so there is no circular dependency.
71 
72```hcl
73resource "azurerm_role_assignment" "api_acr_pull" {
74  scope                = azurerm_container_registry.acr.id
75  role_definition_name = "AcrPull"
76  principal_id         = azurerm_container_app.api.identity[0].principal_id
77  principal_type       = "ServicePrincipal"
78}
79```
80 
81> 💡 **Tip:** Always set `principal_type = "ServicePrincipal"` for managed identities. This skips the Graph API lookup and speeds up role assignment propagation.
82 
83## Phase 2: Post-Apply Deployment (CLI)
84 
85After `terraform apply` succeeds, run these commands to build the real image and switch the Container App to it:
86 
87```bash
88ACR_NAME=$(terraform output -raw acr_name)
89ACR_SERVER=$(terraform output -raw acr_login_server)
90APP_NAME=$(terraform output -raw container_app_name)
91RG_NAME=$(terraform output -raw resource_group_name)
92 
93# 1. Build and push the application image to ACR
94az acr build --registry $ACR_NAME --image myapp:latest ./src/api
95 
96# 2. Configure the registry/identity link (managed identity, no passwords)
97az containerapp registry set \
98  --name $APP_NAME \
99  --resource-group $RG_NAME \
100  --server $ACR_SERVER \
101  --identity system
102 
103# 3. Update the Container App to use the real image
104az containerapp update \
105  --name $APP_NAME \
106  --resource-group $RG_NAME \
107  --image $ACR_SERVER/myapp:latest
108```
109 
110**PowerShell:**
111```powershell
112$AcrName = terraform output -raw acr_name
113$AcrServer = terraform output -raw acr_login_server
114$AppName = terraform output -raw container_app_name
115$RgName = terraform output -raw resource_group_name
116 
117# 1. Build and push the application image to ACR
118az acr build --registry $AcrName --image myapp:latest ./src/api
119 
120# 2. Configure the registry/identity link (managed identity, no passwords)
121az containerapp registry set `
122  --name $AppName `
123  --resource-group $RgName `
124  --server $AcrServer `
125  --identity system
126 
127# 3. Update the Container App to use the real image
128az containerapp update `
129  --name $AppName `
130  --resource-group $RgName `
131  --image "$AcrServer/myapp:latest"
132```
133 
134> ⚠️ **Warning:** Step 2 requires the `AcrPull` role assignment to have propagated (1–5 minutes after `terraform apply`). If the image pull fails, wait and retry. See the **azure-deploy** skill's `references/pre-deploy-checklist.md` (Container Apps + ACR pre-deploy RBAC health check).
135 
136## Terraform Outputs
137 
138Export the values needed by Phase 2:
139 
140```hcl
141output "acr_name" {
142  value = azurerm_container_registry.acr.name
143}
144 
145output "acr_login_server" {
146  value = azurerm_container_registry.acr.login_server
147}
148 
149output "container_app_name" {
150  value = azurerm_container_app.api.name
151}
152 
153output "resource_group_name" {
154  value = azurerm_resource_group.rg.name
155}
156 
157output "api_url" {
158  value = "https://${azurerm_container_app.api.ingress[0].fqdn}"
159}
160```
161 
162## Container Apps Environment
163 
164```hcl
165resource "azurerm_container_app_environment" "env" {
166  name                       = azurecaf_name.container_app_env.result
167  location                   = azurerm_resource_group.rg.location
168  resource_group_name        = azurerm_resource_group.rg.name
169  log_analytics_workspace_id = azurerm_log_analytics_workspace.logs.id
170}
171```
172