OpenTofu is now part of the Linux Foundation 🎉

Read more here →


Terragrunt vs. Terraform – Comparison & When to Use

Terraform vs Terragrunt

In the field of DevOps, there are numerous tools available to help streamline the process of infrastructure management and deployment. In this article, we will take a deep dive into two such tools: Terraform and Terragrunt.

Terraform is a widely used Infrastructure as Code (IaC) tool that enables users to define their infrastructure rather than manually configuring and managing it. Terraform allows for automation of infrastructure provisioning, configuration, and deployment not only across multiple cloud platforms, like AWS, GCP, and Azure, but also for other products like Kubernetes, Datadog, VMware, etc.

Terragrunt, on the other hand, is a wrapper tool that was specifically developed to assist with the efficient maintenance and deployment of infrastructure. It provides a simple way to manage multiple Terraform modules and deployments, making it easier to manage complex infrastructures.

Throughout this article, we will explore both Terraform and Terragrunt individually to understand their purpose, features, and benefits. We will also compare and contrast the two tools, examining their similarities and differences. 

We will cover:

  1. Terraform in a nutshell
  2. Terragrunt in a nutshell
  3. Why should I use Terragrunt?
  4. Terragrunt and Terraform comparison
  5. Is Terragrunt better than Terraform workspaces?

Terraform in a Nutshell

Terraform is an open-source Infrastructure as Code (IaC) tool developed by Hashicorp. Its primary function is to enable users to provision their infrastructure in a simple, efficient, and declarative manner through repeatable code. With Terraform, you can automate the process of infrastructure provisioning, configuration, and deployment, whether it be on cloud or on-premises environments.

One of Terraform’s most valuable features is its cloud-agnostic nature, which allows you to deploy infrastructure to any cloud environment. This means you can use Terraform to automate your cloud infrastructure without having to learn or adopt different tools for each cloud service provider. Terraform supports a wide range of cloud platforms, including Azure, AWS, GCP, and VMware, among others.

Another key benefit of Terraform is its ability to manage complex infrastructure. With Terraform, you can define infrastructure as a set of declarative templates that can be versioned, reviewed, and modified over time. This enables you to make changes in a safe and predictable manner and maintain a consistent state across your entire infrastructure.

Terraform also supports a vast library of third-party modules and plugins, which can be used to extend its functionality and integrate with other tools and services. These modules and plugins are developed and maintained by the Terraform community, which is made up of thousands of developers and DevOps professionals from around the world.

Terragrunt in a Nutshell

Terragrunt is an open-source tool developed by Gruntwork that serves as a thin wrapper on top of Terraform. Its primary goal is to reduce repetition in your Terraform code and simplify its structure, making it easier to manage and maintain. Terragrunt is based on the DRY (Do Not Repeat Yourself) concept, which involves reducing redundancy by using multiple Terraform modules and managing remote states.

Learn how to keep your configuration DRY with Terragrunt on Spacelift.

One of the key benefits of Terragrunt is its ability to manage Terraform configurations across multiple modules, enabling you to easily reuse code across your infrastructure. Terragrunt also allows you to define reusable code as modules that can be shared across different projects, reducing the time and effort required to create and maintain infrastructure code.

Another important feature of Terragrunt is its ability to manage remote states, which enables you to store and share state files securely across multiple environments. This helps to ensure that your infrastructure remains consistent and up-to-date, regardless of changes made by different team members or in different environments.

Why Should I Use Terragrunt?

While working with Terraform, it is easy to write code for setting up an infrastructure limited to a single environment. However, if you are working on a project that involves multiple environments, you will need to duplicate the same code for each environment with different values, which can lead to code redundancy.

For instance, the below screenshot shows a typical Terraform project structure for deploying Azure storage account to various environments.

You can see that all the environments, including “int,” “staging,” and “prod,” have the same files. To write the code for each environment, you would copy and paste the same code from the .tf files and customize them based on the environment requirement.

In this scenario, the code for,, and is replicated twice for every environment.

terraform project

To deploy the code for the Int environment using Terraform, you need to take the following steps:

  1. Change to the directory for the development environment by running cd '/Int'.
  2. View the plan by running terraform plan.
  3. Apply the plan by running terraform apply.

These steps need to be repeated for all other environments to provision them. Terragrunt can be incredibly useful in avoiding the repetition mentioned above. 

When using Terragrunt, .hcl files are utilized, and the Terraform code itself is structured into modules and kept in the modules folder.

The .hcl file refers to the actual module for the .tf file, while the actual Terraform code is stored in the modules folder along with its corresponding .tf file. Input values for the module are supplied in the relevant .hcl files, as shown below:

To deploy a storage account for the Dev environment in the folder structure mentioned above, you should execute the following commands:

  1. Change to the ‘Dev’ environment directory by running cd /dev/
  2. Review the plan by running terragrunt plan.
  3. Apply the plan by running terragrunt apply.

Terragrunt also offers the option to deploy resources for all environments at once by using the run-all switch. In the scenario mentioned above, if a storage account needs to be deployed to all environments, the following commands should be executed:

  1. Change to the Terragrunt directory by running cd /Terragrunt.
  2. Execute terragrunt run-all apply.

