Obay's Terraform Naming Convention (OTN)

Obay’s Terraform Naming Convention (OTN)

Overview

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”)

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: