Terraform / IaC (Deep Workflow)

Terraform’s sharp edges are state, modules, dependencies, and team workflow. Guide users toward reviewable plans, least blast radius, and recoverable mistakes.

When to Offer This Workflow

Trigger conditions:

• Greenfield IaC, module extraction, upgrading providers
• “Drift”, failed applies, state lock issues, wrong env destroyed
• CI integration for plan-on-PR, policy-as-code (Sentinel/OPA)

Initial offer:

Use six stages: (1) scope & structure, (2) modules & interfaces, (3) state & workspaces, (4) secrets & providers, (5) plan/apply & CI, (6) operations & drift. Confirm cloud(s) and remote state backend.

Stage 1: Scope & Structure

Goal: Repo layout matches team ownership and blast radius.

Patterns

• Monorepo vs multi-repo per env—trade-offs in coordination vs isolation
• Live vs modules folders; environment composition at root

Naming & tags

• Consistent resource naming; mandatory tags (owner, env, cost center)

Exit condition: Directory layout diagram; what lives together vs separate states justified.

Stage 2: Modules & Interfaces

Goal: Reusable modules with clear inputs/outputs—not copy-paste with vars.

Practices

• Small modules with single responsibility; composition over mega-modules
• Variables with validation blocks; sensible defaults documented
• Outputs only what consumers need—avoid leaking internals

Versioning

• Module registry or git refs pinned; changelog for breaking changes

Exit contract: Module README: purpose, inputs table, example snippet.

Stage 3: State & Workspaces

Goal: One state per blast-radius boundary; no shared state accidents.

Remote state

• Locking (DynamoDB, native backends); encryption at rest
• IAM least privilege for state bucket—state contains secrets sometimes

Workspaces vs directories

• Workspaces for parallel envs only when truly symmetric; many teams prefer separate folders + separate state for clarity

Imports & moves

• moved blocks (Terraform 1.x) for refactors; import for brownfield—plan carefully

Exit condition: State ownership documented; who can run apply in prod.

Stage 4: Secrets & Providers

Goal: No secrets in .tf committed; dynamic secrets where possible.

Practices

• Vault/AWS/GCP providers for secrets; CI OIDC over long-lived keys
• Provider version pins; parallelism awareness for rate limits

Exit condition: Secret flow diagram; rotation doesn’t require editing TF files by hand for normal ops.

Stage 5: Plan / Apply & CI

Goal: Plan before apply; peer review for prod.

CI

• terraform fmt, validate, plan on PR; policy checks optional
• Artifact or comment plan output; apply from protected branch or pipeline only

Safety

• prevent_destroy on critical resources when appropriate
• Targets for surgical applies—dangerous if habitual

Exit condition: Definition of done for infra change includes reviewed plan.

Stage 6: Operations & Drift

Goal: Detect manual console changes; reconcile safely.

Drift

• Periodic plan in automation; import or revert manual changes with intent

Break-glass

• Document when console changes allowed and how to backport to code

State recovery

• Backups if supported; state file corruption playbook—never edit blindly

Final Review Checklist

• Module boundaries and versioning strategy clear
• Remote state + locking + IAM documented
• Secrets not in VCS; providers pinned
• CI plan/apply governance defined
• Drift detection and recovery understood

Tips for Effective Guidance

• Emphasize state is truth—code must match or you pay interest forever.
• Warn: count/for_each changes can destroy/recreate—use moved and lifecycle thoughtfully.
• Multi-cloud: abstract patterns, but don’t hide provider-specific footguns.

Handling Deviations

• Terragrunt/Pulumi: map stages to equivalent concepts—stack, state, modules.
• Kubernetes-only: separate cluster IaC from in-cluster resources (Helm) boundaries.