TERRAFORM

Installation Methods

Terraform ships as a single binary. Download it for your platform or use a package manager.

For the APT method, you must first add the HashiCorp GPG key and repository:

# Add HashiCorp GPG key
wget -O- https://apt.releases.hashicorp.com/gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

# Add the repository
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
  https://apt.releases.hashicorp.com $(lsb_release -cs) main" | \
  sudo tee /etc/apt/sources.list.d/hashicorp.list

# Update and install
sudo apt-get update && sudo apt-get install terraform

# Verify
terraform version

Provider Configuration

Every Terraform project declares the providers it requires in a required_providers block. This tells Terraform where to download the provider plugin and which versions are acceptable.

# terraform.tf or versions.tf
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

# Provider configuration with region and default tags
provider "aws" {
  region = "us-east-1"

  default_tags {
    tags = {
      Environment = "production"
      ManagedBy   = "terraform"
    }
  }
}

Backend Configuration

Remote backends store state outside your local filesystem, enabling team collaboration and state locking. The most common setups:

# AWS S3 backend with DynamoDB locking
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "prod/network/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

# Azure Blob Storage backend
terraform {
  backend "azurerm" {
    resource_group_name  = "tfstate-rg"
    storage_account_name = "tfstateaccount"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"
  }
}

# Google Cloud Storage backend
terraform {
  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "terraform/state"
  }
}

Init Workflow

The terraform init command is the first command you run in any Terraform configuration directory. It performs three main tasks:

Version Pinning

After terraform init, Terraform creates a .terraform.lock.hcl file that records the exact provider versions and checksums selected. Commit this file to version control.

# .terraform.lock.hcl (auto-generated, commit to VCS)
provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.31.0"
  constraints = "~> 5.0"
  hashes = [
    "h1:abc123...",
    "zh:def456...",
  ]
}

# .gitignore for Terraform projects
.terraform/
*.tfstate
*.tfstate.*
*.tfplan
crash.log
override.tf
override.tf.json
*_override.tf
*_override.tf.json

Resource Blocks

A resource block declares a piece of infrastructure. Terraform manages the full lifecycle: creation, in-place updates, replacement, and destruction. Each resource has a type (determined by the provider) and a local name used for references within the configuration.

# Syntax: resource "TYPE" "LOCAL_NAME" { ... }
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
  subnet_id     = aws_subnet.public[0].id

  root_block_device {
    volume_size = 20
    volume_type = "gp3"
    encrypted   = true
  }

  tags = {
    Name = "${local.name_prefix}-web"
  }
}

# Reference attributes: RESOURCE_TYPE.LOCAL_NAME.ATTRIBUTE
output "web_ip" {
  value = aws_instance.web.public_ip
}

When you run terraform apply, Terraform compares the desired state (your HCL) against the current state (the state file). It then calculates the minimum set of API calls needed to reconcile the two. Resources are created if new, updated in-place when possible, or destroyed and recreated when a change forces replacement.

Data Sources

Data sources are read-only queries to existing infrastructure or external systems. They do not create or modify anything. Use them to look up AMIs, fetch existing VPC IDs, read secrets, or reference resources managed outside your configuration.

# Look up the latest Ubuntu AMI
data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["099720109477"] # Canonical

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }
}

# Use the data source result in a resource
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
}

# Fetch an existing VPC by tag
data "aws_vpc" "main" {
  filter {
    name   = "tag:Name"
    values = ["production-vpc"]
  }
}

# Read remote state from another project
data "terraform_remote_state" "network" {
  backend = "s3"

  config = {
    bucket = "my-terraform-state"
    key    = "network/terraform.tfstate"
    region = "us-east-1"
  }
}

# Reference: data.terraform_remote_state.network.outputs.vpc_id

Meta-Arguments

Meta-arguments are special arguments available on every resource block, regardless of provider. They control how Terraform manages the resource rather than configuring its attributes.

# count — create multiple identical instances
resource "aws_instance" "worker" {
  count         = 3
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
  subnet_id     = element(var.subnet_ids, count.index)

  tags = {
    Name = "worker-${count.index}"
  }
}

