ranbot-ai/terraform-skill

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:

| Type | When to Use | Scope | |------|-------------|-------| | Resource Module | Single logical group of connected resources | VPC + subnets, Security group + rules | | Infrastructure Module | Collection of resource modules for a purpose | Multiple resource modules in one region/account | | Composition | Complete infrastructure | Spans multiple regions/accounts |

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?

| Your Situation | Recommended Approach | Tools | Cost | |----------------|---------------------|-------|------| | Quick syntax check | Static analysis | terraform validate, fmt | Free | | Pre-commit validation | Static + lint | validate, tflint, trivy, checkov | Free | | Terraform 1.6+, simple logic | Native test framework | Built-in terraform test | Free-Low | | Pre-1.6, or Go expertise | Integration testing | Terratest | Low-Med | | Security/compliance focus | Policy as code | OPA, Sentinel | Free | | Cost-sensitive workflow | Mock providers (1.7+) | Native tests + mocking | Free | | Multi-cloud, complex | Full integration | Terratest + real infra | Med-High |

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]