Terraform and OpenTofu Guide

Terraform Skill for Claude

Comprehensive Terraform and OpenTofu guidance covering testing, modules, CI/CD, and production patterns. Based on terraform-best-practices.com and enterprise experience.

When to Use This Skill

Activate this skill when:

• Creating new Terraform or OpenTofu configurations or modules
• Setting up testing infrastructure for IaC code
• Deciding between testing approaches (validate, plan, frameworks)
• Structuring multi-environment deployments
• Implementing CI/CD for infrastructure-as-code
• Reviewing or refactoring existing Terraform/OpenTofu projects
• Choosing between module patterns or state management approaches

Don't use this skill for:

• Basic Terraform/OpenTofu syntax questions (Claude knows this)
• Provider-specific API reference (link to docs instead)
• Cloud platform questions unrelated to Terraform/OpenTofu

Core Principles

1. Code Structure Philosophy

Module Hierarchy:

Hierarchy: Resource → Resource Module → Infrastructure Module → Composition

Directory Structure:

environments/        # Environment-specific configurations
├── prod/
├── staging/
└── dev/

modules/            # Reusable modules
├── networking/
├── compute/
└── data/

examples/           # Module usage examples (also serve as tests)
├── complete/
└── minimal/

Key principle from terraform-best-practices.com:

• Separate environments (prod, staging) from modules (reusable components)
• Use examples/ as both documentation and integration test fixtures
• Keep modules small and focused (single responsibility)

For detailed module architecture, see: Code Patterns: Module Types & Hierarchy

2. Naming Conventions

Resources:

# Good: Descriptive, contextual
resource "aws_instance" "web_server" { }
resource "aws_s3_bucket" "application_logs" { }

# Good: "this" for singleton resources (only one of that type)
resource "aws_vpc" "this" { }
resource "aws_security_group" "this" { }

# Avoid: Generic names for non-singletons
resource "aws_instance" "main" { }
resource "aws_s3_bucket" "bucket" { }

Singleton Resources:

Use "this" when your module creates only one resource of that type:

✅ DO:

resource "aws_vpc" "this" {}           # Module creates one VPC
resource "aws_security_group" "this" {}  # Module creates one SG

❌ DON'T use "this" for multiple resources:

resource "aws_subnet" "this" {}  # If creating multiple subnets

Use descriptive names when creating multiple resources of the same type.

Variables:

# Prefix with context when needed
var.vpc_cidr_block          # Not just "cidr"
var.database_instance_class # Not just "instance_class"

Files:

• main.tf - Primary resources
• variables.tf - Input variables
• outputs.tf - Output values
• versions.tf - Provider versions
• data.tf - Data sources (optional)

Testing Strategy Framework

Decision Matrix: Which Testing Approach?

Testing Pyramid for Infrastructure

        /\
       /  \          End-to-End Tests (Expensive)
      /____\         - Full environment deployment
     /      \        - Production-like setup
    /________\
   /          \      Integration Tests (Moderate)
  /____________\     - Module testing in isolation
 /              \    - Real resources in test account
/________________\   Static Analysis (Cheap)
                     - validate, fmt, lint
                     - Security scanning

Native Test Best Practices (1.6+)

Before generating test code:

1. Validate schemas with Terraform MCP:

   Search provider docs → Get resource schema → Identify block types

2. Choose correct command mode:

   • command = plan - Fast, for input validation
   • command = apply - Required for computed values and set-type blocks

3. Handle set-type blocks correctly:

   • Cannot index with [0]
   • Use for expressions to iterate
   • Or use command = apply to materialize

Common patterns:

• S3 encryption rules: set (use for expressions)
• Lifecycle transitions: set (use for expressions)
• IAM policy statements: set (use for expressions)

For detailed testing guides, see:

• Testing Frameworks Guide - Deep dive into static analysis, native tests, and Terratest
• Quick Reference - Decision flowchart and command cheat sheet

