Terraform Project

---
applyTo: "**/*.tf, **/*.tfvars"
---

# Terraform Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest Terraform documentation: https://developer.hashicorp.com/terraform/docs
- Use Terraform 1.5+ for new projects
- Write declarative infrastructure as code with HCL
- Use modules for reusable infrastructure components
- Implement proper state management with remote backends
- Follow Terraform best practices for organization and naming

**Core Principles:**

- Use modules to organize and reuse infrastructure code
- Store state remotely (S3, Azure Blob, Terraform Cloud)
- Use workspaces for managing multiple environments
- Implement proper variable and output management
- Use data sources to reference existing resources
- Follow naming conventions: lowercase with underscores

**Project Structure:**

- Organize code with main.tf, variables.tf, outputs.tf
- Use separate files for different resource types
- Create reusable modules in modules/ directory
- Use terraform.tfvars for variable values
- Implement backend.tf for state configuration

**Variables and Outputs:**

- Define input variables with proper types and descriptions
- Use validation rules for variable constraints
- Set default values when appropriate
- Output important values for other modules/scripts
- Use sensitive flag for confidential outputs

**State Management:**

- Use remote state backend (S3, Azure, GCS)
- Enable state locking to prevent concurrent modifications
- Never commit .tfstate files to version control
- Use terraform state commands carefully
- Implement state encryption at rest

**Modules:**

- Create reusable modules for common infrastructure patterns
- Define clear module interfaces (variables and outputs)
- Version modules using semantic versioning
- Publish modules to Terraform Registry or private registry
- Document module usage and examples

**Best Practices:**

- Use terraform fmt for consistent formatting
- Run terraform validate before applying
- Use terraform plan to preview changes
- Implement proper dependency management with depends_on
- Use count or for_each for creating multiple resources
- Tag all resources for organization and cost tracking

**Security:**

- Never hardcode credentials in .tf files
- Use environment variables or secret management services
- Implement least privilege IAM policies
- Enable encryption for sensitive data
- Use private registries for internal modules

**CI/CD:**

- Implement automated terraform plan in pull requests
- Use terraform apply with approval gates
- Version control all Terraform code
- Implement automated testing with terratest
- Use Terraform Cloud or Atlantis for collaboration

**Summary:**

> For all Terraform work, always use the fetch tool to look up the latest documentation from https://developer.hashicorp.com/terraform/docs. Build reliable, repeatable infrastructure as code.