--- name: apex-iac-common user-invocable: false disable-model-invocation: false description: '**UTILITY SKILL** — Shared Bicep/Terraform workflow contracts: planning, codegen cadence, handoffs, deployment strategies and bounded recovery. WHEN: "shared IaC workflow", "phased deployment", "circuit breaker", "deploy strategy", "deploy issue", "shared IaC pattern". DO NOT USE FOR: language-specific modules (apex-azure-bicep-patterns / apex-terraform-patterns) or standalone preflight (apex-azure-validate).' --- # IaC Common Skill Shared planning, codegen and deployment contracts used by Bicep and Terraform agents and their explicitly authorized leaf workers. > **Preflight validation** (CLI auth, governance mapping, stop rules, known issues) > has moved to the **apex-azure-validate** skill. See `apex-azure-validate/references/infraops-preflight.md`. --- ## Rules - **Preflight first** — 07b/07t use the APEX branch of `apex-azure-validate` and the shared deploy readiness contract; generic applications use their prepared plan and recorded proof. Preflight never starts generic preparation for APEX. - **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`](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 `apex-azure-validate`); code generation (use `apex-azure-bicep-patterns` or `apex-terraform-patterns`) ## Steps Standard deploy flow used by `07b-Bicep Deploy` and `07t-Terraform Deploy`: 1. **Preflight** — use APEX-mode `apex-azure-validate` (auth, governance, handoff/readiness); return results and stop for validation-only 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`](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`](references/azure-resource-graph-primer.md) (canonical shared head used by `apex-azure-compliance` / `apex-azure-cost-optimization` / `apex-azure-diagnostics` resource-graph references) | | Preflight validation | `apex-azure-validate/references/infraops-preflight.md` | | CLI auth validation procedure | `apex-azure-defaults/references/azure-cli-auth-validation.md` | | Policy effect decision tree | `apex-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 | `apex-terraform-patterns/references/bootstrap-backend-template.md` | | Deploy script templates | `apex-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 Unless a stricter operation-specific cap applies, 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` | Propose a substitute for explicit approval and owning-agent reconciliation; never apply it automatically. | | `change-region` | Propose a region change for explicit approval; refresh affected policy, capacity, pricing and plan evidence. | | `abort` | None of the above is safe — return control to the user. | Neither choice bypasses a required step, security rule, unresolved blocker, frozen plan, SKU manifest, or review. Route revisions to the owning agent, regenerate affected evidence, rerun required validation/reviews and obtain final evidence-bound approval before retrying. No skip-step or unlimited reset option. Missing/empty reviewer output has the stricter one identical-input retry cap. Use the same options across these loops. 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.