Code Structure Standards

Resource Block Ordering

Strict ordering for consistency:

1. count or for_each FIRST (blank line after)
2. Other arguments
3. tags as last real argument
4. depends_on after tags (if needed)
5. lifecycle at the very end (if needed)

# ✅ GOOD - Correct ordering
resource "aws_nat_gateway" "this" {
  count = var.create_nat_gateway ? 1 : 0

  allocation_id = aws_eip.this[0].id
  subnet_id     = aws_subnet.public[0].id

  tags = {
    Name = "${var.name}-nat"
  }

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }
}

Variable Block Ordering

1. description (ALWAYS required)
2. type
3. default
4. validation
5. nullable (when setting to false)

variable "environment" {
  description = "Environment name for resource tagging"
  type        = string
  default     = "dev"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be one of: dev, staging, prod."
  }

  nullable = false
}

For complete structure guidelines, see: Code Patterns: Block Ordering & Structure

Count vs For_Each: When to Use Each

Quick Decision Guide

Common Patterns

Boolean conditions:

# ✅ GOOD - Boolean condition
resource "aws_nat_gateway" "this" {
  count = var.create_nat_gateway ? 1 : 0
  # ...
}

Stable addressing with for_each:

# ✅ GOOD - Removing "us-east-1b" only affects that subnet
resource "aws_subnet" "private" {
  for_each = toset(var.availability_zones)

  availability_zone = each.key
  # ...
}

# ❌ BAD - Removing middle AZ recreates all subsequent subnets
resource "aws_subnet" "private" {
  count = length(var.availability_zones)

  availability_zone = var.availability_zones[count.index]
  # ...
}

For migration guides and detailed examples, see: Code Patterns: Count vs For_Each

Locals for Dependency Management

Use locals to ensure correct resource deletion order:

# Problem: Subnets might be deleted after CIDR blocks, causing errors
# Solution: Use try() in locals to hint deletion order

locals {
  # References secondary CIDR first, falling back to VPC
  # Forces Terraform to delete subnets before CIDR association
  vpc_id = try(
    aws_vpc_ipv4_cidr_block_association.this[0].vpc_id,
    aws_vpc.this.id,
    ""
  )
}

resource "aws_vpc" "this" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_vpc_ipv4_cidr_block_association" "this" {
  count = var.add_secondary_cidr ? 1 : 0

  vpc_id     = aws_vpc.this.id
  cidr_block = "10.1.0.0/16"
}

resource "aws_subnet" "public" {
  vpc_id     = local.vpc_id  # Uses local, not direct reference
  cidr_block = "10.1.0.0/24"
}

Why this matters:

• Prevents deletion errors when destroying infrastructure
• Ensures correct dependency order without explicit depends_on
• Particularly useful for VPC configurations with secondary CIDR blocks

For detailed examples, see: Code Patterns: Locals for Dependency Management

Module Development

Standard Module Structure

my-module/
├── README.md           # Usage documentation
├── main.tf             # Primary resources
├── variables.tf        # Input variables with descriptions
├── outputs.tf          # Output values
├── versions.tf         # Provider version constraints
├── examples/
│   ├── minimal/        # Minimal working example
│   └── complete/       # Full-featured example
└── tests/              # Test files
    └── module_test.tftest.hcl  # Or .go

Best Practices Summary

Variables:

• ✅ Always include description
• ✅ Use explicit type constraints
• ✅ Provide sensible default values where appropriate
• ✅ Add validation blocks for complex constraints
• ✅ Use sensitive = true for secrets

Outputs:

• ✅ Always include description
• ✅ Mark sensitive outputs with sensitive = true
• ✅ Consider returning objects for related values
• ✅ Document what consumers should do with each output

For detailed module patterns, see:

• Module Patterns Guide - Variable best practices, output design, ✅ DO vs ❌ DON'T patterns
• Quick Reference - Resource naming, variable naming, file organization

CI/CD Integration