terraform-skill

Terraform Skill - Infrastructure as Code Best Practices Guide

Skill Overview

Based on terraform-best-practices.com and hands-on enterprise experience, this provides end-to-end guidance for Terraform and OpenTofu, covering testing strategies, module design, CI/CD integration, and production deployment patterns.

Use Cases

1. Create Terraform/OpenTofu Configurations and Modules

When you need to write new infrastructure code, the skill provides best practices for module structure design, naming conventions, and resource block ordering. It includes principles for layering resource modules, infrastructure modules, and combination layers to help you build a maintainable and reusable IaC codebase.

2. Build and Optimize an IaC Testing System

The skill helps you choose the right testing strategy: from free static analysis (validate, fmt, tflint) to Terraform 1.6+ native testing frameworks, and then to Terratest for integration testing. It provides a testing pyramid methodology to balance coverage and cost, including low-cost testing approaches using Mock Providers.

3. Build Infrastructure CI/CD Pipelines

Guides you in setting up a complete CI/CD workflow: formatting checks → validation → testing → plan → apply. Provides integration templates for GitHub Actions, GitLab CI, and Atlantis, along with cost-optimization strategies (use Mock for PR validation, run integration tests on the main branch, and automatically clean up test resources).

4. Design Multi-Environment Deployment Architecture

Supports enterprise-grade multi-environment deployment (dev, staging, prod) solutions, including module/environment separation, directory structure organization, and cross-account/cross-region deployment patterns. Offers advanced techniques such as managing dependencies with locals and stateless refactoring with moved blocks.

Core Features

1. Testing Framework Decision and Implementation

Provides a testing decision matrix. Based on your Terraform version, team skills, and cost budget, it recommends the most suitable testing approach. Includes best practices for Terraform 1.6+ native testing frameworks and low-cost unit testing guidance with Mock Provider for 1.7+.

2. Code Structure Conventions

Strictly defines ordering rules for resource blocks and variable blocks to ensure code consistency. Covers when to use count vs for_each, module hierarchy design, naming conventions (resources, variables, files), and applying modern Terraform features (try(), optional(), cross-variable validation).

3. Production Security and Compliance

Integrates security scanning tools such as Trivy and Checkov. Provides security best practices including key management (AWS Secrets Manager/Parameter Store), encrypting state files, and minimal-permission security groups. Includes policy-as-code compliance checks using OPA and Sentinel.

4. Version Management and Migration

Provides feature comparisons between Terraform and OpenTofu, along with migration guidance. Covers version constraint syntax (~>, >=, exact versions), Provider/Module version pinning strategies, and upgrade workflows. Offers differentiated guidance for versions Terraform 1.0–1.5, 1.6+, and 1.7+.

Common Questions

What’s the difference between Terraform and OpenTofu? Which should I choose?

Terraform and OpenTofu are highly compatible in terms of functionality; OpenTofu is Terraform’s open-source fork. The main differences are licensing (HashiCorp BSL vs Mozilla MPL) and community governance. For new projects, if you care about license flexibility and open community governance, choose OpenTofu; if your enterprise already uses the HashiCorp product ecosystem, you can continue using Terraform. This skill fully supports both and provides a detailed comparison in the Quick Reference.

How do I write tests for Terraform code?

Recommended approach depends on your Terraform version and needs: Terraform 1.6+ uses the native terraform test command (free, built-in); complex integration tests use Terratest; security compliance uses OPA/Sentinel; cost-sensitive cases use Mock Provider for 1.7+. The skill provides a testing pyramid methodology: lower-level static analysis (validate, tflint, trivy) → mid-level module isolation tests → top-level end-to-end environment tests.

How should Terraform modules be organized?

Recommended is a three-layer directory structure: environments/ (environment-specific configuration), modules/ (reusable modules), examples/ (usage examples and integration tests). Modules are divided into resource modules (a single logical resource group) → infrastructure modules (combinations of multiple resource modules) → composition layer (across regions/accounts). File naming conventions: main.tf (main resources), variables.tf (input variables), outputs.tf (outputs), versions.tf (Provider versions).

When should I use count vs for_each?

count: Suitable for boolean condition toggles (count = condition ? 1 : 0) or duplicating a fixed number of identical resources.
for_each: Suitable for cases where list elements may be reordered or deleted (avoid unintended resource recreation), referencing resources by key, and scenarios involving multiple named resources.
Core principle: use for_each when you need stable resource addresses; use count for simple switches.

How do I set up a Terraform CI/CD pipeline?

A standard workflow has four stages: Validate (format checks + syntax validation + lint) → Test (run automated tests) → Plan (generate an execution plan for review) → Apply (execute changes; production environments require approval). Cost-optimization strategies: use Mock Provider for PR validation (free), run real integration tests on the main branch (to control cost), and automatically clean up test resources. The skill provides complete templates for GitHub Actions, GitLab CI, and Atlantis.

How do I perform security scanning for Terraform code?

Recommend using Trivy (fewer false positives, fast) and Checkov (rich rules) for static security scanning. Common checks include hard-coded secrets, default VPC usage, missing encryption, and security group rules opening 0.0.0.0/0. Use pre-commit hooks to run checks automatically before code is committed. Secret management should use AWS Secrets Manager/Parameter Store or similar services to avoid storing secrets in plaintext within variables.

What are best practices for Terraform multi-environment deployment?

Core principles: separate environment configuration from reusable modules. Store dev, staging, and prod environment-specific configurations in the environments/ directory, and store common modules in modules/. Module version management: production environments pin exact versions (version = "5.1.2"), while development environments allow patch updates (version = "~> 5.1"). Use Workspaces or separate backend state files for isolation, and use a consistent module structure across environments to ensure consistency.

Note: This skill focuses on best practices at the Terraform/OpenTofu code level. It does not cover specific cloud platform API references or general syntax issues (Claude has built-in support). For Provider-specific configuration, refer to the official documentation.