# count as a conditional (0 or 1)
resource "aws_lb" "main" {
  count = var.create_lb ? 1 : 0
  name  = "${local.name_prefix}-lb"
  # ...
}

# Reference: aws_lb.main[0].dns_name (must check length)

# for_each with a map — create subnets per AZ
resource "aws_subnet" "private" {
  for_each = {
    "us-east-1a" = "10.0.1.0/24"
    "us-east-1b" = "10.0.2.0/24"
    "us-east-1c" = "10.0.3.0/24"
  }

  vpc_id            = aws_vpc.main.id
  availability_zone = each.key
  cidr_block        = each.value

  tags = {
    Name = "private-${each.key}"
  }
}

# for_each with a set of strings
resource "aws_iam_user" "devs" {
  for_each = toset(["alice", "bob", "carol"])
  name     = each.value
}

# Reference: aws_subnet.private["us-east-1a"].id

# depends_on — explicit dependency when Terraform can't infer it
resource "aws_instance" "app" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  # Wait for the IAM role policy to be attached before launching
  depends_on = [aws_iam_role_policy_attachment.app_policy]
}

# provider — select a specific provider configuration
provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

resource "aws_instance" "west_server" {
  provider      = aws.west
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"
}

Lifecycle Rules

The lifecycle block customizes how Terraform handles resource creation, update, and destruction. Every rule is declared inside a lifecycle { } block within the resource.

# create_before_destroy — zero-downtime replacements
resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = "t3.micro"

  lifecycle {
    create_before_destroy = true
  }
}

# prevent_destroy — protect critical resources
resource "aws_db_instance" "primary" {
  identifier     = "production-db"
  engine         = "postgres"
  instance_class = "db.r6g.xlarge"

  lifecycle {
    prevent_destroy = true
  }
}

# ignore_changes — ignore external modifications
resource "aws_instance" "managed" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"

  lifecycle {
    # ASG or external process may update these tags
    ignore_changes = [tags, instance_type]
  }
}

# replace_triggered_by — force replacement when another resource changes
resource "aws_instance" "app" {
  ami           = var.ami_id
  instance_type = "t3.micro"

  lifecycle {
    replace_triggered_by = [
      null_resource.config_hash.id
    ]
  }
}

# Combining multiple lifecycle rules
resource "aws_launch_template" "web" {
  name_prefix   = "web-"
  image_id      = var.ami_id
  instance_type = "t3.micro"

  lifecycle {
    create_before_destroy = true
    ignore_changes        = [description]
  }
}

Provisioners

Provisioners execute scripts on a local or remote machine as part of resource creation or destruction. They are a last resort for bootstrapping that cannot be done through provider-native features.

# local-exec — run a command on the machine running Terraform
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  provisioner "local-exec" {
    command = "echo ${self.private_ip} >> inventory.txt"
  }
}

# remote-exec — run commands on the created resource via SSH
resource "aws_instance" "app" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
  key_name      = aws_key_pair.deploy.key_name

  connection {
    type        = "ssh"
    user        = "ubuntu"
    private_key = file("~/.ssh/deploy.pem")
    host        = self.public_ip
  }

  provisioner "remote-exec" {
    inline = [
      "sudo apt-get update",
      "sudo apt-get install -y nginx",
      "sudo systemctl start nginx",
    ]
  }
}

terraform_data vs null_resource

The terraform_data resource (Terraform 1.4+) is the modern replacement for null_resource. Both serve as generic containers for provisioners and triggers, but terraform_data is built into Terraform core and does not require the hashicorp/null provider.

# Legacy approach — null_resource (requires null provider)
resource "null_resource" "config_update" {
  triggers = {
    config_hash = sha256(file("config.yaml"))
  }

  provisioner "local-exec" {
    command = "./deploy-config.sh"
  }
}

# Modern approach — terraform_data (TF 1.4+, no extra provider)
resource "terraform_data" "config_update" {
  input = sha256(file("config.yaml"))

  provisioner "local-exec" {
    command = "./deploy-config.sh"
  }
}

