Terraform Developer Productivity Master Guide: Tools, Workflow, Security, Testing, CI/CD, Automation and Best Practices

An End-to-End Practical Engineering Blueprint for Modern Infrastructure-as-Code Development

---

PART 1 — TERRAFORM DEVELOPMENT ECOSYSTEM

End-to-End Ecosystem Architecture

Developer
  │
  ├─► VS Code / Cursor / Claude Code (IDE)
  │     ├─► HashiCorp Terraform Extension
  │     ├─► terraform-ls (Language Server Protocol)
  │     └─► Terraform MCP Server (AI Context & Schema Provider)
  │
  ├─► tenv (Version Manager)
  │     └─► Terraform CLI (Runtime Engine)
  │           ├─► terraform fmt
  │           ├─► terraform validate
  │           └─► terraform test
  │
  ├─► TFLint (Static Analysis & Cloud Rule Linter)
  ├─► Trivy / Checkov (IaC Security & Compliance Scanners)
  ├─► terraform-docs (Automated Documentation Generator)
  ├─► Infracost (Cloud Cost Estimator)
  │
  └─► pre-commit-terraform (Local Git Hook Automation)
        │
        ▼
   Git Repository (GitHub / GitLab)
        │
        ▼
   CI/CD Engine (GitHub Actions / GitLab CI)
        │
        ├─► Remote Execution / Orchestration (HCP Terraform / Atlantis)
        ├─► Policy-as-Code Engine (Sentinel / OPA / Conftest)
        │
        ▼
   Cloud Infrastructure (AWS / Azure / GCP / Kubernetes)

Layer Responsibilities & Categorization

Tool Category	Core Responsibilities	Specific Tools
Editor Tools	Human interface, file editing, syntax highlighting, diff viewing.	VS Code, Cursor, Claude Code
Language-Server Tools	Provides real-time autocompletion, schema diagnostics, symbol references, and hover docs to the editor.	terraform-ls
AI Development Tools	Connects LLM tools directly to provider schemas, live registry metadata, and local state context.	Terraform MCP Server
Version Managers	Manages concurrent binary versions of Terraform, OpenTofu, and Terragrunt per project.	tenv
Terraform CLI Tools	Core engine executing plan synthesis, state updates, resource graphing, and native testing.	terraform CLI
Linting Tools	Enforces naming conventions, detects deprecated attributes, and catches provider-specific syntax errors.	TFLint
Security Tools	Scans IaC for misconfigurations, exposed secrets, unencrypted resources, and IAM policy violations.	Trivy, Checkov
Testing Tools	Validates structural logic, variable constraints, and functional execution through plan/apply assertions.	terraform test, Terratest
Documentation Tools	Auto-generates markdown tables for input variables, outputs, providers, and resources directly into READMEs.	terraform-docs
Cost-Analysis Tools	Calculates delta monthly cloud cost estimates directly within local workflows and PR comments.	Infracost
Git Automation Tools	Intercepts local commits to run validation pipelines before code leaves the developer’s workstation.	pre-commit-terraform
CI/CD Tools	Automates plan execution, quality gate checks, and automated state operations across team workflows.	GitHub Actions, GitLab CI
Orchestration Tools	PR-driven terraform plan/apply execution engines with state locking and repo-level automation.	Atlantis
Remote Execution Platforms	Managed execution platform with centralized state storage, team RBAC, audit logging, and private module registries.	HCP Terraform, Terraform Enterprise
Policy-as-Code Systems	Hard guardrails enforcing organizational compliance rules before state modifications occur.	Sentinel, OPA / Conftest

---

PART 2 — CORE TERRAFORM DEVELOPMENT TOOLS

1. Terraform CLI

Command Reference & Workflow Execution

# Initialize working directory, download provider plugins, and configure backend state
terraform init -backend-config="key=environments/dev/terraform.tfstate"

# Auto-format all HCL files recursively in current directory to standard formatting style
terraform fmt -recursive

# Validate structural consistency, variable references, and syntax against loaded provider schemas
terraform validate

# Synthesize an execution plan comparing real-world cloud state against defined HCL declarations
terraform plan -out=tfplan.binary -var-file="dev.tfvars"

# Apply state modifications recorded in the synthesized plan file
terraform apply tfplan.binary

# Destroy all managed infrastructure defined in the current root module state
terraform destroy -var-file="dev.tfvars"

# Open an interactive command-line console to evaluate expressions, functions, and state queries
terraform console

# Extract and output values declared in the output block from state
terraform output -json

# Inspect human-readable state or saved execution plans
terraform show -json tfplan.binary

# Display tree-view of provider dependencies required across all modules
terraform providers

# Query and mutate state file items without modifying HCL declarations
terraform state list
terraform state show aws_s3_bucket.data_vault

# Bring existing cloud infrastructure into Terraform state tracking
terraform import aws_s3_bucket.legacy_vault my-existing-bucket-name

# Run native HCL test suites (.tftest.hcl) against code modules
terraform test

2. VS Code + HashiCorp Terraform Extension

The official HashiCorp Terraform extension (hashicorp.terraform) exposes language-server integration directly into VS Code and Cursor.

Recommended .vscode/settings.json

{
  "terraform.languageServer.enable": true,
  "terraform.languageServer.args": ["serve"],
  "[terraform]": {
    "editor.defaultFormatter": "hashicorp.terraform",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  },
  "[terraform-vars]": {
    "editor.defaultFormatter": "hashicorp.terraform",
    "editor.formatOnSave": true
  },
  "gitsigns.currentLineBlame": true
}

Essential VS Code Extensions

