Terraform Docs

Terraform Documentation Generator

Overview

Transform Terraform code into comprehensive, user-friendly documentation. This skill analyzes Terraform configurations and generates formatted documentation including module READMEs, architecture overviews, operational runbooks, and quick reference guides.

Quick Start

Provide Terraform files or point to a Terraform module/configuration, then specify the documentation type needed:

"Document this Terraform module"
"Create architecture docs for these Terraform files"
"Generate a runbook for this infrastructure"
"Create a quick reference for this Terraform configuration"

The skill will analyze the code and produce formatted documentation appropriate for the target audience.

Detailed Instructions

Step 1: Analyze Terraform Code

Parse and understand the Terraform configuration:

Identify Key Components:

• Resources - What infrastructure is being created (awsinstance, azurermstorage_account, etc.)
• Variables - Input parameters, their types, defaults, and descriptions
• Outputs - Values exported by the module
• Providers - Cloud providers and versions required
• Data sources - External data being referenced
• Locals - Internal computed values
• Modules - Child modules being called

Extract Metadata:

• Required provider versions
• Terraform version constraints
• Backend configuration
• Dependencies between resources
• Security configurations (IAM, security groups, policies)

Understand Purpose:

• What problem does this infrastructure solve?
• What services/resources are the core components?
• How do components interact?
• What are the security and networking patterns?

Step 2: Choose Documentation Format

Select the appropriate documentation type based on user request:

Module README

For: Terraform modules that will be reused Audience: Developers using the module Focus: Inputs, outputs, usage examples

Architecture Documentation

For: Complete infrastructure setups Audience: Technical stakeholders, architects Focus: High-level design, component relationships, diagrams

Runbook

For: Operational infrastructure Audience: DevOps, SRE, operations teams Focus: Deployment, troubleshooting, maintenance

Quick Reference

For: Complex configurations Audience: Team members working with the code Focus: Key resources, variables, common tasks

Step 3: Generate Documentation

Module README Format

# [Module Name]

## Overview
[Brief description of what this module creates and why]

## Architecture
[Simple diagram or description of resources created]

## Usage

### Basic Example
```hcl
module "example" {
  source = "./modules/[module-name]"

  # Required variables
  [var1] = "[value1]"
  [var2] = "[value2]"
}

Complete Example

[Full working example with all options]

Requirements

| Name | Version | |------|---------| | terraform | >= 1.0 | | aws | >= 4.0 |

Providers

| Name | Version | |------|---------| | aws | >= 4.0 |

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | [var1] | [description] | string | "default" | no | | [var2] | [description] | number | n/a | yes |

Outputs

| Name | Description | |------|-------------| | [output1] | [description] | | [output2] | [description] |

Resources Created

• [resource_type]: [description of what it does]
• [resource_type]: [description of what it does]

Security Considerations

• [Security feature 1]
• [Security feature 2]

Cost Considerations

[Notes about what will incur costs]

Examples

See the [examples](examples/) directory for more usage examples.

License

[License information]

#### Architecture Documentation Format

```markdown
# [Infrastructure Name] - Architecture Documentation

## Overview

[High-level description of the infrastructure]

### Purpose
[What problem this infrastructure solves]

### Key Components
- **[Component 1]**: [Role and purpose]
- **[Component 2]**: [Role and purpose]
- **[Component 3]**: [Role and purpose]

## Architecture Diagram

[ASCII diagram or mermaid diagram showing component relationships]

Example: ┌─────────────────┐ │ CloudFront │ └────────┬────────┘ │ ┌────▼─────┐ │ ALB │ └────┬─────┘ │ ┌──────┴──────┐ │ ECS │ │ Cluster │ └──────┬──────┘ │ ┌────▼─────┐ │ RDS │ └──────────┘

## Components

### [Component 1 Name]

**Type**: [e.g., Load Balancer, Database, Compute]

**Purpose**: [What this component does]

**Configuration Highlights**:
- [Key setting 1]
- [Key setting 2]

**Resources**:
- `[resource_name]` - [description]

**Dependencies**:
- Depends on: [other components]
- Used by: [other components]

### [Component 2 Name]
[Repeat structure]

## Networking

### VPC Architecture
- **CIDR Block**: [CIDR]
- **Subnets**: [Public/Private configuration]
- **Availability Zones**: [AZ strategy]

### Security Groups
- **[SG Name]**: [Purpose and rules]

### Network Flow
[Description of how traffic flows through the architecture]

## Security

### IAM Roles and Policies
- **[Role Name]**: [Purpose and permissions]

