Terraform Module Drafting with the Full Verification Chain

Tier: Core · Workflow area: Infrastructure as Code

The professional response is not to avoid AI IaC — it is to make the verification chain non-optional: validate → plan → policy scan → cost estimate → human review, every time, wired so skipping a link is impossible. This playbook is the anchor pattern for the whole track.

When to use

• •
  Drafting a new module or environment stack (VPC, EKS/AKS/GKE cluster, RDS + app tier).
• •
  Extending modules with new variables/resources where provider docs would take longer than review.
• •
  Learning an unfamiliar provider — with double verification skepticism.

Skip AI for terraform state surgery and provider version upgrades on live stateful infra unless you are following the dedicated playbooks (pb-10, pb-12).

Prerequisites

• •
  Terraform or OpenTofu; a sandbox account/subscription where plan (not apply) can run.
• •
  The chain tools: terraform validate, TFLint, Checkov (or tfsec/Trivy), Infracost — all free/OSS.
• •
  An AI coding assistant, ideally one that reads your repo for conventions.

The workflow

1. 1.

   Prompt with constraints, versions, and conventions — not just intent.

   Copy

   Write a Terraform module for an AWS RDS PostgreSQL instance.
   
   Constraints:
   - Terraform >= 1.7, AWS provider ~> 5.40. Use only attributes that exist
     in this provider version.
   - Multi-AZ toggle via variable, default true for prod workspaces.
   - Storage encrypted with a KMS key passed in as a variable (no default key).
   - No public accessibility, deletion protection on, backups 14 days.
   - Follow the variable/output naming style in ./modules/elasticache (attached).
   - Outputs: endpoint, port, security group id.
   Do not invent attributes. If unsure an attribute exists in provider 5.x,
   say so instead of guessing.
   

2. 2.

   Gate 1 — validate + lint. Catches nonexistent attributes and type errors in seconds:

   Copy

   terraform init -backend=false && terraform validate
   tflint --init && tflint
   

   Feed errors straight back to the assistant; this loop usually takes 2–3 rounds on unfamiliar providers.

3. 3.

   Gate 2 — plan against the sandbox. Validate proves syntax; only plan proves the provider accepts the semantics:

   Copy

   terraform plan -var-file=sandbox.tfvars -out=tfplan
   terraform show -json tfplan > tfplan.json
   

   Read the plan yourself. Count resources. Anything being created that you did not ask for (default security groups, log groups, random passwords in state) gets challenged.

4. 4.

   Gate 3 — policy scan. Checkov on the plan JSON catches the insecure defaults AI loves:

   Copy

   checkov -f tfplan.json --compact
   conftest test tfplan.json --policy policy/   # org policies from pb-07
   

5. 5.

   Gate 4 — cost estimate. AI-drafted modules routinely default to oversized instances and gp3 volumes with provisioned IOPS nobody asked for:

   Copy

   infracost breakdown --path . --format table
   

   Compare against your expectation before review, not after the first invoice.

6. 6.

   Gate 5 — human review with the chain outputs attached. The PR includes: plan summary, Checkov results, Infracost diff. The reviewer reviews intent and blast radius — the mechanical checks are already done. Wire gates 1–4 into CI so the chain runs on every IaC PR whether or not AI was involved.

Tool variants

• Claude Code / repo-aware agent: can run the whole chain itself and iterate until green — review its terminal use; it must never run apply. Consider an alias making terraform apply unavailable in the agent's environment.
• Copilot / inline completion: good for single resources and variable plumbing; the chain is unchanged, you just drive it manually.
• Pulumi/CDK users: same pattern — pulumi preview, cdk diff replace plan; Checkov supports both; unit tests partially replace validate.

Verification

The chain IS the verification; the pass bar explicitly:

• Validate:terraform validate + TFLint clean.
• Plan: sandbox plan succeeds; resource list matches intent exactly — no surprise creations; nothing destroyed/replaced unless intended.
• Policy: zero Checkov CRITICAL/HIGH (documented, justified skips only); org Conftest policies pass.
• Cost: Infracost monthly estimate within the budget you stated before drafting; any 2x surprise investigated.
• Human: a named reviewer approved the PR with the artifacts above attached.

Pitfalls

• Attribute hallucination survives validate sometimes. Valid-but-wrong values (a fake instance class, a wrong engine version string) pass validate and fail at plan or apply. This is why gate 2 is mandatory, not optional.
• Trusting AI-suggested provider versions. Assistants train on old docs; they mix provider 3.x and 5.x idioms. Pin versions yourself and state them in the prompt.
• Plausible module sources.source = "terraform-aws-modules/rds/aws" is real; subtle variants are not. Verify registry sources exist at the pinned version.
• The chain rots when it is optional. If engineers can merge IaC without the chain running, AI-drafted code will eventually ship unverified. CI enforcement is part of this playbook, not an extra.

Restricted-environment variant

Client account IDs, CIDR plans, and naming conventions are confidential. Draft with placeholders (CLIENT_CIDR, ACCOUNT_ALIAS) on any approved assistant, substitute locally, and run the chain entirely inside the client environment — every chain tool is OSS and offline-capable. If the client provides Bedrock/Azure OpenAI in-tenancy, use it and skip the placeholder dance. Never paste terraform plan output (it contains real IDs) into unapproved tools.

Success criteria

• •
  Module merged with all five gates green, artifacts attached to the PR.
• •
  You caught at least one hallucinated attribute or insecure default via the chain — and can name which gate caught it.
• •
  Chain runs automatically in CI on every IaC PR.
• •
  Time from intent to reviewed PR is under half a day for a standard module — with the confidence to apply.