infrastructure-terraform-patterns

Provisioning cloud infrastructure (AWS, GCP, Azure, Cloudflare)

Terraform Patterns

Scope: Infrastructure as Code with Terraform - modules, state management, workspaces, backends Lines: 387 Last Updated: 2025-10-18 Format Version: 1.0 (Atomic)

---

When to Use This Skill

Activate when:

• Provisioning cloud infrastructure (AWS, GCP, Azure, Cloudflare)
• Managing infrastructure state across environments
• Creating reusable infrastructure modules
• Implementing infrastructure as code workflows
• Managing multi-environment deployments
• Migrating from manual infrastructure management

Prerequisites:

• Terraform CLI installed (brew install terraform or download from terraform.io)
• Cloud provider credentials configured
• Basic understanding of target cloud platform
• Version control system (Git) for state tracking

Common scenarios:

• Setting up staging/production environments
• Creating repeatable infrastructure patterns
• Managing infrastructure across multiple regions
• Implementing infrastructure versioning and rollback
• Collaborating on infrastructure changes with teams

---

Core Concepts

1. Provider Configuration

# versions.tf
terraform {
  required_version = ">= 1.6"

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

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

provider "aws" {
  region = var.aws_region

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

2. Variable Definitions

# variables.tf
variable "environment" {
  description = "Environment name (dev, staging, production)"
  type        = string
  validation {
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "Environment must be dev, staging, or production"
  }
}

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

variable "instance_config" {
  description = "EC2 instance configuration"
  type = object({
    instance_type = string
    volume_size   = number
    enable_monitoring = bool
  })
  default = {
    instance_type     = "t3.micro"
    volume_size       = 20
    enable_monitoring = false
  }
}

variable "tags" {
  description = "Additional tags for resources"
  type        = map(string)
  default     = {}
}

3. State Management

# Remote state with S3 backend
terraform {
  backend "s3" {
    bucket         = "company-terraform-state"
    key            = "env/${var.environment}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"

    # Enable versioning for state file recovery
    versioning = true
  }
}

# State locking with DynamoDB
resource "aws_dynamodb_table" "terraform_lock" {
  name         = "terraform-state-lock"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

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

  tags = {
    Name = "Terraform State Lock"
  }
}

4. Data Sources

# Fetch existing resources
data "aws_vpc" "main" {
  id = var.vpc_id
}

data "aws_subnets" "private" {
  filter {
    name   = "vpc-id"
    values = [data.aws_vpc.main.id]
  }

  tags = {
    Tier = "private"
  }
}

data "aws_ami" "amazon_linux" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

# Remote state data source
data "terraform_remote_state" "networking" {
  backend = "s3"

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

---

Patterns

Module Structure

# modules/web-app/main.tf
resource "aws_security_group" "web" {
  name        = "${var.name}-web-sg"
  description = "Security group for ${var.name} web tier"
  vpc_id      = var.vpc_id

  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = var.allowed_cidrs
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }

  tags = merge(
    var.tags,
    {
      Name = "${var.name}-web-sg"
    }
  )
}

resource "aws_lb" "web" {
  name               = "${var.name}-alb"
  internal           = false
  load_balancer_type = "application"
  security_groups    = [aws_security_group.web.id]
  subnets            = var.subnet_ids

  enable_deletion_protection = var.environment == "production"

  tags = merge(
    var.tags,
    {
      Name = "${var.name}-alb"
    }
  )
}

# modules/web-app/variables.tf
variable "name" {
  description = "Application name"
  type        = string
}

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

variable "vpc_id" {
  description = "VPC ID"
  type        = string
}

variable "subnet_ids" {
  description = "Subnet IDs for load balancer"
  type        = list(string)
}

variable "allowed_cidrs" {
  description = "Allowed CIDR blocks for ingress"
  type        = list(string)
  default     = ["0.0.0.0/0"]
}

variable "tags" {
  description = "Additional tags"
  type        = map(string)
  default     = {}
}

# modules/web-app/outputs.tf
output "alb_dns_name" {
  description = "DNS name of the load balancer"
  value       = aws_lb.web.dns_name
}

output "alb_arn" {
  description = "ARN of the load balancer"
  value       = aws_lb.web.arn
}

output "security_group_id" {
  description = "Security group ID"
  value       = aws_security_group.web.id
}

Using Modules

# main.tf
module "web_app" {
  source = "./modules/web-app"

  name        = "my-app"
  environment = var.environment
  vpc_id      = data.aws_vpc.main.id
  subnet_ids  = data.aws_subnets.public.ids

  allowed_cidrs = var.environment == "production" ? var.allowed_cidrs : ["0.0.0.0/0"]

  tags = {
    Team  = "Platform"
    Owner = "DevOps"
  }
}

# Use module outputs
resource "aws_route53_record" "web" {
  zone_id = var.route53_zone_id
  name    = "app.${var.domain}"
  type    = "A"

  alias {
    name                   = module.web_app.alb_dns_name
    zone_id                = module.web_app.alb_zone_id
    evaluate_target_health = true
  }
}

Workspace Management

# Create workspaces for environments
terraform workspace new dev
terraform workspace new staging
terraform workspace new production

# Switch between workspaces
terraform workspace select dev

# List workspaces
terraform workspace list

# Use workspace in configuration
locals {
  environment = terraform.workspace

  instance_counts = {
    dev        = 1
    staging    = 2
    production = 5
  }

  instance_count = local.instance_counts[terraform.workspace]
}

resource "aws_instance" "app" {
  count         = local.instance_count
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.instance_type

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

Dynamic Blocks

# Dynamic ingress rules
variable "ingress_rules" {
  type = list(object({
    from_port   = number
    to_port     = number
    protocol    = string
    cidr_blocks = list(string)
    description = string
  }))
  default = [
    {
      from_port   = 443
      to_port     = 443
      protocol    = "tcp"
      cidr_blocks = ["0.0.0.0/0"]
      description = "HTTPS"
    },
    {
      from_port   = 80
      to_port     = 80
      protocol    = "tcp"
      cidr_blocks = ["0.0.0.0/0"]
      description = "HTTP"
    }
  ]
}

resource "aws_security_group" "dynamic" {
  name        = "dynamic-sg"
  description = "Security group with dynamic rules"
  vpc_id      = var.vpc_id

  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
      description = ingress.value.description
    }
  }
}

For Each Patterns

# Create resources from map
variable "s3_buckets" {
  type = map(object({
    versioning = bool
    encryption = bool
  }))
  default = {
    "logs" = {
      versioning = true
      encryption = true
    }
    "backups" = {
      versioning = true
      encryption = true
    }
    "assets" = {
      versioning = false
      encryption = false
    }
  }
}

resource "aws_s3_bucket" "buckets" {
  for_each = var.s3_buckets

  bucket = "${var.project}-${each.key}-${var.environment}"

  tags = {
    Name = each.key
    Type = each.key
  }
}

resource "aws_s3_bucket_versioning" "buckets" {
  for_each = {
    for k, v in var.s3_buckets : k => v if v.versioning
  }

  bucket = aws_s3_bucket.buckets[each.key].id

  versioning_configuration {
    status = "Enabled"
  }
}

Conditional Resources

# Create resource only in production
resource "aws_cloudwatch_dashboard" "main" {
  count          = var.environment == "production" ? 1 : 0
  dashboard_name = "${var.project}-dashboard"

  dashboard_body = jsonencode({
    widgets = [
      {
        type = "metric"
        properties = {
          metrics = [
            ["AWS/Lambda", "Invocations"]
          ]
        }
      }
    ]
  })
}

# Conditional values
locals {
  instance_type = var.environment == "production" ? "t3.large" : "t3.micro"

  backup_retention = {
    dev        = 7
    staging    = 14
    production = 30
  }[var.environment]
}

---

Quick Reference

Essential Commands

# Initialize Terraform
terraform init

# Validate configuration
terraform validate

# Format configuration
terraform fmt -recursive

# Plan changes
terraform plan -out=tfplan

# Apply changes
terraform apply tfplan

# Destroy infrastructure
terraform destroy

# Show current state
terraform show

# List resources in state
terraform state list

# Remove resource from state
terraform state rm aws_instance.example

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

# Refresh state
terraform refresh

# Output values
terraform output
terraform output -json

State Management

# Pull remote state
terraform state pull > terraform.tfstate.backup

# Push local state to remote
terraform state push terraform.tfstate

# Move resource in state
terraform state mv aws_instance.old aws_instance.new

# Replace provider in state
terraform state replace-provider hashicorp/aws registry.terraform.io/hashicorp/aws

Workspace Commands

# Create workspace
terraform workspace new staging

# Select workspace
terraform workspace select production

# List workspaces
terraform workspace list

# Show current workspace
terraform workspace show

# Delete workspace
terraform workspace delete dev

Module Commands

# Initialize and download modules
terraform init

# Update modules
terraform get -update

# Show module tree
terraform providers

---

Anti-Patterns

Critical Violations

# ❌ NEVER: Hardcode credentials
provider "aws" {
  access_key = "AKIAIOSFODNN7EXAMPLE"  # NEVER do this
  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

# ✅ CORRECT: Use environment variables or instance profiles
provider "aws" {
  # Uses AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  region = var.aws_region
}

# ❌ NEVER: Store state locally for team projects
terraform {
  # No backend configuration - uses local state
}

# ✅ CORRECT: Use remote backend with locking
terraform {
  backend "s3" {
    bucket         = "terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-lock"
  }
}

# ❌ NEVER: Use count for resources that might be reordered
resource "aws_instance" "app" {
  count = 3  # Risky - reordering changes indices
  # ...
}

# ✅ CORRECT: Use for_each with stable keys
resource "aws_instance" "app" {
  for_each = toset(["web-1", "web-2", "web-3"])

  tags = {
    Name = each.key
  }
}

Common Mistakes

# ❌ Don't ignore .terraform directory in git
# .gitignore missing .terraform/

# ✅ CORRECT: Proper .gitignore
# .gitignore
.terraform/
*.tfstate
*.tfstate.backup
.terraform.lock.hcl  # or commit for version locking
tfplan

# ❌ Don't create circular dependencies
resource "aws_security_group" "a" {
  ingress {
    security_groups = [aws_security_group.b.id]
  }
}

resource "aws_security_group" "b" {
  ingress {
    security_groups = [aws_security_group.a.id]
  }
}

# ✅ CORRECT: Use separate rules
resource "aws_security_group_rule" "a_to_b" {
  type                     = "ingress"
  security_group_id        = aws_security_group.b.id
  source_security_group_id = aws_security_group.a.id
  from_port                = 443
  to_port                  = 443
  protocol                 = "tcp"
}

Best Practices

# Use consistent naming
locals {
  name_prefix = "${var.project}-${var.environment}"

  common_tags = {
    Project     = var.project
    Environment = var.environment
    ManagedBy   = "Terraform"
    Timestamp   = timestamp()
  }
}

# Version pin providers
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Allow minor updates only
    }
  }
}

