AutoGineer
Generated banner for Tf Best Practices
Generated logo for Tf Best Practices

Tf Best Practices

AWSOfficialPublished by AWS

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Low risk
  • Has scripts
Download ZIP

From the author

Best-practice authoring guidance AND a read-only policy gate for AWS Terraform generated by a migration skill. Load during any phase that writes a terraform/ directory — first as the "what to emit" posture rules + security-baseline spec, then after writing as the deterministic policy verdict. Read-only: it reports whether the generated Terraform passes; it never edits .tf files, never touches .phase-status.json, and never decides phase completion. Complements (does not replace) terraform fmt/init/validate.
— the description by AWS

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

tf-best-practices provides a structured approach to authoring and validating AWS Terraform code. It functions as a two-part system: an authoring guide that defines security posture rules before code generation, and a read-only policy gate that evaluates generated Terraform against those rules after it is written. The skill is designed to be integrated into migration workflows, providing deterministic verdicts and actionable fix hints without modifying the underlying files.

What it does

  • Provides security posture rules for authoring AWS Terraform.
  • Executes a read-only policy check on generated Terraform directories.
  • Generates machine-readable JSON reports detailing policy violations.
  • Offers specific fix hints for identified infrastructure issues.
  • Validates migration artifacts including database and deployment configurations.
  • Supports a multi-stage validation protocol including fmt, init, and validate.

When to use it

  • Before writing Terraform code to ensure adherence to security posture rules.
  • After generating Terraform to verify compliance with defined policy gates.
  • When integrating automated validation into a migration workflow.
  • To identify and remediate infrastructure configuration issues during development.

Advantages

  • Enforces consistent security standards across generated infrastructure.
  • Provides actionable feedback with file and line-specific remediation hints.
  • Operates as a read-only tool that does not modify user files.
  • Functions without requiring provider downloads or active registry connections.
  • Integrates into existing migration pipelines as a deterministic gate.

Usage examples

“Check the generated terraform/ directory for policy violations.”
The skill runs the policy checker against the specified directory and returns a JSON report containing any identified violations and corresponding fix hints.
“What are the security requirements for an internet-facing ALB?”
The skill provides the posture rules requiring an HTTPS listener on port 443 and an HTTP redirect to HTTPS on port 80.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/aws/tf-best-practices/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip tf-best-practices.zip -d .agents/skills

Documentation by AWS

tf-best-practices — Generated-IaC posture rules + read-only policy gate

A shared authoring guide and verdict producer, not a workflow. It answers two questions for a phase that generates AWS Terraform:

  1. Before writing — "what security posture must the generated terraform/ follow?" (the posture rules + the baseline.tf account-hardening spec)

  2. After writing — "does the generated terraform/ pass policy?" (a deterministic, read-only verdict + a machine-readable report)

Routing — load the part that matches your context

This skill is entered at two touchpoints in the caller's Generate flow, with the caller's own terraform-authoring work in between. The caller states which touchpoint it is at when it loads this skill, and reads the corresponding part:

Caller contextLoadWhy
About to author terraform/ (before writing)Part 1 → references/security-posture-rules.mdThe "what to emit" AWS authoring rules (gate-enforced + authoring-only + compliance-conditional).
terraform/ written, ready to validate (after writing)Part 2 → references/terraform-validation.md + run the gate scriptThe fmt → init → validate → policy protocol and the read-only verdict.

Everything this skill states is source-cloud-agnostic (pure AWS Terraform). Any GCP/Heroku detection or artifact reading is the caller's job; where a rule needs a caller-known fact (e.g. declared compliance frameworks), the caller passes it as a caller-context signal — see references/security-posture-rules.md § Caller-context signals.

Boundary (read this first)

This unit is a verdict producer, never a mutator. Its entire write surface is the JSON verdict it is asked to emit. Specifically it MUST NOT:

  • edit, format, or rewrite any .tf file (the caller owns remediation),

  • read or write .phase-status.json or any run-state file (interpreter-owned),

  • decide whether a phase may complete, or prompt the user (caller policy).

