---

name: writing-bicep-templates description: Provides Bicep coding standards for Azure infrastructure in this repository. Use when writing or modifying Bicep files, configuring Container Apps, setting up RBAC, or working with Azure resources.

Bicep Coding Standards

Goal: Create consistent, secure Azure infrastructure

Naming Convention

Use resourceToken from uniqueString():

Copyvar token = toLower(uniqueString(subscription().id, environmentName, location))
name: '${abbrs.appContainerApps}web-${token}'  // ca-web-abc123

Exception: ACR requires alphanumeric only: cr${resourceToken}

Parameters

Always add @description() and use @allowed() for constrained values:

Copy@description('Environment (dev, prod)')
param environmentName string

@description('Azure region')
@allowed(['eastus2', 'westus2'])
param location string = 'eastus2'

Outputs

Expose key identifiers for azd and other modules:

Copyoutput containerAppName string = containerApp.name
output webEndpoint string = 'https://${containerApp.properties.configuration.ingress.fqdn}'
output identityPrincipalId string = containerApp.identity.principalId

Managed Identity

Always use system-assigned identity + output principalId:

Copyidentity: { type: 'SystemAssigned' }
output identityPrincipalId string = resource.identity.principalId

RBAC Assignments

Use guid() for names + specify principalType:

Copyresource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(resource.id, principalId, roleId)
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleId)
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}

Container Apps

Key settings: System identity + scale-to-zero + HTTPS only:

Copyresource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  identity: { type: 'SystemAssigned' }
  properties: {
    configuration: {
      ingress: {
        external: true
        targetPort: 8080
        allowInsecure: false
      }
    }
    template: {
      scale: { minReplicas: 0, maxReplicas: 3 }
    }
  }
}

Secrets Pattern

Use Container App secrets + listCredentials():

Copysecrets: [{
  name: 'registry-password'
  value: containerRegistry.listCredentials().passwords[0].value
}]

Validation

Copyaz bicep build --file main.bicep
az deployment group what-if --template-file main.bicep

---

Project-Specific: Module Hierarchy

Copymain.bicep (subscription scope)
├─ Resource group
├─ main-infrastructure.bicep (ACR + Container Apps Env + Log Analytics)
├─ main-app.bicep (Container App)
└─ RBAC (Cognitive Services User role)

Project-Specific: Container App Configuration

Copyresource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  identity: { type: 'SystemAssigned' }
  properties: {
    managedEnvironmentId: containerAppsEnvironmentId
    configuration: {
      ingress: {
        external: true
        targetPort: 8080
        allowInsecure: false
      }
      secrets: [{
        name: 'registry-password'
        value: containerRegistry.listCredentials().passwords[0].value
      }]
    }
    template: {
      containers: [{
        name: 'web'
        image: containerImage
        env: [
          { name: 'ENTRA_SPA_CLIENT_ID', value: entraSpaClientId }
          { name: 'AI_AGENT_ENDPOINT', value: aiAgentEndpoint }
          { name: 'AI_AGENT_ID', value: aiAgentId }
        ]
        resources: { cpu: json('0.5'), memory: '1Gi' }
      }]
      scale: { minReplicas: 0, maxReplicas: 3 }
    }
  }
}

output fqdn string = containerApp.properties.configuration.ingress.fqdn
output identityPrincipalId string = containerApp.identity.principalId

Related Skills

• deploying-to-azure - Deployment commands and hook workflow
• writing-csharp-code - Backend configuration for Container Apps
• troubleshooting-authentication - RBAC and managed identity debugging