Layout

Learn how Terraform project layout works and how you can structure the project files.

We'll cover the following

Terraform file

Until now, we have been creating several Terraform projects to get used to different concepts. In every project, though, we have been creating a single file called main.tf where we have placed all of our Terraform code (HCL). You may have wondered why all of the code was in a single file. Terraform actually does not care what the file’s name is, as long as it ends in .tf. So, in all of the projects thus far, we could have called the file project.tf, code.tf, or foo.tf. It really does not matter.

Terraform project folders

We can also split the code over as many files as we wish. The only rule is that all of the files have to be in the same folder since folders have significance in Terraform (as we will learn in the next chapter on modules). The top-level folder we have been working in is considered the main Terraform project. All files at that level (directly in that folder) are considered part of the project.

Example

So, if we have the following folder structure on disk:

/project
  main.tf

Then we have the code inside main.tf as we had in our first Terraform project:


provider "aws" {
    region = "us-east-2"
}

resource "aws_s3_bucket" "first_bucket" {
    bucket = "<yourname>-first-bucket"
}
main.tf file of our Terraform project

📝Note: Please do change "<yourname>-first-bucket" with your name in main.tf file before running the project. And don’t forget to run terraform destroy after you have run the project.

Changing the project structure

Terraform will now consider that we are setting up the AWS provider and creating a single S3 bucket. If we change our project folder structure to the following:

/project
    provider.tf
    s3.tf

Then in the provider.tf file we place the following code:

Press + to interact
provider "aws" {
    region = "us-east-2"
}

In s3.tf we place the S3 bucket creation:



resource "aws_s3_bucket" "first_bucket" {
    bucket = "<yourname>-first-bucket"
}
S3 bucket creation of our Terraform project in s3.tf file

📝Note: Please do change "<yourname>-first-bucket" with your name in s3.tf file before running the project. And don’t forget to run terraform destroy after you have run the project.

If we run Terraform again with the files in this structure, Terraform will not show any difference. Terraform will still create a single S3 bucket. A good way to think about this is that when you run Terraform, it combines all of the code from all of the files in the top-level folder together (in this case, /project) and makes them into a single big text block. It then works out what you have defined in that block, and throws away the original filenames.

Terraform naming conventions

Even though this means we are free to name the files and organise our code as we wish, there are some conventions the community follows that make it easier to move from one Terraform project to another.

  • Generally, providers are set up in a file called main.tf. This gives you a place to look as to where all providers are configured.

  • Files are normally broken up around different areas of the system.

For example, if we create an AWS ECS cluster, we could put all of the setups for that cluster in a file called ecs.tf.

If we are configuring our DNS entries in route53, we could put that in a file called dns.tf. The important point is to lay out the code in a way that makes the most sense for you and the people you are working on the project with.

Creating a child folder

One last thing to cover on project structure is what happens when you create a child folder. Let’s update the project above and add a child folder, so our project structure now looks like this:

/project
    provider.tf
    s3.tf
other/
    bucket.tf

Inside the file bucket.tf place the following code:



resource "aws_s3_bucket" "first_bucket" {
    bucket = "<yourname>-first-bucket"
}
Adding bucket.tf file in the child folder of our Terraform project

📝Note: Please do change "<yourname>-other-bucket" with your name in s3.tf and bucket.tf files before running the project. And don’t forget to run terraform destroy after you have run the project.

After running the project, you will see the Terraform runs and creates one S3 bucket. It completely ignores the code inside bucket.tf. That is because it is in a subfolder, and Terraform considers only the code in the top-level folder.

Get hands-on with 1300+ tech skills courses.