Terragrunt’s capability to deploy resources across multiple environments not only reduces code duplication but also aids in the efficient management of environment configurations. This is just one of the many use cases of Terragrunt.

Terragrunt is widely adopted and has a laundry list of use cases for users to leverage. The Gruntwork team has documented an official list of Terragrunt use cases, including managing multiple AWS accounts, handling dependencies between Terraform modules, and automating the deployment of Kubernetes clusters.

Recommended folder structure for organizing Terragrunt files can be found in the following GitHub repo.

Learn more with our Terragrunt tutorial.

Terragrunt vs. Terraform Comparison

Terraform and Terragrunt are both tools used for Infrastructure as Code (IaC). Let’s take a look at their similarities and differences.

Below you can find Terraform vs. Terragrunt table comparison.

Terragrunt and Terraform Similarities

1. Syntax

Terragrunt and Terraform both use a declarative syntax for defining Infrastructure as Code, allowing you to describe the desired state of your infrastructure rather than specifying a sequence of steps to reach that state.

2. HashiCorp Configuration Language

They both rely on HCL (HashiCorp Configuration Language) for configuration, which is a simple, human-readable language that allows you to define resources, variables, and other configuration elements.

3. Cloud providers support

Both Terraform and Terragrunt support a wide range of cloud providers, including AWS, Azure, Google Cloud, and others, making it possible to manage infrastructure across multiple cloud platforms using the same toolset.

4. Modularization

They both support modularization, allowing you to reuse and share code across multiple projects, as well as manage complex infrastructure deployments more easily.

5. Community

Both tools have a robust and active community of users, providing support, resources, and examples of how to use the tools effectively.

6. Infrastructure management

They both provide the ability to manage infrastructure in a version-controlled environment, enabling collaboration and traceability.

Terragrunt and Terraform Differences

1. Purpose

Terraform is designed to build and configure infrastructure, while Terragrunt is a thin wrapper that is built on top of Terraform.

2. Scope

Terraform is created to operate at the resource level, while Terragrunt is designed to handle complex infrastructure deployments, which is typically composed of multiple Terraform modules.

3. Configuration

Terraform and Terragrunt both use HCL for configuration, but Terragrunt uses additional configuration files called .hcl files that provide additional functionality such as dependency management, automatic remote state configuration, and a simple way to define input variables.

3. Dependency Management

Terraform handles dependency at each resource level using implicit dependency and explicitly dependency between resources using depends_on keyword. Terragrunt provides a simple way to handle such dependencies between the modules and ensures that resources are provisioned in correct order.

Learn why and how to use Terraform’s depends_on meta-argument.

4. Remote state management

Terraform handles the remote state by maintaining separate state files per environment. Terragrunt handles state files for multiple environments in a single .hcl file.

5. Project Structure

Terraform’s project structure involves separate .tf files for resource provisioning per environment, whereas Terragrunt eliminates this code duplication by utilizing modules, and input configuration per environment is managed in separate .hcl files.

6. Command execution

With Terragrunt, you can provision multiple environments with a single command, whereas with Terraform, you have to switch to different environment folders individually in order to provision all the environments.

Is Terragrunt Better Than Terraform Workspaces?

Terraform offers a feature called workspaces that helps reduce code redundancy and enables the provisioning of different environments. When using Terraform, a separate state file is created per workspace.

To illustrate this better, imagine the same folder structure described in the above examples for provisioning a storage account.

terraform project

To create a new workspace and provision resources for dev environment, you would use following command:

  1. terraform workspace new intthis creates a new workspace.
    To provision the resources, you would run the following command:
  2. terraform plan – to run the plan
  3. terraform apply – to apply the configuration

This creates a new state file for ‘dev’ workspace and maintains the infrastructure state. To provision another environment, we have to repeat the above steps per environment.

However, Terraform workspaces are a good option for local development and testing purposes. For production-grade deployments, it’s not a recommended feature. Terraform’s official documentation recommends avoiding using the workspaces feature for managing multiple environments.

Terragrunt handles the deployment of resources to different environments efficiently, not only by using a single command but also gives goods visibility and control over the source code for infrastructure provisioning. Hence, Terragrunt is an ideal tool when it comes to provisioning large-scale, complex infrastructure deployments.

Key Points

In this blog post, we explored two popular IaC tools – Terraform and Terragrunt. We have discussed how both of them are similar when it comes to handling infrastructure deployments and a few key differences between both of them. We also have touched upon how Terragrunt is better when compared to using Terraform workspaces for the deployment of resources to multiple environments.

We encourage you also to explore how Spacelift makes it easy to work with Terraform and Terragrunt. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine, Spacelift is a fantastic tool for this. It supports Git workflows, policy as code, programmatic configuration, context sharing, drift detection, and many more great features right out of the box.

Manage Terraform Better with Spacelift

Build more complex workflows based on Terraform using policy as code, programmatic configuration, context sharing, drift detection, resource visualization and many more.

Start free trial