# Use lifecycle rules for safety
resource "aws_db_instance" "main" {
  # ...

  lifecycle {
    prevent_destroy = true  # Prevent accidental deletion
    create_before_destroy = true  # Zero-downtime updates
    ignore_changes = [
      tags["LastModified"]  # Ignore external changes
    ]
  }
}

---

Level 3: Resources

Location: ~/.hanzo/skills/infrastructure/terraform-best-practices/resources/

Comprehensive Reference

REFERENCE.md (1,875 lines)

• Complete Terraform best practices guide
• State management strategies and troubleshooting
• Module design patterns and composition
• Variable management and validation
• Security best practices and encryption
• Cost optimization techniques
• CI/CD integration patterns
• Multi-environment strategies
• Performance optimization
• Disaster recovery procedures

Executable Scripts

scripts/analyze_terraform.py - Terraform code analyzer

• Detects security vulnerabilities and anti-patterns
• Checks for hardcoded secrets, unencrypted resources
• Validates naming conventions and tagging
• Identifies overly permissive IAM policies and security groups
• Suggests improvements and best practices
• Supports JSON and table output formats

./analyze_terraform.py .
./analyze_terraform.py --json --output report.json terraform/
./analyze_terraform.py --severity high --format table .

scripts/validate_state.py - State file health checker