• HashiCorp Terraform (hashicorp.terraform): Official syntax highlighting and LSP integration.
• TFLint (eamodio.gitlens / marpenn.tflint): Real-time inline linting diagnostics.
• YAML (redhat.vscode-yaml): Schema validation for pre-commit, GitHub Actions, and terraform-docs configs.

3. terraform-ls

terraform-ls is the official Language Server Protocol (LSP) implementation maintained by HashiCorp for Terraform.

┌────────────────────────┐      LSP Protocol       ┌────────────────────────┐
│  Editor (VS Code)      │ ◄─────────────────────► │     terraform-ls       │
└────────────────────────┘                         └───────────┬────────────┘
                                                               │
                                                               ▼
                                                   ┌────────────────────────┐
                                                   │ Terraform Provider     │
                                                   │ Schemas & Local State  │
                                                   └────────────────────────┘

Functionality

• Autocomplete: Deep attribute auto-completion using cloud provider schemas.
• Diagnostics: Highlights syntax errors, unknown variables, missing required attributes, and invalid type assignments in real-time.
• Navigation: Go to definition (F12) across local child modules, local variables, and named outputs.
• Hover Docs: Renders official documentation in hover tooltips for resources and input parameters.

Note: Developers should let the official VS Code Terraform extension install and manage the terraform-ls binary automatically.

4. Terraform MCP Server

The Model Context Protocol (MCP) server for Terraform bridges AI assistants (Claude Code, Cursor, Windsurf) directly to the HashiCorp Registry and provider documentation. It prevents AI models from inventing (“hallucinating”) non-existent resource attributes or using deprecated arguments.

AI Agent + MCP Workflow

Developer Request ("Provision an S3 bucket with KMS encryption")
                       │
                       ▼
                 AI Coding Agent
                       │
             ┌─────────┴─────────┐
             │  Query Schema     │ (MCP Tool Call)
             ▼                   ▼
    Terraform MCP Server ──► Terraform Registry
             │                   │
             └─────────┬─────────┘
                       │
                       ▼
     Inject Actual Provider Schema Specs
                       │
                       ▼
       Generate Exact, Up-to-Date HCL Code

Standard Developer Prompts for AI Tools

• Module Generation:

“Using the Terraform MCP server, look up the latest aws_s3_bucket and aws_s3_bucket_server_side_encryption_configuration schemas from the AWS provider v5.x. Generate a production-ready module that enforces SSE-KMS encryption, blocks public access, and sets key ownership.”

• Refactoring:

“Inspect my main.tf file against current provider schemas. Identify deprecated resource attributes and upgrade them to match current syntax.”

---

PART 3 — TERRAFORM VERSION MANAGEMENT

5. tenv

tenv is a modern binary version manager written in Rust. It manages versions for Terraform, OpenTofu, and Terragrunt in a single tool.

┌────────────────────────────────────────────────────────┐
│                         tenv                           │
└───────────┬───────────────────┬───────────────────┬────┘
            │                   │                   │
            ▼                   ▼                   ▼
     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
     │  Terraform  │     │  OpenTofu   │     │ Terragrunt  │
     │ v1.6 / 1.7  │     │    v1.8     │     │   v0.58     │
     └─────────────┘     └─────────────┘     └─────────────┘

Installation & Basic Operations

# macOS via Homebrew
brew install tenv

# Install specific Terraform version
tenv tf install 1.9.5

# Set global default version
tenv tf use 1.9.5

# Detect and install version defined in local project configuration (.terraform-version)
tenv tf detect

Project-Based Version Pinning

Create a .terraform-version file in your repository root:

1.9.5

tenv automatically switches to this exact version when running commands inside this directory tree.

Comparison Matrix: Version Managers

Feature	tenv	tfenv	asdf	mise
Language / Speed	Rust (Extremely Fast)	Bash (Slower)	Shell / Elixir	Rust (Extremely Fast)
OpenTofu Support	Native	No	Via Plugin	Via Plugin
Terragrunt Support	Native	No	Via Plugin	Via Plugin
Active Maintenance	Active	Stale / Unmaintained	Active	Active
Recommendation	Default Choice	Legacy / Deprecated	General Tooling	Polyglot Devs

---

PART 4 — TERRAFORM CODE QUALITY

6. terraform fmt

terraform fmt formats HCL code according to canonical language standards.

# Format files in current working directory
terraform fmt

# Format recursively across all nested child modules
terraform fmt -recursive

# Dry-run check for CI pipelines; returns exit code 1 if unformatted files exist
terraform fmt -check -recursive -diff

7. terraform validate

terraform validate verifies syntax, resource structures, and type matching against loaded provider schemas.

# Initialize working directory before validating (downloads required providers)
terraform init -backend=false
terraform validate

What terraform validate Checks vs. What It Misses

┌───────────────────────────────────────┬───────────────────────────────────────┐
│     What terraform validate CHECKS    │     What terraform validate MISSES    │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ ✓ Invalid HCL syntax                  │ ✗ Cloud provider IAM permissions      │
│ ✓ Undeclared input variables          │ ✗ Real-world resource availability    │
│ ✓ Incorrect argument types (e.g. str) │ ✗ Cloud specific rule logic (e.g. EC2)│
│ ✓ Missing required resource arguments │ ✗ Dynamic expressions evaluated at run│
│ ✓ Invalid function call syntax        │ ✗ Pre-execution quota restrictions    │
└───────────────────────────────────────┴───────────────────────────────────────┘

8. TFLint

TFLint is a framework-aware linter that checks for provider-specific issues, invalid configuration parameters, and anti-patterns that standard validation misses.

Production Configuration (.tflint.hcl)

