1# Container Apps Bicep Patterns
2 
3> **⚠️ Container Registry Naming:** If using Azure Container Registry, names must be alphanumeric only (5-50 characters). Use `replace()` to remove hyphens: `replace('cr${environmentName}${resourceSuffix}', '-', '')`
4 
5> **⚠️ Two-Phase Deployment (Mandatory):** To avoid a circular dependency when scoping the AcrPull role assignment to a Bicep module, use the two-phase pattern below:
6> - **Phase 1:** Deploy ACR and Container App with a public placeholder image and **no** `registries` block.
7> - **Phase 2:** Deploy the AcrPull role assignment as a **separate module** using outputs from Phase 1.
8>
9> The Bicep template does **not** need a `registries` block. `azd deploy` handles the registry/identity link by calling `az containerapp registry set --server <acr-server> --identity system` via the Azure API before updating the container image. If you are not using AZD, you must run this command manually before switching the image to an ACR-hosted image; otherwise the app will hit image pull failures.
10 
11## Phase 1: Container App Module (No Registry Link)
12 
13```bicep
14// Placeholder image allows provisioning before app image exists in ACR.
15// No registries block in Bicep — azd deploy configures the registry/identity link
16// (az containerapp registry set --identity system) and updates the image via the Azure API.
17// If not using AZD, run that command manually before switching to an ACR-hosted image.
18param containerImageName string = 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'
19 
20resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
21  name: appName
22  location: location
23  identity: {
24    type: 'SystemAssigned'
25  }
26  properties: {
27    environmentId: containerAppsEnvironment.id
28    configuration: {
29      ingress: {
30        external: true
31        targetPort: 8080
32        transport: 'auto'
33      }
34      // No registries block in Bicep. azd deploy sets the registry/identity link via
35      // 'az containerapp registry set --identity system' before pushing the real image.
36      // Without this step (or its manual equivalent), the app will fail to pull from ACR.
37    }
38    template: {
39      containers: [
40        {
41          name: serviceName
42          image: containerImageName
43          resources: {
44            cpu: json('0.5')
45            memory: '1Gi'
46          }
47        }
48      ]
49    }
50  }
51}
52 
53output systemAssignedMIPrincipalId string = containerApp.identity.principalId
54```
55 
56## Phase 2: AcrPull Role Assignment Module (acr-pull-role.bicep)
57 
58Place this in a **separate module file** so neither the ACR module nor the Container App module depends on it, eliminating the circular dependency.
59 
60```bicep
61// acr-pull-role.bicep
62param acrName string
63param principalId string
64 
65resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
66  name: acrName
67}
68 
69resource acrPullRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
70  name: guid(containerRegistry.id, principalId, 'acrpull')
71  scope: containerRegistry
72  properties: {
73    roleDefinitionId: subscriptionResourceId(
74      'Microsoft.Authorization/roleDefinitions',
75      '7f951dda-4ed3-4680-a7ca-43fe172d538d'
76    )
77    principalId: principalId
78    principalType: 'ServicePrincipal'
79  }
80}
81```
82 
83> 💡 **Tip:** Always set `principalType: 'ServicePrincipal'` for managed identities. This avoids a Graph API lookup and speeds up role assignment propagation.
84 
85## Wiring Phase 1 and Phase 2 in main.bicep
86 
87```bicep
88// Phase 1: ACR and Container App — neither module depends on the role assignment
89module containerRegistry './modules/container-registry.bicep' = {
90  name: 'containerRegistry'
91  scope: rg
92  params: { /* ... */ }
93}
94 
95module api './modules/container-app.bicep' = {
96  name: 'api'
97  scope: rg
98  params: {
99    containerImageName: 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'
100    // No registries param in Bicep — azd deploy configures the registry/identity link
101    // and updates the image via the Azure API after provisioning.
102    /* ... */
103  }
104}
105 
106// Phase 2: Role assignment depends on outputs of both Phase 1 modules,
107// but neither Phase 1 module depends on this — no circular dependency.
108module acrPullRole './modules/acr-pull-role.bicep' = {
109  name: 'acrPullRole'
110  scope: rg
111  params: {
112    acrName: containerRegistry.outputs.name
113    principalId: api.outputs.systemAssignedMIPrincipalId
114  }
115}
116```
117 
118## Container Apps Environment
119 
120```bicep
121resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2023-05-01' = {
122  name: '${resourcePrefix}-env'
123  location: location
124  properties: {
125    appLogsConfiguration: {
126      destination: 'log-analytics'
127      logAnalyticsConfiguration: {
128        customerId: logAnalyticsWorkspace.properties.customerId
129        sharedKey: logAnalyticsWorkspace.listKeys().primarySharedKey
130      }
131    }
132  }
133}
134```
135