---
name: Terraform Best Practices
description: Comprehensive rules for Terraform and Terragrunt development
---
# Terraform & Terragrunt Development Standards

## Code Structure & Organization
- Always use consistent resource naming: `{environment}-{service}-{resource_type}`
- Group related resources in the same .tf file (e.g., all networking in network.tf)
- Use meaningful file names: variables.tf, outputs.tf, main.tf, locals.tf
- For Terragrunt: keep terragrunt.hcl files focused and minimal

## Resource Configuration
- Always include required_providers block with explicit version constraints
- Use data sources instead of hardcoded values for external resources
- Include comprehensive tags for all AWS resources (at minimum: Name, Environment, Project, Owner)
- Use locals block for computed or repeated values
- Prefer resource-specific data sources over generic ones

## Variables & Outputs
- Always include description and type for variables
- Use validation blocks for variables when constraints are known
- Mark sensitive variables as sensitive = true
- Include meaningful descriptions for all outputs
- Group related variables logically

## Security & Best Practices
- Never hardcode secrets, API keys, or passwords
- Use random_password or similar for generated secrets
- Implement least-privilege IAM policies
- Always encrypt storage at rest and in transit
- Use security groups with specific ports and sources, avoid 0.0.0.0/0 when possible

## Terragrunt Specific
- Use dependency blocks to manage resource dependencies
- Leverage remote_state for cross-stack references
- Use generate blocks for common provider configurations
- Keep inputs block organized and documented
- Use include blocks for shared configurations

## State Management
- Always use remote state backends (S3 + DynamoDB for AWS)
- Use unique state file names per environment/stack
- Include state locking configuration
- Never commit .tfstate files to version control

## Documentation
- Include README.md with usage examples
- Document all module inputs and outputs
- Provide examples of typical usage patterns
- Include terraform-docs formatted comments

Please review this Terraform/Terragrunt code for:

**Security:**
- Hardcoded secrets or sensitive data
- Overly permissive IAM policies or security groups
- Missing encryption configurations

**Best Practices:**
- Proper resource naming conventions
- Appropriate use of variables, locals, and data sources
- Required provider version constraints
- Proper tagging strategy

**Structure:**
- Code organization and file structure
- Use of modules vs. inline resources
- State management configuration

**Terragrunt Specific (if applicable):**
- Proper use of dependencies and remote_state
- Appropriate generate blocks
- Include block usage

Provide specific suggestions for improvement with code examples.

Generate Terraform code for the requested AWS resources following these requirements:

1. Include proper provider configuration with version constraints
2. Use appropriate variable definitions with types and descriptions
3. Implement comprehensive tagging
4. Follow security best practices (encryption, least privilege)
5. Include relevant outputs
6. Add inline comments explaining complex configurations
7. Use data sources for external references where appropriate

Format the response with proper file organization suggestions.

Help me troubleshoot this Terraform/Terragrunt issue:

**Analysis needed:**
- Identify the root cause of the error
- Explain why this error occurred
- Provide step-by-step resolution
- Suggest preventive measures

**Consider common issues:**
- State inconsistencies
- Resource dependencies
- Provider version conflicts
- Authentication/permissions
- Variable/output references

Provide practical solutions with example commands or code fixes.

Analyze this Terraform code for optimization opportunities:

**Performance:**
- Resource creation order and dependencies
- Unnecessary data source calls
- Module efficiency

**Cost Optimization:**
- Right-sizing resources
- Unused or over-provisioned resources
- Storage and compute optimization

**Maintainability:**
- Code duplication reduction
- Module abstraction opportunities
- Variable and local simplification

Provide specific recommendations with cost estimates where possible.

Help me with Terragrunt conversion or improvement:

**For Terraform → Terragrunt conversion:**
- Identify repeated code that can be DRYed up
- Suggest appropriate terragrunt.hcl structure
- Recommend dependency management
- Propose remote state configuration

**For Terragrunt improvement:**
- Optimize include and dependency blocks
- Improve input organization
- Suggest generate block usage
- Recommend module structure

Provide step-by-step migration or improvement plan.