| name | iac-common |
| description | **UTILITY SKILL** — Shared IaC deploy patterns for Bicep + Terraform agents: deployment strategies, circuit breaker, known deploy issues. WHEN: "phased deployment", "circuit breaker", "deploy strategy", "deploy issue", "shared IaC pattern". DO NOT USE FOR: preflight (azure-validate), code generation (azure-bicep-patterns / terraform-patterns). |
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:
- Preflight — run
azure-validate (auth, governance, plan, what-if review)
- Set environment —
azd env set AZURE_SUBSCRIPTION_ID/RESOURCE_GROUP/LOCATION + verify via azd env get-values
- Preview —
azd provision --preview (Bicep) or terraform plan (Terraform); user reviews destructive operations
- Approve gate — user explicitly approves the preview before any apply
- Apply —
azd provision / azd up (Bicep) or terraform apply (Terraform); for high-risk projects, deploy in phases (Foundation → Security → Data → Compute → Edge)
- Circuit-break on failure — stop on policy/governance/budget violations; surface diagnostics to user
- 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
| Reference | Location |
|---|
| Deployment strategies | references/deployment-strategies.md |
azd vs deploy.ps1 guide | references/azd-vs-deploy-guide.md |
| AVM module index | references/avm-module-index.md (canonical CSV + JSON list of AVM modules in .github/data/) |
| AVM version freeze gate | references/avm-version-freeze-gate.md (Phase 4.4 gate before plan_status=APPROVED) |
| Codegen shared workflow | references/codegen-shared-workflow.md (Phase 2 output cadence loaded by 06b/06t CodeGen agents) |
| Codegen file-order | references/codegen-file-order.md (per-tool file emission order loaded by 06b/06t CodeGen agents) |
| Codegen DO / DON'T | references/codegen-do-dont.md (shared DO/DON'T bullets between 06b + 06t; tool-specific bullets stay in each agent body) |
| Preflight policy checks | references/preflight-policy-checks.md (deploy-agent jq snippets, skip-validation shortcut, L3 precheck routing matrix, deprecation scan regex) |
| Azure Resource Graph primer | references/azure-resource-graph-primer.md (canonical shared head used by azure-compliance / azure-cost-optimization / azure-diagnostics resource-graph references) |
| Preflight validation | azure-validate/references/infraops-preflight.md |
| CLI auth validation procedure | azure-defaults/references/azure-cli-auth-validation.md |
| Policy effect decision tree | azure-defaults/references/policy-effect-decision-tree.md |
| IaC policy compliance | .github/instructions/iac-bicep-best-practices.instructions.md / .github/instructions/iac-terraform-best-practices.instructions.md |
| Bootstrap backend templates | terraform-patterns/references/bootstrap-backend-template.md |
| Deploy script templates | terraform-patterns/references/deploy-script-template.md |
| Circuit breaker | references/circuit-breaker.md |
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):
| Option | When to choose |
|---|
proceed-with-substitute | A safe substitute exists (alternate SKU, alternate AVM module, alternate parameter set). |
change-region | The failure is region-scoped (capacity, regional service gap, regional pricing spike). |
abort | None of the above is safe — return control to the user. |
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.
