website: Explicit examples of -var escaping in various shells

The -var command line option comes with the disadvantage that a user must
contend both with Terraform's own parser and with the parser in whichever
shell they've decided to use, and different shells on different platforms
have different rules.

Previously we've largely just assumed that folks know the appropriate
syntax for the shell they chose, but it seems that command lines involving
spaces and other special characters arise rarely enough in other commands
that Terraform is often the first time someone needs to learn the
appropriate syntax for their shell.

We can't possibly capture all of the details of all shells in our docs,
because that's far outside of our own scope, but hopefully this new
section will go some way to give some real examples that will help folks
figure out how to write suitable escape sequences, if they choose to
set complex variable values on the command line rather than in .tfvars
as we recommend elsewhere on this page.
This commit is contained in:
Martin Atkins 2021-06-21 16:26:21 -07:00
parent 50fe980877
commit a945b379d8
2 changed files with 89 additions and 4 deletions

View File

@ -176,7 +176,9 @@ the previous section, are also available with the same meanings on
* `-var 'NAME=VALUE` - Sets a value for a single * `-var 'NAME=VALUE` - Sets a value for a single
[input variable](/docs/language/values/variables.html) declared in the [input variable](/docs/language/values/variables.html) declared in the
root module of the configuration. Use this option multiple times to set root module of the configuration. Use this option multiple times to set
more than one variable. more than one variable. For more information see
[Input Variables on the Command Line](#input-variables-on-the-command-line),
below.
* `-var-file=FILENAME` - Sets values for potentially many * `-var-file=FILENAME` - Sets values for potentially many
[input variables](/docs/language/values/variables.html) declared in the [input variables](/docs/language/values/variables.html) declared in the
@ -189,6 +191,79 @@ module, aside from the `-var` and `-var-file` options. For more information,
see see
[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables). [Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables).
### Input Variables on the Command Line
You can use the `-var` command line option to specify values for
[input variables](/docs/language/values/variables.html) declared in your
root module.
However, to do so will require writing a command line that is parsable both
by your chosen command line shell _and_ Terraform, which can be complicated
for expressions involving lots of quotes and escape sequences. In most cases
we recommend using the `-var-file` option instead, and write your actual values
in a separate file so that Terraform can parse them directly, rather than
interpreting the result of your shell's parsing.
To use `-var` on a Unix-style shell on a system like Linux or macOS we
recommend writing the option argument in single quotes `'` to ensure the
shell will interpret the value literally:
```
terraform plan -var 'name=value'
```
If your intended value also includes a single quote then you'll still need to
escape that for correct interpretation by your shell, which also requires
temporarily ending the quoted sequence so that the backslash escape character
will be significant:
```
terraform plan -var 'name=va'\''lue'
```
When using Terraform on Windows, we recommend using the Windows Command Prompt
(`cmd.exe`). When you pass a variable value to Terraform from the Windows
Command Prompt, use double quotes `"` around the argument:
```
terraform plan -var "name=value"
```
If your intended value includes literal double quotes then you'll need to
escape those with a backslash:
```
terraform plan -var "name=va\"lue"
```
PowerShell on Windows cannot correctly pass literal quotes to external programs,
so we do not recommend using Terraform with PowerShell when you are on Windows.
Use Windows Command Prompt instead.
The appropriate syntax for writing the variable value is different depending
on the variable's [type constraint](/docs/language/expressions/type-constraints.html).
The primitive types `string`, `number`, and `bool` all expect a direct string
value with no special punctuation except that required by your shell, as
shown in the above examples. For all other type constraints, including list,
map, and set types and the special `any` keyword, you must write a valid
Terraform language expression representing the value, and write any necessary
quoting or escape characters to ensure it will pass through your shell
literally to Terraform. For example, for a `list(string)` type constraint:
```
# Unix-style shell
terraform plan -var 'name=["a", "b", "c"]'
# Windows Command Prompt (do not use PowerShell on Windows)
terraform plan -var "name=[\"a\", \"b\", \"c\"]"
```
Similar constraints apply when setting input variables using environment
variables. For more information on the various methods for setting root module
input variables, see
[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables).
### Resource Targeting ### Resource Targeting
> **Hands-on:** Try the [Target resources](https://learn.hashicorp.com/tutorials/terraform/resource-targeting?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. > **Hands-on:** Try the [Target resources](https://learn.hashicorp.com/tutorials/terraform/resource-targeting?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.

View File

@ -349,7 +349,13 @@ terraform apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_
terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}' terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'
``` ```
The `-var` option can be used any number of times in a single command. The above examples show appropriate syntax for Unix-style shells, such as on
Linux or macOS. For more information on shell quoting, including additional
examples for Windows Command Prompt, see
[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line).
You can use the `-var` option multiple times in a single command to set several
different variables.
<a id="variable-files"></a> <a id="variable-files"></a>
@ -424,10 +430,11 @@ to assign complex-typed values, like lists and maps.
Some special rules apply to the `-var` command line option and to environment Some special rules apply to the `-var` command line option and to environment
variables. For convenience, Terraform defaults to interpreting `-var` and variables. For convenience, Terraform defaults to interpreting `-var` and
environment variable values as literal strings, which do not need to be quoted: environment variable values as literal strings, which need only shell quoting,
and no special quoting for Terraform. For example, in a Unix-style shell:
``` ```
$ export TF_VAR_image_id=ami-abc123 $ export TF_VAR_image_id='ami-abc123'
``` ```
However, if a root module variable uses a [type constraint](#type-constraints) However, if a root module variable uses a [type constraint](#type-constraints)
@ -442,6 +449,9 @@ $ export TF_VAR_availability_zone_names='["us-west-1b","us-west-1d"]'
For readability, and to avoid the need to worry about shell escaping, we For readability, and to avoid the need to worry about shell escaping, we
recommend always setting complex variable values via variable definitions files. recommend always setting complex variable values via variable definitions files.
For more information on quoting and escaping for `-var` arguments,
see
[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line).
### Values for Undeclared Variables ### Values for Undeclared Variables