Terraform Copilot

Generates, validates, and manages Terraform infrastructure-as-code configurations with registry intelligence and HCP Terraform workflow automation.

When to Use This Agent

Choose this agent when you need to:

• Generate compliant Terraform configurations using latest provider and module versions resolved from public and private registries
• Manage HCP Terraform workspace lifecycles including creation, variable management, run orchestration, and plan review
• Refactor existing Terraform codebases into modular, well-structured layouts following HashiCorp style conventions

Consider alternatives when:

• Your infrastructure tooling is Pulumi, CloudFormation, or Ansible rather than Terraform and HCL
• You need to manually execute terraform apply against a local state backend without HCP Terraform integration

Quick Start

Configuration

Copy
name: terraform-copilot
type: agent
category: security

Example Invocation

Copy
claude agent:invoke terraform-copilot "Create a Terraform module for an AWS VPC with public and private subnets across 3 AZs"

Example Output

Module: terraform-aws-vpc v1.0.0

Registry Resolution:
  Provider: hashicorp/aws v5.82.0 (latest)
  Module: hashicorp/vpc/aws v5.16.0 (reference)

Generated Files:
  terraform-aws-vpc/
  ├── main.tf          (VPC, subnets, NAT gateways, route tables)
  ├── variables.tf     (12 inputs, alphabetical order)
  ├── outputs.tf       (8 outputs, alphabetical order)
  ├── providers.tf     (AWS provider with version constraint)
  ├── backend.tf       (HCP Terraform cloud block)
  ├── locals.tf        (AZ calculation, CIDR slicing)
  ├── README.md        (Usage examples, input/output docs)
  └── tests/
      └── vpc.tftest.hcl  (4 test cases)

Validation: terraform validate passed
Security: No hardcoded secrets detected

Core Concepts

Terraform Workflow Overview

Aspect	Details
Registry Intelligence	Resolve latest provider and module versions from public and private registries before code generation
File Structure	Required: main.tf, variables.tf, outputs.tf, README.md. Recommended: providers.tf, backend.tf, locals.tf
Code Standards	2-space indentation, aligned equals signs, meta-arguments first, alphabetical variables and outputs
State Management	Remote state via HCP Terraform cloud backend with workspace isolation per environment
Run Lifecycle	Create run, review plan output, verify expected changes, apply or discard, monitor for drift

Terraform Module Architecture

terraform-<PROVIDER>-<NAME>/
├── main.tf              [Resource definitions]
├── variables.tf         [Inputs - alphabetical]
├── outputs.tf           [Outputs - alphabetical]
├── providers.tf         [Provider version constraints]
├── backend.tf           [HCP Terraform cloud block]
├── locals.tf            [Computed local values]
├── README.md            [Usage documentation]
├── modules/
│   ├── submodule-a/     [Nested, public if README]
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── submodule-b/     [Nested, internal if no README]
├── examples/
│   └── basic/           [External source references]
└── tests/
    └── module.tftest.hcl [Terraform test framework]

Configuration

Parameter	Type	Default	Description
cloudOrganization	string	""	HCP Terraform organization name for backend configuration and workspace management
providerVersioning	string	"latest"	Provider version strategy: latest, pinned, or pessimistic constraint (~>)
moduleNaming	string	"terraform-{provider}-{name}"	Naming convention pattern for generated module directories
stateBackend	string	"cloud"	State storage backend: cloud (HCP Terraform), s3, gcs, azurerm, or local
validationLevel	string	"strict"	Post-generation validation: basic (syntax only), strict (security + formatting), or full (with plan)

Best Practices

1. Resolve Registry Versions Before Generating Code - Always query the registry for latest provider and module versions rather than hardcoding version numbers from memory. Stale version constraints miss critical bug fixes and security patches, while unresolvable versions cause init failures. Document resolved versions in code comments for auditability.

2. Never Hardcode Sensitive Values in HCL Files - API keys, passwords, and tokens must flow through workspace variables marked as sensitive, not through terraform.tfvars or inline defaults. HCL files are committed to version control where secrets become permanently embedded in git history, creating a security exposure that persists even after the values are rotated.

3. Structure Modules Around Single Infrastructure Concerns - A module that provisions a VPC, deploys containers, and configures DNS violates single-responsibility and becomes difficult to test, version, and reuse. Decompose into focused modules (networking, compute, DNS) composed at the root level, enabling independent evolution and selective adoption across projects.

4. Review Plans Before Every Apply Operation - Terraform plan output reveals the exact resources to be created, modified, or destroyed. Skipping plan review risks unintended data loss, service disruption, or cost spikes. Treat plan review as a mandatory gate in both manual workflows and CI/CD pipelines, with explicit approval required for destructive changes.

5. Write Terraform Tests for Module Contracts - The terraform test framework validates that modules produce expected outputs for given inputs without provisioning real infrastructure. Test files in the tests/ directory verify variable validation rules, output value correctness, and resource configuration logic, catching regressions before modules are consumed by downstream configurations.

Common Issues

1. State Lock Contention in Team Environments - Multiple engineers running terraform apply simultaneously against the same workspace causes state lock conflicts. HCP Terraform serializes runs automatically, but teams using S3 or GCS backends must configure DynamoDB or GCS-native locking. Establish a workflow where only CI/CD pipelines apply changes, reducing concurrent access to state.

2. Provider Version Constraint Conflicts - When root modules and child modules specify incompatible provider version constraints, terraform init fails with version resolution errors. Use pessimistic constraints (~> 5.0) rather than exact pins (= 5.82.0) in modules, reserving exact pinning for root-level configurations where you control the full dependency tree.

3. Drift Between Applied State and HCL Configuration - Manual changes made through cloud consoles create drift that terraform plan surfaces as unexpected modifications. Enable drift detection in HCP Terraform workspaces, run scheduled plan-only operations to detect drift early, and enforce a policy that all infrastructure changes flow through Terraform to maintain configuration as the single source of truth.