How to manage multiple environments with Terraform

A comparison of using workspaces, branches, and Terragrunt

Update, Jan 28, 2025: OpenTofu offers a new way to manage environments. See How to manage state and environments with OpenTofu for the details.

You used Terraform to deploy one environment (e.g., development), and things are working great, but now you need to deploy several more environments (e.g., staging, production), and you need to figure out how to organize your code. Should you use workspaces? Or branches? Or Terragrunt?

This question comes up early in the life of a Terraform project, and many developers make a decision without giving it too much thought, only to be blindsided later by a variety of issues, such as huge amounts of code duplication, insufficient isolation between environments, and difficulty in debugging. To help you avoid these problems, I’ve put together a blog post series that compares the three most popular options for defining and managing environments in Terraform:

• Part 1: Workspaces
• Part 2: Branches
• Part 3: Terragrunt

These three blog posts will show you how to use each option to set up multiple environments, switch between environments, use different configurations, backends, and versions in each environment, and how to work with multiple modules. At the end of each post, you’ll see a list of the advantages and drawbacks of using that option.

If you’re just looking for a quick recommendation of which option to use, here’s a preview of the summary table from the very final blog post, which shows how the three options compare (more black squares = better):

Copy
|                                         | Workspaces | Branches | Terragrunt |
|-----------------------------------------|------------|----------|------------|
| Minimize code duplication               | ■■■■■      | □□□□□    | ■■■■□      |
| See and navigate environments           | □□□□□      | ■■■□□    | ■■■■■      |
| Different settings in each environment  | ■■■■■      | ■■■■□    | ■■■■■      |
| Different backends for each environment | □□□□□      | ■■■■□    | ■■■■■      |
| Easy to manage multiple backends        | □□□□□      | ■■■■□    | ■■■■■      |
| Different versions in each environment  | □□□□□      | ■■□□□    | ■■■■■      |
| Share data between modules              | ■■□□□      | ■■□□□    | ■■■■■      |
| Work with multiple modules concurrently | □□□□□      | □□□□□    | ■■■■■      |
| No extra tooling to learn or use        | ■■■■■      | ■■■■■    | □□□□□      |
| Works with Terraform Cloud              | ■■■■■      | ■■■■■    | ■□□□□      |

terraform-environments-comparison.md view raw

If you want to know all the details and how we came up with these ratings, then let’s dive into the series, starting with Part 1: How to manage multiple environments with Terraform using workspaces.

Your entire infrastructure. Defined as code. In about a day. Gruntwork.io.