Azure App Onboard

Code Deployment — Container Apps

After IaC deployment creates the Container App with a placeholder image (mcr.microsoft.com/azuredocs/containerapps-helloworld:latest), deploy the actual application code. This is Phase 2 of the two-phase Container Apps deployment pattern.

⛔ --subscription {subscriptionId} on EVERY az command (from context.json.azure.subscriptionId). Without it, the CLI uses whatever subscription is currently active — which may have changed since the prepare phase. This applies to ALL commands below.

⛔ Phase 2 is NOT optional. If IaC deployed a Container App with a placeholder image, you MUST execute Phase 2 before health checks. Do NOT leave a placeholder image and tell the user to deploy code manually.

Determine the code deploy path:

Step 0 — Add ACR to IaC (if not already present)

Add container-registry.bicep module (ACR Basic, adminUserEnabled: false) + AcrPull role assignment for CA's managed identity (role GUID: 7f951dda-4ed3-4680-a7ca-43fe172d538d). Redeploy IaC, wait ~60s for AcrPull role propagation. Log as healing attempt.

⛔ Update prepare-plan.json (add ACR to services[]), scaffold-manifest.json.files[], and costEstimate.

Steps 1–4 — ACR Build + Image Update (IaC-compliant)

⛔ az acr build failures count toward the deploy-result.json.healingAttempts[] counter. After 3 failed builds (even with different root causes), pause and present a diagnosis to the user: "Web image build failed 3 times: [root causes]. Continue healing? (Yes / Cancel)." Each build fix attempt = 1 healing entry. Cross-reference deploy PHASE.md healing loop rule.

⛔ Windows: az acr build may fail with UnicodeEncodeError. Azure CLI log streaming crashes on non-ASCII characters (✓, ✗) using Windows charmap codec. Append --no-logs to the build command. Build success/failure is still reported via exit code.

Step 5 — Oryx Shortcut (no ACR needed, no Dockerfile)

az containerapp update --subscription {subscriptionId} -g {rg} -n {ca} --source . --set-env-vars NODE_ENV=production

⛔ az containerapp update --source is allowed for code deploy ONLY. This is different from az containerapp up --source (which is ⛔ BLOCKED because it creates resources imperatively). update --source updates an EXISTING Container App — no state drift.

Seed KV Secrets (between Phase 1 and Phase 2)

After Phase 1, seed real secret values into KV before Phase 2 activates secretRef:

az keyvault secret set --subscription {subscriptionId} --vault-name {kvName} --name {secret-name} --value $generatedValue

⛔ Use the SAME generated password passed to az deployment sub create. Shell variables don't persist between tool calls — reload from deploy-secrets.env (see deploy-safety.md § Deploy Checklist) or pass to BOTH commands in the same block.

After Code Deploy (all paths)

• Wait 30–60s for the new revision to become ready

• Proceed to Step 7 (Health-Check Endpoints)

• If health check returns placeholder content → image update didn't take effect. Check az containerapp revision list

⛔ az containerapp revision restart does NOT re-resolve KV secrets. Container Apps caches KV-backed secretRef values at revision creation time. To pick up updated KV secrets, create a NEW revision by redeploying Bicep (preferred) or az containerapp update --revision-suffix rev{timestamp}. Do NOT use revision restart for KV secret rotation — it only restarts the container with the same cached values.

⛔ KV secretRef AND ACR registries require managed identity + roles to exist first. Phase 1 of the two-phase deploy creates the Container App with a placeholder image, registries: [], and secrets: []. Both KV secretRef and ACR registries with identity: 'system' fail in Phase 1 because the CA's managed identity doesn't exist yet (no principalId → AcrPull/KV role assignment fails → "Operation expired"). After Phase 1 completes and RBAC propagates (~60s), Phase 2 redeploys with ACR registries + KV secretRef + real image + correct targetPort.

Config-File Apps (Go/Viper, Spring Boot, etc.)

Creating Azure-specific config (e.g., config-azure.yml) is fine for non-secret values.

⛔ NEVER bake secrets into config files COPY'd into Docker images.

Secret injection: Config uses placeholders → az containerapp secret set → az containerapp update --set-env-vars KEY=secretref:name → framework env var override.

Go/Viper: AutomaticEnv() maps POSTGRES_PASSWORD → postgres_password (underscores), NOT postgres.password. Without SetEnvKeyReplacer(strings.NewReplacer(".", "_")), env vars can't override nested keys.

BuildKit Dockerfile Handling

ACR's az acr build uses the classic Docker builder — it does NOT support BuildKit. When buildRequirements.hasBuildKitSyntax == true: build using the ACR-compatible copy instead: az acr build -f Dockerfile.azure .. The user's original Dockerfile stays untouched. If Dockerfile.azure doesn't exist yet, create it by stripping BuildKit syntax from the original Dockerfile per dockerfile-generation.md § ACR Build Compatibility.

Parameter Pass-Through (Bicep Redeploy Safety)

⛔ On every redeploy, pass the SAME values you originally used — a full desired-state apply, not a patch, so an omitted param reverts to its default and a regenerated secret overwrites the live value. Two params bite:

• containerImage — omitting it reverts the Container App to the placeholder image.

• administratorLoginPassword (DB modules) — passing a new or placeholder value silently RESETS the database admin password, desyncing it from the Key Vault secret the app reads → runtime auth failures (Access denied for user).

$dbPassword = az keyvault secret show --subscription {subscriptionId} --vault-name {kvName} --name {db-secret} --query value -o tsv
az deployment sub create ... `
  --parameters containerImage='{acrLoginServer}/{appName}:latest' `
  --parameters administratorLoginPassword=$dbPassword `
  --query properties.provisioningState -o tsv

Database Post-Deploy Verification

⛔ You MUST read database-post-deploy.md for migration discovery, execution via Container Apps exec, error handling, and PostgreSQL-specific checks.