Apex Iac Common

---
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.