Directory Structure Patterns in Terraform

A Terraform project's directory structure can greatly influence the ease of management and scalability of your infrastructure. A well-organized structure ensures that the code is easy to understand and debug.

Terraform's flexible nature allows you to organize your files and directories in various ways depending on the complexity of your infrastructure and your team's preferences. This article will focus on three common patterns for structuring your Terraform directories:

• Workspaces
  This method involves using Terraform's workspace feature to switch environments within the same Terraform resources.

• Environment Directory Isolation
  In this pattern, directories are separated for each environment, managing individual Terraform resources separately.

• Modules
  This approach leverages Modules to template resource creation, where environmental differences are realized through variables passed when calling the Module.

Workspaces

Terraform Workspaces provide a way to manage multiple environment states within a single Terraform configuration. Instead of creating separate directories for each environment, the workspace feature allows you to switch environments within the same Terraform resources.

Let's take a look at a simple Terraform code snippet to understand this better:

# Define constants per environment
variable "env_vars" {
  type = map(object({
    region = string
    cidr   = string
  }))

  default = {
    development = {
      region = "us-west-2"
      cidr   = "10.0.0.0/16"
    }

    production = {
      region = "us-east-1"
      cidr   = "10.1.0.0/16"
    }
  }
}

resource "aws_vpc" "main" {
  cidr_block = var.env_vars[terraform.workspace].cidr
  region     = var.env_vars[terraform.workspace].region

  tags = {
    Name = "${terraform.workspace}-vpc"
  }
}

In this example, we define variables region and cidr for each environment in our Terraform configuration, and then use the workspace name to select the correct set of variables when creating an AWS VPC.

Benefits of Using Workspace

Using Workspaces in Terraform has several advantages:

• DRY (Don't Repeat Yourself) Principle
  The workspace feature allows you to manage different environments without duplicating Terraform configurations, promoting code reuse.
• Ease of understanding
  All environmental variables are defined at the beginning of the files, making it easier to comprehend the differences between environments.

Drawbacks of Using Workspace

Using Workspaces may not be suitable in certain scenarios:

• Lack of control for diverse infrastructures
  If the infrastructure structure differs significantly between environments, it can be challenging to manage these variations within a single configuration using Workspaces.

• Inadequate for varying authentication and access controls
  Workspaces might not be ideal when different environments require unique authentication credentials and access controls.

It is also worth noting that Terraform's official documentation does not recommend using workspaces for system decomposition or deployments that require separate credentials and access controls.

Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls.

https://developer.hashicorp.com/terraform/language/state/workspaces

Environment Directory Isolation

Another common pattern in managing Terraform configurations is Environment Directory Isolation. In this pattern, you manage Terraform resources individually by dividing directories for each environment.

Here is an example of how this directory structure might look:

.
├── development
│   ├── vpc.tf
│   └── instances.tf
├── staging
│   ├── vpc.tf
│   └── instances.tf
└── production
    ├── vpc.tf
    └── instances.tf

In each environment folder (development, staging, production), we have separate Terraform files for managing different resources (VPC, instances). This way, each environment can have its own unique configuration and resource allocation as needed.

Benefits of Using Environment Directory Isolation

There are several benefits to structuring your directories this way:

• Environment Differences
  This structure is ideal if your environments differ significantly, as you can customize the configuration for each environment as required.

• Simplicity of Implementation
  Since there are no dependencies between environments, it can be simpler to implement and manage.

Drawbacks of Using Environment Directory Isolation

However, this approach does come with its own set of challenges:

• Code Duplication
  The biggest drawback of this approach is that it can lead to code duplication, as the same configurations may need to be written in each environment's directory, going against the DRY principle.

Modules

Modules in Terraform are used to create reusable components of your infrastructure. These can be defined once and called with different input variables in different environments, making them a highly efficient way to manage your resources.

Below is an example of a directory structure using Modules:

.
├── modules
|   ├── ec2_instance
|   |   ├── main.tf
|   |   ├── variables.tf
|   |   └── output.tf
|   └── vpc
|       ├── main.tf
|       ├── variables.tf
|       └── output.tf
├── development
│   └── main.tf
├── staging
│   └── main.tf
└── production
    └── main.tf

In this structure, reusable resources like an EC2 instance or a VPC are abstracted into modules. Each environment then calls these modules with its own set of input variables. For instance, your development/main.tf file might look like this:

module "vpc" {
  source  = "../modules/vpc"
  cidr    = "10.0.0.0/16"
  region  = "us-west-2"
}

module "ec2_instance" {
  source  = "../modules/ec2_instance"
  ami     = "ami-0c94855ba95c574c8"
  instance_type = "t2.micro"
  subnet_id = module.vpc.subnet_id
}

Benefits of Using Modules

The use of Modules has several benefits:

• DRY Principle
  With modules, you can abstract out reusable components of your infrastructure, promoting code reuse.

Drawbacks of Using Modules

There are some challenges in using Modules:

• Difficulty in Writing Generic Modules
  Writing modules that are generic enough to be reused across various scenarios can be challenging.
• Requires Advanced Understanding of Terraform
  Designing and using modules effectively requires a solid understanding of Terraform, which might be a hurdle for beginners.