# terraform_data with replacement triggers
resource "terraform_data" "bootstrap" {
  triggers_replace = [
    aws_instance.web.id,
    var.app_version,
  ]

  provisioner "local-exec" {
    command = "ansible-playbook -i '${aws_instance.web.public_ip},' deploy.yml"
  }
}

Module Structure

A well-structured module follows a standard directory layout. Every Terraform directory is implicitly a module — the root directory is the root module, and any module called via a module block is a child module.

# Standard module directory layout
modules/
  vpc/
    main.tf           # Primary resource definitions
    variables.tf      # Input variable declarations
    outputs.tf        # Output value declarations
    versions.tf       # Required providers and Terraform version
    README.md         # Documentation (used by registry)
    locals.tf         # Local value computations (optional)
    data.tf           # Data source lookups (optional)

# versions.tf — pin provider requirements in child modules
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0"
    }
  }
}

# variables.tf — define the module's inputs
variable "vpc_cidr" {
  description = "CIDR block for the VPC"
  type        = string
  default     = "10.0.0.0/16"
}

variable "environment" {
  description = "Environment name (dev, staging, prod)"
  type        = string
}

# outputs.tf — expose values to the caller
output "vpc_id" {
  description = "ID of the created VPC"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "List of private subnet IDs"
  value       = aws_subnet.private[*].id
}

Module Sources

The source argument in a module block tells Terraform where to find the module code. Terraform supports many source types.

# Local path — relative to the calling module
module "vpc" {
  source      = "./modules/vpc"
  vpc_cidr    = "10.0.0.0/16"
  environment = "production"
}

# Terraform Registry (public)
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "production-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway = true
  single_nat_gateway = true
}

# GitHub (HTTPS)
module "app" {
  source = "github.com/my-org/terraform-modules//modules/app?ref=v2.1.0"
}

# GitHub (SSH)
module "app" {
  source = "git@github.com:my-org/terraform-modules.git//modules/app?ref=v2.1.0"
}

# Generic Git repository
module "networking" {
  source = "git::https://git.example.com/infra/modules.git//networking?ref=main"
}

# S3 bucket (versioned zip archive)
module "legacy" {
  source = "s3::https://s3-us-east-1.amazonaws.com/my-modules/vpc/v1.2.0.zip"
}

Module Versioning

Version constraints control which versions of a module are acceptable. Versioning is supported for Terraform Registry modules and can be simulated for Git sources using ref.

# Registry module with pessimistic version constraint
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"  # any 20.x.x
  # ...
}

# Git source with tag
module "network" {
  source = "git@github.com:my-org/modules.git//network?ref=v3.2.0"
}

# Git source with branch
module "network" {
  source = "git@github.com:my-org/modules.git//network?ref=main"
}

# Git source with commit SHA (most reproducible)
module "network" {
  source = "git@github.com:my-org/modules.git//network?ref=a1b2c3d"
}

Module Composition

Large infrastructure configurations should be composed from small, focused modules rather than written as a single monolith. Two common patterns emerge: the composition pattern and the facade pattern.

# Composition pattern — assembling small modules in the root
# Each module handles one concern

module "network" {
  source      = "./modules/network"
  vpc_cidr    = "10.0.0.0/16"
  environment = var.environment
}

module "database" {
  source     = "./modules/database"
  subnet_ids = module.network.private_subnet_ids
  vpc_id     = module.network.vpc_id
}

module "application" {
  source          = "./modules/application"
  subnet_ids      = module.network.public_subnet_ids
  db_endpoint     = module.database.endpoint
  db_port         = module.database.port
  security_groups = [module.network.app_sg_id]
}

# Facade pattern — a high-level module that wraps lower-level modules
# modules/platform/main.tf

module "network" {
  source      = "../network"
  vpc_cidr    = var.vpc_cidr
  environment = var.environment
}

module "database" {
  source     = "../database"
  subnet_ids = module.network.private_subnet_ids
  vpc_id     = module.network.vpc_id
}

module "application" {
  source      = "../application"
  subnet_ids  = module.network.public_subnet_ids
  db_endpoint = module.database.endpoint
}

