Terraform Engineer Consultant

Your expert agent for designing and implementing Terraform infrastructure across multiple cloud providers, with deep focus on module design, state management, testing, and CI/CD integration.

When to Use This Agent

Choose Terraform Engineer Consultant when:

• Designing reusable Terraform modules for multi-cloud infrastructure
• Implementing Terraform CI/CD pipelines with plan/apply workflows
• Solving complex state management challenges (migration, splitting, importing)
• Establishing Terraform coding standards and module registries
• Evaluating and implementing Terraform testing strategies

Consider alternatives when:

• You need Azure-specific Terraform patterns — use a Terraform Azure agent
• You need infrastructure design without Terraform focus — use a cloud architect agent
• You need Terragrunt orchestration — use a Terragrunt specialist

Quick Start

Copy
# .claude/agents/terraform-engineer.yml
name: Terraform Engineer Consultant
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Multi-cloud Terraform engineer for module design, state management, testing, and CI/CD integration

Example invocation:

claude "Design a composable Terraform module structure for a microservices platform that deploys to AWS with EKS, RDS, ElastiCache, and a service mesh"

Core Concepts

Module Design Principles

Principle	Description	Example
Single Responsibility	One module, one logical resource group	modules/vpc handles networking only
Composability	Modules accept IDs from other modules	VPC module outputs subnet_ids for EKS module
Sensible Defaults	Works out of box, customizable via vars	Default instance size, overridable
Minimal Interface	Expose only necessary variables/outputs	Don't expose internal implementation details
Version Pinning	Pin module versions in consumers	source = "modules/vpc?ref=v2.1.0"

State Management Strategies

├── Monolithic State (small projects)
│   └── Single state file for all resources
│
├── Environment Split (medium projects)
│   ├── dev/terraform.tfstate
│   ├── staging/terraform.tfstate
│   └── prod/terraform.tfstate
│
└── Component Split (large projects)
    ├── networking/terraform.tfstate
    ├── compute/terraform.tfstate
    ├── database/terraform.tfstate
    └── monitoring/terraform.tfstate

Configuration

Parameter	Description	Default
cloud_providers	Target clouds (aws, azure, gcp)	aws
module_registry	Module registry (terraform-cloud, s3, git)	git
test_framework	Testing tool (terratest, terraform-test, checkov)	terraform-test
state_backend	State storage (s3, azurerm, gcs, terraform-cloud)	s3
ci_platform	CI/CD system for plan/apply	github-actions

Best Practices

1. Design modules with clear input/output contracts. Define every variable with a type constraint, description, and validation rule where appropriate. Use output blocks to expose resource attributes that downstream modules need. A well-defined contract makes modules composable and self-documenting.

2. Split state by blast radius, not by convenience. Group resources that change together and have similar risk profiles. Networking state should be separate from application state — a broken Terraform apply on app configs shouldn't risk deleting your VPC.

3. Test infrastructure code at multiple levels. Use terraform validate and terraform plan for fast syntax/logic checks, terraform test (HCL tests) for module contract validation, and Terratest for full integration tests that provision and destroy real resources.

4. Implement a module versioning strategy from the start. Tag module releases with semantic versions. Consumer configs should reference specific versions, never main branch. This prevents a module change from silently affecting all consumers and enables controlled rollouts.

5. Use moved blocks for state refactoring. When renaming resources or reorganizing modules, add moved { from = ... to = ... } blocks in your config. This tells Terraform to update the state rather than destroying and recreating resources, ensuring zero-downtime refactors.

Common Issues

Module versioning conflicts across environments. When dev uses module v3 and prod uses v2, managing the upgrade path is complex. Maintain a compatibility matrix, test each version upgrade in dev first, and use a changelog in each module that clearly marks breaking changes.

State becomes too large and operations are slow. Monolithic state files with hundreds of resources make plans slow and increases blast radius. Split state into logical components using separate Terraform configurations with remote state data sources to share outputs between them.

Provider version conflicts between root and child modules. When modules pin different provider versions, Terraform can't resolve the constraint. Use pessimistic version constraints (~>) in modules, pin exact versions only in the root module, and test provider upgrades by running plans across all environments.