Terraform Best Practices 2025: Structure, State, Security, and CI/CD

Project Structure

A consistent project structure prevents confusion as your team and codebase grow. Use this pattern for medium to large projects:

project/
├── main.tf          # Root module — call child modules
├── variables.tf     # All input variable declarations
├── outputs.tf       # All output declarations
├── providers.tf     # Provider and version constraints
├── versions.tf      # terraform {} block with required_version
├── locals.tf        # Local values (avoid inline locals)
├── data.tf          # Data source lookups
├── terraform.tfvars.example  # Example values (no secrets!)
└── modules/
    ├── networking/
    ├── compute/
    └── database/

State Management

State is the most operationally sensitive part of Terraform. Follow these rules:

• Always use remote backends — S3+DynamoDB, Azure Blob, GCS, or Terraform Cloud
• Enable state locking — DynamoDB for S3, always enabled for Terraform Cloud
• Enable state encryption — encrypt = true in your S3 backend
• Never commit state files — add *.tfstate and *.tfstate.backup to .gitignore
• Separate state per environment — dev, staging, prod must never share state

terraform {
  backend "s3" {
    bucket         = "company-tf-state-prod"
    key            = "services/api/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-locks"
  }
}

Module Design

Modules should be small, focused, and reusable. Follow these principles:

• One module per logical resource group (VPC, compute cluster, database)
• Never nest more than 3 levels deep
• Always document input/output variables with description
• Pin module versions when using the Terraform Registry
• Use count or for_each instead of duplicating resources

variable "instance_count" {
  description = "Number of EC2 instances to launch"
  type        = number
  default     = 2
  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    error_message = "Instance count must be between 1 and 20."
  }
}

Security Best Practices

• Use OIDC for CI/CD authentication — no long-lived AWS access keys in GitHub Secrets
• Least-privilege IAM — your Terraform IAM user/role should have only what it needs
• Secrets via Secrets Manager — never put passwords or API keys in .tfvars or state
• Run tfsec or Checkov — catch misconfigurations before they reach production
• Enable S3 versioning on state bucket — allows rolling back accidental state corruption

Testing Terraform Code

Treat infrastructure code with the same rigour as application code:

• terraform validate — syntax and type checking, run in every PR
• tflint — provider-specific linting rules for AWS, Azure, GCP
• Checkov / tfsec — security scanning before apply
• Terratest (Go) — write unit and integration tests for modules
• Infracost — cost estimation before merge to prevent surprise cloud bills