config {
  format = "compact"
  plugin_dir = "~/.tflint.d/plugins"
  module = true
  force = false
}

# Enable AWS Provider Linter Plugin
plugin "aws" {
  enabled = true
  version = "0.34.0"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}

# Enforce Deep Resource Attribute Checks
rule "aws_instance_invalid_type" {
  enabled = true
}

rule "aws_s3_bucket_declared_name" {
  enabled = true
}

Execution Steps

# Initialize plugins defined in .tflint.hcl
tflint --init

# Execute linting against repository
tflint

---

PART 5 — TERRAFORM SECURITY

9. Trivy

Trivy scans Terraform source files and plan binaries for security vulnerabilities, exposed credentials, and infrastructure misconfigurations.

# Scan current directory for IaC security misconfigurations
trivy config .

# Scan generated binary plan file for runtime exposure risk
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
trivy config --severity HIGH,CRITICAL tfplan.json

10. Checkov

Checkov is a static code analysis tool for infrastructure-as-code. It evaluates configurations against built-in policy frameworks (CIS Benchmarks, NIST, HIPAA, PCI-DSS).

# Scan Terraform files in directory
checkov -d . --framework terraform

# Scan JSON plan file
checkov -f tfplan.json --framework terraform_plan

Security Tool Decision Matrix

                      IaC Security Tooling Choice
                                   │
         ┌─────────────────────────┴────────────────────────┐
         ▼                                                  ▼
   Trivy Selected                                    Checkov Selected
┌─────────────────────────────────────┐            ┌─────────────────────────────────────┐
│ • Fast binary execution             │            │ • Deep regulatory compliance flags  │
│ • Unified container/IaC scanning    │            │ • Custom Python/YAML policy rules   │
│ • Low resource consumption          │            │ • Rich native framework maps        │
└─────────────────────────────────────┘            └─────────────────────────────────────┘

---

PART 6 — TERRAFORM TESTING

11. terraform test (Native Framework)

Terraform 1.6+ includes a native testing framework that uses standard HCL to write functional test suites inside .tftest.hcl files.

Realistic Test Example (tests/vpc_validation.tftest.hcl)

variables {
  environment = "test"
  vpc_cidr    = "10.100.0.0/16"
}

provider "aws" {
  region = "us-east-1"
}

run "verify_vpc_cidr_allocation" {
  command = plan

  assert {
    condition     = aws_vpc.main.cidr_block == "10.100.0.0/16"
    error_message = "VPC CIDR block does not match expected test variable assignment."
  }

  assert {
    condition     = aws_vpc.main.enable_dns_hostnames == true
    error_message = "DNS Hostnames must be explicitly enabled for network environments."
  }
}

run "verify_subnet_split" {
  command = plan

  assert {
    condition     = length(aws_subnet.public) == 2
    error_message = "Public subnets must be provisioned across exactly two Availability Zones."
  }
}

Running Tests

terraform test

Testing Framework Comparison Matrix

Testing Framework	Test Language	Execution Speed	Provisioning Required?	Primary Use Case
terraform validate	CLI Built-in	Fast (<1s)	No	Syntax & Reference Validation
TFLint	Ruleset Engine	Fast (<2s)	No	Cloud Best Practices & Types
terraform test	Native HCL	Fast to Medium	Plan (No) / Apply (Optional)	Unit / Module Logic Assertions
Terratest	Go	Slow (Minutes)	Yes (Real Infra)	End-to-End Integration Tests

---

PART 7 — TERRAFORM DOCUMENTATION

12. terraform-docs

terraform-docs inspects Terraform code modules and automatically builds structured Markdown documentation.

Production Configuration (.terraform-docs.yml)

formatter: "markdown table"

header-from: main.tf
footer-from: ""

sections:
  show:
    - header
    - requirements
    - providers
    - modules
    - inputs
    - outputs

sort:
  enabled: true
  by: name

output:
  file: README.md
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

Execution

# Inject generated documentation directly into target markers inside README.md
terraform-docs markdown table --output-file README.md --output-mode inject .

---

PART 8 — TERRAFORM COST MANAGEMENT

13. Infracost

Infracost parses execution plans to estimate monthly cloud infrastructure costs before code is merged.

┌────────────────────┐     ┌────────────────────┐     ┌────────────────────┐
│   Terraform Code   │ ──► │   terraform plan   │ ──► │     Infracost      │
└────────────────────┘     └────────────────────┘     └─────────┬──────────┘
                                                                │
                                                                ▼
                                                      ┌────────────────────┐
                                                      │ PR Cost Breakdown  │
                                                      │    Delta Comment   │
                                                      └────────────────────┘

Command Line Operations

# Generate real-time cost breakdown from code
infracost breakdown --path .

# Generate comparative cost difference based on saved plan file
terraform plan -out=tfplan.binary
infracost diff --path tfplan.binary

---

PART 9 — GIT AUTOMATION

14. pre-commit-terraform

pre-commit-terraform runs quality, security, formatting, and documentation hooks locally before git commits are written to the branch history.

Production .pre-commit-config.yaml

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.92.0
    hooks:
      - id: terraform_fmt
      - id: terraform_validate
      - id: terraform_tflint
        args:
          - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
      - id: terraform_trivy
        args:
          - --args=--severity=HIGH,CRITICAL
      - id: terraform_docs
        args:
          - --args=--recursive
          - --args=--use-filename-list

Setup Commands

# Install pre-commit framework via Homebrew or pip
brew install pre-commit

# Install hooks into local repository .git/hooks directory
pre-commit install

# Execute manual run across all files in repository
pre-commit run --all-files

---