# Caller uses the facade with minimal configuration
# root main.tf
module "platform" {
  source      = "./modules/platform"
  environment = "production"
  vpc_cidr    = "10.0.0.0/16"
}

Root vs Child Modules

Every Terraform run operates on a root module — the directory where you invoke terraform plan/apply. Any module called from the root (or from other child modules) is a child module. Understanding their different responsibilities is important.

Passing Data Between Modules

Modules communicate through inputs (variables) and outputs. The output of one module becomes the input to another. This creates an explicit dependency graph that Terraform uses for ordering.

# Module A (network) — outputs.tf
output "vpc_id" {
  description = "The VPC ID"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "Private subnet IDs"
  value       = aws_subnet.private[*].id
}

# Module B (compute) — variables.tf
variable "vpc_id" {
  description = "VPC to deploy into"
  type        = string
}

variable "subnet_ids" {
  description = "Subnets for the instances"
  type        = list(string)
}

# Root module — wiring modules together
module "network" {
  source      = "./modules/network"
  environment = var.environment
}

module "compute" {
  source     = "./modules/compute"
  vpc_id     = module.network.vpc_id            # output -> input
  subnet_ids = module.network.private_subnet_ids # output -> input
}

# Terraform automatically knows to create network before compute

Terraform Registry

The Terraform Registry hosts public modules and providers. Public modules follow a strict naming convention and are versioned with semantic versioning.

# Using popular registry modules

# AWS VPC module (most downloaded Terraform module)
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "my-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway   = true
  single_nat_gateway   = true
  enable_dns_hostnames = true

  tags = local.common_tags
}

# AWS EKS module
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name    = "production"
  cluster_version = "1.30"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnets

  eks_managed_node_groups = {
    default = {
      min_size     = 2
      max_size     = 10
      desired_size = 3

      instance_types = ["t3.medium"]
    }
  }
}

# Using a private registry module
module "internal_app" {
  source  = "app.terraform.io/my-company/app-template/aws"
  version = "~> 2.0"

  app_name    = "billing-service"
  environment = "production"
}

CLI Workspaces

Terraform CLI workspaces let you maintain separate state instances from a single configuration directory. Each workspace has its own terraform.tfstate file, but all share the same code and backend configuration.

Workspace-Based Environments

Use terraform.workspace to vary configuration based on the active workspace. A common pattern uses a locals map to define environment-specific settings:

# locals.tf — environment-specific configuration via workspace
locals {
  env_config = {
    dev = {
      instance_type = "t3.micro"
      instance_count = 1
      db_class       = "db.t3.micro"
      multi_az       = false
    }
    staging = {
      instance_type  = "t3.small"
      instance_count = 2
      db_class       = "db.t3.small"
      multi_az       = false
    }
    production = {
      instance_type  = "t3.large"
      instance_count = 3
      db_class       = "db.r6g.large"
      multi_az       = true
    }
  }

  # Select config for the active workspace
  config = local.env_config[terraform.workspace]
}

# main.tf — use workspace-driven values
resource "aws_instance" "app" {
  count         = local.config.instance_count
  instance_type = local.config.instance_type
  ami           = data.aws_ami.ubuntu.id

  tags = {
    Name        = "app-${terraform.workspace}-${count.index}"
    Environment = terraform.workspace
  }
}

resource "aws_db_instance" "main" {
  instance_class = local.config.db_class
  multi_az       = local.config.multi_az
  identifier     = "app-db-${terraform.workspace}"
}

Directory-Based Structure

The recommended approach for production environments is a directory-based layout. Each environment gets its own directory with its own backend configuration and state file, providing full isolation.

# Recommended directory layout
infrastructure/
  modules/
    vpc/
      main.tf
      variables.tf
      outputs.tf
    app/
      main.tf
      variables.tf
      outputs.tf
  environments/
    dev/
      main.tf           # Calls modules with dev values
      backend.tf        # Dev-specific state backend
      terraform.tfvars  # Dev variable values
    staging/
      main.tf
      backend.tf
      terraform.tfvars
    production/
      main.tf
      backend.tf
      terraform.tfvars

