Code Organization
This guide covers best practices for organizing Terraform code in a maintainable and scalable way.
Project Structure
Root Level Organization
├── environments/
│ ├── dev/
│ ├── staging/
│ └── prod/
├── modules/
│ ├── networking/
│ ├── compute/
│ └── database/
├── templates/
└── scripts/
File Naming Conventions
Standard Files
├── main.tf # Primary configuration file
├── variables.tf # Input variables
├── outputs.tf # Output definitions
├── versions.tf # Required providers and versions
├── locals.tf # Local variables
└── terraform.tfvars # Variable values (git-ignored)
Module Structure
Module Organization
modules/
└── networking/
├── main.tf
├── variables.tf
├── outputs.tf
├── README.md
└── examples/
└── complete/
└── main.tf
Module Interface Design
# variables.tf
variable "resource_prefix" {
description = "Prefix for all resources created by this module"
type = string
}
variable "tags" {
description = "Tags to apply to all resources"
type = map(string)
default = {}
}
Code Style Guidelines
Naming Conventions
# Resource Naming
resource "aws_instance" "web_server" {
name = "${var.environment}-${var.project}-web-server"
}
# Variable Naming
variable "vpc_cidr_block" {
description = "CIDR block for VPC"
type = string
}
Resource Blocks
resource "aws_instance" "web_server" {
# Required parameters first
ami = var.ami_id
instance_type = var.instance_type
# Optional/computed parameters
tags = merge(
var.common_tags,
{
Name = "web-server"
}
)
# Nested blocks last
root_block_device {
volume_size = 20
}
}
Workspaces Organization
Environment Separation
# prod/main.tf
module "vpc" {
source = "../../modules/vpc"
environment = terraform.workspace
cidr_block = var.vpc_cidr_blocks[terraform.workspace]
}
Variables Management
Variable Definition Structure
# variables.tf
variable "instance_config" {
description = "Configuration for EC2 instances"
type = object({
instance_type = string
ami_id = string
volume_size = number
})
}
# terraform.tfvars
instance_config = {
instance_type = "t3.micro"
ami_id = "ami-12345678"
volume_size = 20
}
Documentation Standards
Module Documentation
# AWS VPC Module
## Description
Creates a VPC with public and private subnets.
## Requirements
| Name | Version |
|------|---------|
| terraform | >= 1.0.0 |
| aws | >= 4.0.0 |
## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| vpc_cidr | The CIDR block for the VPC | string | n/a | yes |
## Outputs
| Name | Description |
|------|-------------|
| vpc_id | The ID of the VPC |
Version Control
.gitignore Template
# Local .terraform directories
**/.terraform/*
# .tfstate files
*.tfstate
*.tfstate.*
# Crash log files
crash.log
# Exclude tfvars files that may contain sensitive data
*.tfvars
*.tfvars.json
# Override files
override.tf
override.tf.json
*_override.tf
*_override.tf.json
Code Review Guidelines
Pull Request Template
## Description
Describe the changes made in this PR.
## Type of Change
- [ ] New Resource
- [ ] Resource Modification
- [ ] Bug Fix
- [ ] Breaking Change
## Checklist
- [ ] `terraform fmt` run
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] Example added (if applicable)
Testing Structure
Test Organization
module/
├── test/
│ ├── fixtures/
│ │ └── example/
│ │ └── main.tf
│ └── integration/
│ └── example_test.go
└── examples/
└── complete/
└── main.tf
Best Practices Checklist
Last updated