[HPR-763] Update HCL variable documentation (#12058)

* Update HCL variable documentation * Add supported arguments section for variables * Add inpage links to key variable arguments * Reorder content to cluster assignment documentation together * Split variable definitions into two sub-sections Co-authored-by: Lucas Bajolet <[email protected]>
2026-09-25 17:24:00 -04:00 · 2022-10-24 20:58:32 -04:00
parent 7f533a0a63
commit bc55d6d2d6
4 changed files with 70 additions and 35 deletions
@@ -79,33 +79,32 @@ name for the variable, which must be unique among all variables in the same
 build. This name is used to assign a value to the variable from outside and to
 reference the variable's value from within the build.

-The `variable` block can optionally include a `type` argument to specify what
-value types are accepted for the variable, as described in the following
-section.

-The `variable` declaration can also include a `default` argument. If present,
+## Arguments
+
+Packer defines the following arguments for variable declarations:
+
+* [`default`][inpage-default] - A default value which then makes the variable optional.
+* [`type`][inpage-type] - This argument specifies what value types are accepted for the variable.
+* [`description`][inpage-description] - This specifies the input variable's documentation.
+* [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints.
+* [`sensitive`][inpage-sensitive] -  This causes string-values from that variable to be obfuscated from Packer's output.
+
+
+
+### Default values
+
+[inpage-default]: #default-values
+
+The variable declaration can also include a `default` argument. If present,
 the variable is considered to be _optional_ and the default value will be used
-if no value is set when calling the build or running Packer. The `default`
+if no value is set when calling the module or running Terraform. The `default`
 argument requires a literal value and cannot reference other objects in the
 configuration.

-## Using Input Variable Values

-Within the build that declared a variable, its value can be accessed from
-within [expressions](/docs/templates/hcl_templates/expressions) as `var.<NAME>`, where `<NAME>`
-matches the label given in the declaration block:
-
-```hcl
-source "googlecompute" "debian"  {
-    zone = var.gcp_zone
-    tags = var.gcp_debian_tags
-}
-```
-
-The value assigned to a variable can be accessed only from expressions within
-the folder where it was declared.
-
-## Type Constraints
+### Type Constraints
+[inpage-type]: #type-constraints

 The `type` argument in a `variable` block allows you to restrict the [type of
 value](/docs/templates/hcl_templates/expressions#types-and-values) that will be accepted as the value
@@ -146,7 +145,9 @@ variable [from env vars](#environment-variables) or [from the command
 line](#variables-on-the-command-line), the variable will always be interpreted
 as a string.

-## Input Variable Documentation
+### Input Variable Documentation
+
+[inpage-description]: #input-variable-documentation

 Because the input variables of a build are part of its user interface, you can
 briefly describe the purpose of each variable using the optional `description`
@@ -165,12 +166,32 @@ documentation about the build, and so it should be written from the perspective
 of the user of the build rather than its maintainer. For commentary for build
 maintainers, use comments.

+`@include 'from-1.5/variables/custom-validation.mdx'`
+
+`@include 'from-1.5/variables/sensitive.mdx'`
+
+
+## Using Input Variable Values
+
+Within the build that declared a variable, its value can be accessed from
+within [expressions](/docs/templates/hcl_templates/expressions) as `var.<NAME>`, where `<NAME>`
+matches the label given in the declaration block:
+
+```hcl
+source "googlecompute" "debian"  {
+    zone = var.gcp_zone
+    tags = var.gcp_debian_tags
+}
+```
+
+The value assigned to a variable can be accessed only from expressions within
+the folder where it was declared.
+
+
 `@include 'from-1.5/variables/assignment.mdx'`

 The following sections describe these options in more detail.

-`@include 'from-1.5/variables/custom-validation.mdx'`
-
 ### Variables on the Command Line

 To specify individual variables on the command line, use the `-var` option when
@@ -189,11 +210,11 @@ you at least set a default type instead of using empty blocks; this helps the
 HCL parser understand what is being set. Otherwise, the interpreter will assume
 that any variable set on the command line is a string.

-### Variable Definitions (`.pkrvars.hcl` and `.auto.pkrvars.hcl`) Files
+### Standard Variable Definitions Files

 To set lots of variables, it is more convenient to specify their values in a
-_variable definitions file_ (with a filename ending in either `.pkrvars.hcl` or
-`.pkrvars.json`) and then specify that file on the command line with
+_variable definitions file_ with a filename ending in either `.pkrvars.hcl` or
+`.pkrvars.json` and then specify that file on the command line with
 `-var-file`:

 ```shell-session
@@ -201,7 +222,7 @@ $ packer build -var-file="testing.pkrvars.hcl"
 ```

 A variable definitions file uses the same basic syntax as Packer language
-files, but consists only of variable name assignments:
+files, but consists only of variable name and its assigned values:

 ```hcl
 image_id = "ami-abc123"
@@ -211,7 +232,13 @@ availability_zone_names = [
 ]
 ```

-Packer also automatically loads a number of variable definitions files if they
+~> **Important**: Unlike legacy JSON templates the input variables within a variable definitions file must be declared 
+via a variables block within a standard HCL2 template file `*.pkr.hcl` before it can be assigned a value. 
+Failure to do so will result in an unknown variable error during Packer's runtime.
+
+### Auto-loaded Variable Definitions Files
+
+Packer also has the ability automatically load one or more variable definitions files if they
 are present:

 - Any files with names ending in `.auto.pkrvars.hcl` or `.auto.pkrvars.json`.
@@ -226,6 +253,11 @@ with the root object properties corresponding to variable names:
 }
 ```

+~> **Important**: Unlike legacy JSON templates the input variables within a variable definitions file must be declared 
+via a variables block within a standard HCL2 template file `*.pkr.hcl` before it can be assigned a value. 
+Failure to do so will result in an unknown variable error during Packer's runtime.
+
+
 ### Environment Variables

 As a fallback for the other ways of defining variables, Packer searches the
@@ -307,4 +339,3 @@ other variables: the last value found overrides the previous values.
 |     `-var bar=yz` argument     | error, "bar undeclared" |  error, "bar undeclared"  |
 |    `export PKR_VAR_bar=yz`     |            -            |             -             |

-`@include 'from-1.5/variables/sensitive.mdx'`
@@ -1,8 +1,7 @@
-## Assigning Values to build Variables
+## Assigning Values to input Variables

 Once a variable is declared in your configuration, you can set it:

 - Individually, with the `-var foo=bar` command line option.
- In variable definitions (`.pkrvars.hcl` and `.auto.pkrvars.hcl`) files,
-  either specified on the command line or automatically loaded.
+- In variable definitions files, either specified on the command line with the `-var-files values.pkrvars.hcl` or automatically loaded (`*.auto.pkrvars.hcl`).
 - As environment variables, for example: `PKR_VAR_foo=bar`
@@ -1,4 +1,6 @@
-## Custom Validation Rules
+### Custom Validation Rules
+
+[inpage-validation]: #custom-validation-rules

 In addition to Type Constraints, you can specify arbitrary custom validation
 rules for a particular variable using one or more `validation` block nested
@@ -1,4 +1,7 @@
-## A variable can be sensitive
+### Suppressing Sensitive Variables
+
+[inpage-sensitive]: #suppressing-sensitive-variables
+

 When a variable is sensitive all string-values from that variable will be
 obfuscated from Packer's output :