### Encryption
- **At Rest**: [What's encrypted and how]
- **In Transit**: [TLS/SSL configuration]

### Access Control
[How access is controlled]

## High Availability & Disaster Recovery

### HA Strategy
[How high availability is achieved]

### Backup Strategy
[What's backed up and how]

### Disaster Recovery
- **RTO**: [Recovery Time Objective]
- **RPO**: [Recovery Point Objective]

## Monitoring & Logging

### CloudWatch Metrics
- [Key metrics being tracked]

### Logging
- [What's being logged and where]

### Alarms
- [Critical alarms configured]

## Cost Optimization

### Cost Breakdown
- [Major cost drivers]

### Optimization Opportunities
- [Potential cost savings]

## Deployment

See [RUNBOOK.md](RUNBOOK.md) for deployment instructions.

## Terraform Configuration

- **Terraform Version**: [version]
- **Providers**: [list]
- **Backend**: [backend type and configuration]

## File Structure

terraform/ ├── main.tf # Main resource definitions ├── variables.tf # Input variables ├── outputs.tf # Output values ├── providers.tf # Provider configurations └── modules/ # Child modules

## Maintenance

### Updates
[How to update the infrastructure]

### Scaling
[How to scale resources]

## Support

For issues or questions, contact [team/email].

Runbook Format

# [Infrastructure Name] - Operations Runbook

## Quick Reference

| Item | Value |
|------|-------|
| AWS Account | [account-id] |
| Region | [region] |
| Environment | [prod/staging/dev] |
| Terraform Backend | [S3 bucket/location] |

## Prerequisites

- Terraform >= [version]
- AWS CLI configured with appropriate credentials
- Required permissions: [list]

## Initial Deployment

### Step 1: Configure Backend

```bash
# Initialize Terraform backend
terraform init \
  -backend-config="bucket=[bucket-name]" \
  -backend-config="key=[state-key]" \
  -backend-config="region=[region]"

Step 2: Review Configuration

# Review variables
cat terraform.tfvars

# Validate configuration
terraform validate

# Plan deployment
terraform plan -out=tfplan

Step 3: Deploy

# Apply the plan
terraform apply tfplan

# Verify deployment
terraform output

Daily Operations

Viewing Current State

# Show current state
terraform show

# List all resources
terraform state list

# Get specific resource details
terraform state show [resource_address]

Making Changes

# 1. Update .tf files or variables
# 2. Plan changes
terraform plan -out=tfplan

# 3. Review the plan carefully
# 4. Apply changes
terraform apply tfplan

Checking Outputs

# View all outputs
terraform output

# Get specific output
terraform output [output_name]

Common Tasks

Adding a New Environment

1. Copy terraform.tfvars.example to [env].tfvars
2. Update variables for the new environment
3. Deploy: terraform apply -var-file=[env].tfvars

Scaling Resources

Scale Up/Down [Resource Type]:

# Update the variable
terraform apply -var="[instance_count]=5"

# Or update terraform.tfvars and apply
terraform apply

Updating Security Groups

# 1. Update security group rules in main.tf
# 2. Plan to see impact
terraform plan

# 3. Apply changes
terraform apply

Rotating Credentials

Database Credentials:

# 1. Update secrets in AWS Secrets Manager
# 2. Force resource update
terraform apply -replace="[resource_address]"

Backup and Recovery

Create Manual Backup:

# For RDS
aws rds create-db-snapshot \
  --db-instance-identifier [db-name] \
  --db-snapshot-identifier [snapshot-name]

Restore from Backup:

[Step-by-step restoration procedure]

Troubleshooting

Issue: Terraform State Lock

Symptoms: "Error acquiring the state lock"

Solution:

# Check who has the lock (in DynamoDB)
aws dynamodb get-item \
  --table-name [lock-table] \
  --key '{"LockID":{"S":"[state-path]"}}'

# Force unlock (use with caution!)
terraform force-unlock [lock-id]

Issue: Resource Creation Fails

Symptoms: Apply fails with error creating resource

Diagnosis:

1. Check AWS service limits
2. Verify IAM permissions
3. Review CloudWatch logs

Solution:

# Get detailed error
terraform apply -debug 2>&1 | tee terraform-debug.log

# Check specific resource
terraform state show [resource_address]

# Taint and recreate if needed
terraform taint [resource_address]
terraform apply

Issue: Drift Detection

Symptoms: Manual changes made outside Terraform

Detection:

# Run plan to detect drift
terraform plan -refresh-only

# Refresh state to match reality
terraform apply -refresh-only

Resolution:

• Option 1: Update Terraform to match reality
• Option 2: Revert manual changes to match Terraform

Issue: Dependency Errors

Symptoms: "depends on resource that doesn't exist"

Solution:

# Refresh state
terraform refresh

# Re-import resource if needed
terraform import [resource_address] [resource_id]

Disaster Recovery

Complete Infrastructure Loss

Recovery Steps:

1. Retrieve State File:

``bash # State is in S3 backend aws s3 cp s3://[bucket]/[key] terraform.tfstate ``

1. Verify State:

``bash terraform state list ``

1. Rebuild:

``bash terraform apply ``

State File Corruption

Recovery:

# Retrieve previous version from S3
aws s3api list-object-versions \
  --bucket [bucket] \
  --prefix [key]

# Download specific version
aws s3api get-object \
  --bucket [bucket] \
  --key [key] \
  --version-id [version] \
  terraform.tfstate.backup

Maintenance Windows

Applying Updates

Best Practices:

1. Always run during maintenance window
2. Create backup before changes
3. Test in non-prod environment first
4. Have rollback plan ready

Procedure:

# 1. Create state backup
terraform state pull > backup-$(date +%Y%m%d-%H%M%S).tfstate

# 2. Plan changes
terraform plan -out=tfplan

# 3. Apply with auto-approve (in scripts only)
terraform apply tfplan

# 4. Verify
[verification commands]

Rolling Back Changes

# Revert to previous state
terraform state push backup-[timestamp].tfstate

# Or revert code and re-apply
git revert [commit]
terraform apply

Monitoring

Key Metrics to Watch

• [Metric 1]: [What it means, threshold]
• [Metric 2]: [What it means, threshold]

Accessing Logs

# CloudWatch Logs
aws logs tail [log-group-name] --follow

# Application logs
[specific log access commands]

Alerts

| Alert | Severity | Action | |-------|----------|--------| | [Alert name] | Critical | [What to do] | | [Alert name] | Warning | [What to do] |

Decommissioning

Destroying Infrastructure

WARNING: This is irreversible!

# 1. Backup critical data first!
[backup commands]

# 2. Create final state backup
terraform state pull > final-backup-$(date +%Y%m%d).tfstate

# 3. Plan destroy
terraform plan -destroy

# 4. Destroy (with confirmation)
terraform destroy

# 5. Clean up backend
[cleanup commands]

Contacts

| Role | Contact | Escalation | |------|---------|------------| | Primary | [name/email] | [phone] | | Secondary | [name/email] | [phone] | | Manager | [name/email] | [phone] |

References

• Architecture Docs: [ARCHITECTURE.md](ARCHITECTURE.md)
• Module README: [README.md](README.md)
• Terraform Docs: https://terraform.io/docs

#### Quick Reference Format

```markdown
# [Infrastructure Name] - Quick Reference

## Terraform Basics

### Initialize
```bash
terraform init

Plan

terraform plan
terraform plan -out=tfplan
terraform plan -var-file=prod.tfvars

Apply

terraform apply
terraform apply tfplan
terraform apply -auto-approve  # Use with caution!

Destroy

terraform destroy
terraform destroy -target=[resource_address]

Common Commands

State Management

# List resources
terraform state list

# Show resource details
terraform state show [resource_address]

# Move resource
terraform state mv [source] [destination]

# Remove resource from state
terraform state rm [resource_address]

# Import existing resource
terraform import [resource_address] [resource_id]

Outputs

# Show all outputs
terraform output

# Show specific output
terraform output [output_name]

# JSON format
terraform output -json

Workspace Management

# List workspaces
terraform workspace list

# Create workspace
terraform workspace new [name]

# Switch workspace
terraform workspace select [name]

# Delete workspace
terraform workspace delete [name]

Key Resources

[Resource Category 1]

| Resource | Address | Purpose | |----------|---------|---------| | [Name] | [resource_address] | [What it does] |

[Resource Category 2]

| Resource | Address | Purpose | |----------|---------|---------| | [Name] | [resource_address] | [What it does] |

Variables

Required Variables

| Variable | Type | Description | Example | |----------|------|-------------|---------| | [var1] | string | [description] | "value" | | [var2] | number | [description] | 10 |

Optional Variables

| Variable | Type | Default | Description | |----------|------|---------|-------------| | [var1] | string | "default" | [description] | | [var2] | bool | true | [description] |

Outputs

| Output | Description | Usage | |--------|-------------|-------| | [output1] | [description] | [how to use it] | | [output2] | [description] | [how to use it] |

File Structure

.
├── main.tf              # Main configuration
├── variables.tf         # Input variables
├── outputs.tf           # Output values
├── providers.tf         # Provider configs
├── terraform.tfvars     # Variable values (gitignored)
├── versions.tf          # Version constraints
└── modules/
    └── [module-name]/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Useful Snippets

Get Resource ARN

terraform state show [resource_address] | grep arn

Find Resources by Type

terraform state list | grep [resource_type]

Format All Files

terraform fmt -recursive

Validate Configuration

terraform validate

Check for Drift

terraform plan -refresh-only

Target Specific Resource

terraform apply -target=[resource_address]

Troubleshooting Quick Fixes

State Lock Issue

terraform force-unlock [lock-id]

Refresh State

terraform refresh

Taint Resource (force recreate)

terraform taint [resource_address]
terraform apply

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tomique34](https://github.com/tomique34)
- **Source:** [tomique34/claude-skill-creator](https://github.com/tomique34/claude-skill-creator)
- **License:** MIT

Install and usage instructions live in the source repository linked above.