From a4776bfb40a929caaaee1f11fd610e1a9ccef27a Mon Sep 17 00:00:00 2001 From: Nick Fagerlund Date: Tue, 1 Sep 2020 13:28:30 -0700 Subject: [PATCH] website: Clarify `locals` vs. `local.thing` distinction The subtle difference in keywords when creating vs. accessing locals trips people up, even more than the "variable" vs. "var" distinction. It deserves its own subheader on the page, plus a nice noisy callout. --- website/docs/configuration/locals.html.md | 37 ++++++++++++-------- website/docs/configuration/variables.html.md | 12 ++++++- 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/website/docs/configuration/locals.html.md b/website/docs/configuration/locals.html.md index 33452efd1..54502a288 100644 --- a/website/docs/configuration/locals.html.md +++ b/website/docs/configuration/locals.html.md @@ -14,13 +14,15 @@ earlier, see [0.11 Configuration Language: Local Values](../configuration-0-11/locals.html). A local value assigns a name to an [expression](./expressions.html), -allowing it to be used multiple times within a module without repeating +so you can use it multiple times within a module without repeating it. -Comparing modules to functions in a traditional programming language: -if [input variables](./variables.html) are analogous to function arguments and -[outputs values](./outputs.html) are analogous to function return values, then -_local values_ are comparable to a function's local temporary symbols. +If you're familiar with traditional programming languages, it can be useful to +compare Terraform modules to function definitions: + +- [Input variables](./variables.html) are like function arguments. +- [Output values](./outputs.html) are like function return values. +- Local values are like a function's temporary local variables. -> **Note:** For brevity, local values are often referred to as just "locals" when the meaning is clear from context. @@ -37,10 +39,9 @@ locals { } ``` -The expressions assigned to local value names can either be simple constants -like the above, allowing these values to be defined only once but used many -times, or they can be more complex expressions that transform or combine -values from elsewhere in the module: +The expressions in local values are not limited to literal constants; they can +also reference other values in the module in order to transform or combine them, +including variables, resource attributes, or other local values: ```hcl locals { @@ -51,24 +52,32 @@ locals { locals { # Common tags to be assigned to all resources common_tags = { - Service = local.service_name #notice it's "local," no "s." + Service = local.service_name Owner = local.owner } } ``` -As shown above, local values can be referenced from elsewhere in the module -with an expression like `local.common_tags`, and locals can reference -each other in order to build more complex values from simpler ones. +## Using Local Values + +Once a local value is declared, you can reference it in +[expressions](./expressions.html) as `local.`. + +-> **Note:** Local values are _created_ by a `locals` block (plural), but you +_reference_ them as attributes on an object named `local` (singular). Make sure +to leave off the "s" when referencing a local value! ``` resource "aws_instance" "example" { # ... - tags = local.common_tags #notice it's "local," no "s." + tags = local.common_tags } ``` +A local value can only be accessed in expressions within the module where it +was declared. + ## When To Use Local Values Local values can be helpful to avoid repeating the same values or expressions diff --git a/website/docs/configuration/variables.html.md b/website/docs/configuration/variables.html.md index 1632c6e70..294995a76 100644 --- a/website/docs/configuration/variables.html.md +++ b/website/docs/configuration/variables.html.md @@ -22,6 +22,13 @@ set their values using CLI options and environment variables. When you declare them in [child modules](./modules.html), the calling module should pass values in the `module` block. +If you're familiar with traditional programming languages, it can be useful to +compare Terraform modules to function definitions: + +- Input variables are like function arguments. +- [Output values](./outputs.html) are like function return values. +- [Local values](./locals.html) are like a function's temporary local variables. + Input variable usage is introduced in the Getting Started guide section [_Input Variables_](https://learn.hashicorp.com/terraform/getting-started/variables). @@ -100,6 +107,9 @@ Within the module that declared a variable, its value can be accessed from within [expressions](./expressions.html) as `var.`, where `` matches the label given in the declaration block: +-> **Note:** Local values are _created_ by a `variable` block, but you +_reference_ them as attributes on an object named `var`. + ```hcl resource "aws_instance" "example" { instance_type = "t2.micro" @@ -107,7 +117,7 @@ resource "aws_instance" "example" { } ``` -The value assigned to a variable can be accessed only from expressions within +The value assigned to a variable can only be accessed in expressions within the module where it was declared. ## Type Constraints