Terragrunt vs. Terraform – Comparison & When to Use

Terraform is an 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.

Terraform features

Here a five key features that Terraform offers:

• Declarative language (HCL) — allows users to specify what should be the desired end state of the system using a declarative language that is easy to understand and write.
• State management — holds the current state of the infrastructure in a state file, making it easy to map real-world resources to your configuration.
• Modularity and reusability — with modules, you can encapsulate and reuse configurations for various parts of your infrastructure.
• Loops and conditionals — gives you the ability to write complex loops and conditionals, allowing you to create multiple resources of the same kind based on flags and other items while maintaining a clear declarative approach.
• Provide ecosystem — Terraform is cloud-agnostic and has a vast ecosystem of providers that allow you to manage services in your cloud provider (and other platforms).

Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.

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.

Terragrunt features

While Terraform does a great job on its own for most of the use cases, when it comes to respecting the DRY principle, modules will not be enough. With Terragrunt, you get:

• DRY configuration — gives you the ability to keep your code DRY by defining your configuration once and reusing it across multiple environments.
• Better remote state management — simplifies the overall management of your Terraform state files.
• Dependencies management — it can automatically manage dependencies between your Terraform modules, ensuring they are applied in the correct order.
• Before and after hooks — it supports before and after hooks, allowing you to execute custom actions and scripts before the Terraform commands.

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 storageaccount.tf, variables.tf, and outputs.tf is replicated twice for every environment.

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/1.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.

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.

Differences between Terragrunt and Terraform

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.

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.

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

1. terraform workspace new int – this 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.

Spacelift supports both Terraform and Terragrunt and improves your workflows drastically by adding the following:

• Remote state management – Spacelift can manage the remote state for you and allows you to manage it in any supported remote backend you want.
• Dynamic credentials – you can easily integrate with AWS, Azure, and GCP.
• Adding OPA policies – you can control what resources people can create, what parameters these resources can have, how many approvals you need for a run, where to send notifications, what happens when a PR is open, and others.
• Adding reusable contexts – contexts are containers for your variables, mounted files, and lifecycle hooks that can be easily attached to any number of Terraform and Terragrunt stacks.
• Providing self-service infrastructure – with Blueprints, you can create self-service infrastructure based on your Terraform and Terragrunt configurations.
• Providing a module and provider registry – with Spacelift, you get a private module and provider registry that can host your modules and providers.

If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.

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.