From da15b8545150da5fbcc96e6cb898184dcebf2624 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Wed, 14 Oct 2020 13:35:21 -0700 Subject: [PATCH 1/2] more updates --- website/pages/docs/from-1.5/variables.mdx | 79 +++---------------- .../from-1.5/variables/assignment.mdx | 4 +- .../from-1.5/variables/must-be-set.mdx | 1 + 3 files changed, 13 insertions(+), 71 deletions(-) diff --git a/website/pages/docs/from-1.5/variables.mdx b/website/pages/docs/from-1.5/variables.mdx index 1cd2eb260..b22792667 100644 --- a/website/pages/docs/from-1.5/variables.mdx +++ b/website/pages/docs/from-1.5/variables.mdx @@ -177,71 +177,10 @@ The `-var` option can be used any number of times in a single command. If you plan to assign variables via the command line, we strongly recommend that you at least set a default type instead of using empty blocks; this helps the -HCL parser understand what is being set. +HCL parser understand what is being set. Otherwise, the interpreter will assume +that any variable set on the command line is a string. -For example: - -```hcl -variable "pizza" { - type = string -} -source "null" "example" { - communicator = "none" -} -build { - sources = [ - "source.null.example" - ] - provisioner "shell-local" { - inline = ["echo $PIZZA"] - environment_vars = ["PIZZA=${var.pizza}"] - } -} -``` - -If you call the above template using the command - -```sh -packer build -var pizza=pineapple shell_local_variables.pkr.hcl -``` - -then the Packer build will run successfully. However, if you define the variable -using an empty block, the parser will not know what type the variable is, and it -cannot infer the type from the command line, as shown in this example: - -```hcl -variable "pizza" {} -source "null" "example" { - communicator = "none" -} -build { - sources = [ - "source.null.example" - ] - provisioner "shell-local" { - inline = ["echo $PIZZA"] - environment_vars = ["PIZZA=${var.pizza}"] - } -} -``` -The above template will result in the error: - -``` -Error: Variables not allowed - on line 1: - (source code not available) -Variables may not be used here. -``` - -You can work around this either by quoting the variable on the command line, or -by adding the type to the variable block as shown in the previous example. -Setting the expected type is the more resilient option. - -```sh -packer build -var 'pizza="pineapple"' shell_local_variables.pkr.hcl -``` - -### Variable Definitions (`.pkrvars.hcl`) Files +### Variable Definitions (`.pkrvars.hcl` and `.auto.pkrvars.hcl`) 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 @@ -330,18 +269,20 @@ files. ### Variable Definition Precedence The above mechanisms for setting variables can be used together in any -combination. If the same variable is assigned multiple values, Packer uses the -_last_ value it finds, overriding any previous values. Note that the same -variable cannot be assigned multiple values within a single source. +combination. Packer loads variables in the following order, with later sources taking precedence over earlier ones: -- Environment variables +- Environment variables (lowest priority) - Any `*.auto.pkrvars.hcl` or `*.auto.pkrvars.json` files, processed in lexical order of their filenames. - Any `-var` and `-var-file` options on the command line, in the order they are - provided. + provided. (highest priority) + +If the same variable is assigned multiple values using different mechanisms, +Packer uses the _last_ value it finds, overriding any previous values. Note +that the same variable cannot be assigned multiple values within a single source. ~> **Important:** Variables with map and object values behave the same way as other variables: the last value found overrides the previous values. diff --git a/website/pages/partials/from-1.5/variables/assignment.mdx b/website/pages/partials/from-1.5/variables/assignment.mdx index 49bdcf9a2..0ddd243c5 100644 --- a/website/pages/partials/from-1.5/variables/assignment.mdx +++ b/website/pages/partials/from-1.5/variables/assignment.mdx @@ -3,6 +3,6 @@ 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`) files, either specified on the - command line or automatically loaded. +- In variable definitions (`.pkrvars.hcl` and `.auto.pkrvars.hcl`) files, + either specified on the command line or automatically loaded. - As environment variables, for example: `PKR_VAR_foo=bar` diff --git a/website/pages/partials/from-1.5/variables/must-be-set.mdx b/website/pages/partials/from-1.5/variables/must-be-set.mdx index 9ae63bc01..ecf887360 100644 --- a/website/pages/partials/from-1.5/variables/must-be-set.mdx +++ b/website/pages/partials/from-1.5/variables/must-be-set.mdx @@ -5,6 +5,7 @@ Take the following variable for example: ```hcl variable "foo" { type = string +} ``` Here `foo` must have a known value but you can default it to `null` to make From 06efa61c13526790d275ab8340552141a460611a Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Wed, 14 Oct 2020 15:56:58 -0700 Subject: [PATCH 2/2] a tiny bit more cleanup --- website/pages/docs/from-1.5/expressions.mdx | 7 +++---- website/pages/docs/from-1.5/syntax-json.mdx | 7 ++++++- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/website/pages/docs/from-1.5/expressions.mdx b/website/pages/docs/from-1.5/expressions.mdx index 6cb8b260c..245237b4b 100644 --- a/website/pages/docs/from-1.5/expressions.mdx +++ b/website/pages/docs/from-1.5/expressions.mdx @@ -65,10 +65,9 @@ Whenever the distinction isn't relevant, the Packer documentation uses each pair of terms interchangeably (with a historical preference for "list" and "map"). -However, module authors and provider developers should understand the -differences between these similar types (and the related `set` type), since they -offer different ways to restrict the allowed values for input variables and -source arguments. +However, plugin authors should understand the differences between these similar +types (and the related `set` type), since they offer different ways to restrict +the allowed values for input variables and source arguments. ### Type Conversion diff --git a/website/pages/docs/from-1.5/syntax-json.mdx b/website/pages/docs/from-1.5/syntax-json.mdx index 59b6e9e39..42063c5b4 100644 --- a/website/pages/docs/from-1.5/syntax-json.mdx +++ b/website/pages/docs/from-1.5/syntax-json.mdx @@ -20,13 +20,18 @@ syntax is useful when generating portions of a configuration programmatically, since existing JSON libraries can be used to prepare the generated configuration files. +This syntax is not to be confused with the pre-version-1.5 "legacy" Packer +templates, which were exclusively JSON and follow a different format. + The JSON syntax is defined in terms of the native syntax. Everything that can be expressed in native syntax can also be expressed in JSON syntax, but some constructs are more complex to represent in JSON due to limitations of the JSON grammar. Packer expects native syntax for files named with a `.pkr.hcl` suffix, and JSON -syntax for files named with a `.pkr.json` suffix. +syntax for files named with a `.pkr.json` suffix. If you leave out the `.pkr` +portion of suffix, Packer will try to read your json file as a legacy Packer +template. The low-level JSON syntax, just as with the native syntax, is defined in terms of a specification called _HCL_. It is not necessary to know all of the details