Terraform Configuration Directory Best Practices

Q: Can I use multiple .tf files in the same Terraform configuration directory?

Yes. Terraform automatically loads and merges all .tf files located within the same configuration directory.

Q: Is main.tf required?

No. main.tf is a common convention but not a Terraform requirement. You can use any file name as long as it has a supported Terraform configuration extension.

Q: What is terraform.tfvars used for?

terraform.tfvars provides values for input variables declared in variables.tf. It allows you to separate configuration values from infrastructure definitions.

Every Terraform project starts with a directory that contains configuration files. How you organize those files affects maintainability, troubleshooting, code reviews, and long-term scalability.

Terraform automatically loads all configuration files from a working directory and evaluates them as a single configuration. Understanding how the Terraform configuration directory works helps you build cleaner infrastructure code and collaborate more effectively with other engineers.

In this guide, you'll learn what a Terraform configuration directory is, which files typically belong in it, how Terraform processes those files, and the best practices used in production environments.

What Is a Terraform Configuration Directory and Why Does It Matter?

A Terraform configuration directory is the folder that contains your Terraform configuration files.

When you run commands such as terraform init, terraform plan, or terraform apply, Terraform scans the current working directory for files ending in the .tf or .tf.json extension.

Terraform then combines all configuration files within that directory into a single configuration during execution.

Because of this behavior, you can split infrastructure code across multiple files without changing how Terraform processes the configuration.

If you're new to Terraform, consider reviewing our guide on Terraform Commands Explained to understand how Terraform interacts with your configuration directory during initialization, planning, and deployment.

Organizing .tf Files Inside a Terraform Configuration Directory

Terraform does not require specific file names. As long as the files use the .tf extension, Terraform loads them automatically.

That said, most teams follow naming conventions that make projects easier to understand and maintain.

main.tf

main.tf typically contains the primary resource definitions for your infrastructure.

For smaller projects, this file may contain most of the configuration. As the project grows, many teams split resources into additional files such as networking.tf, compute.tf, or security.tf.

variables.tf

variables.tf contains input variable declarations.

Separating variable definitions from resource definitions makes configurations easier to reuse across environments and modules.

If you want a deeper understanding of variable declarations, read our guide on Terraform Variable Block.

outputs.tf

outputs.tf defines output values.

Outputs expose useful information after deployment, such as:

Public IP addresses
DNS names
Resource IDs
Load balancer endpoints

You can also use outputs when working with modules and remote state.

providers.tf

providers.tf contains provider configurations.

This is where you configure providers such as:

AWS
Azure
Google Cloud
Kubernetes
Local

Provider definitions are usually separated into their own file to keep infrastructure code organized.

Learn more about providers in our guide on Using Terraform Providers.

Can You Use Multiple .tf Files in One Terraform Directory?

Yes.

Terraform automatically loads and merges all .tf files located in the same configuration directory.

For example, you might have:

main.tf
networking.tf
security.tf
storage.tf

Terraform treats these files as a single configuration during planning and deployment.

This flexibility becomes especially useful when infrastructure grows beyond a handful of resources.

In production environments, it's common to separate resources by responsibility instead of placing everything inside a single file.

Pro Tip

Terraform loads all .tf files within a directory automatically. Many teams organize files by resource type such as networking.tf, security.tf, and compute.tf rather than placing every resource inside main.tf.

Sample Terraform Configuration Directory Structure

A typical Terraform project may look like this:

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

Purpose of each file:

main.tf — Resource definitions
variables.tf — Input variable declarations
outputs.tf — Output values
providers.tf — Provider configurations
terraform.tfvars — Variable values

A larger production project often evolves into something like:

terraform-project/
├── providers.tf
├── variables.tf
├── outputs.tf
├── networking.tf
├── security-groups.tf
├── ec2.tf
└── terraform.tfvars

