diff --git a/docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx b/docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx index e646c84d91..e6516b99d4 100644 --- a/docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx +++ b/docs-starlight/src/content/docs/01-getting-started/01-quick-start.mdx @@ -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: + + - 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. + + 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. + + 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: + + ```hcl + variable "content" {} + variable "output_dir" {} + + resource "local_file" "file" { + content = var.content + filename = "${var.output_dir}/hi.txt" + } + ``` + + Then in your `foo/terragrunt.hcl` and `bar/terragrunt.hcl` files, you can use the `get_terragrunt_dir()` built-in function to get the directory where the `terragrunt.hcl` file is located: + + ```hcl + terraform { + source = "../shared" + } + + inputs = { + output_dir = get_terragrunt_dir() + content = "Hello from bar, Terragrunt!" + } + ``` + Similar to the `tofu` CLI, there is a prompt to confirm that you are sure you want to run the command in each unit when performing a command that's potentially destructive. You can skip this prompt by using the `--non-interactive` flag, just as you would with `-auto-approve` in OpenTofu. ```bash diff --git a/docs/_docs/01_getting-started/01-quick-start.md b/docs/_docs/01_getting-started/01-quick-start.md index 3f86a3dace..6107c343c9 100644 --- a/docs/_docs/01_getting-started/01-quick-start.md +++ b/docs/_docs/01_getting-started/01-quick-start.md @@ -306,6 +306,42 @@ Are you sure you want to run 'terragrunt apply' in each folder of the stack desc 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: + +- 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. + +The `.terragrunt-cache` directory is typically added to `.gitignore` files, similar to the `.terraform` directory that OpenTofu generates. + +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: + +```hcl +variable "content" {} +variable "output_dir" {} + +resource "local_file" "file" { + content = var.content + filename = "${var.output_dir}/hi.txt" +} +``` + +Then in your `foo/terragrunt.hcl` and `bar/terragrunt.hcl` files, you can use the `get_terragrunt_dir()` built-in function to get the directory where the `terragrunt.hcl` file is located: + +```hcl +terraform { + source = "../shared" +} + +inputs = { + output_dir = get_terragrunt_dir() + content = "Hello from bar, Terragrunt!" +} +``` + Similar to the `tofu` CLI, there is a prompt to confirm that you are sure you want to run the command in each unit when performing a command that's potentially destructive. You can skip this prompt by using the `--non-interactive` flag, just as you would with `-auto-approve` in OpenTofu. ```bash diff --git a/test/fixtures/docs/01-quick-start/step-05.1/.gitignore b/test/fixtures/docs/01-quick-start/step-05.1/.gitignore new file mode 100644 index 0000000000..2ffc55046a --- /dev/null +++ b/test/fixtures/docs/01-quick-start/step-05.1/.gitignore @@ -0,0 +1,2 @@ +.terragrunt-cache +hi.txt \ No newline at end of file diff --git a/test/fixtures/docs/01-quick-start/step-05.1/README.md b/test/fixtures/docs/01-quick-start/step-05.1/README.md new file mode 100644 index 0000000000..f3c6669da9 --- /dev/null +++ b/test/fixtures/docs/01-quick-start/step-05.1/README.md @@ -0,0 +1,3 @@ +This example demonstrates how to control output file locations using get_terragrunt_dir(). + +The hi.txt files will be created directly in the foo and bar directories instead of the .terragrunt-cache directory. \ No newline at end of file diff --git a/test/fixtures/docs/01-quick-start/step-05.1/bar/terragrunt.hcl b/test/fixtures/docs/01-quick-start/step-05.1/bar/terragrunt.hcl new file mode 100644 index 0000000000..0956eed4d3 --- /dev/null +++ b/test/fixtures/docs/01-quick-start/step-05.1/bar/terragrunt.hcl @@ -0,0 +1,8 @@ +terraform { + source = "../shared" +} + +inputs = { + output_dir = get_terragrunt_dir() + content = "Hello from bar, Terragrunt!" +} \ No newline at end of file diff --git a/test/fixtures/docs/01-quick-start/step-05.1/foo/terragrunt.hcl b/test/fixtures/docs/01-quick-start/step-05.1/foo/terragrunt.hcl new file mode 100644 index 0000000000..6db28e740f --- /dev/null +++ b/test/fixtures/docs/01-quick-start/step-05.1/foo/terragrunt.hcl @@ -0,0 +1,8 @@ +terraform { + source = "../shared" +} + +inputs = { + output_dir = get_terragrunt_dir() + content = "Hello from foo, Terragrunt!" +} \ No newline at end of file diff --git a/test/fixtures/docs/01-quick-start/step-05.1/shared/main.tf b/test/fixtures/docs/01-quick-start/step-05.1/shared/main.tf new file mode 100644 index 0000000000..bb1ea59819 --- /dev/null +++ b/test/fixtures/docs/01-quick-start/step-05.1/shared/main.tf @@ -0,0 +1,7 @@ +variable "content" {} +variable "output_dir" {} + +resource "local_file" "file" { + content = var.content + filename = "${var.output_dir}/hi.txt" +} \ No newline at end of file