Tryboy869 Terraform Best Practices
Terraform configurations are production-grade software. Treat them with the same rigor: readable, versioned, testable, and governed by automated policies. This guide provides opinionated, actionable best practices for our team's Terraform development, ensuring consistency, reliability, and security.
1. Code Organization and Structure
Organize your Terraform code for clarity, reusability, and environment isolation.
1.1 Project Layout
Always separate environments and reusable components.
❌ BAD: Monolithic main.tf or environment-specific resources mixed with modules.
# environments/dev/main.tf
resource "aws_vpc" "dev_vpc" { # ... }
resource "aws_s3_bucket" "dev_app_bucket" { # ... }
# Duplicated for staging/prod
✅ GOOD: Dedicated directories for environments and shared modules.
├── environments/
│ ├── dev/
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ ├── backend.tf
│ │ └── terraform.tfvars
│ ├── prod/
│ ├── main.tf
│ ├── variables.tf
│ ├── backend.tf
│ └── terraform.tfvars
├── modules/
│ ├── vpc/
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ └── outputs.tf
│ └── s3_bucket/
│ ├── main.tf
│ ├── variables.tf
│ └── outputs.tf
1.2 Standard File Naming
Use HashiCorp's recommended file naming conventions for consistency.
backend.tf: Remote state configuration.main.tf: Primary resource and module calls.outputs.tf: All output blocks, alphabetically sorted.providers.tf:terraformblock (required version/providers) andproviderblocks.variables.tf: All variable blocks, alphabetically sorted.locals.tf: Local values.
2. Naming Conventions
Consistency in naming is paramount for readability.
2.1 Resource and Variable Names
Use lower_snake_case for all resource, data source, variable, and output names. Never include the resource type in the name.
❌ BAD:
resource "aws_s3_bucket" "s3_bucket_app_logs" { # ... }
variable "vpcName" { # ... }
✅ GOOD:
resource "aws_s3_bucket" "app_logs" { # ... }
variable "vpc_name" { # ... }
2.2 Boolean Variables
Use positive boolean flags ending with _enabled.
❌ BAD:
variable "disable_encryption" { type = bool }
✅ GOOD:
variable "encryption_enabled" { type = bool }
2.3 Descriptions
Every variable and output block must include a description.
variable "instance_type" {
description = "The EC2 instance type to use for the server."
type = string
default = "t3.micro"
}
output "vpc_id" {
description = "The ID of the created VPC."
value = aws_vpc.main.id
}
3. State Management
Remote state and locking are non-negotiable for team collaboration.
3.1 Remote State and Locking
Always use a remote backend (e.g., S3 with DynamoDB locking). Never rely on local state in shared environments.
# backend.tf
terraform {
backend "s3" {
bucket = "my-team-terraform-state"
key = "environments/prod/app/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-state-lock" # Must be pre-created
encrypt = true
}
}
3.2 Workspaces
Avoid terraform workspace for environment isolation. Use separate backend configurations in distinct directories (e.g., environments/dev, environments/prod) instead. Workspaces are primarily for ephemeral, short-lived deployments or testing variations within a single configuration.
4. Modules: Reusability and Abstraction
Modules are the cornerstone of scalable Terraform.
4.1 Module Design
Design modules to be single-purpose, composable, and reusable. Abstract implementation details.
❌ BAD: A module that creates a VPC, an RDS instance, and an S3 bucket.
✅ GOOD: Separate modules for vpc, rds_instance, and s3_bucket.
4.2 Module Inputs and Outputs
- Inputs: Parameterize only what needs to vary. Use
nullable = falsefor variables that should never benull(especially lists, maps, objects defaulting to empty). - Outputs: Provide meaningful outputs with descriptions. Never pass outputs directly through input variables; reference resource attributes to ensure implicit dependencies.
# modules/vpc/variables.tf
variable "vpc_cidr" {
description = "CIDR block for the VPC."
type = string
}
variable "tags" {
description = "A map of tags to assign to all resources in the VPC."
type = map(string)
default = {}
nullable = false # Ensure tags is always a map, even if empty
}
# modules/vpc/outputs.tf
output "vpc_id" {
description = "The ID of the created VPC."
value = aws_vpc.main.id
}
5. Common Patterns and Anti-patterns
5.1 Loops and Conditionals (for_each, count)
Use for_each for creating multiple instances of a resource when you have a map or set of strings, as it provides better state management and readability than count. Use count for simple numeric iteration or conditional resource creation (when count is 0 or 1).
❌ BAD: Using count with a map for resource creation.
resource "aws_instance" "app_servers" {
count = length(var.instance_configs) # var.instance_configs is a map
# ...
tags = {
Name = var.instance_configs[count.index].name
}
}
✅ GOOD: Using for_each with a map for resource creation.
resource "aws_instance" "app_servers" {
for_each = var.instance_configs # var.instance_configs is a map of objects
# ...
tags = {
Name = each.value.name
}
}
5.2 Dynamic Blocks
Use dynamic blocks to construct repeatable nested blocks based on a complex variable.
resource "aws_security_group" "web" {
# ...
dynamic "ingress" {
for_each = var.ingress_rules
content {
from_port = ingress.value.from_port
to_port = ingress.value.to_port
protocol = ingress.value.protocol
cidr_blocks = ingress.value.cidr_blocks
}
}
}
5.3 Tagging Resources
Always tag all resources with meaningful metadata (e.g., Project, Environment, Owner, CostCenter). Use a default_tags block in your provider configuration.
provider "aws" {
region = "us-east-1"
default_tags {
tags = {
Project = "MyApplication"
Environment = "prod"
ManagedBy = "Terraform"
}
}
}
6. Security and Configuration Management
6.1 Secrets Management
Never hardcode sensitive data. Fetch secrets dynamically from a dedicated secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault).
❌ BAD:
resource "aws_db_instance" "app_db" {
password = "SuperSecretPassword123!" # NEVER DO THIS
}
✅ GOOD:
data "aws_secretsmanager_secret_version" "db_creds" {
secret_id = "prod/my-app/db-credentials"
}
locals {
db_credentials = jsondecode(data.aws_secretsmanager_secret_version.db_creds.secret_string)
}
resource "aws_db_instance" "app_db" {
password = local.db_credentials.password
}
6.2 Policy as Code
Integrate Policy as Code (e.g., Open Policy Agent (OPA) or HashiCorp Sentinel) into your CI/CD pipeline to enforce organizational compliance and security policies before deployment.
7. Common Pitfalls and Gotchas
7.1 Formatting and Validation
Always run terraform fmt and terraform validate before committing. Integrate these into Git pre-commit hooks and CI/CD pipelines.
7.2 Linting
Use a linter like TFLint to catch style violations, potential errors, and enforce best practices early.
7.3 Version Pinning
Always pin versions for Terraform, providers, and modules to ensure reproducible deployments and prevent unexpected changes.
# providers.tf
terraform {
required_version = "~> 1.5" # Pin Terraform CLI version
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0" # Pin AWS provider version
}
}
}
# main.tf (for modules)
module "vpc" {
source = "cloudposse/vpc/aws"
version = "2.0.0" # Pin module version
# ...
}
7.4 Lifecycle Management
Use the lifecycle block judiciously, especially prevent_destroy for critical resources and create_before_destroy for zero-downtime updates.
resource "aws_s3_bucket" "critical_data" {
bucket = "my-critical-data-bucket"
# ...
lifecycle {
prevent_destroy = true # Protect critical resources from accidental deletion
}
}
8. CI/CD Integration
Automate your Terraform workflow with CI/CD.
8.1 Automated Plan Checks
Every pull request must trigger a terraform plan and post the output as a comment or check. This ensures visibility and prevents unexpected changes.
8.2 Automated Apply
Implement automated terraform apply on merge to main (or environment branches) only after successful plan, validation, and policy checks. This requires robust state locking and access controls.