iac-common

IaC Common Skill

Shared deployment patterns used by both Bicep and Terraform deploy agents (07b, 07t) and review subagents.

Preflight validation (CLI auth, governance mapping, stop rules, known issues) has moved to the azure-validate skill. See azure-validate/references/infraops-preflight.md.

Rules

• Preflight first — always run azure-validate before invoking any deploy strategy in this skill
• azd by default — use azd provision / azd up for all new projects. The legacy deploy.ps1 path is deprecated; full decision matrix in references/azd-vs-deploy-guide.md.
• Phased deployment for high-risk changes — split into Foundation → Security → Data → Compute → Edge with user approval at each gate
• Circuit breaker — stop deployment automatically when policy violations, governance failures, or budget breaches are detected; surface to user before retrying
• Set environment values before --no-prompt — AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, AZURE_ENV_NAME, AZURE_LOCATION must all be present (azd env get-values)
• Use azd env new {project}-{env} to avoid environment-name collisions across projects
• Out of scope: preflight (use azure-validate); code generation (use azure-bicep-patterns or terraform-patterns)

Steps

Standard deploy flow used by 07b-Bicep Deploy and 07t-Terraform Deploy:

1. Preflight — run azure-validate (auth, governance, plan, what-if review)
2. Set environment — azd env set AZURE_SUBSCRIPTION_ID/RESOURCE_GROUP/LOCATION + verify via azd env get-values
3. Preview — azd provision --preview (Bicep) or terraform plan (Terraform); user reviews destructive operations
4. Approve gate — user explicitly approves the preview before any apply
5. Apply — azd provision / azd up (Bicep) or terraform apply (Terraform); for high-risk projects, deploy in phases (Foundation → Security → Data → Compute → Edge)
6. Circuit-break on failure — stop on policy/governance/budget violations; surface diagnostics to user
7. Hand off to 08-As-Built for documentation

Deployment Strategies

Default: use azd for every project. Each project is a self-contained azd project (azure.yaml + .azure/ inside infra/{iac}/{project}/). Phased deployment is now done via azd hooks (preprovision / postprovision).

Full procedure (azd up / azd provision --preview, environment preflight checklist for --no-prompt deploys, deprecated phased table, single-deployment fallback, and the legacy deploy.ps1 decision matrix) lives in references/deployment-strategies.md.

Single-deployment exception: for projects with < 5 resources in dev/test, a single azd deployment is acceptable. All deploys still require explicit user approval.

Reference Index

Circuit Breaker

Deploy agents MUST read references/circuit-breaker.md before starting any deployment. It defines:

• Failure taxonomy: 6 categories (build, validation, deployment, empty, timeout, auth)
• Anomaly patterns: detection thresholds for repetitive failures
• Stopping rule: 3 consecutive same-type failures → halt + escalate
• Escalation protocol: write to session state, notify user, wait for guidance

Bounded retry

Any retry loop in 04g-governance, 07b-bicep-deploy, 07t-terraform-deploy, or the deploy-time subagents (bicep-whatif, terraform-plan, policy-precheck, cost-estimate) is capped at 3 attempts. On the third failure the agent escalates to the user with these three fixed options (and no others):

Use the same options across all four loops so the user's mental model is consistent. The challenger-review-subagent checklist enforces "retry loop bounded ≤3 with named escalation options"; unbounded loops are flagged as HIGH.

Implementation hooks:

• Loop counter lives in the agent body, not in shared infrastructure (counts reset between human approvals).
• Record the substitute/region change as an apex-recall decide entry before retrying so the next session can trace the path.
• Combine with the circuit breaker: a 3-failure retry that escalates with abort ALSO trips the circuit breaker's escalation protocol.