Infrastructure as Code (Terraform / OpenTofu)

Complete guide for Terraform and OpenTofu covering modules, tests, CI/CD and production patterns. Based on terraform-best-practices.com and Anton Babenko's enterprise experience.

When to use this Skill

Activate this skill to:

• Create Terraform/OpenTofu configurations or modules
• Set up the test infrastructure for IaC
• Choose between testing approaches (validate, plan, frameworks)
• Structure multi-environment deployments
• Implement CI/CD for infrastructure-as-code
• Review or refactor existing Terraform/OpenTofu projects

Do not use for:

• Basic syntax questions (Claude already knows)
• Provider-specific API reference (use the documentation)
• Cloud questions unrelated to Terraform/OpenTofu

Core Principles

1. Module Hierarchy

Hierarchy: Resource -> Resource Module -> Infrastructure Module -> Composition

2. Directory Structure

environments/        # Configurations per environment
├── prod/
├── staging/
└── dev/

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

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

3. Naming Conventions

Resources:

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

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

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

Variables:

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

Files:

• main.tf - Main resources
• variables.tf - Input variables
• outputs.tf - Output values
• versions.tf - Provider versions

Block Order

Resource Block

Strict order for consistency:

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

# GOOD - Correct order
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

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

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

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

  nullable = false
}

Count vs For_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 this subnet
resource "aws_subnet" "private" {
  for_each = toset(var.availability_zones)

  availability_zone = each.key
  # ...
}

# BAD - Removing the middle AZ recreates all the following ones
resource "aws_subnet" "private" {
  count = length(var.availability_zones)

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

Testing Strategy

Decision Matrix

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 (Inexpensive)
                     - validate, fmt, lint
                     - Security scanning

Security and Compliance

Essential Security Checks

# Static security scanning
trivy config .
checkov -d .

Common Issues to Avoid

DO NOT:

• Store secrets in variables
• Use the default VPC
• Omit encryption
• Open security groups to 0.0.0.0/0

DO:

• Use AWS Secrets Manager / Parameter Store
• Create dedicated VPCs
• Enable encryption at rest
• Use least-privilege security groups

Version Management

Constraint Syntax

version = "5.0.0"      # Exact (avoid - inflexible)
version = "~> 5.0"     # Recommended: 5.0.x only
version = ">= 5.0"     # Minimum (risky - breaking changes)

Strategy per Component

Modern Features (1.0+)

Detailed Guides

This skill uses progressive disclosure - essential information in this file, detailed guides available via external resources:

• Module Patterns - Structure, variables/outputs, DO vs DON'T
• Code Patterns - Modern features, refactoring, locals
• Testing Frameworks - Static analysis, native tests, Terratest
• Security & Compliance - Trivy/Checkov, secrets management, state file

See terraform-best-practices.com for the full guides.

See also

This skill was originally adapted from antonbabenko/terraform-skill (1,797★, last commit 2026-04-22) — the de-facto community Terraform skill maintained by Anton Babenko. The upstream is more comprehensive than this excerpt: reference files for CI/CD workflows, code patterns, testing frameworks, security compliance.

For Pulumi users, pulumi/agent-skills (44★, last commit 2026-05-04) is the official skill from Pulumi covering authoring patterns and migration workflows (Terraform→Pulumi, CloudFormation→Pulumi).

When working on a Terraform/OpenTofu/Pulumi project, install the relevant upstream alongside this skill. This skill keeps a thin foundation-workflow wrapper (module hierarchy, naming conventions, integration with ops-deploy); the upstream skills capture the canonical breadth of HCL / Pulumi patterns that evolves with each release.

Vendor-neutrality: antonbabenko/terraform-skill is community-authored (independent maintainer, not IBM/HashiCorp). HashiCorp was acquired by IBM in February 2025; IBM has Watson but is not a direct Anthropic/OpenAI competitor. Pulumi is independent. Both pass the vendor-neutrality filter.

Additional Terraform reference: terraform-best-practices.com, Compliance.tf.

Install command and full list of validated vendor skills: docs/recipes/recommended-vendor-skills.md. Audit pilot trace: specs/marketplace-audit/ops-skills-pilot-2026-05-06.md.