PART 10 — TERRAFORM PROJECT STRUCTURE

Standard Production Repository Layout

terraform-aws-architecture/
├── .github/
│   └── workflows/
│       ├── terraform-ci.yml
│       └── terraform-cd.yml
├── modules/
│   ├── networking/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   └── README.md
│   └── compute/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── README.md
├── environments/
│   ├── dev/
│   │   ├── backend.tf
│   │   ├── providers.tf
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   └── terraform.tfvars
│   └── prod/
│       ├── backend.tf
│       ├── providers.tf
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── terraform.tfvars
├── tests/
│   └── integration_test.tftest.hcl
├── .pre-commit-config.yaml
├── .tflint.hcl
├── .terraform-docs.yml
├── .terraform-version
└── README.md

Repository Architectures

• Monorepo Strategy: Centralizes all infrastructure modules and deployment environments in one repository. Simplifies code sharing and policy enforcement, but requires careful directory filtering in CI/CD.
• Multi-Repository Strategy: Separates reusable modules and deployment configurations into dedicated repositories. Improves isolation, version tagging, and access control, but increases cross-repository release overhead.

---

PART 11 — TERRAGRUNT

15. Terragrunt Overview

Terragrunt is a thin wrapper that keeps code DRY (Don’t Repeat Yourself), manages remote state automatically, and handles complex multi-module dependency chains across accounts and regions.

Example Directory Architecture

live/
├── terragrunt.hcl          # Parent configuration (remote state & provider generator)
├── dev/
│   ├── env.hcl
│   ├── vpc/
│   │   └── terragrunt.hcl  # Child configuration referencing modules/vpc
│   └── app/
│       └── terragrunt.hcl  # Child configuration referencing modules/app
└── prod/
    ├── env.hcl
    └── vpc/
        └── terragrunt.hcl

Parent Configuration (live/terragrunt.hcl)

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    bucket         = "company-tf-state-${path_relative_to_include()}"
    key            = "terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
  }
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "us-east-1"
}
EOF
}

When Terragrunt is Unnecessary: If you are deploying single-region infrastructures, using HCP Terraform workspaces natively, or managing projects with few state files, native Terraform (with workspaces or standard directory structures) is simpler and avoids the added abstraction layer.

---

PART 12 — CI/CD

16. GitHub Actions Pipeline Architecture

Production Workflow (.github/workflows/terraform.yml)

name: "Terraform Production Quality Pipeline"

on:
  pull_request:
    branches: [ "main" ]
  push:
    branches: [ "main" ]

permissions:
  id-token: write
  contents: read
  pull-requests: write

jobs:
  validate-and-plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./environments/dev
    steps:
      - name: Checkout Code Repository
        uses: actions/checkout@v4

      - name: Configure AWS Credentials (OIDC - Keyless)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsTFRole
          aws-region: us-east-1

      - name: Setup Tenv and Switch Version
        uses: tofuutils/setup-tenv@v1
        with:
          terraform-version: 1.9.5

      - name: Terraform Format Check
        run: terraform fmt -check -recursive

      - name: Terraform Initialization
        run: terraform init

      - name: Terraform Validation
        run: terraform validate

      - name: Run TFLint
        uses: reviewdog/action-tflint@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          working_directory: ./environments/dev

      - name: Run Security Scan with Trivy
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'config'
          exit-code: '1'
          severity: 'HIGH,CRITICAL'

      - name: Execute Native Tests
        run: terraform test

      - name: Synthesize Plan Execution
        run: terraform plan -no-color -out=tfplan.binary

      - name: Run Infracost Analysis
        uses: infracost/actions/setup@v3
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}

17. GitLab CI Configuration Pattern

stages:
  - validate
  - test
  - plan
  - apply

image:
  name: hashicorp/terraform:1.9.5
  entrypoint: [""]

before_script:
  - terraform init

validate:
  stage: validate
  script:
    - terraform fmt -check
    - terraform validate

security_scan:
  stage: test
  image:
    name: aquasec/trivy:latest
    entrypoint: [""]
  script:
    - trivy config .

plan:
  stage: plan
  script:
    - terraform plan -out=tfplan.binary
  artifacts:
    paths:
      - tfplan.binary

---

PART 13 — ATLANTIS

18. Pull-Request Execution Engine

Atlantis is an open-source pull-request automation tool for Terraform. It Listens for GitHub/GitLab webhooks and executes plan/apply operations directly from PR comments.

Developer             GitHub / GitLab                  Atlantis Server              Cloud
    │                        │                                │                       │
    ├─► Open Pull Request ──►│                                │                       │
    │                        ├─► Webhook Event (PR Open) ────►│                       │
    │                        │                                ├─► terraform plan ────►│
    │                        │◄── Comment Plan Output ────────┤                       │
    │                        │                                │                       │
    ├─► Comment: "atlantis apply"                             │                       │
    │                        ├─► Webhook Event (Comment) ────►│                       │
    │                        │                                ├─► terraform apply ───►│
    │                        │◄── Comment Apply Success ──────┤                       │

Repository Lock File (atlantis.yaml)

version: 3
projects:
- name: dev-infrastructure
  dir: environments/dev
  workspace: default
  autoplan:
    when_modified: ["*.tf", "../modules/**/*.tf"]
    enabled: true
  apply_requirements: [approved, mergeable]

---

PART 14 — HCP TERRAFORM

19. Managed Cloud Platform Integration

HCP Terraform (formerly Terraform Cloud) provides a centralized execution engine, remote state locking, private module registries, and native policy enforcement.

                      HCP Terraform Platform Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ Workspace: production-app-us-east-1                                         │
