Terraform is a powerful tool for managing infrastructure as code (IaC), but without best practices, projects can become hard to maintain. Below are key best practices related to modularity, reusability, and code structure.

Use Modules to Encapsulate Infrastructure Components

Terraform modules help break down infrastructure into reusable components. This promotes consistency, reduces duplication, and simplifies maintenance.

• Organize resources into logical modules (e.g., network, compute, database).
• Keep module input and output clean—only expose what is necessary.
• Version control your modules to maintain stability.
• Store reusable modules in a private registry, Git repository, or Terraform Cloud.

terraform/
│── modules/
│   ├── vpc/
│   ├── rds/
│   ├── s3/
│── environments/
│   ├── dev/
│   ├── prod/
│── main.tf
│── variables.tf
│── outputs.tf
│── providers.tf

Use Remote or Public Modules Where Possible

Instead of reinventing the wheel, leverage community-maintained modules from Terraform Registry. Example of using an AWS VPC module:

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "5.0.0"
  name = "my-vpc"
  cidr = "10.0.0.0/16"
}

Use of Variables

Avoid hardcoded values. Instead, use variables for configurations such as region, instance types, or networking settings.

• Group related variables in variables.tf.
• Use descriptive names for clarity.
• Provide default values when applicable.
• Use terraform.tfvars or environment variables for sensitive configurations.

variable "region" {
  description = "AWS region"
  type        = string
  default     = "us-east-1"
}

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.micro"
}

Usage in terraform.tfvars:

region = "us-west-2"
instance_type = "t3.small"

Use Local Modules and Keep main.tf Light

Instead of defining all resources in main.tf, break down infrastructure into local modules.

• Store modules in a separate modules/ directory.
• Avoid embedding too many locals inside a single file—use modules instead.
• Keep modules loosely coupled by exposing only necessary variables and outputs.

terraform/
│── modules/
│   ├── ec2/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│── environments/
│   ├── dev/
│   ├── prod/

Example Module (modules/ec2/main.tf)

resource "aws_instance" "app" {
  ami           = var.ami
  instance_type = var.instance_type
  tags = {
    Name = var.name
  }
}

output "instance_id" {
  value = aws_instance.app.id
}

Usage in the main project:

module "ec2" {
  source        = "../modules/ec2"
  ami           = "ami-123456"
  instance_type = "t3.micro"
  name          = "web-server"
}

Keep Names Meaningful and Consistent**

Naming conventions are crucial for clarity and organization.

• Use snake_case or kebab-case consistently.
• Prefix resource names with the environment (e.g., prod-db, dev-vpc).
• Use tags for resource tracking and filtering.

resource "aws_s3_bucket" "app_logs" {
  bucket = "mycompany-app-logs"
}

resource "aws_instance" "web_server" {
  ami           = "ami-123456"
  instance_type = "t3.micro"
  tags = {
    Name = "web-server-prod"
  }
}

Version Control & State Management

Keep Terraform State Secure Not In Source Control.

• Use Terraform Cloud/Enterprise or AWS S3 with DynamoDB for state locking.
• Never commit terraform.tfstate to Git.
• Use backend configuration for remote state management.

Example (backend.tf for AWS S3 backend):

terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-lock"
  }
}

Linting, Formatting, and CI/CD Integration

• Run terraform fmt to maintain consistent code formatting.
• Use terraform validate to catch syntax errors.
• Implement terraform plan and terraform apply in CI/CD pipelines (e.g., GitHub Actions, GitLab CI, Jenkins).

Example GitHub Actions workflow:

name: Terraform CI

on:
    push:
        branches:
            - main

jobs:
    terraform:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout code
              uses: actions/checkout@v3

            - name: Setup Terraform
              uses: hashicorp/setup-terraform@v2

            - name: Terraform Init
              run: terraform init

            - name: Terraform Validate
              run: terraform validate

            - name: Terraform Plan
              run: terraform plan -out=tfplan

            - name: Terraform Apply
              if: github.ref == 'refs/heads/main'
              run: terraform apply -auto-approve tfplan

Managing Secrets Securely

Always use a secrets manager.

• Do not store secrets in Terraform code or terraform.tfvars.
• Use AWS Secrets Manager, HashiCorp Vault, or SSM Parameter Store.
• For sensitive variables, use terraform input variables and avoid hardcoding.

Example using AWS SSM:

data "aws_ssm_parameter" "db_password" {
  name = "/prod/db/password"
  with_decryption = true
}

resource "aws_db_instance" "mysql" {
  allocated_storage = 20
  engine            = "mysql"
  instance_class    = "db.t3.micro"
  password         = data.aws_ssm_parameter.db_password.value
}

Resource vs Module

For most use-cases, you should probably avoid using resource directly in main.tf.

• Small, one-off resources? Use resource directly.
• Repeated or complex infrastructure? Use a module.
• Consistency across teams? Modules ensure best practices.
• Want better maintainability? Modules abstract complexity.