Terragrunt

Terragrunt is a thin wrapper that provides extra tools for keeping your Terraform configurations DRY, working with multiple Terraform modules, and managing remote state. Terrateam seamlessly integrates with Terragrunt, allowing you to leverage its features while still benefiting from Terrateam’s collaboration and automation capabilities.

Configuring Terrateam for Terragrunt

To use Terragrunt with Terrateam, you need to configure Terrateam to use the Terragrunt CLI instead of the default Terraform CLI. You can do this by specifying the engine in your Terrateam configuration file (.terrateam/config.yml).

Here’s an example configuration that sets Terragrunt as the default engine and triggers Terrateam operations when any terragrunt.hcl file is modified, except for the root terragrunt.hcl:

engine:
  name: terragrunt
dirs:
  "**/terragrunt.hcl":
    when_modified:
      file_patterns: ['${DIR}/terragrunt.hcl']
  '.':
    when_modified:
      file_patterns: []

Alternatively, you can specify the engine in the workflows section of your configuration file:

dirs:
  "**/terragrunt.hcl":
    when_modified:
      file_patterns: ['${DIR}/terragrunt.hcl']
  '.':
    when_modified:
      file_patterns: []
workflows:
  - tag_query: ""
    engine:
      name: terragrunt

With this configuration, Terrateam will replace the terraform command with terragrunt in all plan and apply workflows.

Example repository

Gruntwork maintains an infrastructure-live repository that demonstrates how to use Terragrunt with a real-world project structure. You can use this repository as a starting point for your own Terragrunt setup with Terrateam.

Prerequisites

• Terrateam installed on your GitHub organization. See our quickstart guide.
• GitHub CLI

Setting up your repository

1. Export your organization/repository combination for your Terragrunt code:

   export GITHUB_ORG="<MY_GITHUB_ORG>"
   export TERRAGRUNT_REPO="${GITHUB_ORG}/infrastructure-live"

2. Create the new repository:

   gh repo create --private "$TERRAGRUNT_REPO"

3. Clone the official infrastructure-live example repository:

   git clone --bare https://github.com/gruntwork-io/terragrunt-infrastructure-live-example

4. Mirror the infrastructure-live repository:

   cd terragrunt-infrastructure-live-example.git
   git push --mirror "https://github.com/$TERRAGRUNT_REPO"

5. Clone your new infrastructure-live repository:

   cd ../
   gh repo clone "$TERRAGRUNT_REPO" infrastructure-live

6. Set the default branch to master:

   cd infrastructure-live
   git checkout master
   gh repo edit --default-branch master

7. Create the Terrateam GitHub Actions workflow file:

   mkdir -p .github/workflows
   curl -o .github/workflows/terrateam.yml https://raw.githubusercontent.com/terrateamio/terrateam-example/main/github/actions/workflows/default/terrateam.yml
   git add .github

8. Create a custom Terrateam configuration file:

   mkdir .terrateam
   curl -o .terrateam/config.yml https://raw.githubusercontent.com/terrateamio/terrateam-example/main/terrateam/terragrunt-infrastructure-live/config.yml
   git add .terrateam

   Note

   The above configuration file will set up the following:

   • A custom TG_BUCKET_PREFIX for your Terraform state S3 bucket. Make sure you replace this value with something unique.
   • Enable the terragrunt CLI in plan and apply operations.
   • Properly trigger Terrateam operations when terragrunt.hcl files are updated.

9. Commit and push your changes:

   git commit -a -m "Changes for Terragrunt infra live and Terrateam"
   git push

10. Complete the Cloud Provider Setup for your new infrastructure-live repository.

Modules

The infrastructure-live example repository pulls modules from the terragrunt-infrastructure-modules-example repository found here. See the envcommon terragrunt.hcl files for the base_source_url definitions. You can continue to use this repository, but it’s recommended to mirror the repository into your GitHub organization and reference the new URL in your base_source_url definitions.

Note

The Terrateam GitHub application must be installed on module repositories for Terrateam to successfully clone the repository during plan and apply operations.

Making changes

With your infrastructure-live repository set up and configured for Terragrunt and Terrateam, you can start making changes and creating pull requests. Terrateam will automatically detect changes to your terragrunt.hcl files and trigger the appropriate plan and apply operations based on your configuration.

Best practices

• Keep your Terragrunt configurations modular and reusable, leveraging the features provided by Terragrunt to reduce duplication and simplify management.
• Use a consistent naming convention for your terragrunt.hcl files and directory structure to make it easy to navigate and understand your infrastructure setup.
• Ensure that the Terrateam GitHub application is installed on any repositories containing Terraform modules referenced by your Terragrunt configurations.