How to Organize Terraform Files for Clean Infrastructure Code

Organize Terraform files by separating configuration into logical files like main.tf, variables.tf, and outputs.tf. Use folders for modules and environments to keep code reusable and manageable.

Syntax

Terraform configuration is split into multiple files with specific roles:

• main.tf: Core resource definitions.
• variables.tf: Input variable declarations.
• outputs.tf: Output values to expose.
• providers.tf: Provider configurations.
• terraform.tfvars: Variable values.

Folders can group modules or environments for better structure.

plaintext

terraform-project/
├── main.tf
├── variables.tf
├── outputs.tf
├── providers.tf
├── terraform.tfvars
└── modules/
    └── network/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Example

This example shows a simple Terraform project with separated files and a module folder for reusable network resources.

terraform

terraform-project/

# main.tf
resource "aws_instance" "example" {
  ami           = var.ami_id
  instance_type = var.instance_type
  subnet_id     = module.network.subnet_id
}

module "network" {
  source = "./modules/network"
  cidr_block = var.vpc_cidr
}

# variables.tf
variable "ami_id" {
  description = "AMI ID to use for the instance"
  type        = string
}

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t2.micro"
}

variable "vpc_cidr" {
  description = "CIDR block for VPC"
  type        = string
  default     = "10.0.0.0/16"
}

# outputs.tf
output "instance_id" {
  value = aws_instance.example.id
}

# modules/network/main.tf
resource "aws_vpc" "main" {
  cidr_block = var.cidr_block
}

resource "aws_subnet" "main" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.0.1.0/24"
}

# modules/network/variables.tf
variable "cidr_block" {
  description = "VPC CIDR block"
  type        = string
}

# modules/network/outputs.tf
output "subnet_id" {
  value = aws_subnet.main.id
}

Output

Plan: 3 to add, 0 to change, 0 to destroy.

Common Pitfalls

Common mistakes when organizing Terraform files include:

• Putting all code in one file, making it hard to read and maintain.
• Mixing variable declarations and resource definitions in the same file.
• Not using modules for reusable components, causing duplication.
• Ignoring environment separation, which can lead to accidental changes.

Keep files focused and use folders for modules and environments.

terraform

Wrong organization example:

# all_resources.tf
variable "ami_id" {}
resource "aws_instance" "example" {}
output "instance_id" {}

Right organization example:

# variables.tf
variable "ami_id" {}

# main.tf
resource "aws_instance" "example" {}

# outputs.tf
output "instance_id" {}

Quick Reference

Tips for organizing Terraform files:

• Use main.tf for resources.
• Declare inputs in variables.tf.
• Define outputs in outputs.tf.
• Configure providers in providers.tf.
• Group reusable code in modules/ folders.
• Separate environments with folders like dev/, prod/.

Key Takeaways

Separate Terraform code into logical files like main.tf, variables.tf, and outputs.tf for clarity.

Use modules folders to keep reusable infrastructure components organized.

Avoid mixing variable declarations and resource definitions in the same file.

Create folders for different environments to prevent accidental resource changes.

Consistent file organization improves maintainability and collaboration.