• Validates state file integrity and structure
• Detects orphaned resources and duplicates
• Checks for circular dependencies
• Analyzes state lineage and serial numbers
• Identifies sensitive data exposure
• Optionally checks for infrastructure drift

./validate_state.py
./validate_state.py --remote --json
./validate_state.py --check-drift --output state-report.json

scripts/cost_estimate.sh - Infrastructure cost estimator

• Estimates monthly costs from Terraform plans
• Integrates with Infracost for accurate pricing
• Provides cost breakdowns by resource type
• Compares costs across environments
• Supports budget limits and threshold alerts
• Outputs in table, JSON, or CSV formats

./cost_estimate.sh
./cost_estimate.sh --json --output costs.json
./cost_estimate.sh --budget 5000 --threshold 80
./cost_estimate.sh --compare production-costs.json

Production Examples

Reusable Modules:

• examples/modules/vpc/ - Production-ready VPC with multi-AZ, NAT gateways, flow logs
• examples/modules/eks/ - EKS cluster with node groups and IRSA
• examples/modules/rds/ - RDS with encryption, backups, monitoring

Environment Configurations:

• examples/environments/dev/ - Development environment (cost-optimized)
• examples/environments/prod/ - Production environment (HA, redundant)

Best Practices Examples:

• examples/good-practices/security.tf - Encryption, least privilege IAM, secure networking
• examples/bad-practices/anti-patterns.tf - Common mistakes with explanations and fixes

Usage

1. Code Quality Analysis:

``bash cd /path/to/terraform/project /path/to/analyze_terraform.py . --severity high ``

1. State Validation:

``bash cd /path/to/terraform/project /path/to/validate_state.py --check-drift ``

1. Cost Estimation:

``bash cd /path/to/terraform/project /path/to/cost_estimate.sh --budget 10000 --json ``

1. Module Reuse:

```hcl module "vpc" { source = "/path/to/terraform-best-practices/resources/examples/modules/vpc"

name = "production" cidr_block = "10.0.0.0/16" availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"] } ```

All scripts support --help for detailed usage information.

---

Related Skills

Infrastructure:

• aws-serverless.md - AWS Lambda, API Gateway, DynamoDB integration
• kubernetes-basics.md - Container orchestration with Terraform Kubernetes provider
• infrastructure-security.md - IAM roles, security groups, secrets management
• cost-optimization.md - Resource sizing, reserved instances

Development:

• modal-functions-basics.md - Alternative serverless platform
• cloudflare-workers.md - Edge computing with Terraform Cloudflare provider

Standards from CLAUDE.md:

• Use Terraform for infrastructure as code
• Remote state with S3 backend mandatory for team projects
• Version pin all providers
• Tag all resources consistently
• Enable state locking with DynamoDB

---

Last Updated: 2025-10-18 Format Version: 1.0 (Atomic)