Approach Comparison

Pros & Cons of CLI Workspaces

terraform validate

The fastest feedback loop. terraform validate checks configuration syntax and internal consistency without accessing any remote services or state. It catches typos, missing required arguments, and invalid references — no credentials needed.

# Basic validation (requires terraform init first)
terraform validate

# JSON output for CI/CD pipelines
terraform validate -json

# Example JSON output
{
  "valid": false,
  "error_count": 1,
  "warning_count": 0,
  "diagnostics": [
    {
      "severity": "error",
      "summary": "Missing required argument",
      "detail": "The argument \"region\" is required."
    }
  ]
}

Native Testing Framework

Terraform 1.6 introduced a built-in testing framework using .tftest.hcl files. Tests live alongside your configuration and use run blocks with assertions to verify plan and apply behavior. No external tools or languages required.

# tests/basic.tftest.hcl

# Global variables for all run blocks
variables {
  project_name = "test-project"
  environment  = "test"
}

# Plan-only test — fast, no real infrastructure
run "validates_instance_type" {
  command = plan

  assert {
    condition     = aws_instance.web.instance_type == "t3.micro"
    error_message = "Instance type must be t3.micro"
  }
}

# Apply test — creates real resources, then destroys
run "creates_s3_bucket" {
  command = apply

  assert {
    condition     = aws_s3_bucket.data.bucket_regional_domain_name != ""
    error_message = "Bucket should have a regional domain name after creation"
  }

  assert {
    condition     = aws_s3_bucket.data.tags["Environment"] == "test"
    error_message = "Bucket must be tagged with the correct environment"
  }
}

# Override variables in a specific run block
run "validates_production_sizing" {
  command = plan

  variables {
    environment  = "production"
    instance_type = "m5.xlarge"
  }

  assert {
    condition     = aws_instance.web.instance_type == "m5.xlarge"
    error_message = "Production should use m5.xlarge"
  }
}

# Run all tests
terraform test

# Run tests with verbose output
terraform test -verbose

# Run a specific test file
terraform test -filter=tests/basic.tftest.hcl

# JSON output for CI
terraform test -json

Provider Mocking

Terraform 1.7 added mock providers for fast unit tests that never touch real infrastructure. Mock providers simulate provider behavior, returning placeholder values so you can test module logic, variable validation, and output expressions without any API calls.

# tests/unit.tftest.hcl — mock provider tests

# Mock the AWS provider entirely
mock_provider "aws" {}

# All resources get synthetic values; no real API calls
run "test_naming_convention" {
  command = plan

  variables {
    project_name = "payments"
    environment  = "staging"
  }

  assert {
    condition     = aws_s3_bucket.data.bucket == "payments-staging-data"
    error_message = "Bucket name should follow {project}-{env}-data pattern"
  }
}

# Mock with overridden data for specific resources
mock_provider "aws" {
  alias = "with_data"

  mock_data "aws_caller_identity" {
    defaults = {
      account_id = "123456789012"
      arn        = "arn:aws:iam::123456789012:root"
    }
  }
}

run "test_account_id_usage" {
  command = plan

  providers = {
    aws = aws.with_data
  }

  assert {
    condition     = contains(aws_iam_policy.deploy.policy, "123456789012")
    error_message = "Policy should reference the correct account ID"
  }
}

Third-Party Testing Tools

CI/CD Integration

Integrate testing into your pipeline with a layered approach: fast checks first, then progressively more expensive validations.

# Example: GitHub Actions workflow for Terraform CI
name: Terraform CI
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3

      # Layer 1: Format check (instant)
      - name: Check formatting
        run: terraform fmt -check -recursive

      # Layer 2: Validate syntax (fast, no creds)
      - name: Init & validate
        run: |
          terraform init -backend=false
          terraform validate -json

      # Layer 3: Lint (seconds)
      - name: TFLint
        uses: terraform-linters/setup-tflint@v4
        run: tflint --recursive

      # Layer 4: Security scan (seconds)
      - name: Trivy / tfsec
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: config

      # Layer 5: Native tests (seconds for mocked, minutes for apply)
      - name: Terraform test
        run: terraform test

      # Layer 6: Plan (requires credentials)
      - name: Plan
        run: terraform plan -out=tfplan -no-color
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Project Structure