│                                                                             │
│ ┌──────────────────────┐  ┌──────────────────────┐  ┌─────────────────────┐ │
│ │  Remote State File   │  │  Private Module Reg  │  │  Variable Sets      │ │
│ │  & Lock Engine       │  │  & Provider Catalog  │  │  (Encrypted OIDC)   │ │
│ └──────────────────────┘  └──────────────────────┘  └─────────────────────┘ │
│                                                                             │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Remote Execution Workers (Run Tasks -> Policy Engine -> Cloud Apply)    │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

Backend Integration Block (backend.tf)

terraform {
  cloud {
    organization = "enterprise-core"

    workspaces {
      name = "prod-network-us-east-1"
    }
  }
}

---

PART 15 — POLICY AS CODE

20. Sentinel (HashiCorp Engine)

Sentinel runs directly inside HCP Terraform execution workflows to enforce policies before state modification.

Policy Example: Mandatory Tagging (tags_enforcement.sentinel)

import "tfplan/v2" as tfplan

mandatory_tags = ["Environment", "Owner", "CostCenter"]

main = rule {
  all tfplan.resource_changes as _, rc {
    rc.mode is "managed" and (rc.change.actions contains "create" or rc.change.actions contains "update") implies
      all mandatory_tags as tag {
        rc.change.after.tags contains tag
      }
  }
}

21. Open Policy Agent (OPA) / Conftest

Conftest evaluates rego policies against saved JSON plan files for cloud-agnostic compliance checks.

Rego Policy Example (policy/s3_encryption.rego)

package main

deny[msg] {
  resource := input.resource_changes[_]
  resource.type == "aws_s3_bucket"
  resource.change.actions[_] == "create"
  not resource.change.after.server_side_encryption_configuration
  msg := sprintf("S3 Bucket %v missing required server side encryption settings", [resource.address])
}

Decision Matrix: Policy Frameworks

Policy Engine	Primary Ecosystem	Syntax	Vendor Dependency
Sentinel	HCP Terraform / TFE	HashiCorp HCL-like Sentinel	High (HashiCorp Exclusive)
OPA / Conftest	Cloud-Native / Kubernetes / CI	Rego	Zero (Open Source / CNCF)

---

PART 16 — DEPENDENCY MANAGEMENT

22. Renovate Automation

Renovate automatically checks for outdated versions of Terraform binaries, cloud providers, and external modules, then opens PRs with dependency updates.

Production .github/renovate.json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:base"],
  "terraform": {
    "enabled": true
  },
  "packageRules": [
    {
      "matchPackagePatterns": ["*"],
      "matchManagers": ["terraform"],
      "automerge": false,
      "labels": ["dependencies", "terraform"]
    }
  ]
}

23. tfupdate

tfupdate is a lightweight CLI utility for updating version constraints across multiple HCL files programmatically.

# Update provider version requirements in HCL code
tfupdate provider aws ~> 5.60.0 ./environments/

---

PART 17 — TERRAFORM CONSOLE

Use terraform console to test expressions, data transformations, and function logic locally without applying code.

$ terraform console

# Test subnet IP calculations
> cidrsubnet("10.0.0.0/16", 8, 2)
"10.0.2.0/24"

# Validate string manipulation logic
> lower(replace("PRODUCTION-APP-01", "-", "_"))
"production_app_01"

# Query complex dynamic locals and maps
> lookup({ dev = "t3.micro", prod = "m5.large" }, "prod", "t3.micro")
"m5.large"

# Test dynamic list filtering via for-expressions
> [for s in ["web", "db", "app"] : upper(s) if s != "db"]
[
  "WEB",
  "APP",
]

---

PART 18 — IDE + AI DEVELOPMENT WORKFLOW

Responsible AI Usage Boundaries

┌─────────────────────────────────────────────────────────────────────────────┐
│                     IDE AI-Assisted Terraform Workflow                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Safe AI Responsibilities                          │
├─────────────────────────────────────────────────────────────────────────────┤
│ • Generating HCL boilerplate code for basic resources                       │
│ • Writing initial unit test assertions (.tftest.hcl)                        │
│ • Generating complex function regex and CIDR math                           │
│ • Refactoring deprecated syntax based on schema inputs                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                   Critical Boundaries (Human Review Required)               │
├─────────────────────────────────────────────────────────────────────────────┤
│ ❌ NEVER trust AI with IAM wildcard permissions or Security Group rules     │
│ ❌ NEVER allow AI to run destructive execution plans (terraform apply)      │
│ ❌ NEVER allow AI tools access to unencrypted state files or secrets        │
│ ❌ ALWAYS pass AI generated code through TFLint and Trivy security gates    │
└─────────────────────────────────────────────────────────────────────────────┘

---

PART 19 — TERRAFORM DEVELOPER DAILY WORKFLOW

 1. Pull Code Changes       ──► git pull origin main
 2. Align Version Engine    ──► tenv tf detect
 3. Isolate Feature Branch  ──► git checkout -b feature/vpc-endpoint-update
 4. Author Infrastructure   ──► Edit .tf files via VS Code / Cursor + MCP
 5. Format Code Layout      ──► terraform fmt -recursive
 6. Check Local Syntax      ──► terraform validate
 7. Perform Deep Linting    ──► tflint
 8. Run Security Analysis   ──► trivy config .
 9. Execute Unit Tests      ──► terraform test
