Terraform

Terraform Best Practices

Terraform configurations are production-grade software. Treat them with the same rigor: readable, versioned, testable, and governed by automated policies. This guide provides opinionated, actionable best practices for our team's Terraform development, ensuring consistency, reliability, and security.

1. Code Organization and Structure

Organize your Terraform code for clarity, reusability, and environment isolation.

1.1 Project Layout

Always separate environments and reusable components.

❌ BAD: Monolithic main.tf or environment-specific resources mixed with modules.

# environments/dev/main.tf
resource "aws_vpc" "dev_vpc" { # ... }
resource "aws_s3_bucket" "dev_app_bucket" { # ... }
# Duplicated for staging/prod

✅ GOOD: Dedicated directories for environments and shared modules.

├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── backend.tf
│   │   └── terraform.tfvars
│   ├── prod/
│       ├── main.tf
│       ├── variables.tf
│       ├── backend.tf
│       └── terraform.tfvars
├── modules/
│   ├── vpc/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── s3_bucket/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf

1.2 Standard File Naming

Use HashiCorp's recommended file naming conventions for consistency.

• backend.tf: Remote state configuration.
• main.tf: Primary resource and module calls.
• outputs.tf: All output blocks, alphabetically sorted.
• providers.tf: terraform block (required version/providers) and provider blocks.
• variables.tf: All variable blocks, alphabetically sorted.
• locals.tf: Local values.

2. Naming Conventions

Consistency in naming is paramount for readability.

2.1 Resource and Variable Names

Use lower_snake_case for all resource, data source, variable, and output names. Never include the resource type in the name.

❌ BAD:

resource "aws_s3_bucket" "s3_bucket_app_logs" { # ... }
variable "vpcName" { # ... }

✅ GOOD:

resource "aws_s3_bucket" "app_logs" { # ... }
variable "vpc_name" { # ... }

2.2 Boolean Variables

Use positive boolean flags ending with _enabled.

❌ BAD:

variable "disable_encryption" { type = bool }

✅ GOOD:

variable "encryption_enabled" { type = bool }

2.3 Descriptions

Every variable and output block must include a description.

variable "instance_type" {
  description = "The EC2 instance type to use for the server."
  type        = string
  default     = "t3.micro"
}

output "vpc_id" {
  description = "The ID of the created VPC."
  value       = aws_vpc.main.id
}

3. State Management

Remote state and locking are non-negotiable for team collaboration.

3.1 Remote State and Locking

Always use a remote backend (e.g., S3 with DynamoDB locking). Never rely on local state in shared environments.

# backend.tf
terraform {
  backend "s3" {
    bucket         = "my-team-terraform-state"
    key            = "environments/prod/app/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock" # Must be pre-created
    encrypt        = true
  }
}

3.2 Workspaces

Avoid terraform workspace for environment isolation. Use separate backend configurations in distinct directories (e.g., environments/dev, environments/prod) instead. Workspaces are primarily for ephemeral, short-lived deployments or testing variations within a single configuration.

4. Modules: Reusability and Abstraction

Modules are the cornerstone of scalable Terraform.

4.1 Module Design

Design modules to be single-purpose, composable, and reusable. Abstract implementation details.

❌ BAD: A module that creates a VPC, an RDS instance, and an S3 bucket. ✅ GOOD: Separate modules for vpc, rds_instance, and s3_bucket.

4.2 Module Inputs and Outputs

• Inputs: Parameterize only what needs to vary. Use nullable = false for variables that should never be null (especially lists, maps, objects defaulting to empty).
• Outputs: Provide meaningful outputs with descriptions. Never pass outputs directly through input variables; reference resource attributes to ensure implicit dependencies.

# modules/vpc/variables.tf
variable "vpc_cidr" {
  description = "CIDR block for the VPC."
  type        = string
}

variable "tags" {
  description = "A map of tags to assign to all resources in the VPC."
  type        = map(string)
  default     = {}
  nullable    = false # Ensure tags is always a map, even if empty
}

# modules/vpc/outputs.tf
output "vpc_id" {
  description = "The ID of the created VPC."
  value       = aws_vpc.main.id
}

5. Common Patterns and Anti-patterns

5.1 Loops and Conditionals (for_each, count)

Use for_each for creating multiple instances of a resource when you have a map or set of strings, as it provides better state management and readability than count. Use count for simple numeric iteration or conditional resource creation (when count is 0 or 1).

❌ BAD: Using count with a map for resource creation.

resource "aws_instance" "app_servers" {
  count = length(var.instance_configs) # var.instance_configs is a map
  # ...
  tags = {
    Name = var.instance_configs[count.index].name
  }
}

✅ GOOD: Using for_each with a map for resource creation.

resource "aws_instance" "app_servers" {
  for_each = var.instance_configs # var.instance_configs is a map of objects
  # ...
  tags = {
    Name = each.value.name
  }
}

5.2 Dynamic Blocks

Use dynamic blocks to construct repeatable nested blocks based on a complex variable.

resource "aws_security_group" "web" {
  # ...
  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.from_port
      to_port     = ingress.value.to_port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
    }
  }
}

5.3 Tagging Resources

Always tag all resources with meaningful metadata (e.g., Project, Environment, Owner, CostCenter). Use a default_tags block in your provider configuration.

provider "aws" {
  region = "us-east-1"
  default_tags {
    tags = {
      Project     = "MyApplication"
      Environment = "prod"
      ManagedBy   = "Terraform"
    }
  }
}

6. Security and Configuration Management

6.1 Secrets Management

Never hardcode sensitive data. Fetch secrets dynamically from a dedicated secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault).

❌ BAD:

resource "aws_db_instance" "app_db" {
  password = "SuperSecretPassword123!" # NEVER DO THIS
}

✅ GOOD:

data "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "prod/my-app/db-credentials"
}

locals {
  db_credentials = jsondecode(data.aws_secretsmanager_secret_version.db_creds.secret_string)
}

resource "aws_db_instance" "app_db" {
  password = local.db_credentials.password
}

6.2 Policy as Code

Integrate Policy as Code (e.g., Open Policy Agent (OPA) or HashiCorp Sentinel) into your CI/CD pipeline to enforce organizational compliance and security policies before deployment.

7. Common Pitfalls and Gotchas

7.1 Formatting and Validation

Always run terraform fmt and terraform validate before committing. Integrate these into Git pre-commit hooks and CI/CD pipelines.

7.2 Linting

Use a linter like TFLint to catch style violations, potential errors, and enforce best practices early.

7.3 Version Pinning

Always pin versions for Terraform, providers, and modules to ensure reproducible deployments and prevent unexpected changes.

# providers.tf
terraform {
  required_version = "~> 1.5" # Pin Terraform CLI version
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0" # Pin AWS provider version
    }
  }
}

# main.tf (for modules)
module "vpc" {
  source  = "cloudposse/vpc/aws"
  version = "2.0.0" # Pin module version
  # ...
}

7.4 Lifecycle Management

Use the lifecycle block judiciously, especially prevent_destroy for critical resources and create_before_destroy for zero-downtime updates.

resource "aws_s3_bucket" "critical_data" {
  bucket = "my-critical-data-bucket"
  # ...
  lifecycle {
    prevent_destroy = true # Protect critical resources from accidental deletion
  }
}

8. CI/CD Integration

Automate your Terraform workflow with CI/CD.

8.1 Automated Plan Checks

Every pull request must trigger a terraform plan and post the output as a comment or check. This ensures visibility and prevents unexpected changes.

8.2 Automated Apply

Implement automated terraform apply on merge to main (or environment branches) only after successful plan, validation, and policy checks. This requires robust state locking and access controls.