Skip to content

Commit

Permalink
fix: Replacing usage of run-all with run --all in starlight docs
Browse files Browse the repository at this point in the history
  • Loading branch information
yhakbar committed Mar 1, 2025
1 parent 2ede06c commit 4f506ae
Showing 1 changed file with 32 additions and 32 deletions.
64 changes: 32 additions & 32 deletions docs-starlight/src/content/docs/02-features/02-stacks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,30 +70,30 @@ To solve the problem above, first convert the OpenTofu/Terraform modules into un

Because you've created a directory of units, you've also implicitly created a stack!

Now, you can go into the `root` directory and deploy all the units within it by using the `run-all` command with `apply`:
Now, you can go into the `root` directory and deploy all the units within it by using the `run --all` command with `apply`:

```bash
cd root
terragrunt run-all apply
terragrunt run --all apply
```

When you run this command, Terragrunt will recursively discover all the units under the current working directory, and run `terragrunt apply` on each of those units concurrently\*.

Similarly, to undeploy all the OpenTofu/Terraform units, you can use the `run-all` command with `destroy`:
Similarly, to undeploy all the OpenTofu/Terraform units, you can use the `run --all` command with `destroy`:

```bash
cd root
terragrunt run-all destroy
terragrunt run --all destroy
```

To see the currently applied outputs of all of the subfolders, you can use the `run-all` command with `output`:
To see the currently applied outputs of all of the subfolders, you can use the `run --all` command with `output`:

```bash
cd root
terragrunt run-all output
terragrunt run --all output
```

Finally, if you make some changes to your project, you could evaluate the impact by using `run-all` command with `plan`:
Finally, if you make some changes to your project, you could evaluate the impact by using `run --all` command with `plan`:

Note: It is important to realize that you could get errors running `run --all plan` if you have dependencies between your
projects and some of those dependencies haven’t been applied yet.
Expand All @@ -102,7 +102,7 @@ _Ex: If unit A depends on unit B and unit B hasn’t been applied yet, then `run

```bash
cd root
terragrunt run-all plan
terragrunt run --all plan
```

\* Note that the units _might_ run concurrently, but some units can be blocked from running until their dependencies are run.
Expand Down Expand Up @@ -176,7 +176,7 @@ inputs = {
}
```

