From 485e0807258aae7328ba95036037a3d29e54dd97 Mon Sep 17 00:00:00 2001 From: Alan Szlosek Jr Date: Wed, 12 Apr 2023 18:05:29 -0400 Subject: [PATCH] clarify local and input variables (#12334) * clarify local and input variables * Apply suggestions from code review Co-authored-by: Rose M Koron <32436232+rkoron007@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Rose M Koron <32436232+rkoron007@users.noreply.github.com> Co-authored-by: Wilken Rivera * Apply suggestions from code review Co-authored-by: Wilken Rivera --------- Co-authored-by: Rose M Koron <32436232+rkoron007@users.noreply.github.com> Co-authored-by: Wilken Rivera --- .../docs/templates/hcl_templates/locals.mdx | 29 +++++++++---------- .../templates/hcl_templates/variables.mdx | 10 +++---- 2 files changed, 18 insertions(+), 21 deletions(-) diff --git a/website/content/docs/templates/hcl_templates/locals.mdx b/website/content/docs/templates/hcl_templates/locals.mdx index 21f6914b4..456f6af90 100644 --- a/website/content/docs/templates/hcl_templates/locals.mdx +++ b/website/content/docs/templates/hcl_templates/locals.mdx @@ -1,35 +1,34 @@ --- -page_title: Local Values - HCL Configuration Language +page_title: Local Variables - HCL Configuration Language description: >- - Local values assign a name to an expression that can then be used multiple + Local variables assign a name to an expression that you can use multiple times within a folder. --- -# Local Values +# Local Variables `@include 'from-1.5/beta-hcl2-note.mdx'` There are two kinds of variables in HCL Packer templates: Input variables, sometimes simply called "variables", and Local variables, also known as -"locals". Input variables may have defaults, but those defaults can -be overridden from the command line or special variable files. Local variables -can be thought of as constants, and are not able to be overridden at runtime. +"locals". Input variables may have defaults, but those defaults can be +overridden using command line options, environment variables, or variable +definitions files. Local variables can not be overridden. This page is about local variables. To learn about input variables, see the [input variables](/packer/docs/templates/hcl_templates/variables) page. -Local values assign a name to an expression, that can then be used multiple -times within a folder. - -If [variables](/packer/docs/templates/hcl_templates/variables) are analogous to function arguments then -_local values_ are comparable to a function's local variables. +Local variables assign a name to an expression, which you can use multiple +times within a folder. The expression is evaluated at run time, and can +reference input variables, other local variables, data sources, and HCL +functions. Input variable and local variable usage are introduced in the [_Variables Guide_](/packer/guides/hcl/variables). ## Examples -Local values are defined in `local` or `locals` blocks: +Local variables are defined in a `local` or `locals` block: ```hcl # Using the local block allows you to mark locals as sensitive, which will @@ -51,7 +50,7 @@ locals { name_prefix = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}" } -# Local values can be interpolated elsewhere using the "local." prefix. +# Local variables can be referenced using the "local." prefix. source "virtualbox-iso" "example" { output = "${local.name_prefix}-files" # ... @@ -120,10 +119,10 @@ The expression of a local value can refer to other locals, but reference cycles are not allowed. That is, a local cannot refer to itself or to a variable that refers (directly or indirectly) back to it. -It's recommended to group together logically-related local values into a single +It's recommended to group together logically-related local variables into a single block, particularly if they depend on each other. This will help the reader understand the relationships between variables. Conversely, prefer to define -_unrelated_ local values in _separate_ blocks, and consider annotating each +_unrelated_ local variables in _separate_ blocks, and consider annotating each block with a comment describing any context common to all of the enclosed locals. diff --git a/website/content/docs/templates/hcl_templates/variables.mdx b/website/content/docs/templates/hcl_templates/variables.mdx index 43b2a7db1..4c8f856fa 100644 --- a/website/content/docs/templates/hcl_templates/variables.mdx +++ b/website/content/docs/templates/hcl_templates/variables.mdx @@ -11,9 +11,10 @@ description: |- There are two kinds of variables in HCL Packer templates: Input variables, sometimes simply called "variables", and Local variables, also known as -"locals". Input variables may have defaults, but those defaults can -be overridden from the command line or special variable files. Local variables -can be thought of as constants, and are not able to be overridden at runtime. +"locals". Input variables may have defaults, but those defaults can be +overridden using command line options, environment variables, or variable +definitions files. However, nothing can change the value of an input variable +after the initial override. This page is about input variables. To learn about local variables, see the [locals](/packer/docs/templates/hcl_templates/locals) page. @@ -21,9 +22,6 @@ This page is about input variables. To learn about local variables, see the Input variables serve as parameters for a Packer build, allowing aspects of the build to be customized without altering the build's own source code. -When you declare variables in the build of your configuration, you can set -their values using CLI options and environment variables. - Input variable and local variable usage are introduced in the [_Variables Guide_](/packer/guides/hcl/variables).