A Terraform Directory Structure

Here is a directory structure that I am using for Terraform that I think works pretty well. The quick and dirty of it is to think of your configurations in terms of a organizational and systems hierarchy, and to design your plans to support that hierarchy. Each tier depends on and builds upon the previous tier.

I create a separate terraform project for each tier of my stack. I am nearly 100% in AWS these days so this is going to feel a little AWS centric, but the basic idea is the same regardless of cloud provider.

I like this structure because it's pretty clear where things are. It also keeps my terraform plans smallish. However it is a bit tedious as it's just a bunch of different terraform configurations to manage, but also it's actually pretty fast to make changes. It keeps me honest about design since foundational tiers need to be stable because other tiers depend on them. I think it's created better habits in my terraform work.

Terraform Directory Struture

terraform/
  01-organization/
  02-network/
  03-security/
  04-data/
  05-application/

I think these are pretty self explanatory, but for the sake of being thorough-ish I expand a bit below.

The first tier is the organization and account level stuff. For example setting up account level billing alerts.

Second tier is networking. Defining the overall network topology that the rest of the application hangs on. This is your VPC, subnets, nat, route tables, peering connections.

Third tier is basic security baseline, including VPC security groups, IAM groups, roles, and policies, and so forth.

The fourth tier is for database servers, caching servers, the various data services that your application depend on and that are evergreen.

Tier five is application specific. For example, I configure docker image repositories here, logging systems, cloudwatch events, and various other services of which my applications depend. It's the infrastructure required to run our Rails, Laravel, NextJS, and Angular artifacts.

From this I build application environment specific configurations. For example a Docker cluster for a QA environment. It would have it's own directory and configurations but is be built upon the foundation we have here.

Each tier has basically the same inner structure.

Terraform Directory Inner Struture

terraform/
  01-organization/
    modules/
      billing/
      ...
    backend.tf
    data.tf
    main.tf
    providers.tf
    README.md
  02-network/
  ...

So far it's served me well. I hope that if you are using vanilla terraform that you also find it useful when designing your infrastructure and IaC.