From 9ad61ca08a4803fcb559a9d815cf74ba65c1a8a1 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Wed, 20 Mar 2024 21:47:34 +0100 Subject: [PATCH 1/7] docs: change sidebar --- docs/.vitepress/config.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 1214ec04a..3c73e6931 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -217,7 +217,7 @@ export default defineConfig({ ], }, { text: 'Filter Stacks', link: '/cli/orchestration/tag-filter' }, - // { text: 'Order of Execution ', link: '/cli/orchestration/order-of-execution' }, + { text: 'Order of Execution ', link: '/cli/orchestration/order-of-execution' }, { text: 'Configure Runtime ENV', link: '/cli/orchestration/runtime-configuration' }, { text: 'Disable Safeguards', link: '/cli/orchestration/safeguards' }, ], @@ -956,7 +956,7 @@ export default defineConfig({ link: '/cli/guides/', }, { - text: 'Community', + text: '🌍 Community', link: 'https://terramate.io/discord', }, ], From a4663c7ebe54f9f827e5c7c5c404af47dd486337 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Wed, 20 Mar 2024 21:47:53 +0100 Subject: [PATCH 2/7] docs: update create stacks section --- docs/cli/stacks/create.md | 66 ++++++++++++++------------------------- 1 file changed, 24 insertions(+), 42 deletions(-) diff --git a/docs/cli/stacks/create.md b/docs/cli/stacks/create.md index 50fb32a36..3f209c9c4 100644 --- a/docs/cli/stacks/create.md +++ b/docs/cli/stacks/create.md @@ -1,25 +1,35 @@ --- title: Create Stacks description: Learn how to create and manage Infrastructure as Code agnostic stacks with Terramate. +outline: [2, 3] --- -# Create stacks +# Create Stacks -## Create a stack +## Create a plain stack -Stacks can be created using the [create](../cmdline/create.md) command, e.g.: +Stacks can be created using the [terramate create](../cmdline/create.md) command. +The command accepts a set of options to allow to initialize all its details programmatically. +You can set metadata like the `name`, `description`, add `tags`, or define an order of execution. ```sh -terramate create [options] +terramate create ``` -By default, this will create a directory with a `stack.tm.hcl` file that contains the configuration for your stack, -which comes with some default properties: +By default, the `terramate create` command will create a directory and add a `stack.tm.hcl` file that contains the configuration for your stack adding the directory basename as `name` and `description` and creating a UUIDv4 as `id` that needs to be unique within the current reposiory and identifies the stack in Terramate Cloud if connected. + +It is recommended to never change the `id` once committed to allow tracking of the stack when refactoring the directory hierarchy. + +The generated file is an HCL file and can be edited and extended at any point in time. + +The following example ```sh terramate create stacks/vpc --name "Main VPC" --description "Stack to manage the main VPC" ``` +will lead to the creation of the following file: + ```hcl # ./stacks/vpc/stack.tm.hcl stack { @@ -29,46 +39,18 @@ stack { } ``` -- `name`: name of the stack, defaults to the basename of the directory -- `description`: description of the stack, defaults to the basename of the directory -- `id`: a project-wide random UUID +You can use all available configuration properties as attributes to the [terramate create](../cmdline/create.md) command, e.g. -You can use all available configuration properties as attributes to the [create](../cmdline/create.md) command, e.g. For an overview of all properties available for configuring stacks, -please see [stacks configuration](./configuration.md) documentation. +please see [Stack Configuration](./configuration.md) documentation. -## Generating code when creating stacks +Terramate detects stacks based on the exitance of a `stack {}` Block. The name of the file is not important and can be different from `stack.tm.hcl`. There can be exactly one stack block defined in a stack. -Whenever you create a new stack using the [create](../cmdline/create.md) command, Terramate will automatically run the -code generation for you. This comes especially handy when you want to automatically create files such as -Terraform configurations for each newly created stack. +For new stacks, [Code Generation](../code-generation/index.md) will be triggered so that the new stack gets initialized with a default configuration if desired. -For example, the following Terramate configuration will automatically create the Terraform backend configuration using the -`stack.id` property as a reference for the key of the Terraform state in all stacks that are tagged with `terraform`. +## Import existing stacks -```hcl -generate_hcl "_terramate_generated_backend.tf" { - condition = tm_contains(terramate.stack.tags, "terraform") - - content { - terraform { - backend "s3" { - region = "us-east-1" - bucket = "terraform-state-bucket" - key = "terraform/stacks/by-id/${terramate.stack.id}/terraform.tfstate" - encrypt = true - dynamodb_table = "terraform_state" - } - } - } -} -``` - -Running the code generation upon stack creation can be disabled by passing the `-no-generate` argument to the -[create](../cmdline/create.md) command, e.g.: - -```hcl -terramate create -no-generate -``` +Terramate can detect and import various existing configurations. -For details, please see [Code Generation](../code-generation/index.md) documentation. +- `terramate create --all-terraform` will [import existing Terraform](../on-boarding/terraform.md) +- `terramate create --all-terragrunt` will [import existing Terragrunt](../on-boarding/terragrunt.md) From 4ad5d7edf5407d838f3bd4db20f8f3b9a27916f2 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Wed, 20 Mar 2024 21:48:10 +0100 Subject: [PATCH 3/7] docs: update stack config section --- docs/cli/stacks/configuration.md | 182 ++++++++++++++++++------------- 1 file changed, 107 insertions(+), 75 deletions(-) diff --git a/docs/cli/stacks/configuration.md b/docs/cli/stacks/configuration.md index 070b9a6f9..76dfe88c0 100644 --- a/docs/cli/stacks/configuration.md +++ b/docs/cli/stacks/configuration.md @@ -1,143 +1,178 @@ --- title: Stack Configuration description: Learn how to configure the metadata and orchestration behavior of stacks in Terramate. +outline: [2, 3] --- # Configure stacks -Stacks can be configured in the `stack {}` block (by default in `stack.tm.hcl`). The options available cover: +Terramate detects stacks based on the exitance of a `stack {}` Block. The name of the file is not important and can be different from `stack.tm.hcl`. There can be exactly one stack block defined in a stack. -- Configuring Metadata (`name`, `description`, `id`, `tags`) for targeting -- Changing the order of execution (`before`, `after`) -- Triggering options (`watch`, `wants`, `wanted_by`) +- Define Stack Metadata: `name`, `description`, `id`, `tags`. +- Set an explicit Order of Execution: `before`, `after`. +- Configure Forced Execution: `watch`, `wants`, `wanted_by`. -## Configure metadata +```hcl +stack { + id = "7b5f4d89-70a7-42f0-972f-3be8550e65df" + name = "My Awesome Stack Name" + description = "My Awesome Stack Description" + tags = [ + "aws", + "vpc", + "bastion", + ] +} +``` + +## General Stack Metadata + +### `id` -### stack.id (string)(optional) +The stack ID **must** be a `string` composed of alphanumeric chars, dashes, and underscores. +The ID can't be bigger than 64 bytes, **is case insensitive** and **must** be unique over the whole project. It is required when synchronizen data to Terramate Cloud. -The stack ID **must** be a string composed of alphanumeric chars + `-` + `_`. -The ID can't be bigger than 64 bytes, **is case insensitive** and -**must** be unique over the whole project. +It is recommended to use a lowercase [UUIDv4]() as stack ID as this is the default when a stack is created using the [`terramate create`](../cmdline/create.md) command. -There is no default value determined for the stack ID, but when users use -the [create](../cmdline/create.md) command to create new stacks or the [clone](../cmdline/experimental/experimental-clone.md) command to clone stacks, -the ID will default to a [random UUID](). +When stacks are [cloned](../cmdline/experimental/experimental-clone.md) a new UUIDv4 is generated for cloned stacks. + +When `id` is missing in stacks, the `terramate create --ensure-id` command can be used to add a UUIDv4 to stacks that did not define an `id` yet. + +Example: ```hcl -stack { - id = "some_id_that_must_be_unique" -} +id = "7b5f4d89-70a7-42f0-972f-3be8550e65df" ``` -### stack.name (string)(optional) +The id is available as `terramate.stack.id` variable in Code Generation. + +### `name` + +The optional stack name can be any string. It is supposed to give the stack a human-readable Name. + +If not set, it defaults to the basename of the stack path. -The stack name can be any string and defaults to the stack directory base name. +The stack name will be synchronized to Terramate Cloud and shown in addition to the stack path to identify a stack. ```hcl -stack { - name = "My Awesome Stack Name" -} +name = "My Awesome Stack Name" ``` -### stack.description (string)(optional) +The name is available as `terramate.stack.name` variable in Code Generation. + +### `description` + +The stack description can be any string and can include multiple lines. -The stack description can be any string and defaults to an empty string. +It will be synchronized to Terramate Cloud and shown in the Stacks Details area. ```hcl -stack { - description = "My Awesome Stack Description" -} +description = "My Awesome Stack Description" ``` -### stack.tags (set(string))(optional) +The description is available as `terramate.stack.description` variable in Code Generation. + +### `tags` -The tags list must be a unique set of strings where each tag must adhere to the following rules: +The tags list is a set of strings and each tag needs to be a lowercase alphanumeric string that can also contain dashes and underscores. -- It must start with a lowercase ASCII alphabetic character (`[a-z]`). -- It must end with a lowercase ASCII alphanumeric character (`[0-9a-z]`). -- It must have only lowercase ASCII alphanumeric, `_` and `` characters (`[0-9a-z_-]`). +Tags can be used to target/filter stacks in various commands and shall be used when defining order of execution of a stack. + +Terramate Cloud allows to filter stacks by tags. ```hcl -stack { - ... - tags = [ - "aws", - "vpc", - "bastion", - ] -} +tags = [ + "aws", + "vpc", + "bastion", +] ``` -## Configuring the order of execution +Tags are available as `terramate.stack.tags` variable in Code Generation and can be used to conditionally generate code for stacks having or not having specific stacks defined. + +Examples of commands with tags support: + +- Listing having or not having tags set: + + - `terramate list --tags a` + - `terramate list --no-tags b` + +- Running any command in stacks having or not having tags set: + + - `terramate run --tags c -- echo "hi from stack with tag c"` + - `terramate run --no-tags d -- echo "hi from stack without tag d"` + +- Running `my script` Terramate Script in stacks having or not having tags set: + + - `terramate script run --tags e my script` + - `terramate script run --no-tags f my script` + +## Explicit Order of Execution ::: tip It's a best practice to use tags instead of paths for defining the order of execution of stacks with `before` and `after`. ::: -### stack.after (set(string))(optional) +### `after` `after` defines a list of stacks that this stack must run after. It accepts project absolute paths (like `/other/stack`), paths relative to the directory of this stack (e.g.: `../other/stack`) or a [Tag Filter](../orchestration/index.md#filter-by-tags). ```hcl -stack { - ... - after = [ - "tag:prod:networking", - "/prod/apps/auth" - ] -} +after = [ + "tag:prod:networking", + "/prod/apps/auth", +] ``` The stack above will run after all stacks tagged with `prod` **and** `networking` and after `/prod/apps/auth` stack. See the [orchestration docs](../orchestration/index.md#order-of-execution) for details. -### stack.before (set(string))(optional) +### `before` Defines the list of stacks that this stack must run `before`, following the same rules as `after`. ```hcl -stack { - ... - before = [ - "tag:prod:networking", - "/prod/apps/auth" - ] -} +before = [ + "tag:prod:networking", + "/prod/apps/auth", +] ``` -## Configure triggering options +## Influence Change Detection -### stack.watch (list)(optional) +### `watch` The list of files that must be watched for changes in the [change detection](../change-detection/index.md). ```hcl -stack { - ... - watch = [ - "/policies/mypolicy.json" - ] -} +watch = [ + "/policies/mypolicy.json" +] ``` The configuration above will mark the stack as changed whenever the file `/policies/mypolicy.json` changes. -### stack.wants (set(string))(optional) +## Forced Execution + +::: warning +Using forced execution is an anti pattern and will lead to a bigger blast radius. +Consider combining the stacks for easier maintainability instead. +Im most scenarios defining Order of Execution is sufficient to guarantee changes are applied in order. +::: + +### `wants` This attribute defines a list of stacks that will be run whenever this stack is run. Example: ```hcl -stack { - ... - wants = [ - "/other/stack" - ] -} +wants = [ + "/other/stack" +] ``` This can be useful to force a dependency relationship between stacks - for example, if a dependent stack is outside of @@ -161,7 +196,7 @@ It's _very important to note_ that adding a stack to `wants` _does not alter the stack to run before or after another you must also use the `before` and `after` attributes. ::: -### stack.wanted_by (set(string))(optional) +### `wanted_by` This attribute is similar to `stack.wants` but works reversely. That is, using the same hierarchy as above, we could achieve the same result (including `stack-b` whenever we trigger `stack-a-2`) by putting @@ -177,8 +212,5 @@ achieve the same result (including `stack-b` whenever we trigger `stack-a-2`) by ```hcl # stack-b/stack.tm.hcl -stack { - ... - wanted_by = ["/stacks/stack-a-2"] -} +wanted_by = ["/stacks/stack-a-2"] ``` From e21feff1e839908c7ed7f40346dd117b3f6150d2 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Wed, 20 Mar 2024 21:48:24 +0100 Subject: [PATCH 4/7] docs: update run in stacks section --- .../orchestration/run-commands-in-stacks.md | 126 ++++++++---------- 1 file changed, 58 insertions(+), 68 deletions(-) diff --git a/docs/cli/orchestration/run-commands-in-stacks.md b/docs/cli/orchestration/run-commands-in-stacks.md index 226696c3e..a6a15db08 100644 --- a/docs/cli/orchestration/run-commands-in-stacks.md +++ b/docs/cli/orchestration/run-commands-in-stacks.md @@ -1,122 +1,112 @@ --- title: Run Commands in Stacks description: Learn how to orchestrate the execution of commands in stacks with the terramate run command. +outline: [2, 3] --- -# Run Commands in Stacks +# Run any Commands in Stacks Terramate CLI allows you to orchestrate the execution of stacks by running commands in all stacks or filtering stacks using certain criteria. +Terramate is not limited to executing `terraform` inside of stacks but can execute any command available. This includes but is not limited to `terragrunt`, `tofu`, `kubectl`, `helm`, and `make`. + +When running commands in stacks the [defined order of execution](../stacks/configuration#explicit-order-of-execution) is honored and stacks are run in order. + ## Run commands in all stacks Running commands in stacks sequentially can be done with the -[run](../cmdline/run.md) command. +[terramate run](../cmdline/run.md) command. -**Example:** Run commands in all stacks with `terramate run` +**Example:** Run hello world commands in all stacks with `terramate run` ```hcl -terramate run +terramate run echo "hello world" ``` -::: tip -The [`list --run-order`](../cmdline/list.md) command returns a list that describes the order of execution of your stacks. -::: +## Run commands in selected stacks -## Run commands in a subset of stacks using filter +When `terramate run` is executed it will run in all stacks that are reachable from the working directory. -There are three main ways to filter stacks targeted in `terramate run`: -**scope**, **tags** and **change detection**. +The following filters can be used to select a subset of stacks to execute commands in. They can be combined to limit the number of stacks executed in a single run. -### Filter by scope +### Filter by directory subtree -Terramate uses the current directory it is being executed to filter out stacks, -i.e., limit the scope of the execution. So if you execute `terramate` from the -project's root directory, all stacks will be selected and change to inner -directories in the project structure will select only stacks that are children -of the current directory. +It is possible to execute Terramate in a subtree of your repository by either changing the working directory into the subdirectory or by temporarily changing the working directory during execution using the `--chdir ` command line option (short: `-C `). + +```hcl +terramate --chdir path/to/tree -- echo "hello from subtree" +``` -The `-C ` flag can be used to change the scope without having to `cd` to the directory. +### Filter a specific stack -**Example:** Change the scope to `some/dir` +When selecting a specific stack using the `--chdir` command line option the selected stack and all nested stacks will be selected. To only execute the parent stack, using the `--no-recursive` command line option will ensure, that no child stacks will be executed. ```hcl -terramate run -C some/dir -- +terramate --chdir path/to/parent-stack --no-recursive -- echo "hello from stack" ``` ### Filter by tags -Stacks can also be tagged to allow for further targeting. +When [tags are defined on stacks](../stacks/configuration#tags), this information can be used to execute commands in stacks with or without specific tags. ```hcl -stack { - name = "Some Application" - tags = ["kubernetes"] - id = "f2b426b2-f614-4fa5-8f12-af78e5dcc13e" -} +terramate --tags k8s,kubernetes -- echo "hello from k8s stack" +terramate --no-tags k8s,kubernetes -- echo "hello from non k8s stack" ``` -Tags can be used to filter stacks on any command using `--tags` (or `--no-tags` -to exclude). Logical **AND** and **OR** can be achieved with the `:` and `,` operators. +### Filter for changed stacks + +Terramate integrates with various tools to enable [Change Detection](../change-detection/index.md). + +Making use of Change Detection features when running commands can improve run-times on local machines and in automation. -**Example:** Run a command in all stacks tagged with `kubernetes` or `k8s`. +To enable it add the `--changed` command line option. + +**Example:** Execute a command in all stacks that contain changes ```hcl -terramate run --tags kubernetes,k8s -- +terramate run --changed -- echo "hello from changed stack" ``` -### Filter for changed stacks +## Influence the order of execution -The `--changed` flag will filter by stacks that have changed in Git compared to a base ref -using the [Git integration](../change-detection/integrations/git.md) of the -[change detection](../change-detection/index.md). +Terramate honors the explicit and implicit order of execution when running commands. -**Example:** Execute a command in all stacks that contain changes +`terramate list --run-order` or `terramate run --dry-run` can be used to preview the order in which commands will be executed in stacks. + +### Run in parallel + +Stacks that are not affected by a specific order of execution can be executed in parallel. + +Terramate will always guarantee that ordered stacks will still run in order but independent stacks or stacks that have their depending stacks completed can run in parallel. + +By default, Terramate will always execute all stacks in sequence one stack at a time. + +**Example:** Run multiple stacks in parallel ```hcl -terramate run --changed -- +terramate run --parallel 100 -- echo "hello from stack in parallel" ``` -::: info -The default base ref is `origin/main` when working in a feature branch and -`HEAD^` when on main. The base ref can be changed in the project configuration -(or with `-B`), but the defaults allow for the most common workflow where all -changed stacks in a feature branch should be previewed in a PR and applied on merge. +::: warning +It is not possible to run `terraform init` in parallel when provider caching is enabled via `TF_PLUGIN_CACHE_DIR` as terraform does not support this mode of operation at this time. ::: -::: tip -Terramate supports importing code with `import` blocks to allow for code re-use, -and when the source of one of these `import` blocks changes, all stacks where -the code is imported will be marked as changed. -::: +### Reverse the run order -It is possible to monitor files that are outside the stack for changes -using the `watch` property in the configuration of a stack. +The order defined in the configuration of a stack and defined via integrations can be reverted when executing commands in stacks. -**Example:** Watch for changes outside the current stack +**Example:** Execute a command in all stacks but in reverse order ```hcl -stack { - name = "Some Application" - tags = ["kubernetes"] - id = "f2b426b2-f614-4fa5-8f12-af78e5dcc13e" - watch = [ - "/path/to/file", - ] -} - +terramate run --reverse -- echo "hello from stack in reversed order" ``` -### Changing the run scope and order +This is useful when running destructive operations where dependent stacks need to remove their configuration before other stacks. -Sometimes, you want to change the [default order of execution](./index.md#order-of-execution), which can be done -with the [`before`](../stacks/configuration.md#stackbefore-setstringoptional) and -[`after`](../stacks/configuration.md#stackafter-setstringoptional) attributes in the configuration of a stack. -For details, please see the [stacks configuration](../stacks/configuration.md#configuring-the-order-of-execution) documentation. +A very good example here is the destroy operation of Terraform to destroy stacks in opposite order: -By default, Terramate will run against all child stacks selected by the filter -(e.g., all changed stacks with `--changed`). It is possible to add explicit -dependencies for stacks not beneath the current directory by using -[`watch`](../stacks/configuration.md#stackwatch-listoptional), -[`wants`](../stacks/configuration.md#stackwants-setstringoptional) and -[`wanted_by`](../stacks/configuration.md#stackwanted_by-setstringoptional) attributes. +```hcl +terramate run --reverse -- terraform destroy +``` From e307508b5176bf512bf9cc4216d49cae06854c80 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Thu, 21 Mar 2024 16:40:19 +0100 Subject: [PATCH 5/7] docs: add order of execution --- docs/cli/orchestration/order-of-execution.md | 28 ++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/cli/orchestration/order-of-execution.md diff --git a/docs/cli/orchestration/order-of-execution.md b/docs/cli/orchestration/order-of-execution.md new file mode 100644 index 000000000..d6a086e40 --- /dev/null +++ b/docs/cli/orchestration/order-of-execution.md @@ -0,0 +1,28 @@ +--- +title: Order of Execution +description: Define the order stacks are executed in. +outline: [2, 3] +--- + +# Order of Execution + +## Implicit Order of Execution + +implicit order will be detected by Terramate depending on integrations and hierarchy of stacks. + +### Parent and Child Stacks + +Currently Terramate orders stacks implicitly when they are nested. +Nested Stacks are stacks that are in a subdirectory of stack. + +Any level of nesting is supported. + +Parent stacks will be ordered `before` child stacks. + +## Explicit Order of Execution + +In addition to automatical detected order via implicit rules, stacks can be configured to define an explicit order of execution. + +Stacks can be configured to be executed `before` a set of stacks and/or `after` a set of stacks. + +This order can be defined at stack creation time or changed at any point in time. From 8f4369eb4a1116b3b148bc8332fbc9780482e292 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Thu, 21 Mar 2024 17:32:39 +0100 Subject: [PATCH 6/7] docs: remove redundant filter docs from sidebar --- docs/.vitepress/config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 3c73e6931..0f8cdb773 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -216,7 +216,7 @@ export default defineConfig({ { text: 'Integration: Local Files', link: '/cli/change-detection/file-watchers' }, ], }, - { text: 'Filter Stacks', link: '/cli/orchestration/tag-filter' }, + // { text: 'Filter Stacks', link: '/cli/orchestration/tag-filter' }, { text: 'Order of Execution ', link: '/cli/orchestration/order-of-execution' }, { text: 'Configure Runtime ENV', link: '/cli/orchestration/runtime-configuration' }, { text: 'Disable Safeguards', link: '/cli/orchestration/safeguards' }, From ede21738bf3b64ddf442b3cd128b76c3c9349da3 Mon Sep 17 00:00:00 2001 From: Marius Tolzmann Date: Fri, 22 Mar 2024 17:42:50 +0100 Subject: [PATCH 7/7] docs: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sören Martius --- docs/cli/orchestration/order-of-execution.md | 6 +++--- docs/cli/orchestration/run-commands-in-stacks.md | 4 ++-- docs/cli/stacks/configuration.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/cli/orchestration/order-of-execution.md b/docs/cli/orchestration/order-of-execution.md index d6a086e40..a5f673b73 100644 --- a/docs/cli/orchestration/order-of-execution.md +++ b/docs/cli/orchestration/order-of-execution.md @@ -1,6 +1,6 @@ --- title: Order of Execution -description: Define the order stacks are executed in. +description: Learn about the order of execution when orchestration stacks with Terramate. outline: [2, 3] --- @@ -8,12 +8,12 @@ outline: [2, 3] ## Implicit Order of Execution -implicit order will be detected by Terramate depending on integrations and hierarchy of stacks. +Implicit order will be detected by Terramate depending on integrations and hierarchy of stacks. ### Parent and Child Stacks Currently Terramate orders stacks implicitly when they are nested. -Nested Stacks are stacks that are in a subdirectory of stack. +nested stacks are stacks that are in a subdirectory of stack. Any level of nesting is supported. diff --git a/docs/cli/orchestration/run-commands-in-stacks.md b/docs/cli/orchestration/run-commands-in-stacks.md index a6a15db08..546c43dc7 100644 --- a/docs/cli/orchestration/run-commands-in-stacks.md +++ b/docs/cli/orchestration/run-commands-in-stacks.md @@ -90,7 +90,7 @@ terramate run --parallel 100 -- echo "hello from stack in parallel" ``` ::: warning -It is not possible to run `terraform init` in parallel when provider caching is enabled via `TF_PLUGIN_CACHE_DIR` as terraform does not support this mode of operation at this time. +It is not possible to run `terraform init` in parallel when provider caching is enabled via `TF_PLUGIN_CACHE_DIR` as Terraform does not support this mode of operation at this time. ::: ### Reverse the run order @@ -105,7 +105,7 @@ terramate run --reverse -- echo "hello from stack in reversed order" This is useful when running destructive operations where dependent stacks need to remove their configuration before other stacks. -A very good example here is the destroy operation of Terraform to destroy stacks in opposite order: +An example use-case is the destroy operation of Terraform to destroy stacks in opposite order: ```hcl terramate run --reverse -- terraform destroy diff --git a/docs/cli/stacks/configuration.md b/docs/cli/stacks/configuration.md index 76dfe88c0..76fdd9790 100644 --- a/docs/cli/stacks/configuration.md +++ b/docs/cli/stacks/configuration.md @@ -6,7 +6,7 @@ outline: [2, 3] # Configure stacks -Terramate detects stacks based on the exitance of a `stack {}` Block. The name of the file is not important and can be different from `stack.tm.hcl`. There can be exactly one stack block defined in a stack. +Terramate detects stacks based on the existence of a `stack {}` block. The name of the file is not important and can be different from `stack.tm.hcl`. There can be exactly one stack block defined in a stack. - Define Stack Metadata: `name`, `description`, `id`, `tags`. - Set an explicit Order of Execution: `before`, `after`.