Simple layout — for small projects or single environments:

project/
  main.tf           # Resources
  variables.tf      # Input variable declarations
  outputs.tf        # Output declarations
  terraform.tf      # Provider & backend config
  terraform.tfvars  # Variable values (not committed)

Modular layout — for reusable components:

project/
  modules/
    networking/
      main.tf
      variables.tf
      outputs.tf
    compute/
      main.tf
      variables.tf
      outputs.tf
  environments/
    dev/
      main.tf       # Calls modules with dev settings
      terraform.tf
      dev.tfvars
    staging/
      main.tf
      terraform.tf
      staging.tfvars
    production/
      main.tf
      terraform.tf
      prod.tfvars

Component-based layout — for large organizations with independent teams:

infrastructure/
  components/
    networking/       # Separate state per component
      main.tf
      backend.tf
    database/
      main.tf
      backend.tf
    application/
      main.tf
      backend.tf      # References networking/database via remote state
  modules/            # Shared modules used by components
    vpc/
    rds/
    ecs/

Naming Conventions

Tagging Strategy

Consistent tagging is essential for cost tracking, access control, and operational management. Define standard tags in the provider's default_tags block and supplement per-resource.

# Provider-level default tags (applied to all resources)
provider "aws" {
  region = var.region

  default_tags {
    tags = {
      Environment = var.environment
      Project     = var.project_name
      ManagedBy   = "terraform"
      Owner       = var.team_name
      CostCenter  = var.cost_center
    }
  }
}

# Per-resource tags (merged with default_tags)
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type

  tags = {
    Name = "${var.project_name}-web-${var.environment}"
    Role = "webserver"
  }
}

.gitignore for Terraform

# Terraform .gitignore

# Local .terraform directories
**/.terraform/*

# .tfstate files (state should live in remote backend)
*.tfstate
*.tfstate.*

# Crash log files
crash.log
crash.*.log

# Variable files that may contain secrets
*.tfvars
*.tfvars.json

# Override files (used for local dev overrides)
override.tf
override.tf.json
*_override.tf
*_override.tf.json

# CLI configuration files
.terraformrc
terraform.rc

# KEEP the lock file committed
# !.terraform.lock.hcl

Formatting & Linting

# Format all files in current directory (recursive)
terraform fmt -recursive

# Check formatting without modifying (for CI)
terraform fmt -check -recursive -diff

# Pre-commit hook configuration (.pre-commit-config.yaml)
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.96.1
    hooks:
      - id: terraform_fmt
      - id: terraform_validate
      - id: terraform_tflint
      - id: terraform_docs
      - id: terraform_trivy

Security

Cost Estimation & Documentation

# Infracost — cost breakdown from plan
infracost breakdown --path=.

# Infracost in CI — comment on PR with cost diff
infracost diff --path=. \
  --compare-to=infracost-base.json \
  --format=json > infracost-diff.json

infracost comment github \
  --path=infracost-diff.json \
  --repo=myorg/myrepo \
  --pull-request=$PR_NUMBER

# terraform-docs — auto-generate module README
terraform-docs markdown table --output-file README.md .

# terraform-docs in pre-commit
repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: v0.19.0
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md"]

Version Pinning

terraform {
  # Pin Terraform itself to a minor version range
  required_version = ">= 1.7.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      # Pin provider to a minor version range
      version = "~> 5.40"  # Allows 5.40.x, 5.41.x, etc.
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

# Version constraint operators:
# =  1.0.0    Exact version
# != 1.0.0    Exclude version
# >  1.0.0    Greater than
# >= 1.0.0    Greater than or equal
# <  2.0.0    Less than
# ~> 1.0      Pessimistic (allows 1.x, not 2.0)
# ~> 1.0.0    Pessimistic (allows 1.0.x, not 1.1.0)

Top 10 Best Practices