tomevault-io Terraform Standards
Purpose
Ensure infrastructure is defined, managed, and deployed in a consistent, secure, and scalable way using Terraform.
Infrastructure must be:
- reproducible
- version-controlled
- predictable
- safe to change
- aligned with application architecture
Core Principles
1. Infrastructure as Source of Truth
Terraform is the single source of truth for infrastructure.
- do not manually modify resources in production
- do not rely on console-driven changes
- all infrastructure must be declared and versioned
2. Idempotency
Terraform runs should produce the same result every time.
- no side effects
- no unpredictable behavior
- no reliance on execution order hacks
3. Declarative Over Imperative
Define what the infrastructure should be, not how to create it.
4. Safe Change Management
Infrastructure changes must be:
- reviewable
- predictable
- reversible
5. Least Privilege
Infrastructure should enforce minimal access by default.
Project Structure
Recommended Layout
/infra /modules /vpc /ecs /rds /alb /dev main.tf variables.tf outputs.tf /staging /prod
Environment Separation
Each environment must be isolated:
- separate state files
- separate resources where required
- no shared mutable state across environments
Rules
- dev, staging, and prod must not overlap
- production must not depend on dev resources
- environment-specific values must be configurable
State Management
Rules
- use remote state (e.g., S3 + DynamoDB locking)
- never commit state files to version control
- enable state locking
- restrict access to state storage
Security
- state files may contain sensitive data
- restrict access using IAM
- encrypt state at rest
Modules
Purpose
Promote reuse and consistency.
Rules
- create reusable modules for common patterns
- keep modules focused and single-purpose
- avoid overly generic modules
- define clear inputs and outputs
- version modules where appropriate
Examples
- VPC module
- ECS service module
- RDS module
- ALB module
Naming Conventions
Rules
- use consistent naming across all resources
- include environment and service context
Example: app-prod-api-alb app-dev-postgres
- avoid random or ambiguous names
- prefer readability over brevity
Variables and Configuration
Rules
- define all configurable values as variables
- avoid hardcoding values
- use sensible defaults where appropriate
- document variables clearly
Sensitive Variables
- mark secrets as sensitive
- never log or output sensitive values
- use secret managers where possible
Outputs
Rules
- expose only necessary outputs
- do not expose secrets
- use outputs for cross-module communication
Resource Management
Rules
- tag all resources
- define lifecycle rules explicitly when needed
- avoid orphaned resources
- ensure cleanup paths exist
Tagging Standards
All resources must include tags:
- environment (dev, staging, prod)
- service or application name
- owner (team or system)
- cost allocation tag
Example:
Environment = “prod”
Service = “job-board”
Owner = “platform”
}```
---
## Security Standards
### Rules
- restrict security group rules to least privilege
- avoid open ports (0.0.0.0/0) unless necessary
- keep databases in private subnets
- enforce encryption where supported
- use IAM roles instead of static credentials
---
## Networking Standards
### Rules
- separate public and private subnets
- place ALBs in public subnets
- place compute (ECS, services) in private subnets
- restrict outbound access where possible
- use NAT gateways only when required
---
## Secrets Management
### Rules
- do not store secrets in Terraform code
- use AWS Secrets Manager or SSM
- reference secrets dynamically
- avoid exposing secrets in outputs or logs
---
## Plan and Apply Workflow
### Rules
- always run `terraform plan` before apply
- review changes before applying
- do not apply blindly
- use CI/CD pipelines for production changes
---
## CI/CD Integration
### Requirements
- automated plan generation
- manual approval for production applies
- consistent environment deployment flow
- audit trail of changes
---
## Drift Management
### Rules
- detect infrastructure drift regularly
- reconcile drift through Terraform
- do not manually “fix” drift in production without updating code
---
## Dependency Management
### Rules
- use explicit dependencies where needed
- avoid implicit coupling
- avoid circular dependencies
---
## Lifecycle Rules
Use lifecycle blocks carefully:
- prevent_destroy for critical resources
- ignore_changes only when justified
Avoid masking real changes.
---
## Scaling and Resilience
### Rules
- design for high availability where required
- distribute across availability zones
- avoid single points of failure
- configure autoscaling where appropriate
---
## Cost Awareness
### Rules
- avoid unnecessary resources
- clean up unused infrastructure
- monitor cost-impacting resources
- right-size instances and services
---
## Documentation
### Rules
- document module purpose
- document variables and outputs
- explain non-obvious design decisions
---
## Review Checklist
Before applying changes:
- Is the plan reviewed?
- Are resources named correctly?
- Are tags applied?
- Are security rules restricted?
- Are secrets handled securely?
- Is state managed properly?
- Are environments isolated?
- Is this change safe to apply?
- Is rollback possible?
---
## Anti-Patterns to Avoid
Do not:
- manually change infrastructure in the console
- hardcode secrets
- use overly broad security rules
- create giant, unmaintainable modules
- skip plan review
- reuse state across environments
- ignore drift
- create hidden dependencies
---
## Goal
Build infrastructure that is:
- predictable
- secure
- scalable
- easy to understand
- safe to evolve
Infrastructure should be as reliable and maintainable as application code.
---
> Source: [christopherclemmons/startupkit](https://github.com/christopherclemmons/startupkit) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->