10. Update Documentation    ──► terraform-docs markdown table --output-file README.md .
11. Generate Local Plan     ──► terraform plan -out=tfplan.binary
12. Review Cost Estimate    ──► infracost diff --path tfplan.binary
13. Commit Work Locally     ──► git commit -m "feat: attach vpc endpoint to cluster"
14. Pre-commit Hooks Exec   ──► Runs pre-commit-terraform validation hooks
15. Push Branch Remotely    ──► git push origin feature/vpc-endpoint-update
16. Automated Pipeline Run  ──► CI Executes fmt, validate, tflint, trivy, and plan
17. Team Peer Review        ──► Reviewers verify diff, cost reports, and tests
18. Automated Policy Gates  ──► Conftest / OPA / Sentinel verifies compliance
19. Managed Apply Exec      ──► terraform apply via CI / HCP TF / Atlantis
20. Post-Deploy Monitoring  ──► Drift detection verifies state stability

---

PART 20 — COMPLETE DEVELOPER TOOLCHAIN REFERENCE

Tool	Core Category	Tier Classification	Installation Command
Terraform CLI	Runtime Engine	MUST HAVE	brew install hashicorp/tap/terraform
VS Code	IDE	MUST HAVE	Official Installer
HashiCorp Extension	IDE Integration	MUST HAVE	VS Code Extension Marketplace
terraform-ls	Language Server	MUST HAVE	Managed automatically by VS Code extension
Terraform MCP	AI Context Integration	RECOMMENDED	Local MCP Configuration
tenv	Version Manager	MUST HAVE	brew install tenv
TFLint	Code Linter	MUST HAVE	brew install tflint
Trivy	Security Scanner	MUST HAVE	brew install trivy
Checkov	Compliance Scanner	RECOMMENDED	pip install checkov
terraform test	Testing Engine	MUST HAVE	Integrated in Terraform CLI 1.6+
Terratest	Integration Testing	OPTIONAL	Go Module Import
terraform-docs	Doc Generator	MUST HAVE	brew install terraform-docs
Infracost	Cost Engine	RECOMMENDED	brew install infracost
pre-commit-tf	Git Hook Automation	MUST HAVE	brew install pre-commit
Git	Version Control	MUST HAVE	System Package
GitHub / GitLab	Source Hosting	MUST HAVE	SaaS / Self-Hosted Platform
GitHub Actions	CI/CD	MUST HAVE	Integrated Cloud Native Engine
Terragrunt	DRY Architecture Engine	OPTIONAL	brew install terragrunt
Atlantis	Pull Request Automation	OPTIONAL	Helm Chart / Container Deployment
HCP Terraform	Remote Platform	ENTERPRISE	SaaS Cloud Platform
Sentinel	Policy Enforcement	ENTERPRISE	HCP Platform Engine
OPA / Conftest	Open Policy Engine	RECOMMENDED	brew install conftest
Renovate	Dependency Management	RECOMMENDED	GitHub App / Runner Installation

---

PART 21 — RECOMMENDED STACKS BY TIER

Beginner Developer

• Tooling: Terraform CLI, VS Code, HashiCorp Extension, Git.
• Focus: Learning basic HCL syntax, resource relationships, variable wiring, and state concepts.

Professional Developer

• Tooling: Terraform CLI, VS Code, tenv, TFLint, Trivy, terraform test, terraform-docs, pre-commit-terraform, Git, GitHub Actions.
• Focus: Standardized local workflows, automated security scanning, module modularization, and basic CI/CD execution.

Senior / Platform Engineer

• Tooling: Complete Professional Stack + Terraform MCP Server, Infracost, Conftest / OPA, Terragrunt or multi-dir patterns, OIDC Authentication pipelines.
• Focus: Designing reusable modules, managing dynamic cloud environments, preventing cost overruns, and establishing baseline security standards.

Enterprise Platform Team

• Tooling: Complete Platform Stack + HCP Terraform / Terraform Enterprise, Private Module Registry, Sentinel / OPA Policy Sets, Renovate, Centralized Drift Detection, Fine-grained RBAC.
• Focus: Managing multi-account infrastructure at scale, maintaining audit compliance, isolating blast radiuses, and providing secure developer platforms.

---

PART 22 — GOLD STANDARD TERRAFORM PIPELINE

 Local Workstation                                      Continuous Integration (CI) Phase
┌───────────────────────────────────────────────┐     ┌────────────────────────────────────────────────────────┐
│ Write Code -> tenv -> fmt -> validate -> test │ ──► │ Checkout Code -> OIDC Auth -> fmt -check -> Init       │
└───────────────────────┬───────────────────────┘     └───────────────────────────┬────────────────────────────┘
                        │                                                         │
                        ▼                                                         ▼
┌───────────────────────────────────────────────┐     ┌────────────────────────────────────────────────────────┐
│ pre-commit: TFLint -> Trivy -> terraform-docs │     │ Quality & Security: TFLint -> Trivy -> terraform test  │
└───────────────────────────────────────────────┘     └───────────────────────────┬────────────────────────────┘
                                                                                  │
                                                                                  ▼
 Managed Production Apply                               ┌────────────────────────────────────────────────────────┐
┌───────────────────────────────────────────────┐     │ Execution & Governance: Plan -> Infracost -> OPA Policy│
│ Apply Plan Changes -> Drift Monitoring Logs   │ ◄── │ Code Review -> Approval Gate                           │
└───────────────────────────────────────────────┘     └────────────────────────────────────────────────────────┘

---

PART 23 — LOCAL DEVELOPMENT SETUP

macOS Setup (Homebrew)

# Update Homebrew repositories
brew update

# Install Core Toolchain
brew install tenv tflint trivy terraform-docs infracost pre-commit

# Verify Binary Capabilities
tenv --version
tflint --version
trivy --version
terraform-docs --version
infracost --version
pre-commit --version