In this structure, networking, security, and compute resources are separated into dedicated files, making troubleshooting and code reviews significantly easier.

Benefits of Organizing Your Terraform Configuration Directory

A well-structured Terraform configuration directory provides several practical advantages.

Improved Readability

Smaller, focused files are easier to navigate than a single file containing hundreds of lines of code.

Engineers can quickly locate resources without searching through unrelated configurations.

Easier Troubleshooting

When something fails, resource separation helps narrow down the problem area.

Debugging becomes faster because related resources are grouped together.

You can also use techniques discussed in our guide on Debugging in Terraform to troubleshoot complex deployments.

Better Team Collaboration

Clear file organization reduces merge conflicts and makes code reviews more efficient.

Different team members can work on networking, compute, or security resources independently.

Cleaner Version Control History

Smaller files produce cleaner Git diffs.

This makes reviewing infrastructure changes easier and reduces the chance of missing important updates during pull requests.

How Terraform Processes a Configuration Directory

When Terraform executes, it performs the following steps:

Scans the current directory for .tf files.
Parses all configuration files.
Merges them into a single configuration.
Resolves dependencies between resources.
Creates an execution plan.
Applies changes to infrastructure.

Because Terraform builds a dependency graph internally, file order does not affect execution order.

You can name files however you like, provided they use the appropriate Terraform file extensions.

For more details about dependency handling, see our guide on Resource Dependencies in Terraform.

Terraform State Files Inside the Configuration Directory

When Terraform initializes a working directory, it creates additional files and folders.

Common examples include:

.terraform/
.terraform.lock.hcl
terraform.tfstate
terraform.tfstate.backup

.terraform Directory

The .terraform directory stores provider plugins and module dependencies downloaded during terraform init.

This folder is generated automatically and should not be edited manually.

terraform.tfstate

The terraform.tfstate file stores Terraform's current understanding of managed infrastructure.

Terraform uses this state file to determine what changes need to be created, updated, or destroyed.

If you're unfamiliar with state management, read our detailed guide on Introduction to Terraform State.

Production Recommendation

Avoid storing terraform.tfstate in Git repositories. Most production teams use remote backends such as Amazon S3 with state locking enabled to prevent accidental state corruption.

For production environments, also review:

The official Terraform documentation also recommends using remote state storage for collaborative environments.

Best Practices for Terraform Configuration Directories

Follow these practices to keep projects maintainable as they grow:

Use descriptive file names.
Separate variables, outputs, and providers into dedicated files.
Group resources by functionality.
Store secrets outside Terraform code.
Use remote backends for state management.
Keep modules in dedicated directories.
Commit configuration files to version control.
Exclude state files and sensitive artifacts from Git.

For reusable infrastructure components, explore our guides on Modules in Terraform and Creating and Using Module Terraform.

Official Terraform Documentation References

For the most up-to-date Terraform behavior and recommendations, refer to:

These resources are maintained by HashiCorp and reflect the latest Terraform releases and best practices.

FAQ — Terraform Configuration Directory

Can I use multiple .tf files in the same Terraform configuration directory?

Yes.

Terraform automatically loads and merges all .tf files located within the same configuration directory.

Do .tf files need to be in a specific order?

No.

Terraform determines execution order using resource dependencies rather than file names or file positions.

Is main.tf required?

No.

main.tf is a common convention but not a Terraform requirement.

You can use any file name as long as it has a supported Terraform configuration extension.

What is terraform.tfvars used for?

terraform.tfvars provides values for input variables declared in variables.tf.

It allows you to separate configuration values from infrastructure definitions.

Should terraform.tfstate be committed to Git?

Generally, no.

Most teams store state remotely using backends such as Amazon S3 or Terraform Cloud instead of version-controlling state files.

Does every Terraform project need a configuration directory?

Yes.

Terraform requires a working directory that contains configuration files. This directory serves as the Terraform configuration directory and acts as the entry point for all Terraform operations.