From bc55d6d2d6ed01558b4c7cc3fd4912ca08e80249 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Mon, 24 Oct 2022 20:58:32 -0400 Subject: [PATCH] [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 <105649352+lbajolet-hashicorp@users.noreply.github.com> --- .../templates/hcl_templates/variables.mdx | 91 +++++++++++++------ .../from-1.5/variables/assignment.mdx | 5 +- .../from-1.5/variables/custom-validation.mdx | 4 +- .../partials/from-1.5/variables/sensitive.mdx | 5 +- 4 files changed, 70 insertions(+), 35 deletions(-) diff --git a/website/content/docs/templates/hcl_templates/variables.mdx b/website/content/docs/templates/hcl_templates/variables.mdx index 9acfab62c..5f465b8d7 100644 --- a/website/content/docs/templates/hcl_templates/variables.mdx +++ b/website/content/docs/templates/hcl_templates/variables.mdx @@ -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, -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` -argument requires a literal value and cannot reference other objects in the -configuration. +## Arguments -## Using Input Variable Values +Packer defines the following arguments for variable declarations: -Within the build that declared a variable, its value can be accessed from -within [expressions](/docs/templates/hcl_templates/expressions) as `var.`, where `` -matches the label given in the declaration block: +* [`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. -```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 +### 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 module or running Terraform. The `default` +argument requires a literal value and cannot reference other objects in the +configuration. + + +### 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.`, where `` +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'` diff --git a/website/content/partials/from-1.5/variables/assignment.mdx b/website/content/partials/from-1.5/variables/assignment.mdx index 0ddd243c5..737508a99 100644 --- a/website/content/partials/from-1.5/variables/assignment.mdx +++ b/website/content/partials/from-1.5/variables/assignment.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` diff --git a/website/content/partials/from-1.5/variables/custom-validation.mdx b/website/content/partials/from-1.5/variables/custom-validation.mdx index 7bf8146bd..c875a28d4 100644 --- a/website/content/partials/from-1.5/variables/custom-validation.mdx +++ b/website/content/partials/from-1.5/variables/custom-validation.mdx @@ -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 diff --git a/website/content/partials/from-1.5/variables/sensitive.mdx b/website/content/partials/from-1.5/variables/sensitive.mdx index bc5ec3066..5e53f4c85 100644 --- a/website/content/partials/from-1.5/variables/sensitive.mdx +++ b/website/content/partials/from-1.5/variables/sensitive.mdx @@ -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 :