Terraform Skill

1---
2name: terraform-skill
3description: "Terraform infrastructure as code best practices"
4license: Apache-2.0
5metadata: 
6author: "Anton Babenko"
7version: 1.5.0
8source: "https://github.com/antonbabenko/terraform-skill"
9risk: safe
10---
11# Terraform Skill for Claude
12 
13Comprehensive Terraform and OpenTofu guidance covering testing, modules, CI/CD, and production patterns. Based on terraform-best-practices.com and enterprise experience.
14 
15## When to Use This Skill
16 
17**Activate this skill when:**
18- Creating new Terraform or OpenTofu configurations or modules
19- Setting up testing infrastructure for IaC code
20- Deciding between testing approaches (validate, plan, frameworks)
21- Structuring multi-environment deployments
22- Implementing CI/CD for infrastructure-as-code
23- Reviewing or refactoring existing Terraform/OpenTofu projects
24- Choosing between module patterns or state management approaches
25 
26**Don't use this skill for:**
27- Basic Terraform/OpenTofu syntax questions (Claude knows this)
28- Provider-specific API reference (link to docs instead)
29- Cloud platform questions unrelated to Terraform/OpenTofu
30 
31## Core Principles
32 
33### 1. Code Structure Philosophy
34 
35**Module Hierarchy:**
36 
37| Type | When to Use | Scope |
38|------|-------------|-------|
39| **Resource Module** | Single logical group of connected resources | VPC + subnets, Security group + rules |
40| **Infrastructure Module** | Collection of resource modules for a purpose | Multiple resource modules in one region/account |
41| **Composition** | Complete infrastructure | Spans multiple regions/accounts |
42 
43**Hierarchy:** Resource → Resource Module → Infrastructure Module → Composition
44 
45**Directory Structure:**
46```
47environments/        # Environment-specific configurations
48├── prod/
49├── staging/
50└── dev/
51 
52modules/            # Reusable modules
53├── networking/
54├── compute/
55└── data/
56 
57examples/           # Module usage examples (also serve as tests)
58├── complete/
59└── minimal/
60```
61 
62**Key principle from terraform-best-practices.com:**
63- Separate **environments** (prod, staging) from **modules** (reusable components)
64- Use **examples/** as both documentation and integration test fixtures
65- Keep modules small and focused (single responsibility)
66 
67**For detailed module architecture, see:** [Code Patterns: Module Types & Hierarchy](references/code-patterns.md)
68 
69### 2. Naming Conventions
70 
71**Resources:**
72```hcl
73# Good: Descriptive, contextual
74resource "aws_instance" "web_server" { }
75resource "aws_s3_bucket" "application_logs" { }
76 
77# Good: "this" for singleton resources (only one of that type)
78resource "aws_vpc" "this" { }
79resource "aws_security_group" "this" { }
80 
81# Avoid: Generic names for non-singletons
82resource "aws_instance" "main" { }
83resource "aws_s3_bucket" "bucket" { }
84```
85 
86**Singleton Resources:**
87 
88Use `"this"` when your module creates only one resource of that type:
89 
90✅ DO:
91```hcl
92resource "aws_vpc" "this" {}           # Module creates one VPC
93resource "aws_security_group" "this" {}  # Module creates one SG
94```
95 
96❌ DON'T use "this" for multiple resources:
97```hcl
98resource "aws_subnet" "this" {}  # If creating multiple subnets
99```
100 
101Use descriptive names when creating multiple resources of the same type.
102 
103**Variables:**
104```hcl
105# Prefix with context when needed
106var.vpc_cidr_block          # Not just "cidr"
107var.database_instance_class # Not just "instance_class"
108```
109 
110**Files:**
111- `main.tf` - Primary resources
112- `variables.tf` - Input variables
113- `outputs.tf` - Output values
114- `versions.tf` - Provider versions
115- `data.tf` - Data sources (optional)
116 
117## Testing Strategy Framework
118 
119### Decision Matrix: Which Testing Approach?
120 
121| Your Situation | Recommended Approach | Tools | Cost |
122|----------------|---------------------|-------|------|
123| **Quick syntax check** | Static analysis | `terraform validate`, `fmt` | Free |
124| **Pre-commit validation** | Static + lint | `validate`, `tflint`, `trivy`, `checkov` | Free |
125| **Terraform 1.6+, simple logic** | Native test framework | Built-in `terraform test` | Free-Low |
126| **Pre-1.6, or Go expertise** | Integration testing | Terratest | Low-Med |
127| **Security/compliance focus** | Policy as code | OPA, Sentinel | Free |
128| **Cost-sensitive workflow** | Mock providers (1.7+) | Native tests + mocking | Free |
129| **Multi-cloud, complex** | Full integration | Terratest + real infra | Med-High |
130 
131### Testing Pyramid for Infrastructure
132 
133```
134        /\
135       /  \          End-to-End Tests (Expensive)
136      /____\         - Full environment deployment
137     /      \        - Production-like setup
138    /________\
139   /          \      Integration Tests (Moderate)
140  /____________\     - Module testing in isolation
141 /              \    - Real resources in test account
142/________________\   Static Analysis (Cheap)
143                     - validate, fmt, lint
144                     - Security scanning
145```
146 
147### Native Test Best Practices (1.6+)
148 
149**Before generating test code:**
150 
1511. **Validate schemas with Terraform MCP:**
152   ```
153   Search provider docs → Get resource schema → Identify block types
154   ```
155 
1562. **Choose correct command mode:**
157   - `command = plan` - Fast, for input validation
158   - `command = apply` - Required for computed values and set-type blocks
159 
1603. **Handle set-type blocks correctly:**
161   - Cannot index with `[0]`
162   - Use `for` expressions to iterate
163   - Or use `command = apply` to materialize
164 
165**Common patterns:**
166- S3 encryption rules: **set** (use for expressions)
167- Lifecycle transitions: **set** (use for expressions)
168- IAM policy statements: **set** (use for expressions)
169 
170**For detailed testing guides, see:**
171- **[Testing Frameworks Guide](references/testing-frameworks.md)** - Deep dive into static analysis, native tests, and Terratest
172- **[Quick Reference](references/quick-reference.md#testing-approach-selection)** - Decision flowchart and command cheat sheet
173 
174## Code Structure Standards
175 
176### Resource Block Ordering
177 
178**Strict ordering for consistency:**
1791. `count` or `for_each` FIRST (blank line after)
1802. Other arguments
1813. `tags` as last real argument
1824. `depends_on` after tags (if needed)
1835. `lifecycle` at the very end (if needed)
184 
185```hcl
186# ✅ GOOD - Correct ordering
187resource "aws_nat_gateway" "this" {
188  count = var.create_nat_gateway ? 1 : 0
189 
190  allocation_id = aws_eip.this[0].id
191  subnet_id     = aws_subnet.public[0].id
192 
193  tags = {
194    Name = "${var.name}-nat"
195  }
196 
197  depends_on = [aws_internet_gateway.this]
198 
199  lifecycle {
200    create_before_destroy = true
201  }
202}
203```
204 
205### Variable Block Ordering
206 
2071. `description` (ALWAYS required)
2082. `type`
2093. `default`
2104. `validation`
2115. `nullable` (when setting to false)
212 
213```hcl
214variable "environment" {
215  description = "Environment name for resource tagging"
216  type        = string
217  default     = "dev"
218 
219  validation {
220    condition     = contains(["dev", "staging", "prod"], var.environment)
221    error_message = "Environment must be one of: dev, staging, prod."
222  }
223 
224  nullable = false
225}
226```
227 
228**For complete structure guidelines, see:** [Code Patterns: Block Ordering & Structure](references/code-patterns.md#block-ordering--structure)
229 
230## Count vs For_Each: When to Use Each
231 
232### Quick Decision Guide
233 
234| Scenario | Use | Why |
235|----------|-----|-----|
236| Boolean condition (create or don't) | `count = condition ? 1 : 0` | Simple on/off toggle |
237| Simple numeric replication | `count = 3` | Fixed number of identical resources |
238| Items may be reordered/removed | `for_each = toset(list)` | Stable resource addresses |
239| Reference by key | `for_each = map` | Named access to resources |
240| Multiple named resources | `for_each` | Better maintainability |
241 
242### Common Patterns
243 
244**Boolean conditions:**
245```hcl
246# ✅ GOOD - Boolean condition
247resource "aws_nat_gateway" "this" {
248  count = var.create_nat_gateway ? 1 : 0
249  # ...
250}
251```
252 
253**Stable addressing with for_each:**
254```hcl
255# ✅ GOOD - Removing "us-east-1b" only affects that subnet
256resource "aws_subnet" "private" {
257  for_each = toset(var.availability_zones)
258 
259  availability_zone = each.key
260  # ...
261}
262 
263# ❌ BAD - Removing middle AZ recreates all subsequent subnets
264resource "aws_subnet" "private" {
265  count = length(var.availability_zones)
266 
267  availability_zone = var.availability_zones[count.index]
268  # ...
269}
270```
271 
272**For migration guides and detailed examples, see:** [Code Patterns: Count vs For_Each](references/code-patterns.md#count-vs-for_each-deep-dive)
273 
274## Locals for Dependency Management
275 
276**Use locals to ensure correct resource deletion order:**
277 
278```hcl
279# Problem: Subnets might be deleted after CIDR blocks, causing errors
280# Solution: Use try() in locals to hint deletion order
281 
282locals {
283  # References secondary CIDR first, falling back to VPC
284  # Forces Terraform to delete subnets before CIDR association
285  vpc_id = try(
286    aws_vpc_ipv4_cidr_block_association.this[0].vpc_id,
287    aws_vpc.this.id,
288    ""
289  )
290}
291 
292resource "aws_vpc" "this" {
293  cidr_block = "10.0.0.0/16"
294}
295 
296resource "aws_vpc_ipv4_cidr_block_association" "this" {
297  count = var.add_secondary_cidr ? 1 : 0
298 
299  vpc_id     = aws_vpc.this.id
300  cidr_block = "10.1.0.0/16"
301}
302 
303resource "aws_subnet" "public" {
304  vpc_id     = local.vpc_id  # Uses local, not direct reference
305  cidr_block = "10.1.0.0/24"
306}
307```
308 
309**Why this matters:**
310- Prevents deletion errors when destroying infrastructure
311- Ensures correct dependency order without explicit `depends_on`
312- Particularly useful for VPC configurations with secondary CIDR blocks
313 
314**For detailed examples, see:** [Code Patterns: Locals for Dependency Management](references/code-patterns.md#locals-for-dependency-management)
315 
316## Module Development
317 
318### Standard Module Structure
319 
320```
321my-module/
322├── README.md           # Usage documentation
323├── main.tf             # Primary resources
324├── variables.tf        # Input variables with descriptions
325├── outputs.tf          # Output values
326├── versions.tf         # Provider version constraints
327├── examples/
328│   ├── minimal/        # Minimal working example
329│   └── complete/       # Full-featured example
330└── tests/              # Test files
331    └── module_test.tftest.hcl  # Or .go
332```
333 
334### Best Practices Summary
335 
336**Variables:**
337- ✅ Always include `description`
338- ✅ Use explicit `type` constraints
339- ✅ Provide sensible `default` values where appropriate
340- ✅ Add `validation` blocks for complex constraints
341- ✅ Use `sensitive = true` for secrets
342 
343**Outputs:**
344- ✅ Always include `description`
345- ✅ Mark sensitive outputs with `sensitive = true`
346- ✅ Consider returning objects for related values
347- ✅ Document what consumers should do with each output
348 
349**For detailed module patterns, see:**
350- **[Module Patterns Guide](references/module-patterns.md)** - Variable best practices, output design, ✅ DO vs ❌ DON'T patterns
351- **[Quick Reference](references/quick-reference.md#common-patterns)** - Resource naming, variable naming, file organization
352 
353## CI/CD Integration
354 
355### Recommended Workflow Stages
356 
3571. **Validate** - Format check + syntax validation + linting
3582. **Test** - Run automated tests (native or Terratest)
3593. **Plan** - Generate and review execution plan
3604. **Apply** - Execute changes (with approvals for production)
361 
362### Cost Optimization Strategy
363 
3641. **Use mocking for PR validation** (free)
3652. **Run integration tests only on main branch** (controlled cost)
3663. **Implement auto-cleanup** (prevent orphaned resources)
3674. **Tag all test resources** (track spending)
368 
369**For complete CI/CD templates, see:**
370- **[CI/CD Workflows Guide](references/ci-cd-workflows.md)** - GitHub Actions, GitLab CI, Atlantis integration, cost optimization
371- **[Quick Reference](references/quick-reference.md#troubleshooting-guide)** - Common CI/CD issues and solutions
372 
373## Security & Compliance
374 
375### Essential Security Checks
376 
377```bash
378# Static security scanning
379trivy config .
380checkov -d .
381```
382 
383### Common Issues to Avoid
384 
385❌ **Don't:**
386- Store secrets in variables
387- Use default VPC
388- Skip encryption
389- Open security groups to 0.0.0.0/0
390 
391✅ **Do:**
392- Use AWS Secrets Manager / Parameter Store
393- Create dedicated VPCs
394- Enable encryption at rest
395- Use least-privilege security groups
396 
397**For detailed security guidance, see:**
398- **[Security & Compliance Guide](references/security-compliance.md)** - Trivy/Checkov integration, secrets management, state file security, compliance testing
399 
400## Version Management
401 
402### Version Constraint Syntax
403 
404```hcl
405version = "5.0.0"      # Exact (avoid - inflexible)
406version = "~> 5.0"     # Recommended: 5.0.x only
407version = ">= 5.0"     # Minimum (risky - breaking changes)
408```
409 
410### Strategy by Component
411 
412| Component | Strategy | Example |
413|-----------|----------|---------|
414| **Terraform** | Pin minor version | `required_version = "~> 1.9"` |
415| **Providers** | Pin major version | `version = "~> 5.0"` |
416| **Modules (prod)** | Pin exact version | `version = "5.1.2"` |
417| **Modules (dev)** | Allow patch updates | `version = "~> 5.1"` |
418 
419### Update Workflow
420 
421```bash
422# Lock versions initially
423terraform init              # Creates .terraform.lock.hcl
424 
425# Update to latest within constraints
426terraform init -upgrade     # Updates providers
427 
428# Review and test
429terraform plan
430```
431 
432**For detailed version management, see:** [Code Patterns: Version Management](references/code-patterns.md#version-management)
433 
434## Modern Terraform Features (1.0+)
435 
436### Feature Availability by Version
437 
438| Feature | Version | Use Case |
439|---------|---------|----------|
440| `try()` function | 0.13+ | Safe fallbacks, replaces `element(concat())` |
441| `nullable = false` | 1.1+ | Prevent null values in variables |
442| `moved` blocks | 1.1+ | Refactor without destroy/recreate |
443| `optional()` with defaults | 1.3+ | Optional object attributes |
444| Native testing | 1.6+ | Built-in test framework |
445| Mock providers | 1.7+ | Cost-free unit testing |
446| Provider functions | 1.8+ | Provider-specific data transformation |
447| Cross-variable validation | 1.9+ | Validate relationships between variables |
448| Write-only arguments | 1.11+ | Secrets never stored in state |
449 
450### Quick Examples
451 
452```hcl
453# try() - Safe fallbacks (0.13+)
454output "sg_id" {
455  value = try(aws_security_group.this[0].id, "")
456}
457 
458# optional() - Optional attributes with defaults (1.3+)
459variable "config" {
460  type = object({
461    name    = string
462    timeout = optional(number, 300)  # Default: 300
463  })
464}
465 
466# Cross-variable validation (1.9+)
467variable "environment" { type = string }
468variable "backup_days" {
469  type = number
470  validation {
471    condition     = var.environment == "prod" ? var.backup_days >= 7 : true
472    error_message = "Production requires backup_days >= 7"
473  }
474}
475```
476 
477**For complete patterns and examples, see:** [Code Patterns: Modern Terraform Features](references/code-patterns.md#modern-terraform-features-10)
478 
479## Version-Specific Guidance
480 
481### Terraform 1.0-1.5
482- Use Terratest for testing
483- No native testing framework available
484- Focus on static analysis and plan validation
485 
486### Terraform 1.6+ / OpenTofu 1.6+
487- **New:** Native `terraform test` / `tofu test` command
488- Consider migrating from external frameworks for simple tests
489- Keep Terratest only for complex integration tests
490 
491### Terraform 1.7+ / OpenTofu 1.7+
492- **New:** Mock providers for unit testing
493- Reduce cost by mocking external dependencies
494- Use real integration tests for final validation
495 
496### Terraform vs OpenTofu
497 
498Both are fully supported by this skill. For licensing, governance, and feature comparison, see [Quick Reference: Terraform vs OpenTofu](references/quick-reference.md#terraform-vs-opentofu-comparison).
499 
500## Detailed Guides
501 
502This skill uses **progressive disclosure** - essential information is in this main file, detailed guides are available when needed:
503 
504📚 **Reference Files:**
505- **[Testing Frameworks](references/testing-frameworks.md)** - In-depth guide to static analysis, native tests, and Terratest
506- **[Module Patterns](references/module-patterns.md)** - Module structure, variable/output best practices, ✅ DO vs ❌ DON'T patterns
507- **[CI/CD Workflows](references/ci-cd-workflows.md)** - GitHub Actions, GitLab CI templates, cost optimization, automated cleanup
508- **[Security & Compliance](references/security-compliance.md)** - Trivy/Checkov integration, secrets management, compliance testing
509- **[Quick Reference](references/quick-reference.md)** - Command cheat sheets, decision flowcharts, troubleshooting guide
510 
511**How to use:** When you need detailed information on a topic, reference the appropriate guide. Claude will load it on demand to provide comprehensive guidance.
512 
513## License
514 
515This skill is licensed under the **Apache License 2.0**. See the LICENSE file for full terms.
516 
517**Copyright © 2026 Anton Babenko**
518