The caller (a migration skill's Generate phase) owns: the fix-and-retry loop that edits the .tf it generated, terraform fmt auto-apply, the retry/skip/abort prompt, the Phase Completion gate, and every .phase-status.json write. See the consuming skill's generate phase for how the verdict feeds those decisions.

Consumers: gcp-to-aws (prose Generate) and heroku-to-aws (DSL Generate). The contract is source-agnostic; each caller wires the two touchpoints in its own Generate idiom — gcp-to-aws as prose steps, heroku-to-aws as a fragment step plus a fail-closed _postconditions assert enforced by the interpreter.

Part 1 — Authoring posture (load before writing terraform/)

Emit generated Terraform that satisfies the posture in references/security-posture-rules.md.

These are the "what good AWS Terraform looks like" rules. Following them makes the Part 2 gate pass by construction. This unit does not read the caller's artifacts — it consumes only caller-context signals the caller passes in.

Scope. security-posture-rules.md covers, in three tiers:

  • Gate-enforced (Part 2 verifies statically): ALB TLS, no-public-database, RDS + ElastiCache encryption-at-rest, no-public-DB-port ingress, no-public admin/datastore-port ingress, no-wildcard-IAM.

  • Authoring-only (not gate-checkable, still required): deletion_protection, master-password-via-Secrets-Manager, S3 hardening, Fargate/EKS/ECR settings, private-subnet placement, backups, baseline monitoring.

  • Compliance-conditional (emitted when the caller declares soc2/pci/hipaa/fedramp): VPC flow logs, S3 access logging, secret rotation, customer-managed KMS.

Still the caller's own generation concern (candidates to migrate here later): the account-hardening baseline.tf layer (CloudTrail, GuardDuty, Config, Security Hub).

Part 2 — Policy gate (run after writing terraform/)

Run the read-only checker against the generated directory. Resolve the script path relative to the plugin root ($PLUGIN_ROOT/skills/tf-best-practices/scripts/...), the same convention the plugin uses for its other scripts:

python3 "$PLUGIN_ROOT/skills/tf-best-practices/scripts/validate-terraform-policy.py" "$TERRAFORM_DIR" --json "$VERDICT_PATH"

  • $TERRAFORM_DIR — required, caller-supplied: the generated terraform/ directory (e.g. $MIGRATION_DIR/terraform). This skill never defaults or discovers it — the caller always passes the path it wrote Terraform to.

  • --json $VERDICT_PATH — optional; writes a machine-readable verdict the caller can merge into its own validation-report.json.

The policy check is one stage of a larger validation flow (fmt → init → validate → policy). The full protocol — including offline-fallback behavior and how the policy verdict maps into a validation-report.json — is documented in references/terraform-validation.md. That protocol is descriptive: the caller owns the fmt/init/validate execution, the fix-and-retry loop, and the report write; this unit contributes only the read-only policy stage + verdict shape.

Before infrastructure completion, the caller must run scripts/validate-terraform-report.py on the saved validation-report.json and require exit 0. The checker enforces the shared v2 completion contract. Its RUNTIME_REPORT_OK result does not establish that Terraform ran or passed.

Exit codes → caller action
ExitstdoutMeaningCaller does
0POLICY_OKposture satisfiedproceed
1POLICY_FAILviolations presentread violations[], edit the named .tf sites, re-run (caller's retry budget)
2(usage error)bad path / IOsurface to user; do not treat as pass
Verdict shape (--json)
{
  "check": "policy",
  "policy_status": "POLICY_OK | POLICY_FAIL",
  "violations": [
    {
      "check": "policy",
      "rule": "alb_https_listener | alb_http_redirect | no_tf_files",
      "file": "compute.tf",
      "line": 7,
      "severity": "error",
      "summary": "human-readable violation",
      "fix_hint": "concrete remediation the caller can apply"
    }
  ]
}

Each violations[] entry is actionable evidence — file + line + fix_hint tell the caller exactly what to edit. The caller applies the edit; this unit only reports.

Policy rules enforced today

Companion checks for migration artifacts

Migration callers can also run the shared read-only scripts/validate-migration-artifacts.py against their complete migration directory:

python3 "$PLUGIN_ROOT/skills/tf-best-practices/scripts/validate-migration-artifacts.py" \
  "$MIGRATION_DIR" --json "$MIGRATION_DIR/artifact-validation-status.json"

This produces ARTIFACTS_OK, ARTIFACTS_FAIL, or ARTIFACTS_ERROR, separately from the Terraform policy verdict. The caller must inspect the real exit code and report; it must not synthesize success. Supported checks cover PostgreSQL verification control flow, EB/database security-group wiring, GitHub Actions step references and deployment operations, and literal RDS time windows. Unsupported structures require review. This is not a general Bash safety proof, provider validation, or proof that a deployment succeeds.

Heroku callers add --require-postgres-script when PostgreSQL is in the design, and --require-eb-workflow when GitHub Actions is the selected EB deployment method. Other callers must not impose those Heroku-specific requirements. The checker never executes a generated migration script or changes input files or phase state; only the explicit JSON report path may be written.

For RDS/Aurora generation, scripts/rds_windows.py resolves independent daily backup and weekly maintenance windows from caller preferences. It rejects invalid or explicitly conflicting choices rather than silently changing them. Callers use its actual JSON values when authoring Terraform.

Terraform policy rules

Every rule is fail-open on ambiguity — it fires only on unambiguous, in-block literal evidence, so a valid stack is never falsely blocked (a POLICY_FAIL is a hard completion gate for the caller, so a false positive would block a real migration).

Internet-facing ALB TLS posture (an ALB is internet-facing when internal is absent, false, or variable-driven — fail-safe):

  • alb_https_listener — must have an HTTPS listener on 443 with certificate_arn and a forward action.

  • alb_http_redirect — an HTTP :80 listener must redirect to HTTPS, never forward to targets. Internal ALBs (internal = true) are exempt.

Elastic Beanstalk ALBs are invisible to these rules. The ALB rules inspect standalone aws_lb_listener blocks. An EB LoadBalanced environment provisions its ALB from aws_elastic_beanstalk_environment setting blocks, which the static checker does not read — so a pure-EB design passes the ALB rules vacuously (no listener to inspect). EB listener/TLS posture is therefore authoring-only, not gate-enforced. (Fixtures good-heroku-eb-only and good-heroku-eb-singleinstance document this; good-heroku-eb-loadbalanced carries a standalone ALB so the listener rules are exercised on real blocks.)

Managed database exposure & encryption (aws_db_instance, aws_rds_cluster):

  • rds_not_public — must not set publicly_accessible = true (absent/variable → fail-open).

  • rds_encryption_at_rest — must set storage_encrypted = true; missing or literal false fires (RDS defaults to unencrypted), variable-driven fails open. S3 is not checked (default SSE-S3 since Jan 2023).

ElastiCache encryption (aws_elasticache_replication_group, Redis aws_elasticache_cluster):

  • elasticache_encryption_at_rest — a replication group must set at_rest_encryption_enabled = true; missing or literal false fires, variable-driven fails open.

  • elasticache_cluster_encryption — a Redis-engine aws_elasticache_cluster (single-node: engine = "redis", no replication_group_id) must set BOTH at_rest_encryption_enabled = true and transit_encryption_enabled = true; missing or literal false on either fires, variable-driven fails open. engine = "memcached" clusters (and variable-driven/absent engine) are exempt — Memcached does not support these attributes.

Security group ingress:

  • db_sg_no_public_ingress — an inline aws_security_group ingress covering 5432/3306 must not allow 0.0.0.0/0 or ::/0.

  • sg_no_public_admin_ingress — an inline ingress must not open a curated never-public admin/datastore port (22, 3389, 6379, 11211, 27017, 9200/9300, 5601) to 0.0.0.0/0 or ::/0. Web (80/443) and app/game ports are not flagged; DB ports are handled by the rule above. Both check cidr_blocks and ipv6_cidr_blocks independently, so a benign IPv4 list does not mask an open IPv6 one. Both: separate aws_security_group_rule / aws_vpc_security_group_ingress_rule resources fail open (not correlated).

IAM least-privilege (aws_iam_policy, aws_iam_role_policy, aws_iam_group_policy, aws_iam_user_policy):

  • no_wildcard_iam — an Allow statement must not use Action/Resource "*". The one narrow exception is an isolated elasticbeanstalk:CreateStorageLocation statement with Resource = "*" because AWS does not support resource-level permissions for that action. aws_iam_policy_document data sources and assume-role trust policies fail open.

The checker is a zero-dependency static HCL reader (no terraform init, no provider download) — it runs even when the registry is unreachable. It uses brace-depth matching for nested blocks, so a valid HTTPS listener written with a nested forward { ... } block is not a false failure.

Fixtures (also the checker's regression suite)

fixtures/terraform-policy/ holds intentionally-shaped Terraform used by scripts/test_validate_terraform_policy.py:

  • bad-http-forward/ — internet-facing ALB that forwards plaintext HTTP → MUST POLICY_FAIL.

  • internal-alb-only/ — internal ALB on HTTP → MUST POLICY_OK (HTTP allowed internally).

  • good-https-redirect/ — the correct pattern → POLICY_OK.

These are deliberately non-compliant test data (never deployed). They are excluded from the repo-wide checkov scan via .checkov.yaml skip-path; do not "harden" them — doing so breaks the tests that assert the failure paths.

Verification

# from skills/tf-best-practices/
uv run --python 3.12 --with pytest python -m pytest scripts/test_validate_terraform_policy.py -q

Files

references/terraform-validation.md

Terraform Validation Protocol (shared)

Canonical definition of the fmt → init → validate → policy → fix-and-retry → offline-fallback protocol for any phase that emits a terraform/ directory. This document is descriptive and caller-driven: it specifies the mechanics and the report shape, but the caller (a migration skill's Generate phase) owns execution, the fix-and-retry edits, the user prompt, and any run-state decisions.

Ownership boundary (important)

This protocol is part of the read-only tf-best-practices unit. Neither this document nor the policy checker it invokes may:

  • edit .tf files — the caller applies fixes (Stage D is a description of what the caller does, not an action this unit performs),

  • read/write run-state (e.g. a phase-status file) — that is interpreter/caller territory,

  • decide phase completion or prompt the user — caller policy.

The protocol's only durable output is validation-report.json. Where the caller writes it, whether validation failure blocks the phase, and how the terminal status maps to run-state are all caller decisions. The pseudocode below uses "the caller advances / stops" deliberately — this unit never advances a state machine.

When to use

Any step that writes a terraform/ directory and wants to check it for format, HCL-level, and policy defects while degrading gracefully when the provider registry is unreachable.

Protocol

Working directory: the terraform/ directory under test. All commands run non-interactively (-input=false -no-color where supported). $TERRAFORM_DIR is the caller-supplied path.

Stage A — Format

  1. terraform fmt -recursive (auto-apply — a caller action).

  2. terraform fmt -recursive -check. If non-zero, enter the Fix-and-Retry loop targeting fmt failures. On success, advance to Stage B.

Stage B — Initialize (no backend)

  1. terraform init -backend=false -input=false -no-color, capturing stderr.

  2. On non-zero exit, run the Offline Detection algorithm below on the captured stderr.

    • If classified network-unavailable: set validation_status = "passed_degraded_offline", emit warning, SKIP Stage C, proceed to Stage F (policy still runs), then Stage E. Do NOT enter the retry loop.

    • Otherwise: enter the Fix-and-Retry loop targeting init failures.

  3. On success, advance to Stage C.

Stage C — Validate

  1. terraform validate -json, capturing stdout.

  2. On non-zero exit, parse .diagnostics[] and enter the Fix-and-Retry loop targeting validate failures.

  3. On success, set validation_status = "passed" and advance to Stage F (Stage D remains available for policy retries).

Stage D — Fix-and-Retry Loop (caller-executed)

Attempt budget: 3 attempts per batch. Hardcoded.

Per attempt:

  1. Read the failing command's error output:

    • fmt: the diff shown by fmt -recursive -check (list of files that would change).

    • init: the stderr captured from terraform init.

    • validate: the JSON diagnostics array from terraform validate -json.

    • policy: the violations[] from the policy checker's --json verdict (or POLICY_FAIL stderr lines).

  2. Group errors by file path. For each file, open it once, apply all targeted edits for that file, close. Never rewrite a file wholesale; only edit the lines/blocks reported. (These edits are performed by the caller — this unit does not touch .tf.)

  3. Re-run only the failing command (fmt -check, init, validate, or the policy checker).

  4. If it passes, exit the loop and return to the calling stage's success path.

  5. If the same (file, line, summary) reappears on consecutive attempts, emit a "same error recurring" signal in the attempt log — warning only; continue.

On the 3rd consecutive failure in a batch, the caller prompts the user:

Terraform validation failed after 3 automated fix attempts.
Last error: <one-line summary>
[retry] attempt 3 more fixes
[skip]  proceed with warning (validation_status = skipped_user_continue)
[abort] stop
Choose [retry/skip/abort]:

User choices (caller applies its own run-state policy on each):

  • retry — reset the per-batch counter to 0, grant 3 more attempts. Cumulative attempts is NOT reset.

  • skip — set validation_status = "skipped_user_continue", emit warning, proceed to Stage E. (Whether the caller then allows phase completion is a caller decision.)

  • abort — set validation_status = "skipped_user_abort", write validation-report.json with that status, and STOP. The caller MUST NOT record a completion signal (do not advance run-state). This unit does not touch run-state itself.

Stage F — Policy validation (mandatory when terraform/ exists)

  1. Run the read-only policy checker:

    python3 "<tf-best-practices>/scripts/validate-terraform-policy.py" "$TERRAFORM_DIR" --json "$VERDICT_PATH"

  2. On non-zero exit, parse the verdict's violations[] (each carries file, line, rule, fix_hint) and enter Stage D Fix-and-Retry targeting policy violations.

  3. On success (POLICY_OK), advance to Stage E.

  4. If Stage C was skipped due to offline fallback, still run Stage F — the policy check is static and needs no provider init.

Record the policy outcome in validation-report.json policy_status (see schema). A policy failure MUST be visible in the report — it must never be masked by a passed_degraded_offline top-level status.

Stage E — Emit validation-report.json

Write the report to the single canonical path the caller pins, e.g. $MIGRATION_DIR/validation-report.json — slash-joined, never a bare $MIGRATION_DIR/ directory (a bare dir invites a missing-slash <ts>validation-report.json sibling) — per the schema below.

Before returning a completed infrastructure result, run the shared report contract gate:

python3 "<tf-best-practices>/scripts/validate-terraform-report.py" "$MIGRATION_DIR/validation-report.json"

Require RUNTIME_REPORT_OK and exit 0. On failure, correct the report from the actual command receipts; do not invent a version, successful check, or diagnostic to satisfy the schema. This gate validates the recorded fields, not the execution of Terraform. Keep the execution receipts separately.

Offline Detection

FUNCTION isNetworkUnavailable(init_stderr)
  INPUT: init_stderr (string, captured stderr of `terraform init`)
  OUTPUT: boolean

  patterns ← ["lookup", "dial tcp", "connection refused", "timeout", "no such host"]

  IF init_stderr IS NULL OR trim(init_stderr) = "" THEN
    RETURN false   // empty stderr → treat as non-network failure (let retry loop handle)
  END IF

  haystack ← toLowerCase(init_stderr)

  FOR EACH p IN patterns DO              // first-match-wins
    IF contains(haystack, toLowerCase(p)) THEN
      RETURN true
    END IF
  END FOR

  RETURN false
END FUNCTION

Rules:

  • Source stream: stderr of terraform init only.

  • Case sensitivity: case-insensitive.

  • Match semantics: first-match-wins; full-stderr scan.

  • Empty stderr: treat as non-network failure so the retry loop runs (prevents silent offline-fallback when terraform fails for an unrelated reason with no stderr).

  • CLI failure: a missing executable, invalid shim, or failed terraform version is not a provider-network outage. Use the retry/skip/abort flow and record the actual failure; do not assign passed_degraded_offline.

Report Schema (v2)

v2 adds policy_status so the policy verdict is durably recorded independently of the fmt/init/validate outcome. A policy failure is visible even when the top-level status is passed_degraded_offline.

{
  "$schema": "validation-report/v2",
  "status": "passed | passed_degraded_offline | skipped_user_continue | skipped_user_abort | policy_failed",
  "policy_status": "POLICY_OK | POLICY_FAIL | not_run",
  "attempts": 0,
  "errors_found": [
    {
      "file": "string (relative to terraform/)",
      "line": "integer (1-based, 0 if unknown)",
      "severity": "error | warning",
      "summary": "string (≤200 chars)"
    }
  ],
  "errors_fixed": [
    {
      "file": "string",
      "line": "integer",
      "severity": "error | warning",
      "summary": "string",
      "attempt": "integer (1-indexed)"
    }
  ],
  "policy_violations": [
    {
      "rule": "string (e.g. alb_http_redirect)",
      "file": "string",
      "line": "integer",
      "severity": "error | warning",
      "summary": "string",
      "fix_hint": "string"
    }
  ],
  "offline_fallback_used": false,
  "timestamp": "ISO 8601 UTC",
  "terraform_version": "string (empty if unavailable)"
}

Field rules:

  • status: one of the enum values; equals the terminal validation_status. policy_failed is used when the fmt/init/validate stages passed (or offline-skipped) but policy did not and the user did not skip/abort.

  • policy_status: POLICY_OK / POLICY_FAIL from Stage F, or not_run if Stage F did not execute (e.g. no terraform/ produced). MUST reflect the last policy run — never inferred from status.

  • policy_violations: the verdict's violations[] when policy_status == POLICY_FAIL (deduped); empty otherwise.

  • attempts: total fix-and-retry attempts across all batches (never resets on retry).

  • errors_found / errors_fixed: fmt/init/validate diagnostics, deduped by (file, line, summary).

  • offline_fallback_used: true iff status == "passed_degraded_offline".

  • terraform_version: from terraform version -json; empty string if unavailable (never crash).

Example (validate passed first try; policy caught an HTTP-forward ALB, caller fixed it):

{
  "$schema": "validation-report/v2",
  "status": "passed",
  "policy_status": "POLICY_OK",
  "attempts": 1,
  "errors_found": [],
  "errors_fixed": [],
  "policy_violations": [],
  "offline_fallback_used": false,
  "timestamp": "2026-07-15T15:37:04Z",
  "terraform_version": "1.9.5"
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
AWS
Publisher
AWS (Official)
Source
aws/agent-toolkit-for-aws · plugins/aws-startup-advisor/skills/tf-best-practices · commit 0a218f8
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • NOTICE (added by AutoGineer from NOTICE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by AWS or AWS.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download tf-best-practices.zip