Obay's Terraform Naming Convention (OTN)

Obay’s Terraform Naming Convention (OTN) is a standardized approach to organizing Terraform files that promotes clarity, consistency, and maintainability in infrastructure-as-code projects. The core principle is simple: one block per file, named according to the block type and identifier.

Core Principles

#

1. One Block Per File: Each Terraform file contains exactly one resource, data source, provider, variable, output, or module block
2. Predictable Naming: File names follow a consistent pattern based on the block type and name
3. Self-Documenting: File names immediately indicate what infrastructure component they define
4. Tool-Supported: The tfren tool automates file renaming according to this convention

Naming Patterns

#

Resources and Data Sources

#

{block_type}.{resource_type}.{resource_name}.tf

Examples:

• resource.azurerm_virtual_network.sandbox-vnet.tf
• resource.aws_instance.web-server.tf
• data.aws_ami.ubuntu.tf
• data.azurerm_resource_group.production-rg.tf

Providers

#

provider.{provider_name}.tf

Examples:

• provider.aws.tf
• provider.azurerm.tf
• provider.google.tf

With Aliases:

provider.{provider_name}.{alias}.tf

Examples:

• provider.aws.us-east-1.tf
• provider.azurerm.production.tf

Variables and Outputs

#

{block_type}.{name}.tf

Examples:

• variable.environment.tf
• variable.instance_type.tf
• output.public_ip.tf
• output.database_url.tf

Modules

#

module.{module_name}.tf

Examples:

• module.vpc.tf
• module.database.tf
• module.load_balancer.tf

Special Cases

#

Locals Block:

locals.tf

Terraform Block:

terraform.tf

Benefits

#

1. Immediate Understanding

#

When you see a file named resource.aws_lb.web-alb.tf, you instantly know:

• It’s a resource block
• It defines an AWS load balancer
• The resource is named “web-alb”

2. Easier Navigation

#

No more guessing what’s inside each file. The file name tells you everything you need to know.

3. Reduced Merge Conflicts

#

With one block per file, multiple developers can work on different resources without conflicts.

4. Better Code Reviews

#

Reviewers can quickly identify which infrastructure components are being modified.

5. Automated Tooling

#

The tfren tool automatically renames files according to this convention.

Implementation with tfren

#

The tfren tool automates the application of OTN:

Installation

#

Linux & macOS:

brew tap obay/tap
brew install tfren

Windows:

scoop bucket add obay https://github.com/obay/scoop-bucket.git
scoop install obay/tfren

Usage

#

Simply run tfren in your Terraform directory:

cd your-terraform-project
tfren

The tool will:

1. Parse each .tf file
2. Identify the first block in each file
3. Generate the appropriate filename according to OTN
4. Rename files that don’t follow the convention

Example Project Structure

#

Before OTN:

project/
├── main.tf
├── variables.tf
├── outputs.tf
├── providers.tf
└── networking.tf

After OTN:

project/
├── resource.aws_vpc.main.tf
├── resource.aws_subnet.public.tf
├── resource.aws_subnet.private.tf
├── resource.aws_internet_gateway.main.tf
├── resource.aws_route_table.public.tf
├── variable.environment.tf
├── variable.instance_type.tf
├── output.vpc_id.tf
├── output.public_subnet_ids.tf
├── provider.aws.tf
└── terraform.tf

Best Practices

#

1. Start with OTN from Day One

#

Apply the naming convention when creating new Terraform projects to avoid future refactoring.

2. Use Descriptive Resource Names

#

Choose resource names that clearly indicate their purpose:

• web-server instead of server
• production-database instead of db
• public-subnet-1a instead of subnet1

3. Consistent Naming Across Environments

#

Use the same resource names across environments, with environment-specific values in variables:

• resource.aws_instance.web-server.tf (same in dev, staging, prod)
• variable.environment.tf (contains “dev”, “staging”, or “prod”)

4. Group Related Resources

#

While each resource is in its own file, group related resources in the same directory:

networking/
├── resource.aws_vpc.main.tf
├── resource.aws_subnet.public.tf
└── resource.aws_subnet.private.tf

compute/
├── resource.aws_instance.web-server.tf
├── resource.aws_instance.app-server.tf
└── resource.aws_autoscaling_group.web-asg.tf

Migration Guide

#

If you have existing Terraform projects, you can migrate to OTN:

1. Install tfren:

   brew tap obay/tap
   brew install tfren

2. Backup your project:

   cp -r your-project your-project-backup

3. Run tfren:

   cd your-project
   tfren

4. Review changes: The tool will show you which files were renamed and why.

5. Update CI/CD pipelines: Update any scripts that reference specific file names.

Limitations and Considerations

#

1. Comments at File Start

#

The tfren tool expects the first line to contain the resource definition. Comments at the start of files may not be handled correctly.

2. Complex Blocks

#

For very complex resource definitions with many nested blocks, consider if the resource should be split into multiple resources.

3. Tool Compatibility

#

Ensure your CI/CD tools and Terraform workflows are compatible with the new file structure.

Conclusion

#

Obay’s Terraform Naming Convention provides a clear, consistent, and maintainable approach to organizing Terraform code. By following this convention and using the tfren tool, teams can improve their infrastructure-as-code practices and reduce the cognitive load of managing complex Terraform projects.

The convention is designed to be simple yet powerful, making it easy to adopt and maintain across teams of all sizes.

Resources:

• tfren GitHub Repository
• Terraform Best Practices
• Infrastructure as Code Patterns