Terraform Infrastructure Skill

Installation

The skill invokes the Terraform CLI. Install:

macOS: brew tap hashicorp/tap && brew install hashicorp/tap/terraform
Windows: choco install terraform or download from HashiCorp
Linux (apt): Add HashiCorp repo then sudo apt update && sudo apt install terraform (see HashiCorp install)

Verify: terraform --version

Cheat Sheet & Best Practices

Workflow: terraform init → terraform fmt → terraform validate → terraform plan -out=tfplan → review → terraform apply tfplan. Use terraform show tfplan to inspect.

Hacks: Always run plan before apply; never apply blind. Use remote state (e.g. S3 + lock) for team work. Prefer -auto-approve only in CI with reviewed plans. Use terraform state list and terraform state show <resource> to debug. Use service accounts / workload identity in pipelines; avoid static keys.

Certifications & Training

HashiCorp Terraform Associate (004): IaC concepts, Terraform fundamentals, state, modules, Terraform Cloud. Learning path. Skill data: init → fmt → validate → plan -out → apply; remote state; no blind apply.

Hooks & Workflows

Suggested hooks: Pre-apply: run terraform plan -out=tfplan and gate on review. CI: apply only after plan approval. Use with devops (primary).

Workflows: Use with devops (primary). Flow: init → plan → review → apply; use state commands for debugging. See ci-cd-implementation-rule for pipeline integration.

Overview

Provides 90%+ context savings vs raw Terraform MCP server. Includes critical safety controls for infrastructure operations.

Requirements

Terraform CLI (v1.0+)
Cloud provider credentials configured
Working directory with .tf files

Tools (Progressive Disclosure)

Planning & Validation

Tool	Description	Confirmation
plan	Generate terraform plan	No
validate	Validate configuration	No
fmt	Format terraform files	No

State Operations

Tool	Description	Confirmation
show	Display current state	No
list	List state resources	No
state-mv	Move resource in state	Yes

Workspace Operations

Tool	Description	Confirmation
workspace-list	List workspaces	No
workspace-select	Select workspace	No
workspace-new	Create workspace	Yes

Execution (⚠️ Dangerous)

Tool	Description	Confirmation
apply	Apply changes	REQUIRED

Blocked Operations

Tool	Status
destroy	BLOCKED
state-rm	BLOCKED

Quick Reference

# Initialize
terraform init

# Plan changes
terraform plan -out=tfplan

# Validate
terraform validate

# Apply (requires -auto-approve for automation)
terraform apply tfplan

Configuration

Working directory: Must contain terraform files
TFVAR*: Variable values via environment
TF_WORKSPACE: Active workspace

Safety Controls

⚠️ terraform apply ALWAYS requires confirmation ⚠️ terraform destroy is BLOCKED by default ⚠️ State modifications require confirmation ⚠️ Review plan output before apply

Agent Integration

devops (primary): Infrastructure management
architect (secondary): Infrastructure design
cloud-integrator (secondary): Cloud provisioning

Troubleshooting

Issue	Solution
Init failed	Check provider credentials
State locked	Check for other operations
Plan failed	Review error output carefully

Module Development

Creating Reusable Modules

Structure modules following HashiCorp conventions:

modules/
  vpc/
    main.tf          # Resource definitions
    variables.tf     # Input variables
    outputs.tf       # Output values
    versions.tf      # Required provider versions
    README.md        # Module documentation

Module Best Practices

Practice	Description
Single responsibility	Each module manages one logical resource group
Typed variables	Use `type` constraints on all variables
Validation blocks	Add `validation {}` for input constraints
Sensitive outputs	Mark secrets with `sensitive = true`
Version constraints	Pin module source versions

Module Source Patterns

# Local module
module "vpc" {
  source = "./modules/vpc"
}

# Terraform Registry
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"
}

# Git source (pinned tag)
module "vpc" {
  source = "git::https://github.com/org/modules.git//vpc?ref=v1.2.0"
}

Provider Development Patterns

Custom Provider Skeleton

package provider

import (
    "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

func Provider() *schema.Provider {
    return &schema.Provider{
        Schema: map[string]*schema.Schema{
            "api_key": {
                Type:        schema.TypeString,
                Required:    true,
                Sensitive:   true,
                DefaultFunc: schema.EnvDefaultFunc("API_KEY", nil),
            },
        },
        ResourcesMap: map[string]*schema.Resource{
            "myservice_resource": resourceMyServiceResource(),
        },
    }
}

Testing Modules

# Validate module syntax
cd modules/vpc && terraform validate

# Run module tests (Terraform 1.6+)
terraform test

# Plan with module
terraform plan -var-file=examples/basic.tfvars

Iron Laws

ALWAYS run terraform plan and review the output before executing terraform apply
NEVER hardcode credentials or secrets in .tf files — use secret managers (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
ALWAYS use remote state with encryption and state locking to prevent concurrent modifications
NEVER edit state files directly — use terraform state commands exclusively
ALWAYS pin provider and module versions for fully reproducible infrastructure deployments

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Hardcoded credentials in .tf files	Secret exposure in VCS, compliance failure	Use variables with secret manager backend
No state locking	Concurrent applies corrupt state	Enable backend locking (S3+DynamoDB, Azure Blob, GCS)
`terraform apply` without plan review	Unexpected resource deletion or recreation	Always `plan` first, review diff, then `apply`
Unversioned providers and modules	Non-reproducible builds and breaking changes	Pin versions: `version = "~> 4.0"`
Untagged resources	Untrackable costs and compliance failure	Tag all resources with env, owner, cost-center

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

terraform-infra