Multi-instance Vs Single-instance Root Modules

Hey folks,

At Masterpoint, we do IaC day in and day out. In this post, I want to share some terms that we use for Terraform or OpenTofu (TF) organizational structures. We find these useful and hope you do as well. The two terms are: "Multi-instance" and "Single-instance" Root Modules.

We haven't seen analogous terms for these patterns used elsewhere. We found we needed this terminology to talk about these two common patterns.

Since we've been in many client environments, we've seen all the ways that people manage TF. Two patterns are a consistent dividing line in how teams structure their repositories.

Multi-instance Root Modules

A root module directory can have multiple state files associated with it. This is done either with TF workspaces or with dynamic backend configurations, aka "Dynamic Backends".

Consider a db-cluster root module. If you deploy it with different configurations for your dev, stage, and prod environments you have the Multi-instance pattern. With this pattern, there is one directory containing TF files. This directory corresponds to multiple state files; it is one-to-many.

Being able to deploy the same set of resources to a dev account with one tfvars file and then to other accounts with other tfvars files is a beautiful thing!

With this pattern, make sure you know exactly which state file you are working on. You don't want to deploy a change to staging that you meant to ship to dev!

To avoid these mistakes, you should:

• carefully review the actual plan; avoid auto-approving.

• use automation to drive your IaC and avoid applying locally.

That said, I've never seen or even heard of a case of anyone taking the values that they meant to supply for dev and accidentally applying them to production, thereby wiping out infrastructure. I understand it's a possible mistake that can happen, though I think there are deeper problems going on in an org if this actually does happen.

Single-instance Root Modules

With this pattern, a root module directory has only one associated state file. This means the engineering team has directly encoded configuration into the root module for the given deployment environment. To continue with the database cluster example, you would have the following root modules:

• db-cluster-dev

• db-cluster-stage

• db-cluster-prod

Each of these root modules would be in their own separate directories. Each would have the configuration necessary to deploy the clusters for their associated environment.

With this pattern, you have one directory containing TF files corresponding to one state file.

We definitely see people implement this pattern a lot which causes drift and duplication. If you are using a tool to generate TF, like Terramate, then the problems of Single-instance are diminished; my concerns about foot shooting go down by a lot.

Recommendations

At Masterpoint, when clients are building from scratch or are re-architecting, we always suggest that they utilize the Multi-instance pattern over the Single-instance pattern. It encourages less environment drift, enforces better practices, and promotes re-use.

May you always know exactly which tfvars file you are using,

Matt @ Masterpoint

PS If you'd like a bit of a blast from the past, here's a presentation I did a few years ago about the AWS CLI.

Or, want to chat through some tricky IaC issue that you or your org are running into? Grab some time on my calendar here.