|
| 1 | +--- |
| 2 | +title: Automatic Terragrunt Discovery with Config Builder |
| 3 | +description: Automatically discover and configure Terragrunt modules in large monorepos with dependency tracking |
| 4 | +--- |
| 5 | + |
| 6 | +import { Steps } from '@astrojs/starlight/components'; |
| 7 | +import { Tabs, TabItem } from '@astrojs/starlight/components'; |
| 8 | +import MermaidDiagram from '../../../../components/MermaidDiagram.astro'; |
| 9 | + |
| 10 | +For large Terragrunt monorepos with hundreds of modules, manually configuring each module in `.terrateam/config.yml` is tedious and error-prone. Terrateam includes a built-in config builder that automatically discovers all `terragrunt.hcl` files and generates configuration with proper dependency tracking—similar to how [terragrunt-atlantis-config](https://github.com/transcend-io/terragrunt-atlantis-config) works for Atlantis. |
| 11 | + |
| 12 | +## When to Use This |
| 13 | + |
| 14 | +The Terragrunt config builder is ideal for: |
| 15 | + |
| 16 | +- Large monorepos with many Terragrunt modules |
| 17 | +- Repositories using Terragrunt's `dependency` blocks for module relationships |
| 18 | +- Teams migrating from Atlantis with terragrunt-atlantis-config |
| 19 | +- Avoiding manual maintenance of hundreds of `dirs` entries |
| 20 | + |
| 21 | +If you only have a handful of modules, manual configuration may be simpler. For everything else, the config builder automates the process. |
| 22 | + |
| 23 | +## How It Works |
| 24 | + |
| 25 | +The config builder: |
| 26 | +1. Scans the repository for all `terragrunt.hcl` files |
| 27 | +2. Parses each file to extract: |
| 28 | + - `dependency` blocks → Creates `depends_on` relationships |
| 29 | + - `dependencies` blocks → Multiple dependencies |
| 30 | + - `include` blocks → Parent config files |
| 31 | + - `terraform.source` → Local Terraform modules (remote sources ignored) |
| 32 | + - `locals.extra_atlantis_dependencies` → Custom dependencies |
| 33 | +3. Generates configuration with `when_modified` patterns for each module |
| 34 | +4. Creates dependency chains using Terrateam's layered runs |
| 35 | + |
| 36 | +### What Gets Generated |
| 37 | + |
| 38 | +For each Terragrunt module, the config builder creates a `dirs` entry with: |
| 39 | +- `tags`: `['terragrunt']` for easy filtering |
| 40 | +- `when_modified.file_patterns`: List of files that trigger this module |
| 41 | +- `when_modified.depends_on`: Direct dependencies for layered execution |
| 42 | + |
| 43 | +## Quick Start |
| 44 | + |
| 45 | +<Steps> |
| 46 | + |
| 47 | +1. Enable the config builder in your `.terrateam/config.yml`: |
| 48 | + |
| 49 | + ```yaml |
| 50 | + engine: |
| 51 | + name: terragrunt |
| 52 | + version: 0.69.3 |
| 53 | + |
| 54 | + config_builder: |
| 55 | + enabled: true |
| 56 | + script: terragrunt-config-builder |
| 57 | + |
| 58 | + when_modified: |
| 59 | + autoplan: true |
| 60 | + ``` |
| 61 | +
|
| 62 | +2. Commit and push your changes to a branch |
| 63 | +
|
| 64 | +3. Create a pull request |
| 65 | +
|
| 66 | +4. View the generated configuration by commenting on the PR: |
| 67 | + ``` |
| 68 | + terrateam repo-config |
| 69 | + ``` |
| 70 | + |
| 71 | +5. Watch autoplan run for all discovered modules |
| 72 | + |
| 73 | +</Steps> |
| 74 | + |
| 75 | +:::tip |
| 76 | +The `terragrunt-config-builder` script is bundled with Terrateam, no installation required. Just reference it by name in the `config_builder.script` field. |
| 77 | +::: |
| 78 | + |
| 79 | +## Configuration |
| 80 | + |
| 81 | +### Basic Setup |
| 82 | + |
| 83 | +The minimum configuration to enable automatic Terragrunt discovery: |
| 84 | + |
| 85 | +<Tabs> |
| 86 | +<TabItem label="Simple"> |
| 87 | + |
| 88 | +```yaml title=".terrateam/config.yml" |
| 89 | +engine: |
| 90 | + name: terragrunt |
| 91 | + |
| 92 | +config_builder: |
| 93 | + enabled: true |
| 94 | + script: terragrunt-config-builder |
| 95 | +``` |
| 96 | +
|
| 97 | +</TabItem> |
| 98 | +
|
| 99 | +<TabItem label="With Terragrunt Version"> |
| 100 | +
|
| 101 | +```yaml title=".terrateam/config.yml" |
| 102 | +engine: |
| 103 | + name: terragrunt |
| 104 | + version: 0.69.3 |
| 105 | + |
| 106 | +config_builder: |
| 107 | + enabled: true |
| 108 | + script: terragrunt-config-builder |
| 109 | +``` |
| 110 | +
|
| 111 | +</TabItem> |
| 112 | +
|
| 113 | +<TabItem label="Complete"> |
| 114 | +
|
| 115 | +```yaml title=".terrateam/config.yml" |
| 116 | +# Enable Terragrunt engine |
| 117 | +engine: |
| 118 | + name: terragrunt |
| 119 | + version: 0.69.3 |
| 120 | + tf_cmd: tofu # or "terraform" |
| 121 | + tf_version: "1.10.7" |
| 122 | + |
| 123 | +# Enable automatic discovery |
| 124 | +config_builder: |
| 125 | + enabled: true |
| 126 | + script: terragrunt-config-builder |
| 127 | +``` |
| 128 | +
|
| 129 | +</TabItem> |
| 130 | +</Tabs> |
| 131 | +
|
| 132 | +### How the Script is Called |
| 133 | +
|
| 134 | +The config builder: |
| 135 | +1. Receives the current configuration as JSON via stdin |
| 136 | +2. Processes all terragrunt.hcl files |
| 137 | +3. Outputs the modified configuration as JSON to stdout |
| 138 | +
|
| 139 | +The script runs in the GitHub Action environment with full access to your repository. |
| 140 | +
|
| 141 | +## Example Output |
| 142 | +
|
| 143 | +### Repository Structure |
| 144 | +
|
| 145 | +``` |
| 146 | +non-prod/ |
| 147 | +├── us-east-1/ |
| 148 | +│ ├── qa/ |
| 149 | +│ │ ├── mysql/ |
| 150 | +│ │ │ └── terragrunt.hcl |
| 151 | +│ │ └── webserver-cluster/ |
| 152 | +│ │ └── terragrunt.hcl # depends on mysql |
| 153 | +│ └── stage/ |
| 154 | +│ ├── mysql/ |
| 155 | +│ │ └── terragrunt.hcl |
| 156 | +│ └── webserver-cluster/ |
| 157 | +│ └── terragrunt.hcl # depends on mysql |
| 158 | +prod/ |
| 159 | +├── us-east-1/ |
| 160 | +│ └── prod/ |
| 161 | +│ ├── mysql/ |
| 162 | +│ │ └── terragrunt.hcl |
| 163 | +│ └── webserver-cluster/ |
| 164 | +│ └── terragrunt.hcl # depends on mysql |
| 165 | +repo.hcl |
| 166 | +aws.hcl |
| 167 | +``` |
| 168 | + |
| 169 | +### Generated Configuration |
| 170 | + |
| 171 | +Running `terrateam repo-config` shows: |
| 172 | + |
| 173 | +```json |
| 174 | +{ |
| 175 | + "version": "1", |
| 176 | + "dirs": { |
| 177 | + "non-prod/us-east-1/qa/mysql": { |
| 178 | + "tags": ["terragrunt"], |
| 179 | + "when_modified": { |
| 180 | + "file_patterns": [ |
| 181 | + "${DIR}/terragrunt.hcl", |
| 182 | + "${DIR}/*.tf", |
| 183 | + "${DIR}/*.tfvars" |
| 184 | + ] |
| 185 | + } |
| 186 | + }, |
| 187 | + "non-prod/us-east-1/qa/webserver-cluster": { |
| 188 | + "tags": ["terragrunt"], |
| 189 | + "when_modified": { |
| 190 | + "file_patterns": [ |
| 191 | + "${DIR}/terragrunt.hcl", |
| 192 | + "${DIR}/*.tf", |
| 193 | + "${DIR}/*.tfvars", |
| 194 | + "non-prod/us-east-1/qa/mysql/terragrunt.hcl" |
| 195 | + ], |
| 196 | + "depends_on": "dir:non-prod/us-east-1/qa/mysql" |
| 197 | + } |
| 198 | + } |
| 199 | + // ... similar entries for stage and prod |
| 200 | + } |
| 201 | +} |
| 202 | +``` |
| 203 | + |
| 204 | +**Key Points:** |
| 205 | +- Each module has a `dirs` entry |
| 206 | +- MySQL modules have no `depends_on` (no dependencies) |
| 207 | +- Webserver-cluster modules `depends_on` their corresponding MySQL |
| 208 | +- File patterns include the dependency's terragrunt.hcl |
| 209 | + |
| 210 | +## See Also |
| 211 | + |
| 212 | +- [Terragrunt Integration](/integrations/iac-tools/terragrunt) - Basic Terragrunt setup |
| 213 | +- [Config Builder Reference](/reference/configuration/config-builder) - Config builder configuration options |
| 214 | +- [Layered Runs](/workflows/advanced/layered-runs) - Understanding depends_on and execution order |
| 215 | +- [Dynamic Configuration](/workflows/advanced/dynamic-configuration) - How config_builder fits into the config merge process |
0 commit comments