ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #7851 from hashicorp/d-lists-and-maps 

website: Docs sweep for lists & maps
This commit is contained in:
Paul Hinze 2016-07-28 16:05:40 -05:00 committed by GitHub
parent 9dec28bccf d50aeeef0d
commit 70999b1a64
16 changed files with 239 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
website/source/docs/commands/apply.html.markdown
View File

@ -52,11 +52,13 @@ The command-line flags are all optional. The list of available flags are:
be limited to this resource and its dependencies. This flag can be used
multiple times.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This
flag can be set multiple times.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as
[HCL](/docs/configuration/syntax.html#HCL), so list and map values can be
specified via this flag.
* `-var-file=foo` - Set variables in the Terraform configuration from
a file. If "terraform.tfvars" is present, it will be automatically
loaded first. Any files specified by `-var-file` override any values
in a "terraform.tfvars". This flag can be used multiple times.
a [variable file](/docs/configuration/variables.html#variable-files). If
"terraform.tfvars" is present, it will be automatically loaded first. Any
files specified by `-var-file` override any values in a "terraform.tfvars".
This flag can be used multiple times.

10
website/source/docs/commands/output.html.markdown
View File

@ -13,16 +13,16 @@ an output variable from the state file.
## Usage
Usage: `terraform output [options] NAME`
Usage: `terraform output [options] [NAME]`
By default, `output` requires only a variable name and looks in the
current directory for the state file to query.
With no additional arguments, `output` will display all the outputs for the root module.
If an output `NAME` is specified, only the value of that output is printed.
The command-line flags are all optional. The list of available flags are:
* `-json` - If specified, the outputs are formatted as a JSON object, with
a key per output. This can be piped into tools such as `jq` for further
processing.
a key per output. If `NAME` is specified, only the output specified will be
returned. This can be piped into tools such as `jq` for further processing.
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
* `-module=module_name` - The module path which has needed output.
By default this is the root path. Other modules can be specified by

12
website/source/docs/commands/plan.html.markdown
View File

@ -57,12 +57,16 @@ The command-line flags are all optional. The list of available flags are:
be limited to this resource and its dependencies. This flag can be used
multiple times.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This
flag can be set multiple times.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as
[HCL](/docs/configuration/syntax.html#HCL), so list and map values can be
specified via this flag.
* `-var-file=foo` - Set variables in the Terraform configuration from
a file. If "terraform.tfvars" is present, it will be automatically
loaded if this flag is not specified. This flag can be used multiple times.
a [variable file](/docs/configuration/variables.html#variable-files). If
"terraform.tfvars" is present, it will be automatically loaded first. Any
files specified by `-var-file` override any values in a "terraform.tfvars".
This flag can be used multiple times.
## Security Warning

2
website/source/docs/commands/push.html.markdown
View File

@ -59,7 +59,7 @@ The command-line flags are all optional. The list of available flags are:
send the local value to Atlas. This flag can be repeated multiple times.
* `-token=<token>` - Atlas API token to use to authorize the upload.
If blank or unspecified, the `ATLAS_TOKEN` environmental variable
If blank or unspecified, the `ATLAS_TOKEN` environment variable
will be used.
* `-var='foo=bar'` - Set the value of a variable for the Terraform configuration.

14
website/source/docs/commands/refresh.html.markdown
View File

@ -41,11 +41,13 @@ The command-line flags are all optional. The list of available flags are:
be limited to this resource and its dependencies. This flag can be used
multiple times.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This
flag can be set multiple times.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as
[HCL](/docs/configuration/syntax.html#HCL), so list and map values can be
specified via this flag.
* `-var-file=foo` - Set variables in the Terraform configuration from
a file. If "terraform.tfvars" is present, it will be automatically
loaded if this flag is not specified. This flag can be used multiple times.
a [variable file](/docs/configuration/variables.html#variable-files). If
"terraform.tfvars" is present, it will be automatically loaded first. Any
files specified by `-var-file` override any values in a "terraform.tfvars".
This flag can be used multiple times.

2
website/source/docs/configuration/environment-variables.html.md
View File

@ -59,6 +59,8 @@ Environment variables can be used to set variables. The environment variables mu
```
export TF_VAR_region=us-west-1
export TF_VAR_ami=ami-049d8641
export TF_VAR_alist='[1,2,3]'
export TF_VAR_amap='{ foo = "bar", baz = "qux" }'
```
For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/docs/configuration/variables.html).

15
website/source/docs/configuration/interpolation.html.md
View File

@ -9,14 +9,13 @@ description: |-
# Interpolation Syntax
Embedded within strings in Terraform, whether you're using the
Terraform syntax or JSON syntax, you can interpolate other values
into strings. These interpolations are wrapped in `${}`, such as
`${var.foo}`.
Terraform syntax or JSON syntax, you can interpolate other values. These
interpolations are wrapped in `${}`, such as `${var.foo}`.
The interpolation syntax is powerful and allows you to reference
variables, attributes of resources, call functions, etc.
You can also perform simple math in interpolations, allowing
You can also perform [simple math](#math) in interpolations, allowing
you to write expressions such as `${count.index + 1}`.
You can escape interpolation with double dollar signs: `$${foo}`
@ -26,11 +25,11 @@ will be rendered as a literal `${foo}`.
**To reference user variables**, use the `var.` prefix followed by the
variable name. For example, `${var.foo}` will interpolate the
`foo` variable value. If the variable is a mapping, then you
`foo` variable value. If the variable is a map, then you
can reference static keys in the map with the syntax
`var.MAP.KEY`. For example, `${var.amis.us-east-1}` would
get the value of the `us-east-1` key within the `amis` variable
that is a mapping.
that is a map.
**To reference attributes of your own resource**, the syntax is
`self.ATTRIBUTE`. For example `${self.private_ip_address}` will
@ -177,7 +176,7 @@ The supported built-in functions are:
* `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`.
* `${list()}` returns an empty list.
* `lookup(map, key [, default])` - Performs a dynamic lookup into a mapping
* `lookup(map, key [, default])` - Performs a dynamic lookup into a map
variable. The `map` parameter should be another variable, such
as `var.amis`. If `key` does not exist in `map`, the interpolation will
fail unless you specify a third argument, `default`, which should be a
@ -306,6 +305,8 @@ use in combination with our list of `aws_instance.web` resources.
## Math
<a id="math"></a>
Simple math can be performed in interpolations:
```

8
website/source/docs/configuration/modules.html.md
View File

@ -45,10 +45,10 @@ in the
[module section](/docs/modules/index.html).
Other configuration within the module are dependent on the module itself.
Because module configuration maps directly to
[variables](/docs/configuration/variables.html) within the module, they
are always simple key and string values. Complex structures are not used
for modules.
Module configuration maps directly to
[variables](/docs/configuration/variables.html) within the module, so
parameters can have any of the data types that variables support, including
lists and maps.
## Syntax

8
website/source/docs/configuration/outputs.html.md
View File

@ -44,9 +44,11 @@ the output variable.
Within the block (the `{ }`) is configuration for the output.
These are the parameters that can be set:
* `value` (required, string) - The value of the output. This must
be a string. This usually includes an interpolation since outputs
that are static aren't usually useful.
* `value` (required) - The value of the output. This can be a string, list,
or map. This usually includes an interpolation since outputs that are
static aren't usually useful.
* `sensitive` (optional, boolean) - See below.
## Syntax

3
website/source/docs/configuration/resources.html.md
View File

@ -122,7 +122,8 @@ When declaring multiple instances of a resource using [`count`](#count), it is
common to want each instance to have a different value for a given attribute.
You can use the `${count.index}`
[interpolation](/docs/configuration/interpolation.html) along with a mapping [variable](/docs/configuration/variables.html) to accomplish this.
[interpolation](/docs/configuration/interpolation.html) along with a map
[variable](/docs/configuration/variables.html) to accomplish this.
For example, here's how you could create three [AWS Instances](/docs/providers/aws/r/instance.html) each with their own static IP
address:

35
website/source/docs/configuration/syntax.html.md
View File

@ -8,15 +8,18 @@ description: |-
# Configuration Syntax
The syntax of Terraform configurations is custom. It is meant to
strike a balance between human readable and editable as well as being
machine-friendly. For machine-friendliness, Terraform can also
read JSON configurations. For general Terraform configurations,
however, we recommend using the Terraform syntax.
<a id="hcl"></a>
The syntax of Terraform configurations is called [HashiCorp Configuration
Language (HCL)](https://github.com/hashicorp/hcl). It is meant to strike a
balance between human readable and editable as well as being machine-friendly.
For machine-friendliness, Terraform can also read JSON configurations. For
general Terraform configurations, however, we recommend using the HCL Terraform
syntax.
## Terraform Syntax
Here is an example of Terraform syntax:
Here is an example of Terraform's HCL syntax:
```
# An AMI
@ -44,15 +47,14 @@ Basic bullet point reference:
* Multi-line comments are wrapped with `/*` and `*/`
* Values are assigned with the syntax of `key = value` (whitespace
doesn't matter). The value can be any primitive: a string,
number, or boolean.
doesn't matter). The value can be any primitive (string,
number, boolean), a list, or a map.
* Strings are in double-quotes.
* Strings can interpolate other values using syntax wrapped
in `${}`, such as `${var.foo}`. The full syntax for interpolation
is
[documented here](/docs/configuration/interpolation.html).
is [documented here](/docs/configuration/interpolation.html).
* Multiline strings can use shell-style "here doc" syntax, with
the string starting with a marker like `<<EOF` and then the
@ -70,13 +72,14 @@ Basic bullet point reference:
* Boolean values: `true`, `false`.
* Lists of primitive types can be made by wrapping it in `[]`.
Example: `["foo", "bar", 42]`.
* Lists of primitive types can be made with square brackets (`[]`).
Example: `["foo", "bar", "baz"]`.
* Maps can be made with the `{}` syntax:
`{ "foo": "bar", "bar": "baz" }`.
Quotes may be omitted on keys, unless the key starts with a number,
in which case quotes are required.
* Maps can be made with braces (`{}`) and colons (`:`):
`{ "foo": "bar", "bar": "baz" }`. Quotes may be omitted on keys, unless the
key starts with a number, in which case quotes are required. Commas are
required between key/value pairs for single line maps. A newline between
key/value pairs is sufficient in multi-line maps.
In addition to the basics, the syntax supports hierarchies of sections,
such as the "resource" and "variable" in the example above. These

94
website/source/docs/configuration/variables.html.md
View File

@ -35,6 +35,10 @@ variable "images" {
us-west-2 = "image-4567"
}
}
variable "zones" {
default = ["us-east-1a", "us-east-1b"]
}
```
## Description
@ -51,18 +55,14 @@ Within the block (the `{ }`) is configuration for the variable.
These are the parameters that can be set:
* `type` (optional) - If set this defines the type of the variable.
Valid values are `string` and `map`. In older versions of Terraform
this parameter did not exist, and the type was inferred from the
default value, defaulting to `string` if no default was set. If a
type is not specified, the previous behavior is maintained. It is
recommended to set variable types explicitly in preference to relying
on inferrence - this allows variables of type `map` to be set in the
`terraform.tfvars` file without requiring a default value to be set.
Valid values are `string`, `list`, and `map`. If this field is omitted, the
variable type will be inferred based on the `default`. If no `default` is
provided, the type is assumed to be `string`.
* `default` (optional) - If set, this sets a default value
for the variable. If this isn't set, the variable is required
and Terraform will error if not set. The default value can be
a string or a mapping. This is covered in more detail below.
* `default` (optional) - This sets a default value for the variable.
If no default is provided, the variable is considered required and
Terraform will error if it is not set. The default value can be any of the
data types Terraform supports. This is covered in more detail below.
* `description` (optional) - A human-friendly description for
the variable. This is primarily for documentation for users
@ -72,10 +72,8 @@ These are the parameters that can be set:
------
**Default values** can be either strings or maps, and if specified
must match the declared type of the variable. If no value is supplied
for a variable of type `map`, the values must be supplied in a
`terraform.tfvars` file - they cannot be input via the console.
**Default values** can be strings, lists, or maps. If a default is specified,
it must match the declared type of the variable.
String values are simple and represent a basic key to value
mapping where the key is the variable name. An example is:
@ -83,7 +81,6 @@ mapping where the key is the variable name. An example is:
```
variable "key" {
type = "string"
default = "value"
}
```
@ -96,7 +93,6 @@ An example:
```
variable "images" {
type = "map"
default = {
us-east-1 = "image-1234"
us-west-2 = "image-4567"
@ -104,7 +100,16 @@ variable "images" {
}
```
The usage of maps, strings, etc. is documented fully in the
A list can also be useful to store certain variables. For example:
```
variable "users" {
type = "list"
default = ["admin", "ubuntu"]
}
```
The usage of maps, list, strings, etc. is documented fully in the
[interpolation syntax](/docs/configuration/interpolation.html)
page.
@ -125,6 +130,11 @@ where `DEFAULT` is:
```
VALUE
[
VALUE,
...
]
{
KEY = VALUE
...
@ -147,18 +157,60 @@ The variable can be set via an environment variable:
```
$ TF_VAR_image=foo terraform apply
...
```
Maps and lists can be specified using environment variables as well using
[HCL](/docs/configuration/syntax.html#HCL) syntax in the value.
Given the variable declarations:
```
variable "somelist" {
type = "list"
}
```
The variable could be set like so:
```
$ TF_VAR_somelist='["ami-abc123", "ami-bcd234"]' terraform plan
```
Similarly, for a map declared like:
```
variable "somemap" {
type = "map"
}
```
The value can be set like this:
```
$ TF_VAR_somemap='{foo = "bar", baz = "qux"}' terraform plan
```
## Variable Files
<a id="variable-files"></a>
Variables can be collected in files and passed all at once using the
`-var-file=foo.tfvars` flag. The format for variables in `.tfvars`
files is:
files is [HCL](/docs/configuration/syntax.html#HCL), with top level key/value
pairs:
```
foo = "bar"
xyz = "abc"
somelist = [
"one",
"two",
]
somemap = {
foo = "bar"
bax = "qux"
}
```
The flag can be used multiple times per command invocation:
@ -193,5 +245,3 @@ terraform apply -var-file=foo.tfvars -var-file=bar.tfvars
The result will be that `baz` will contain the value `bar` because `bar.tfvars`
has the last definition loaded.

4
website/source/docs/internals/debugging.html.md
View File

@ -3,12 +3,12 @@ layout: "docs"
page_title: "Debugging"
sidebar_current: "docs-internals-debug"
description: |-
Terraform has detailed logs which can be enabled by setting the TF_LOG environmental variable to any value. This will cause detailed logs to appear on stderr
Terraform has detailed logs which can be enabled by setting the TF_LOG environment variable to any value. This will cause detailed logs to appear on stderr
---
# Debugging Terraform
Terraform has detailed logs which can be enabled by setting the `TF_LOG` environmental variable to any value. This will cause detailed logs to appear on stderr.
Terraform has detailed logs which can be enabled by setting the `TF_LOG` environment variable to any value. This will cause detailed logs to appear on stderr.
You can set `TF_LOG` to one of the log levels `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR` to change the verbosity of the logs. `TRACE` is the most verbose and it is the default if `TF_LOG` is set to something other than a log level name.

30
website/source/docs/modules/usage.html.markdown
View File

@ -50,10 +50,12 @@ module "media_bucket" {
variable "name" {} # this is the input parameter of the module
resource "aws_s3_bucket" "the_bucket" {
...
# ...
}
resource "aws_iam_user" "deploy_user" {
...
# ...
}
```
In this example you can provide module implementation in the `./publish_bucket`
@ -101,28 +103,8 @@ above, map directly to [variables](/docs/configuration/variables.html) within
the module itself. Therefore, you can quickly discover all the configuration
for a module by inspecting the source of it very easily.
Additionally, because these map directly to variables, they're always simple
key/value pairs. Modules can't have complex variable inputs.
## Dealing with parameters of the list type
Variables are currently unable to hold the list type. Sometimes, though, it's
desirable to parameterize a module's resource with an attribute that is of the
list type, for example `aws_instance.security_groups`.
Until a future release broadens the functionality of variables to include list
types, the way to work around this limitation is to pass a delimited string as
a module parameter, and then "unpack" that parameter using
[`split`](/docs/configuration/interpolation.html) interpolation function within
the module definition.
Depending on the resource parameter in question, you may have to
indicate that the unpacked string is actually a list by using list notation.
For example:
```
resource_param = ["${split(",", var.CSV_STRING)}"]
```
Additionally, because these map directly to variables, module configuration can
have any data type supported by variables, including maps and lists.
## Outputs

2
website/source/docs/providers/docker/r/container.html.markdown
View File

@ -48,7 +48,7 @@ The following arguments are supported:
* `dns` - (Optional, set of strings) Set of DNS servers.
* `dns_opts` - (Optional, set of strings) Set of DNS options used by the DNS provider(s), see `resolv.conf` documentation for valid list of options.
* `dns_search` - (Optional, set of strings) Set of DNS search domains that are used when bare unqualified hostnames are used inside of the container.
* `env` - (Optional, set of strings) Environmental variables to set.
* `env` - (Optional, set of strings) Environment variables to set.
* `labels` - (Optional, map of strings) Key/value pairs to set as labels on the
container.
* `links` - (Optional, set of strings) Set of links for link based

57
website/source/intro/getting-started/variables.html.md
View File

@ -57,11 +57,6 @@ There are multiple ways to assign variables. Below is also the order
in which variable values are chosen. If they're found in an option first
below, then the options below are ignored.
**UI Input:** If you execute `terraform plan` or apply without doing
anything, Terraform will ask you to input the variables interactively.
These variables are not saved, but provides a nice user experience for
getting started with Terraform.
**Command-line flags:** You can set it directly on the command-line with the
`-var` flag. Any command in Terraform that inspects the configuration
accepts this flag, such as `apply`, `plan`, and `refresh`:
@ -107,17 +102,29 @@ $ terraform plan \
-var-file="production.tfvars"
```
**UI Input:** If you execute `terraform plan` or apply without doing
anything, Terraform will ask you to input the variables interactively.
These variables are not saved, but provides a nice user experience for
getting started with Terraform. (UI Input is only supported for string
variables - list and map variables must be populated via one of the
other mechanisms.
**Variable Defaults**: If no value is assigned to a variable via any of these
methods and the variable has a `default` key in its declaration, that value
will be used for the variable.
<a id="mappings"></a>
## Mappings
<a id="maps"></a>
## Maps
We've replaced our sensitive strings with variables, but we still
are hardcoding AMIs. Unfortunately, AMIs are specific to the region
that is in use. One option is to just ask the user to input the proper
AMI for the region, but Terraform can do better than that with
_mappings_.
_maps_.
Mappings are a way to create variables that are lookup tables. An example
will show this best. Let's extract our AMIs into a mapping and add
Maps are a way to create variables that are lookup tables. An example
will show this best. Let's extract our AMIs into a map and add
support for the "us-west-2" region as well:
```
@ -130,8 +137,9 @@ variable "amis" {
}
```
A variable becomes a mapping when it has a type of "map" assigned, or has a
default value that is a map like above.
A variable can have a "map" type assigned explicitly, or it can be implicitly
declared as a map by specifying a default value that is a map. The above
demonstrates both.
Then, replace the "aws\_instance" with the following:
@ -148,39 +156,40 @@ key is `var.region`, which specifies that the value of the region
variables is the key.
While we don't use it in our example, it is worth noting that you
can also do a static lookup of a mapping directly with
can also do a static lookup of a map directly with
`${var.amis["us-east-1"]}`.
<a id="assigning-mappings"></a>
## Assigning Mappings
<a id="assigning-maps"></a>
## Assigning Maps
We set defaults above, but mappings can also be set using the `-var` and
`-var-file` values. For example, if the user wanted to specify an alternate AMI
for us-east-1:
We set defaults above, but maps can also be set using the `-var` and
`-var-file` values. For example:
```
$ terraform plan -var 'amis.us-east-1=foo'
$ terraform plan -var 'amis={ us-east-1 = "foo", us-west-2 = "bar" }'
...
```
**Note**: even if every key will be assigned as input, the variable must be
established as a mapping by setting its default to `{}`.
established as a map by setting its default to `{}`.
Here is an example of setting a mapping's keys from a file. Starting with these
Here is an example of setting a map's keys from a file. Starting with these
variable definitions:
```
variable "region" {}
variable "amis" {
default = {}
type = "map"
}
```
You can specify keys in a `terraform.tfvars` file:
```
amis.us-east-1 = "ami-abc123"
amis.us-west-2 = "ami-def456"
amis = {
us-east-1 = "ami-abc123"
us-west-2 = "ami-def456"
}
```
And access them via `lookup()`:
@ -207,7 +216,7 @@ Outputs:
## Next
Terraform provides variables for parameterizing your configurations.
Mappings let you build lookup tables in cases where that makes sense.
Maps let you build lookup tables in cases where that makes sense.
Setting and using variables is uniform throughout your configurations.
In the next section, we'll take a look at