Linux (Ubuntu/Debian) Setup

# Install Tenv
curl -fsSL https://raw.githubusercontent.com/tofuutils/tenv/main/install.sh | bash

# Install TFLint
curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash

# Install Trivy
sudo apt-get install wget apt-transport-https gnupg lsb-release -y
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/trivy.list
sudo apt-get update && sudo apt-get install trivy -y

# Install terraform-docs
curl -sSLo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.18.0/terraform-docs-v0.18.0-linux-amd64.tar.gz
tar -xzf terraform-docs.tar.gz
sudo mv terraform-docs /usr/local/bin/

Windows Setup (Chocolatey)

choco install tenv tflint trivy terraform-docs infracost pre-commit

---

PART 24 — SAMPLE REAL PROJECT (PRODUCTION AWS MODULE)

File: providers.tf

terraform {
  required_version = ">= 1.9.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.60"
    }
  }
  backend "s3" {
    bucket         = "production-tf-state-vault-us-east-1"
    key            = "modules/production-workload/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-locks"
    encrypt        = true
  }
}

provider "aws" {
  region = var.aws_region
  default_tags {
    tags = {
      Environment = var.environment
      ManagedBy   = "Terraform"
    }
  }
}

File: variables.tf

variable "aws_region" {
  type        = string
  description = "AWS deployment target region."
  default     = "us-east-1"
}

variable "environment" {
  type        = string
  description = "Execution environment tier."
  default     = "production"
}

variable "vpc_cidr" {
  type        = string
  description = "Root CIDR range allocated to the VPC."
  default     = "10.50.0.0/16"
}

File: main.tf

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = {
    Name = "${var.environment}-vpc"
  }
}

resource "aws_subnet" "public" {
  vpc_id                  = aws_vpc.main.id
  cidr_block              = cidrsubnet(var.vpc_cidr, 8, 1)
  map_public_ip_on_launch = false

  tags = {
    Name = "${var.environment}-public-subnet-1"
  }
}

resource "aws_security_group" "app_server" {
  name        = "${var.environment}-app-security-group"
  description = "Strict egress-only security group for compute layer."
  vpc_id      = aws_vpc.main.id

  egress {
    description      = "Allow secure TLS outbound access."
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }

  tags = {
    Name = "${var.environment}-app-sg"
  }
}

File: outputs.tf

output "vpc_id" {
  type        = string
  value       = aws_vpc.main.id
  description = "Identifier assigned to the provisioned VPC."
}

output "subnet_id" {
  type        = string
  value       = aws_subnet.public.id
  description = "Identifier assigned to the public subnet layer."
}

File: tests/vpc_test.tftest.hcl

run "verify_vpc_subnet_math" {
  command = plan

  assert {
    condition     = aws_subnet.public.cidr_block == "10.50.1.0/24"
    error_message = "Subnet calculation did not produce the expected /24 CIDR allocation."
  }
}

---

PART 25 — COMMON DEVELOPER MISTAKES

┌─────────────────────────────────────────────────────────────────────────────┐
│                    20 Anti-Patterns to Avoid in Terraform                   │
└─────────────────────────────────────────────────────────────────────────────┘

 1. Hardcoding Credentials   ──► Use AWS OIDC Workload Identity with GitHub Actions.
 2. Committing State to Git  ──► Add *.tfstate to .gitignore; use remote S3/HCP backends.
 3. Unpinned Providers       ──► Pin explicitly: version = "~> 5.60" in required_providers.
 4. Unpinned Modules         ──► Pin module source: ?ref=v1.4.0 or version = "2.1.0".
 5. Running Apply Locally    ──► Run terraform apply via CI/CD, Atlantis, or HCP Terraform.
 6. Huge Root Modules        ──► Split code into smaller, isolated functional modules.
 7. Overusing Workspaces     ──► Use distinct directories for separate cloud environments.
 8. Skipping Lock Tables     ──► Configure DynamoDB for S3 backends to prevent concurrent runs.
 9. Blind Apply (-auto-approve) ► Always require human review or policy checks on plan outputs.
10. Skipping terraform fmt   ──► Automate formatting checks with pre-commit hooks and CI gates.
11. Ignoring TFLint Rules    ──► Fix lint warnings early to catch invalid instance types.
12. Ignoring Security Scans  ──► Block PR merges on HIGH or CRITICAL Trivy scanner findings.
13. Skipping Native Tests    ──► Write .tftest.hcl suites for complex variable and resource logic.
14. Manual Cloud Edits       ──► Avoid console edits; import resources properly into Terraform state.
15. Abusing -target          ──► Resolve dependency issues in code instead of forcing -target.
16. Naked Variable Types     ──► Define explicit types and descriptions for all input variables.
17. Hardcoding Passwords     ──► Retrieve secrets dynamically from AWS Secrets Manager or Vault.
18. Missing Tags             ──► Enforce resource tags using default_tags provider configurations.
19. Blind State Removal      ──► Backup state files before running terraform state rm operations.
20. Accepting Blind AI Code  ──► Review and scan AI-generated code before committing to Git.

---

PART 26 — SECURITY BEST PRACTICES

                                Security Checklist