Note that each `dependency` block results in a relevant status in the Terragrunt [DAG](/docs/getting-started/terminology/#directed-acyclic-graph-dag). This means that when you run `run-all apply` on a config that has `dependency` blocks, Terragrunt will not attempt to deploy the config until all the units referenced in `dependency` blocks have been applied. So for the above example, the order for the `run-all apply` command would be:
Note that each `dependency` block results in a relevant status in the Terragrunt [DAG](/docs/getting-started/terminology/#directed-acyclic-graph-dag). This means that when you run `run --all apply` on a config that has `dependency` blocks, Terragrunt will not attempt to deploy the config until all the units referenced in `dependency` blocks have been applied. So for the above example, the order for the `run --all apply` command would be:

1. Deploy the VPC

Expand All @@ -192,15 +192,15 @@ If any of the units failed to deploy, then Terragrunt will not attempt to deploy

Terragrunt will return an error if the unit referenced in a `dependency` block has not been applied yet. This is because you cannot actually fetch outputs out of an unapplied unit, even if there are no resources being created in the unit.

This is most problematic when running commands that do not modify state (e.g `run-all plan` and `run-all validate`) on a completely new setup where no infrastructure has been deployed. You won’t be able to `plan` or `validate` a unit if you can’t determine the `inputs`. If the unit depends on the outputs of another unit that hasn’t been applied yet, you won’t be able to compute the `inputs` unless the dependencies are all applied.
This is most problematic when running commands that do not modify state (e.g `run --all plan` and `run --all validate`) on a completely new setup where no infrastructure has been deployed. You won’t be able to `plan` or `validate` a unit if you can’t determine the `inputs`. If the unit depends on the outputs of another unit that hasn’t been applied yet, you won’t be able to compute the `inputs` unless the dependencies are all applied.

Of course, in real life usage, you typically need the ability to run `run-all validate` or `run-all plan` on a completely new set of infrastructure.
Of course, in real life usage, you typically need the ability to run `run --all validate` or `run --all plan` on a completely new set of infrastructure.

To address this, you can provide mock outputs to use when a unit hasn’t been applied yet. This is configured using the `mock_outputs` attribute on the `dependency` block and it corresponds to a map that will be injected in place of the actual dependency outputs if the target config hasn’t been applied yet.

Using a mock output is typically the best solution here, as you typically don't actually care that an _accurate_ value is used for a given value at this stage, just that it will plan successfully. When you actually apply the unit, that's when you want to be sure that a real value is used.

For example, in the previous scenario with a `mysql` unit and `vpc` unit, suppose you wanted to mock a value for the `vpc_id` during a `run-all validate` for the `mysql` unit.
For example, in the previous scenario with a `mysql` unit and `vpc` unit, suppose you wanted to mock a value for the `vpc_id` during a `run --all validate` for the `mysql` unit.

You can specify that in `mysql/terragrunt.hcl`:

Expand Down Expand Up @@ -242,7 +242,7 @@ inputs = {
}
```

Note that indicating `validate` means that the `mock_outputs` will be used either with `validate` or with `run-all validate`.
Note that indicating `validate` means that the `mock_outputs` will be used either with `validate` or with `run --all validate`.

You can also use `skip_outputs` on the `dependency` block to specify the dependency without pulling in the outputs:

Expand Down Expand Up @@ -342,7 +342,7 @@ dependencies {

Once you’ve specified these dependencies in each `terragrunt.hcl` file, Terragrunt will be able to perform updates respecting the [DAG](/docs/getting-started/terminology/#directed-acyclic-graph-dag) of dependencies.

For the example at the start of this section, the order of runs for the `run-all apply` command would be:
For the example at the start of this section, the order of runs for the `run --all apply` command would be:

1. Deploy the VPC

Expand All @@ -352,9 +352,9 @@ For the example at the start of this section, the order of runs for the `run-all

4. Deploy the frontend-app

Any error encountered in an individual unit during a `run-all` command will prevent Terragrunt from proceeding with the deployment of any dependent units.
Any error encountered in an individual unit during a `run --all` command will prevent Terragrunt from proceeding with the deployment of any dependent units.

To check all of your dependencies and validate the code in them, you can use the `run-all validate` command.
To check all of your dependencies and validate the code in them, you can use the `run --all validate` command.

**Note:** During `destroy` runs, Terragrunt will try to find all dependent units and show a confirmation prompt with a list of detected dependencies. This is because Terragrunt knows that once resources in a dependency are destroyed, any commands run on dependent units may fail. For example, if `destroy` was called on the `redis` unit, you'll be asked for confirmation, as the `backend-app` depends on `redis`. You can avoid the prompt by using `--non-interactive`.

Expand Down Expand Up @@ -384,12 +384,12 @@ If you are using Terragrunt to download [remote OpenTofu/Terraform modules](/doc

```bash
cd root
terragrunt run-all plan --source /source/modules
terragrunt run --all plan --source /source/modules
```

If you set the `--source` parameter, the `run-all` command will assume that parameter is pointing to a folder on your local file system that has a local checkout of all of your OpenTofu/Terraform modules.
If you set the `--source` parameter, the `run --all` command will assume that parameter is pointing to a folder on your local file system that has a local checkout of all of your OpenTofu/Terraform modules.

For each unit that is being processed via a `run-all` command, Terragrunt will:
For each unit that is being processed via a `run --all` command, Terragrunt will:

1. Read in the `source` parameter in that unit’s `terragrunt.hcl` file.
2. Parse out the path (the portion after the double-slash).
Expand All @@ -408,7 +408,7 @@ terraform {
Running the following:

```bash
terragrunt run-all apply --source /source/infrastructure-modules
terragrunt run --all apply --source /source/infrastructure-modules
```

Will result in a unit with the configuration for the source above being resolved to `/source/infrastructure-modules//networking/vpc`.
Expand All @@ -424,20 +424,20 @@ cloud provider.
To limit the maximum number of unit executions at any given time use the `--parallelism [number]` flag

```sh
terragrunt run-all apply --parallelism 4
terragrunt run --all apply --parallelism 4
```

## Saving OpenTofu/Terraform plan output

A powerful feature of OpenTofu/Terraform is the ability to [save the result of a plan as a binary or JSON file using the -out flag](https://opentofu.org/docs/cli/commands/plan/).

Terragrunt provides special tooling in `run-all` execution in order to ensure that the saved plan for a `run-all` against a stack has
Terragrunt provides special tooling in `run --all` execution to ensure that the saved plan for a `run --all` against a stack has
a corresponding entry for each unit in the stack in a directory structure that mirrors the stack structure.

To save plan against a stack, use the `--out-dir` flag (or `TG_OUT_DIR` environment variable) as demonstrated below:

```bash
$ terragrunt run-all plan --out-dir /tmp/tfplan
$ terragrunt run --all plan --out-dir /tmp/tfplan
```

<FileTree>
Expand All @@ -455,20 +455,20 @@ $ terragrunt run-all plan --out-dir /tmp/tfplan
</FileTree>

```bash
$ terragrunt run-all apply --out-dir /tmp/tfplan
$ terragrunt run --all --out-dir /tmp/tfplan apply
```

For planning a destroy operation, use the following commands:

```bash
terragrunt run-all plan -destroy --out-dir /tmp/tfplan
terragrunt run-all apply --out-dir /tmp/tfplan
terragrunt run --all --out-dir /tmp/tfplan plan -destroy
terragrunt run --all --out-dir /tmp/tfplan apply
```

To save plan in json format use `--json-out-dir` flag (or `TG_JSON_OUT_DIR` environment variable):

```bash
terragrunt run-all plan --json-out-dir /tmp/json
terragrunt run --all --json-out-dir /tmp/json plan
```

<FileTree>
Expand All @@ -487,7 +487,7 @@ terragrunt run-all plan --json-out-dir /tmp/json


```bash
terragrunt run-all plan --out-dir /tmp/all --json-out-dir /tmp/all
terragrunt run --all --out-dir /tmp/all --json-out-dir /tmp/all plan
```

<FileTree>
Expand All @@ -512,7 +512,7 @@ To recap:

- The plan for each unit in a stack is saved in the same hierarchy as the unit structure.
- The file name for plan binaries are `tfplan.tfplan` and `tfplan.json` for plan JSON.
- JSON plan files can't be used with `terragrunt run-all apply` command, only binary plan files can be used.
- JSON plan files can't be used with `terragrunt run --all apply` command, only binary plan files can be used.
- Output directories can be combined which will lead to saving both binary and JSON plans.

## Nested Stacks
Expand Down Expand Up @@ -540,18 +540,18 @@ For example, consider the following file structure:
In this example, there's the `root` stack, that contains all the infrastructure you've defined so far,
and there's also the `us-east-1` and `us-west-2` stacks, that contain the infrastructure for the `app` and `db` units in those regions.

You can run `run-all` commands at any depth of the stack to run the units in that stack and all of its children.
You can run `run --all` commands at any depth of the stack to run the units in that stack and all of its children.

For example, to run all the units in the `us-east-1` stack, you can run:

```sh
cd root/us-east-1
terragrunt run-all apply
terragrunt run --all apply
```

Terragrunt will only include the units in the `us-east-1` stack and its children in the queue of units to run (unless external dependencies are pulled in, as discussed in the [run --all command](#the-run---all-command) section).

Generally speaking, this is the primary tool Terragrunt users use to control the blast radius of their changes. For the most part, it is the current working directory that determines the blast radius of a `run-all` command.
Generally speaking, this is the primary tool Terragrunt users use to control the blast radius of their changes. For the most part, it is the current working directory that determines the blast radius of a `run --all` command.

In addition to using your working directory to control what's included in a [run queue](/docs/getting-started/terminology/#run-queue), you can also use flags like [--include-dir](/docs/reference/cli/commands/run#include-dir) and [--exclude-dir](/docs/reference/cli/commands/run#exclude-dir) to explicitly control what's included in a run queue within a stack, or outside of it.

Expand Down

0 comments on commit 4f506ae

Please sign in to comment.