Infrastructure as Code Best Practices

Infrastructure as Code (IaC) treats infrastructure configuration like application code—version controlled, tested, and automated. Here's how to do it well.

Why IaC?#

Benefits:
- Reproducible environments
- Version controlled changes
- Automated deployments
- Self-documenting infrastructure
- Disaster recovery
- Consistency across environments

Tools:
- Terraform: Multi-cloud, declarative
- Pulumi: Real programming languages
- CloudFormation: AWS native
- CDK: AWS with TypeScript/Python

Terraform Basics#

# main.tf - Define resources
terraform {
  required_version = ">= 1.0"

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

  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "production/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = {
      Environment = var.environment
      ManagedBy   = "terraform"
      Project     = var.project_name
    }
  }
}

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

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

# Subnets
resource "aws_subnet" "public" {
  count                   = length(var.availability_zones)
  vpc_id                  = aws_vpc.main.id
  cidr_block              = cidrsubnet(var.vpc_cidr, 4, count.index)
  availability_zone       = var.availability_zones[count.index]
  map_public_ip_on_launch = true

  tags = {
    Name = "${var.project_name}-public-${count.index + 1}"
    Type = "public"
  }
}

resource "aws_subnet" "private" {
  count             = length(var.availability_zones)
  vpc_id            = aws_vpc.main.id
  cidr_block        = cidrsubnet(var.vpc_cidr, 4, count.index + length(var.availability_zones))
  availability_zone = var.availability_zones[count.index]

  tags = {
    Name = "${var.project_name}-private-${count.index + 1}"
    Type = "private"
  }
}

Variables and Outputs#

# variables.tf
variable "aws_region" {
  description = "AWS region"
  type        = string
  default     = "us-east-1"
}

variable "environment" {
  description = "Environment name"
  type        = string

  validation {
    condition     = contains(["development", "staging", "production"], var.environment)
    error_message = "Environment must be development, staging, or production."
  }
}

variable "vpc_cidr" {
  description = "CIDR block for VPC"
  type        = string
  default     = "10.0.0.0/16"
}

variable "availability_zones" {
  description = "Availability zones"
  type        = list(string)
  default     = ["us-east-1a", "us-east-1b", "us-east-1c"]
}

variable "database_password" {
  description = "Database password"
  type        = string
  sensitive   = true
}

# outputs.tf
output "vpc_id" {
  description = "VPC ID"
  value       = aws_vpc.main.id
}

output "public_subnet_ids" {
  description = "Public subnet IDs"
  value       = aws_subnet.public[*].id
}

output "database_endpoint" {
  description = "Database endpoint"
  value       = aws_db_instance.main.endpoint
  sensitive   = true
}

Modular Design#

# modules/vpc/main.tf
variable "name" {
  type = string
}

variable "cidr" {
  type    = string
  default = "10.0.0.0/16"
}

variable "azs" {
  type = list(string)
}

resource "aws_vpc" "this" {
  cidr_block           = var.cidr
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = {
    Name = var.name
  }
}

resource "aws_subnet" "public" {
  count                   = length(var.azs)
  vpc_id                  = aws_vpc.this.id
  cidr_block              = cidrsubnet(var.cidr, 4, count.index)
  availability_zone       = var.azs[count.index]
  map_public_ip_on_launch = true

  tags = {
    Name = "${var.name}-public-${count.index + 1}"
  }
}

output "vpc_id" {
  value = aws_vpc.this.id
}

output "public_subnet_ids" {
  value = aws_subnet.public[*].id
}

# Using the module
module "vpc" {
  source = "./modules/vpc"

  name = "${var.project_name}-${var.environment}"
  cidr = "10.0.0.0/16"
  azs  = ["us-east-1a", "us-east-1b"]
}

module "database" {
  source = "./modules/rds"

  name               = "${var.project_name}-db"
  vpc_id             = module.vpc.vpc_id
  subnet_ids         = module.vpc.private_subnet_ids
  instance_class     = var.environment == "production" ? "db.r5.large" : "db.t3.micro"
  password           = var.database_password
}

Environment Separation#

# environments/production/main.tf
terraform {
  backend "s3" {
    bucket = "terraform-state"
    key    = "production/terraform.tfstate"
    region = "us-east-1"
  }
}

module "infrastructure" {
  source = "../../modules/infrastructure"

  environment = "production"
  vpc_cidr    = "10.0.0.0/16"

  # Production settings
  instance_count = 3
  instance_type  = "t3.large"
  rds_instance   = "db.r5.large"
  multi_az       = true
}

# environments/staging/main.tf
terraform {
  backend "s3" {
    bucket = "terraform-state"
    key    = "staging/terraform.tfstate"
    region = "us-east-1"
  }
}

module "infrastructure" {
  source = "../../modules/infrastructure"

  environment = "staging"
  vpc_cidr    = "10.1.0.0/16"

  # Staging settings (smaller)
  instance_count = 1
  instance_type  = "t3.small"
  rds_instance   = "db.t3.micro"
  multi_az       = false
}

State Management#

# Remote state with locking
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "production/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# State locking table
resource "aws_dynamodb_table" "terraform_locks" {
  name         = "terraform-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

# Import existing resources
# terraform import aws_instance.example i-1234567890abcdef0

# Move resources between states
# terraform state mv aws_instance.old aws_instance.new

# Remove from state without destroying
# terraform state rm aws_instance.example

CI/CD Integration#

# .github/workflows/terraform.yml
name: Terraform

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

env:
  TF_VERSION: 1.5.0

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

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

      - name: Terraform Init
        run: terraform init -backend=false

      - name: Terraform Validate
        run: terraform validate

  plan:
    needs: validate
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init
        run: terraform init
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

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

      - name: Comment Plan
        uses: actions/github-script@v6
        with:
          script: |
            // Post plan output as PR comment

  apply:
    needs: validate
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: production
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init
        run: terraform init

      - name: Terraform Apply
        run: terraform apply -auto-approve

Security Best Practices#

# Use data sources for sensitive values
data "aws_secretsmanager_secret_version" "db_password" {
  secret_id = "production/database/password"
}

resource "aws_db_instance" "main" {
  # ... other config
  password = data.aws_secretsmanager_secret_version.db_password.secret_string
}

# Don't hardcode credentials
# ❌ Bad
provider "aws" {
  access_key = "AKIAIOSFODNN7EXAMPLE"
  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

# ✅ Good - use environment variables or IAM roles
provider "aws" {
  region = "us-east-1"
}

# Mark sensitive outputs
output "database_password" {
  value     = aws_db_instance.main.password
  sensitive = true
}

Best Practices#

Organization:
✓ Use modules for reusability
✓ Separate environments
✓ Consistent naming conventions
✓ Pin provider versions

State Management:
✓ Remote state with locking
✓ Encrypt state at rest
✓ Separate state per environment
✓ Regular state backups

Security:
✓ No secrets in code
✓ Use IAM roles over keys
✓ Encrypt sensitive outputs
✓ Review plans before apply

Operations:
✓ Always run plan first
✓ Use CI/CD for changes
✓ Tag all resources
✓ Document modules

Infrastructure as Code enables reliable, repeatable infrastructure management. Use modules for reusability, remote state for collaboration, and CI/CD for safe deployments. Treat your infrastructure code with the same care as application code.