Bicep Patterns

⛔ Always use targetScope = 'subscription'. Subscription-scope Bicep creates the resource group in IaC with all 5 AppOnboard tags (including created-at). Resource-group scope requires az group create via CLI, which consistently misses created-at because CLI-created resource groups don’t receive IaC-managed tags. There are zero benefits to resource-group scope for AppOnboard.

Each service gets its own module. main.bicep orchestrates resource group creation + module calls.

main.bicep Skeleton

main.parameters.json

⛔ ARM JSON only. Do NOT use .bicepparam syntax (using, param, readEnvironmentVariable()). AppOnboard deploys via az deployment sub create (subscription-scope default) — not azd — and .bicepparam requires azd or newer tooling. If the user lacks subscription-level permissions, the deploy phase falls back to az deployment group create automatically.

Naming Convention (Bicep)

The prepare phase generates a logical resource prefix in prepare-plan.json.naming.resourcePrefix (e.g., myapp-dev). Scaffold MUST add a globally unique suffix using Bicep’s uniqueString() function to prevent cross-deployment name collisions on globally unique Azure resources (App Service, Key Vault, Storage Account, ACR).

⛔ Do NOT use uniqueString() for secrets — it is deterministic and predictable. See bicep-patterns-security.md § Secrets for correct secret patterns.

If prepare-plan.json.naming.resources[] provides pre-computed names with suffixes, prefer those — but ALWAYS ensure globally unique resources include a uniqueString() or equivalent hash in main.bicep as a safety net.

Log Analytics Module Output

⛔ Output the resource ID (.id), NOT .properties.customerId. Container Apps Environment requires workspaceResourceId (the full ARM resource ID). .properties.customerId is the GUID used for queries — passing it as workspaceResourceId causes an ARM deploy failure (BadRequest). Separate the two outputs:

bicepCopy

output workspaceId string = logAnalyticsWorkspace.id                          // ARM resource ID — for CAE, App Insights
output workspaceCustomerId string = logAnalyticsWorkspace.properties.customerId // GUID — for Log Analytics queries only

Compute-Target Patterns

Read the file(s) matching the service mapping — load only what’s needed:

• App Service / Functions: bicep-app-service.md — module template, SCM/FTP auth, native module deploy strategy
• Container Apps: bicep-container-apps.md — two-phase ACR wiring, ingress, secretRef, image parameter, multi-container DNS
• Static Web Apps: bicep-swa.md — module template, detached deploy rule

Load multiple only if the plan includes multiple compute targets.

⛔ F1/D1 SKU: do NOT generate a Dockerfile. If prepare-plan.json specifies F1 or D1 (free/shared tier), use the platform’s built-in runtime stack (e.g., NODE|24-lts for Node.js, PYTHON|3.14 for Python). Dockerfiles are for B1+ or Container Apps only.

⛔ Native module deploy strategy. If prepare-plan.json.deployStrategy exists, read bicep-app-service.md § Native Module Deploy Strategy and apply the startup command + app settings. deployStrategy.startupCommand → appCommandLine, deployStrategy.requiredAppSettings → appSettings[]. When no deployStrategy exists, do NOT set appCommandLine.

Service Tagging

⛔ You MUST read iac-generation-rules.md § Session Tags. All resources MUST include the 5 AppOnboard session tags. Pass tags object from main.bicep into every module.

API Version Policy

Use the latest stable API version for each resource type. Never use preview APIs unless required for a feature with no GA alternative. Validate via bicep build — stale API versions produce warnings.

Key Vault Reference Syntax

Syntax differs by service — never mix. See bicep-container-apps.md for Container Apps secretRef and bicep-patterns-security.md for App Service @Microsoft.KeyVault(). For Terraform, see terraform-patterns.md.