Update QuickStart documentation with an additional example to control the output directory #4299
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
📝 WalkthroughWalkthroughThis change updates the documentation and adds new example files to clarify Terragrunt’s Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Terragrunt
participant Terraform Module (shared)
participant File System
User->>Terragrunt: Run terragrunt apply in foo or bar
Terragrunt->>Terraform Module (shared): Passes content and output_dir (using get_terragrunt_dir())
Terraform Module (shared)->>File System: Creates hi.txt in output_dir (foo/bar directory)
Terragrunt->>User: Operation complete, hi.txt created in correct location
Assessment against linked issues
Suggested reviewers
Note ⚡️ AI Code Reviews for VS Code, Cursor, WindsurfCodeRabbit now has a plugin for VS Code, Cursor and Windsurf. This brings AI code reviews directly in the code editor. Each commit is reviewed immediately, finding bugs before the PR is raised. Seamless context handoff to your AI code agent ensures that you can easily incorporate review feedback. Note ⚡️ Faster reviews with cachingCodeRabbit now supports caching for code and dependencies, helping speed up reviews. This means quicker feedback, reduced wait times, and a smoother review experience overall. Cached data is encrypted and stored securely. This feature will be automatically enabled for all accounts on May 16th. To opt out, configure 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
… the output directory
james03160927
force-pushed
the
quick_start_update
branch
from
0820a02 to
2ce3039
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
test/fixtures/docs/01-quick-start/step-05.1/shared/main.tf (2)
1-2: Specify variable types and descriptions.
To improve clarity and enable built-in validation, explicitly declare each variable’s type (e.g.,type = string) and consider adding a briefdescriptionblock.
5-6: Usejoinpath()for cross-platform paths.
Rather than string interpolation, leverage Terraform’sjoinpath()function to handle OS-specific separators. For example:- filename = "${var.output_dir}/hi.txt" + filename = joinpath(var.output_dir, "hi.txt")test/fixtures/docs/01-quick-start/step-05.1/README.md (2)
1-1: Add a top-level heading.
To satisfy Markdown best practices (MD041) and improve readability, prepend an H1 heading. For example:# Controlling Output File Locations🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
1-1: First line in a file should be a top-level heading
null(MD041, first-line-heading, first-line-h1)
3-3: Remove trailing spaces and ensure single newline.
Delete the extra space at the end of this line and add exactly one newline at EOF to comply with MD009 and MD047.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
3-3: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
3-3: Files should end with a single newline character
null(MD047, single-trailing-newline)
docs/_docs/01_getting-started/01-quick-start.md (3)
309-315: Surround the first bullet list with blank lines
Markdown lint (MD032) requires blank lines before and after lists. Add a blank line between the colon on line 309 and the first list item, and ensure there’s a blank line after the last list item on line 313.Proposed diff:
When Terragrunt runs these commands, it creates a `.terragrunt-cache` directory in each unit's directory. This cache directory serves as Terragrunt's scratch directory where it: - - - Downloads your remote OpenTofu/Terraform configurations + + - Downloads your remote OpenTofu/Terraform configurations - Runs your OpenTofu/Terraform commands - Stores downloaded modules and providers - Stores generated files (in this case, the `hi.txt` file will be created under `.terragrunt-cache/[HASH]/[HASH]/hi.txt` rather than directly in the `foo` or `bar` directories) - + With this configuration, the `hi.txt` files will be created directly in the `foo` and `bar` directories instead of the `.terragrunt-cache` directory. This is a common pattern when you want to generate files in specific locations relative to your Terragrunt configuration.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
310-310: Lists should be surrounded by blank lines
null(MD032, blanks-around-lists)
🪛 GitHub Check: Run Lint
[failure] 310-310: Lists should be surrounded by blank lines
docs/_docs/01_getting-started/01-quick-start.md:310 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Downloads your remote OpenTo..."] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md032.md🪛 GitHub Actions: Markdown Lint
[error] 310-310: markdownlint MD032: Lists should be surrounded by blank lines.
317-321: Surround the second bullet list with blank lines
Similarly, insert a blank line before the list at line 318 and after the last item at line 320 to satisfy MD032.Proposed diff:
Inside the cache directory, Terragrunt automatically converts your `terragrunt.hcl` configuration into standard OpenTofu/Terraform configuration files: - - - Generates `main.tf` with your module source and provider configurations + + - Generates `main.tf` with your module source and provider configurations - Creates `terraform.tfvars` or `terraform.tfvars.json` with your input variables - Sets up any additional files like `outputs.tf` and `variables.tf` based on your Terragrunt configuration - + The `.terragrunt-cache` directory is typically added to `.gitignore` files, similar to the `.terraform` directory that OpenTofu generates. You can safely delete this folder at any time, and Terragrunt will recreate it as necessary.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
318-318: Lists should be surrounded by blank lines
null(MD032, blanks-around-lists)
🪛 GitHub Check: Run Lint
[failure] 318-318: Lists should be surrounded by blank lines
docs/_docs/01_getting-started/01-quick-start.md:318 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Generatesmain.tfwith you..."] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md032.md
324-325: Remove extra blank lines
There are two consecutive blank lines at line 324, which violates MD012. Reduce to a single blank line.Proposed diff:
- - If you want to control where the files are created, you can modify the module to accept an output directory parameter. For example, you can update the `shared/main.tf` file to:🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
324-324: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
🪛 GitHub Check: Run Lint
[failure] 324-324: Multiple consecutive blank lines
docs/_docs/01_getting-started/01-quick-start.md:324 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md012.md
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
docs/_docs/01_getting-started/01-quick-start.md(1 hunks)test/fixtures/docs/01-quick-start/step-05.1/.gitignore(1 hunks)test/fixtures/docs/01-quick-start/step-05.1/README.md(1 hunks)test/fixtures/docs/01-quick-start/step-05.1/bar/terragrunt.hcl(1 hunks)test/fixtures/docs/01-quick-start/step-05.1/foo/terragrunt.hcl(1 hunks)test/fixtures/docs/01-quick-start/step-05.1/shared/main.tf(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`docs/**/*.md`: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration under...
docs/**/*.md: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration underway from the Jekyll based documentation indocsto the Starlight + Astro based documentation indocs-starlight. Whenever changes are made to thedocsdirectory, ensure that an equivalent change is made in thedocs-starlightdirectory to keep thedocs-starlightdocumentation accurate.
docs/_docs/01_getting-started/01-quick-start.md
🪛 markdownlint-cli2 (0.17.2)
test/fixtures/docs/01-quick-start/step-05.1/README.md
1-1: First line in a file should be a top-level heading
null
(MD041, first-line-heading, first-line-h1)
3-3: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
3-3: Files should end with a single newline character
null
(MD047, single-trailing-newline)
docs/_docs/01_getting-started/01-quick-start.md
310-310: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
318-318: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
324-324: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
🪛 GitHub Check: Run Lint
docs/_docs/01_getting-started/01-quick-start.md
[failure] 324-324: Multiple consecutive blank lines
docs/_docs/01_getting-started/01-quick-start.md:324 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md012.md
[failure] 318-318: Lists should be surrounded by blank lines
docs/_docs/01_getting-started/01-quick-start.md:318 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Generates main.tf with you..."] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md032.md
[failure] 310-310: Lists should be surrounded by blank lines
docs/_docs/01_getting-started/01-quick-start.md:310 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Downloads your remote OpenTo..."] https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md032.md
🪛 GitHub Actions: Markdown Lint
docs/_docs/01_getting-started/01-quick-start.md
[error] 310-310: markdownlint MD032: Lists should be surrounded by blank lines.
⏰ Context from checks skipped due to timeout of 90000ms (7)
- GitHub Check: Test (AWS Tofu)
- GitHub Check: Build (linux/amd64)
- GitHub Check: Test (Fixtures Terraform 1.11)
- GitHub Check: Test (macos)
- GitHub Check: Test (ubuntu)
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: build-and-test
🔇 Additional comments (4)
test/fixtures/docs/01-quick-start/step-05.1/.gitignore (1)
1-2: LGTM.
The.gitignoreappropriately excludes the Terragrunt cache directory and the generatedhi.txtfiles, keeping the test fixture directory clean.test/fixtures/docs/01-quick-start/step-05.1/foo/terragrunt.hcl (1)
1-8: Configuration correct.
This Terragrunt configuration properly references the shared module and passes the dynamicoutput_dirviaget_terragrunt_dir()along with thecontentinput as intended.test/fixtures/docs/01-quick-start/step-05.1/bar/terragrunt.hcl (1)
1-8: Configuration correct.
Thebarexample mirrorsfooand correctly demonstrates the same pattern of controlling output directory viaget_terragrunt_dir().docs/_docs/01_getting-started/01-quick-start.md (1)
1-12: Sync changes to docs-starlight directory
To keep the Jekyll-based docs in sync with the new Astro/Starlight site, please apply equivalent edits in the corresponding file underdocs-starlight/01-getting-started/01-quick-start.md.
There was a problem hiding this comment.
There are some inaccuracies that need to be fixed here. Make sure to address the lint errors as well.
Also, note that our docs updates have to be duplicated while we're moving folks over to the new terragrunt-v1.gruntwork.io docs:
https://github.com/gruntwork-io/terragrunt/blob/main/docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx
Addressed your comments. Thanks for the review! |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
docs/_docs/01_getting-started/01-quick-start.md (4)
309-313: Surround list with blank lines for proper Markdown formatting
MarkdownLint (MD032) reports that lists should be surrounded by blank lines. Add a blank line before the first bullet (line 310) and after the last bullet (line 313) to improve rendering.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
310-310: Lists should be surrounded by blank lines
null(MD032, blanks-around-lists)
315-318: Remove trailing whitespace and extra blank lines
Line 315 has trailing spaces (MD009) and there are two consecutive blank lines at 316–317 (MD012). Trim the trailing space on line 315 and collapse the blank lines into a single blank line to satisfy lint rules.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
315-315: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
320-330: Enhanceshared/main.tfexample with variable metadata
To improve clarity, consider adding a description and type for the newoutput_dirvariable. For instance:variable "output_dir" { description = "Directory path where generated files will be written" type = string }This helps readers understand the expected input.
332-342: Clarify the scope of the snippet
This example shows thebar/terragrunt.hclconfiguration. To avoid confusion, either label it explicitly (e.g., add a heading#### bar/terragrunt.hcl) or present bothfooandbarsnippets side-by-side.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx(1 hunks)docs/_docs/01_getting-started/01-quick-start.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx
🧰 Additional context used
📓 Path-based instructions (1)
`docs/**/*.md`: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration under...
docs/**/*.md: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration underway from the Jekyll based documentation indocsto the Starlight + Astro based documentation indocs-starlight. Whenever changes are made to thedocsdirectory, ensure that an equivalent change is made in thedocs-starlightdirectory to keep thedocs-starlightdocumentation accurate.
docs/_docs/01_getting-started/01-quick-start.md
🪛 markdownlint-cli2 (0.17.2)
docs/_docs/01_getting-started/01-quick-start.md
310-310: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
315-315: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
319-319: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: build-and-test
- GitHub Check: Pull Request has non-contributor approval
🔇 Additional comments (1)
docs/_docs/01_getting-started/01-quick-start.md (1)
1-11: Missing mirror updates in docs-starlight
We've updated the Quick Start guide indocs/_docs/.... Please ensure the equivalent changes are applied underdocs-starlight/01-getting-started/01-quick-start.mdxto keep both documentation sites in sync.Do you want me to generate the corresponding edits for the Starlight docs?
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
docs/_docs/01_getting-started/01-quick-start.md (1)
1-537: 🛠️ Refactor suggestionMirror these documentation updates in the Starlight site.
Since you’re migrating to Starlight + Astro, please ensure all of the above changes are also applied todocs-starlight/src/content/docs/01-getting-started/01-quick-start.mdxso both docs remain in sync.🧰 Tools
🪛 LanguageTool
[uncategorized] ~42-~42: This verb does not appear to agree with the subject. Consider using a different form.
Context: ...nderstanding of what OpenTofu/Terraform do. 3. You are using a Unix-like operating...(AI_EN_LECTOR_REPLACEMENT_VERB_AGREEMENT)
[style] ~43-~43: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nding of what OpenTofu/Terraform do. 3. You are using a Unix-like operating system....(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~49-~49: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...have any experience with Terragrunt. 3. You have any existing Terragrunt, OpenTofu ...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~57-~57: Consider removing “of” to be more concise
Context: ...cussing Terragrunt. Finally, note that all of the files created in this tutorial can be c...(ALL_OF_THE)
[style] ~132-~132: Consider using “comfortable using”.
Context: ...g into common problems. As you get more comfortable with using Terragrunt on larger projects, you may ...(COMFORTABLE_WITH_VBG)
[grammar] ~134-~134: Consider removing ‘would’. (Usually, ‘would’ does not occur in a conditional clause, unless to make a request or give a polite order.)
Context: ... the extra information helpful. If you would prefer that Terragrunt output look more like t...(CONDITIONAL_CLAUSE)
[style] ~181-~181: Consider shortening or rephrasing this to strengthen your wording.
Context: ...ble to avoid duplicating effort when we make changes to our infrastructure. ### Step 3: Create...(MAKE_CHANGES)
[style] ~185-~185: Consider shortening or rephrasing this to strengthen your wording.
Context: ... bothfooandbar. This way, we can make changes to our infrastructure in one place and hav...(MAKE_CHANGES)
[uncategorized] ~309-~309: Possible missing comma found.
Context: ...irectory serves as Terragrunt's scratch directory where it: - Downloads your remote Open...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~417-~417: Interjections are usually punctuated.
Context: ...locks-and-attributes/#dependencies ``` Oh no! We got an error. This happens becau...(INTERJECTIONS_PUNCTUATION)
[grammar] ~478-~478: The verb ‘apply’ does not usually follow articles like ‘an’. Check that ‘apply’ is spelled correctly; using ‘apply’ as a noun may be non-standard.
Context: ...nvalid configurations, note that during an apply, the outputs offoowill be known, an...(A_INFINITIVE)
🧹 Nitpick comments (4)
docs/_docs/01_getting-started/01-quick-start.md (4)
309-315: Refactor description of the cache directory for clarity.
The sentence“This cache directory serves as Terragrunt's scratch directory where it:”
feels a bit cumbersome. Consider splitting it into two for better readability, for example:- This cache directory serves as Terragrunt's scratch directory where it: + This cache directory serves as Terragrunt's scratch space. It:🧰 Tools
🪛 LanguageTool
[uncategorized] ~309-~309: Possible missing comma found.
Context: ...irectory serves as Terragrunt's scratch directory where it: - Downloads your remote Open...(AI_HYDRA_LEO_MISSING_COMMA)
316-318: Clarify the effect of the configuration change.
The transition sentence“With this configuration, the
hi.txtfiles will be created directly in thefooandbardirectories instead of the.terragrunt-cachedirectory.”
could be more concise. For example:- With this configuration, the `hi.txt` files will be created directly in the `foo` and `bar` directories instead of the `.terragrunt-cache` directory. + As a result, `hi.txt` is written directly into each unit’s directory instead of `.terragrunt-cache`.
320-329: Ensure HCL snippet is fully contextualized.
The newshared/main.tfexample correctly adds anoutput_dirvariable, but readers would benefit from a brief lead-in. For instance, add a sentence like:Modify your shared module to accept an
output_dirparameter:
before the code block. This sets context and highlights the purpose of the snippet.
332-343: Alignterragrunt.hclexample formatting and commentary.
In thefoo/terragrunt.hcl/bar/terragrunt.hclsnippet, consider:
- Adding an inline comment to explain
get_terragrunt_dir(), e.g.:inputs = { output_dir = get_terragrunt_dir() # Points to the current unit directory content = "Hello from bar, Terragrunt!" }- Verifying that indentation matches surrounding blocks for consistency.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/_docs/01_getting-started/01-quick-start.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`docs/**/*.md`: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration under...
docs/**/*.md: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration underway from the Jekyll based documentation indocsto the Starlight + Astro based documentation indocs-starlight. Whenever changes are made to thedocsdirectory, ensure that an equivalent change is made in thedocs-starlightdirectory to keep thedocs-starlightdocumentation accurate.
docs/_docs/01_getting-started/01-quick-start.md
🪛 LanguageTool
docs/_docs/01_getting-started/01-quick-start.md
[uncategorized] ~309-~309: Possible missing comma found.
Context: ...irectory serves as Terragrunt's scratch directory where it: - Downloads your remote Open...
(AI_HYDRA_LEO_MISSING_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (5)
- GitHub Check: Test (macos)
- GitHub Check: Test (ubuntu)
- GitHub Check: lint
- GitHub Check: build-and-test
- GitHub Check: Pull Request has non-contributor approval
| - Downloads your remote OpenTofu/Terraform configurations | ||
| - Runs your OpenTofu/Terraform commands | ||
| - Stores downloaded modules and providers | ||
| - Stores generated files (in this case, the `hi.txt` file will be created under `.terragrunt-cache/[HASH]/[HASH]/hi.txt` rather than directly in the `foo` or `bar` directories) |
There was a problem hiding this comment.
I think we can cut this. We mention this in the next line, and "generated files" is confusing in this context. OpenTofu/Terraform generates this file, not Terragrunt.
| @@ -315,6 +315,42 @@ You can also see what to expect in your filesystem at each step [here](https://g | |||
|
|
|||
| This is where that additional verbosity in Terragrunt logging is really handy. You can see that Terragrunt concurrently ran `apply -auto-approve` in both the `foo` and `bar` units. The extra logging for Terragrunt also included information on the names of the units that were processed, and disambiguated the output from each unit. | |||
|
|
|||
| When Terragrunt runs these commands, it creates a `.terragrunt-cache` directory in each unit's directory. This cache directory serves as Terragrunt's scratch directory where it: | |||
There was a problem hiding this comment.
This is all good content!
| - Downloads your remote OpenTofu/Terraform configurations | ||
| - Runs your OpenTofu/Terraform commands | ||
| - Stores downloaded modules and providers | ||
| - Stores generated files (in this case, the `hi.txt` file will be created under `.terragrunt-cache/[HASH]/[HASH]/hi.txt` rather than directly in the `foo` or `bar` directories) |
There was a problem hiding this comment.
Make sure to replicate the edit between these two if you accept the suggestion above.
|
Thanks for taking care of it @yhakbar! 👍 |
Description
Fixes #4296.
TODOs
Read the Gruntwork contribution guidelines.
Release Notes (draft)
Added / Removed / Updated [X].
Migration Guide
Summary by CodeRabbit
.terragrunt-cachedirectory, Terragrunt caching behavior, and strategies for controlling output file locations.get_terragrunt_dir()function..gitignorefiles to exclude cache and generated files.