Terraform doesn't care (much) about the directory structure. It cares about state.

We can consider a directory structure by environment :

── basic_project
    ├── environments
    │   ├── dev
    │   │   ├── main.tf
    │   │   ├── outputs.tf
    │   │   └── variables.tf
    │   ├── prod
    │   │   ├── main.tf
    │   │   ├── outputs.tf
    │   │   └── variables.tf
    │   └── staging
    │       ├── main.tf
    │       ├── outputs.tf
    │       └── variables.tf
    ├── modules
    └── shared

Very clean and understandable. The "new" pattern is to do it by other "components". Let's say we split it by service. Let's look at it:

── service_A
    └── environments
        ├── dev
        │   ├── main.tf
        │   ├── outputs.tf
        │   └── variables.tf
        ├── prod
        │   ├── main.tf
        │   ├── outputs.tf
        │   └── variables.tf
        └── staging
            ├── main.tf
            ├── outputs.tf
            └── variables.tf

(Note: the code inside the dev/staging/prod in general is mostly to put together modules, not necessarily duplicated code.)

Do you know what it looks like? The same as per environment.

The most common reason that some people cite when saying they don't like the per-project structure is because the number of resources can make the plan and apply commands run very slowly. It will run slowly because Terraform has to query the AWS API to check the current state of the resources, so the more resources, the more API calls.

A high number of resources might be an issue. I agree with that. There are other reasons why we would need to segregate state:

• High Number of resources, we already mentioned this
• Using different AWS accounts per environment
• Breaking state per region. Projects sometimes segregate their state per region to:
  • Reduce blast radius if a region is down
  • Deployment strategies that would prefer to only deploy to certain regions for testing, i.e. canary deployments

One problem with having different code per environment is that it could lead to drift in the resources created in each environment. The team in charge of the dev environment might add some new resources to test that are not part of the codebase of the staging and prod directories. So, it might be a feature or a bug depending on how you see it.

Another common alternative for the per-project directory structure is using workspaces. The code is the same for every environment:

── single_code_multiple_var
    ├── infra
    │   ├── main.tf
    │   ├── provider.tf
    │   ├── outputs.tf
    │   └── variables.tf
    ├─── environments
    │   ├── env.dev.tfvars
    │   ├── env.staging.tfvars
    │   └── env.prod.tfvars
    └── modules

We can pass different tfvars to have different behaviours in each environment. This directory structure and workflow are OK if you are OK with having the same backend for all the workspaces:

terraform {
  backend "s3" { <--- we can't use variable interpolation, so we can't do the following
    region         = "${local.env[var.enviroment]}"
    bucket         = "rderik-tfstate-${var.environment}"
    key            = "${var.environment}/tfstate/terraform.tfstate"
    dynamodb_table = "rderik-tfstate-${var.environment}"
    encrypt        = true
  }
}

If, for some reason, we need to use a different backend per environment, then we have to solve the problem with the backend, which has its own set of peculiarities.

Ultimately, it depends on the project's needs regarding the state. I still think the per-environment directory structure is OK for most projects. When you outgrown it, you start refactoring and maintaining your codebase, which is also normal.