┌─────────────────────────────────────────────────────────────────────────────┐
│ Credentials & Access                                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ [ ] Zero static cloud access keys stored in developer environments or repos │
│ [ ] CI/CD platforms configured with OIDC Keyless Authentication             │
│ [ ] Least-privilege IAM roles mapped to individual deployment pipelines     │
│                                                                             │
│ State Management                                                            │
├─────────────────────────────────────────────────────────────────────────────┤
│ [ ] S3 backend state buckets protected with KMS encryption at rest          │
│ [ ] DynamoDB configured for state lock operations                           │
│ [ ] Access to state storage restricted to CI deployment pipeline roles      │
│                                                                             │
│ Pipeline & Enforcement                                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│ [ ] Static code scanning (Trivy/Checkov) enabled in pre-commit and CI       │
│ [ ] Policy-as-Code checks (OPA/Sentinel) blocking non-compliant PRs        │
│ [ ] Module and provider dependencies pinned to exact semantic versions      │
└─────────────────────────────────────────────────────────────────────────────┘

---

PART 27 — TERRAFORM CODE REVIEW CHECKLIST

                                Pull Request Review
┌─────────────────────────────────────────────────────────────────────────────┐
│ Structural & Quality Checks                                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│ [ ] terraform fmt -check completed without errors                           │
│ [ ] terraform validate and TFLint completed without warnings                │
│ [ ] Module README files updated via terraform-docs                          │
│                                                                             │
│ Testing & Safety                                                            │
├─────────────────────────────────────────────────────────────────────────────┤
│ [ ] Unit tests (.tftest.hcl) cover new variable constraints and paths       │
│ [ ] Plan diff inspected; no unintended resource destructions                │
│ [ ] Infracost report reviewed for unexpected monthly cost increases        │
│                                                                             │
│ Security & Compliance                                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ [ ] Zero hardcoded plain-text secrets or credentials                        │
│ [ ] Resource security configurations pass Trivy/Checkov static scans         │
│ [ ] Mandatory organizational tags attached via provider defaults             │
└─────────────────────────────────────────────────────────────────────────────┘

---

PART 28 — TERRAFORM PRODUCTIVITY BEST PRACTICES

1. Automate Quality Locally: Catch syntax errors and formatting issues before pushing code by using pre-commit-terraform.
2. Speed Up AI Generation: Provide context to your AI assistant using the Terraform MCP Server so it uses current provider schemas.
3. Use Version Managers: Pin your infrastructure tool versions per repository with tenv and a .terraform-version file.
4. Enforce Consistent Standards: Auto-generate input/output documentation tables in your README.md using terraform-docs.
5. Catch Cost Spikes Early: Review Infracost delta estimates directly in pull request comments before merging changes.

---

PART 29 — TOOL OVERLAP AND DECISION GUIDE

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Tool Selection Matrix                              │
└─────────────────────────────────────────────────────────────────────────────┘

                  Validation Engine
           ┌──────────────┴──────────────┐
           ▼                             ▼
   terraform validate                  TFLint
┌───────────────────────────┐ ┌───────────────────────────┐
│ Basic HCL syntax, types,  │ │ Deep provider rules,      │
│ and internal references   │ │ deprecated attributes     │
└───────────────────────────┘ └───────────────────────────┘

                  Security Scanning
           ┌──────────────┴──────────────┐
           ▼                             ▼
         Trivy                        Checkov
┌───────────────────────────┐ ┌───────────────────────────┐
│ Fast, unified container   │ │ Deep regulatory frameworks│
│ & IaC vulnerability engine│ │ (CIS Benchmarks, NIST)    │
└───────────────────────────┘ └───────────────────────────┘

                  Policy-as-Code
           ┌──────────────┴──────────────┐
           ▼                             ▼
        Sentinel                       OPA
┌───────────────────────────┐ ┌───────────────────────────┐
│ HCP Terraform integrated, │ │ Vendor-neutral, Rego-based│
│ HashiCorp native engine   │ │ cloud-native policy engine│
└───────────────────────────┘ └───────────────────────────┘

---

PART 30 — FINAL GOLD STANDARD RECOMMENDATION

Complete Tooling Baseline

Developer Workstation
        │
        ├─► VS Code / Cursor / Claude Code
        ├─► HashiCorp Terraform Extension
        ├─► Terraform MCP Server
        ├─► tenv
        └─► Local CLI Utilities
              ├─► terraform (fmt, validate, test)
              ├─► TFLint
              ├─► Trivy
              ├─► terraform-docs
              ├─► Infracost
              └─► pre-commit-terraform
                    │
                    ▼
Source Control & Remote Automation
        │
        ├─► Git (GitHub / GitLab)
        ├─► CI Pipeline Engine (GitHub Actions / GitLab CI)
        ├─► Keyless Authentication (OIDC)
        ├─► Remote Platform (HCP Terraform / Atlantis)
        └─► Compliance Engine (OPA / Conftest / Sentinel)

Classification Reference

Classification	Tools Included
MUST HAVE	Terraform CLI, VS Code, HashiCorp Extension, terraform-ls, tenv, TFLint, Trivy, terraform test, terraform-docs, pre-commit-terraform, Git, GitHub Actions / GitLab CI
STRONGLY RECOMMENDED	Terraform MCP Server, Infracost, OIDC Workload Identity, Renovate Bot, Conftest / OPA
OPTIONAL	Terragrunt, Atlantis, Checkov, tfupdate, Terratest
ENTERPRISE	HCP Terraform / Terraform Enterprise, Sentinel Policy Engine, Private Module Registry, Run Tasks

---

Pre-Merge Checklist

[ ] Code formatted with terraform fmt -recursive
[ ] Internal references verified with terraform validate
[ ] Provider rules and best practices checked with tflint
[ ] IaC misconfigurations scanned with trivy config .
[ ] Functional logic verified with terraform test
[ ] Module documentation updated with terraform-docs
[ ] Pre-commit hooks passed successfully
[ ] Keyless OIDC authentication used in CI pipeline
[ ] Infrastructure plan reviewed and approved in Pull Request