From edacae14b076173802e9db5632c4a88b7cf7ea1b Mon Sep 17 00:00:00 2001 From: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> Date: Fri, 22 Nov 2024 09:06:06 -0500 Subject: [PATCH] fix: Adjusting `run-all` docs (#3589) * fix: Adjusting `run-all` docs * fix: Markdown linting --- .../add-to-opentofu-project.md | 2 +- ...orm-commands-on-multiple-units-at-once.md} | 0 docs/_docs/04_reference/cli-options.md | 56 ++++++++++++------- .../config-blocks-and-attributes.md | 2 +- docs/_includes/use-cases-box.html | 2 +- docs/_pages/index/_key-features.html | 2 +- 6 files changed, 41 insertions(+), 23 deletions(-) rename docs/_docs/02_features/{execute-terraform-commands-on-multiple-modules-at-once.md => execute-terraform-commands-on-multiple-units-at-once.md} (100%) diff --git a/docs/_docs/01_getting-started/add-to-opentofu-project.md b/docs/_docs/01_getting-started/add-to-opentofu-project.md index d044d8992d..1e335089b9 100644 --- a/docs/_docs/01_getting-started/add-to-opentofu-project.md +++ b/docs/_docs/01_getting-started/add-to-opentofu-project.md @@ -343,7 +343,7 @@ Group 2 08:57:09.936 ERROR Unable to determine underlying exit code, so Terragrunt will exit with error code 1 ``` -Oh no! We got an error. This is because the way in which dependencies are resolved by default in Terragrunt is to run `terragrunt output` within the dependent unit in order to fetch them for the dependent unit. In this case, the `foo` unit has not been applied yet, so there are no outputs to fetch. +Oh no! We got an error. This is because the way in which dependencies are resolved by default in Terragrunt is to run `terragrunt output` within the dependency for use in the dependent unit. In this case, the `foo` unit has not been applied yet, so there are no outputs to fetch. You should notice, however, that Terragrunt has already figured out the order in which to run the `plan` command across the units in your stack. This is what we mean when we say that Terragrunt uses a DAG to determine the order in which to run commands across your stack. Terragrunt analyzes the dependencies across your units, and determines the order in which to run updates so that outputs are ready to be used as inputs in dependent units. diff --git a/docs/_docs/02_features/execute-terraform-commands-on-multiple-modules-at-once.md b/docs/_docs/02_features/execute-terraform-commands-on-multiple-units-at-once.md similarity index 100% rename from docs/_docs/02_features/execute-terraform-commands-on-multiple-modules-at-once.md rename to docs/_docs/02_features/execute-terraform-commands-on-multiple-units-at-once.md diff --git a/docs/_docs/04_reference/cli-options.md b/docs/_docs/04_reference/cli-options.md index 656ef2f428..35e9343d80 100644 --- a/docs/_docs/04_reference/cli-options.md +++ b/docs/_docs/04_reference/cli-options.md @@ -139,14 +139,13 @@ Run `terraform --help` to get the full list. ### run-all -Runs the provided OpenTofu/Terraform command against a `stack`, where a `stack` is a -tree of terragrunt modules. The command will recursively find terragrunt -modules in the current directory tree and run the OpenTofu/Terraform command in -dependency order (unless the command is destroy, in which case the command is -run in reverse dependency order). +Runs the provided OpenTofu/Terraform command against a [stack](/docs/getting-started/terminology/#stack). +The command will recursively find terragrunt [units](/docs/getting-started/terminology/#unit) in the current directory +tree and run the OpenTofu/Terraform command in dependency order (unless the command is destroy, +in which case the command is run in reverse dependency order). Make sure to read [Execute OpenTofu/Terraform -commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for +commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for context. Example: @@ -155,27 +154,46 @@ Example: terragrunt run-all apply ``` -This will recursively search the current working directory for any folders that contain Terragrunt modules and run +This will recursively search the current working directory for any folders that contain Terragrunt units and run `apply` in each one, concurrently, while respecting ordering defined via [`dependency`](/docs/reference/config-blocks-and-attributes/#dependency) and [`dependencies`](/docs/reference/config-blocks-and-attributes/#dependencies) blocks. -**[WARNING] Using `run-all` with `plan` is currently broken for certain use cases**. If you have a stack of Terragrunt -modules with dependencies between them—either via `dependency` blocks or `terraform_remote_state` data sources—and -you've never deployed them, then `run-all plan` will fail as it will not be possible to resolve the `dependency` blocks -or `terraform_remote_state` data sources! Please [see here for more -information](https://github.com/gruntwork-io/terragrunt/issues/720#issuecomment-497888756). +**[WARNING] Use `run-all` with care if you have unapplied dependencies**. + +If you have a stack of Terragrunt units with dependencies between them—either via `dependency` blocks +or `terraform_remote_state` data sources—and +you've never deployed them, then commands like `run-all plan` will fail, +as it will not be possible to resolve the `dependency` blocks +or `terraform_remote_state` data sources! + +The solution for this is to take advantage of [mock outputs in dependency blocks](/docs/reference/config-blocks-and-attributes/#dependency). + +**[WARNING] Do not set [TF_PLUGIN_CACHE_DIR](https://opentofu.org/docs/cli/config/config-file/#provider-plugin-cache) when using `run-all`** + +Instead take advantage of the built-in [Provider Cache Server](https://terragrunt.gruntwork.io/docs/features/provider-cache/) that +mitigates some of the limitations of using the OpenTofu/Terraform Provider Plugin Cache directly. + +Note that we are [working with the OpenTofu team to improve this behavior](https://github.com/opentofu/opentofu/issues/1483) so that you don't have to worry about this. **[NOTE]** Using `run-all` with `apply` or `destroy` silently adds the `-auto-approve` flag to the command line -arguments passed to OpenTofu/Terraform due to issues with shared `stdin` making individual approvals impossible. Please -[see here for more information](https://github.com/gruntwork-io/terragrunt/issues/386#issuecomment-358306268) +arguments passed to OpenTofu/Terraform due to issues with shared `stdin` making individual approvals impossible. + +**[NOTE]** Using the OpenTofu/Terraform [-detailed-exitcode](https://opentofu.org/docs/cli/commands/plan/#other-options) +flag with the `run-all` command results in an aggregate exit code being returned, rather than the exit code of any particular unit. + +The algorithm for determining the aggregate exit code is as follows: + +- If any unit throws a 1, Terragrunt will throw a 1. +- If any unit throws a 2, but nothing throws a 1, Terragrunt will throw a 2. +- If nothing throws a non-zero, Terragrunt will throw a 0. ### plan-all (DEPRECATED: use run-all) **DEPRECATED: Use `run-all plan` instead.** Display the plans of a `stack` by running `terragrunt plan` in each subfolder. Make sure to read [Execute OpenTofu/Terraform -commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for +commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for context. Example: @@ -200,7 +218,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/720#issuecomment- **DEPRECATED: Use `run-all apply` instead.** Apply a `stack` by running `terragrunt apply` in each subfolder. Make sure to read [Execute OpenTofu/Terraform -commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for +commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for context. Example: @@ -223,7 +241,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/386#issuecomment- **DEPRECATED: Use `run-all output` instead.** Display the outputs of a `stack` by running `terragrunt output` in each subfolder. Make sure to read [Execute OpenTofu/Terraform -commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for +commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for context. Example: @@ -248,7 +266,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/720#issuecomment- **DEPRECATED: Use `run-all destroy` instead.** Destroy a `stack` by running `terragrunt destroy` in each subfolder. Make sure to read [Execute OpenTofu/Terraform -commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for +commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for context. Example: @@ -271,7 +289,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/386#issuecomment- **DEPRECATED: Use `run-all validate` instead.** Validate `stack` by running `terragrunt validate` in each subfolder. Make sure to read [Execute OpenTofu/Terraform -commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for +commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for context. Example: diff --git a/docs/_docs/04_reference/config-blocks-and-attributes.md b/docs/_docs/04_reference/config-blocks-and-attributes.md index b4b48694bf..febe376fb7 100644 --- a/docs/_docs/04_reference/config-blocks-and-attributes.md +++ b/docs/_docs/04_reference/config-blocks-and-attributes.md @@ -977,7 +977,7 @@ inputs = { The `dependency` block is used to configure module dependencies. Each dependency block exports the outputs of the target module as block attributes you can reference throughout the configuration. You can learn more about `dependency` blocks in the [Dependencies between modules -section](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/#dependencies-between-modules) of the +section](/docs/features/execute-terraform-commands-on-multiple-units-at-once/#dependencies-between-modules) of the "Execute Opentofu/Terraform commands on multiple modules at once" use case overview. You can define more than one `dependency` block. Each label you provide to the block identifies another `dependency` diff --git a/docs/_includes/use-cases-box.html b/docs/_includes/use-cases-box.html index 12173768b3..b1789885da 100644 --- a/docs/_includes/use-cases-box.html +++ b/docs/_includes/use-cases-box.html @@ -12,7 +12,7 @@

Use cases

Keep your CLI flags DRY
- Execute OpenTofu/Terraform commands on multiple modules at once + Execute OpenTofu/Terraform commands on multiple modules at once
Work with multiple AWS accounts diff --git a/docs/_pages/index/_key-features.html b/docs/_pages/index/_key-features.html index 884cfd32e2..688b646a85 100644 --- a/docs/_pages/index/_key-features.html +++ b/docs/_pages/index/_key-features.html @@ -68,7 +68,7 @@

Keep your OpenTofu/Terraform CLI arguments DRY

Execute OpenTofu/Terraform commands on multiple modules at once

Run one command for all modules instead of executing it in each module independently.

- Learn more + Learn more