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

website: Docs sweep for lists & maps

website/source/docs/commands/apply.html.markdown

@@ -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
+* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
-  flag can be set multiple times.
+  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
+   a [variable file](/docs/configuration/variables.html#variable-files). If
-   loaded first. Any files specified by `-var-file` override any values
+  "terraform.tfvars" is present, it will be automatically loaded first. Any
-   in a "terraform.tfvars". This flag can be used multiple times.
+  files specified by `-var-file` override any values in a "terraform.tfvars".
-
+  This flag can be used multiple times.

website/source/docs/commands/output.html.markdown

@@ -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
+With no additional arguments, `output` will display all the outputs for the root module.
-current directory for the state file to query.
+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
+    a key per output. If `NAME` is specified, only the output specified will be
-    processing.
+    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

website/source/docs/commands/plan.html.markdown

@@ -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
+* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
-  flag can be set multiple times.
+  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
+   a [variable file](/docs/configuration/variables.html#variable-files). If
-   loaded if this flag is not specified. This flag can be used multiple times.
+  "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
 

website/source/docs/commands/push.html.markdown

@@ -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.

website/source/docs/commands/refresh.html.markdown

@@ -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
+* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
-  flag can be set multiple times.
+  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
+   a [variable file](/docs/configuration/variables.html#variable-files). If
-   loaded if this flag is not specified. This flag can be used multiple times.
+  "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.

website/source/docs/configuration/environment-variables.html.md

@@ -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).

website/source/docs/configuration/interpolation.html.md

@@ -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
+Terraform syntax or JSON syntax, you can interpolate other values. These
-into strings. These interpolations are wrapped in `${}`, such as
+interpolations are wrapped in `${}`, such as `${var.foo}`.
-`${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:
 
 ```

website/source/docs/configuration/modules.html.md

@@ -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
+Module configuration maps directly to
-[variables](/docs/configuration/variables.html) within the module, they
+[variables](/docs/configuration/variables.html) within the module, so
-are always simple key and string values. Complex structures are not used
+parameters can have any of the data types that variables support, including
-for modules.
+lists and maps.
 
 ## Syntax
 

website/source/docs/configuration/outputs.html.md

@@ -30,7 +30,7 @@ An output configuration looks like the following:
 
 ```
 output "address" {
-	value = "${aws_instance.web.public_dns}"
+ value = "${aws_instance.web.public_dns}"
 }
 ```
 
@@ -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
+  * `value` (required) - The value of the output. This can be a string, list,
-    be a string. This usually includes an interpolation since outputs
+    or map. This usually includes an interpolation since outputs that are
-    that are static aren't usually useful.
+    static aren't usually useful.
+
+  * `sensitive` (optional, boolean) - See below.
 
 ## Syntax
 
@@ -54,7 +56,7 @@ The full syntax is:
 
 ```
 output NAME {
-	value = VALUE
+  value = VALUE
 }
 ```
 
@@ -65,8 +67,8 @@ Outputs can be marked as containing sensitive material by setting the
 
 ```
 output "sensitive" {
-    sensitive = true
+  sensitive = true
-    value = VALUE 
+  value     = VALUE
 }
 ```
 
@@ -80,4 +82,4 @@ displayed in place of their value.
   state, and available using the `terraform output` command, so cannot be
   relied on as a sole means of protecting values.
 * Sensitivity is not tracked internally, so if the output is interpolated in
-  another module into a resource, the value will be displayed. 
+  another module into a resource, the value will be displayed.

website/source/docs/configuration/resources.html.md

@@ -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:

website/source/docs/configuration/syntax.html.md

@@ -8,32 +8,35 @@ description: |-
 
 # Configuration Syntax
 
-The syntax of Terraform configurations is custom. It is meant to
+<a id="hcl"></a>
-strike a balance between human readable and editable as well as being
+
-machine-friendly. For machine-friendliness, Terraform can also
+The syntax of Terraform configurations is called [HashiCorp Configuration
-read JSON configurations. For general Terraform configurations,
+Language (HCL)](https://github.com/hashicorp/hcl). It is meant to strike a
-however, we recommend using the Terraform syntax.
+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
 variable "ami" {
-	description = "the AMI to use"
+  description = "the AMI to use"
 }
 
 /* A multi
    line comment. */
 resource "aws_instance" "web" {
-	ami = "${var.ami}"
+  ami               = "${var.ami}"
-	count = 2
+  count             = 2
-	source_dest_check = false
+  source_dest_check = false
 
-	connection {
+  connection {
-		user = "root"
+    user = "root"
-	}
+  }
 }
 ```
 
@@ -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,
+    doesn't matter). The value can be any primitive (string,
-    number, or boolean.
+    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
+    is [documented here](/docs/configuration/interpolation.html).
-    [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 `[]`.
+  * Lists of primitive types can be made with square brackets (`[]`).
-    Example: `["foo", "bar", 42]`.
+    Example: `["foo", "bar", "baz"]`.
 
-  * Maps can be made with the `{}` syntax:
+  * Maps can be made with braces (`{}`) and colons (`:`):
-	`{ "foo": "bar", "bar": "baz" }`.
+    `{ "foo": "bar", "bar": "baz" }`. Quotes may be omitted on keys, unless the
-    Quotes may be omitted on keys, unless the key starts with a number,
+    key starts with a number, in which case quotes are required. Commas are
-    in which case quotes are required.
+    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
@@ -85,15 +88,15 @@ these are nearly equivalent:
 
 ```
 variable "ami" {
-	description = "the AMI to use"
+  description = "the AMI to use"
 }
 
 # is equal to:
 
 variable = [{
-	"ami": {
+  "ami": {
-		"description": "the AMI to use",
+    "description": "the AMI to use",
-	}
+  }
 }]
 ```
 

website/source/docs/configuration/variables.html.md

@@ -24,22 +24,26 @@ A variable configuration looks like the following:
 
 ```
 variable "key" {
-    type = "string"
+  type = "string"
 }
 
 variable "images" {
-    type = "map"
+  type = "map"
 
-	default = {
+  default = {
-		us-east-1 = "image-1234"
+    us-east-1 = "image-1234"
-		us-west-2 = "image-4567"
+    us-west-2 = "image-4567"
-	}
+  }
+}
+
+variable "zones" {
+  default = ["us-east-1a", "us-east-1b"]
 }
 ```
 
 ## Description
 
-The `variable`  block configures a single input variable for
+The `variable` block configures a single input variable for
 a Terraform configuration. Multiple variables blocks can be used to
 add multiple variables.
 
@@ -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
+    Valid values are `string`, `list`, and `map`. If this field is omitted, the
-    this parameter did not exist, and the type was inferred from the
+    variable type will be inferred based on the `default`. If no `default` is
-    default value, defaulting to `string` if no default was set. If a
+    provided, the type is assumed to be `string`.
-    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.
 
-  * `default` (optional) - If set, this sets a default value
+  * `default` (optional) - This sets a default value for the variable.
-    for the variable. If this isn't set, the variable is required
+    If no default is provided, the variable is considered required and
-    and Terraform will error if not set. The default value can be
+    Terraform will error if it is not set. The default value can be any of the
-    a string or a mapping. This is covered in more detail below.
+    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,19 +72,16 @@ These are the parameters that can be set:
 
 ------
 
-**Default values** can be either strings or maps, and if specified
+**Default values** can be strings, lists, or maps. If a default is specified,
-must match the declared type of the variable. If no value is supplied
+it must match the declared type of the variable.
-for a variable of type `map`, the values must be supplied in a
-`terraform.tfvars` file - they cannot be input via the console.
 
 String values are simple and represent a basic key to value
 mapping where the key is the variable name. An example is:
 
 ```
 variable "key" {
-    type = "string"
+  type    = "string"
-
+  default = "value"
-	default = "value"
 }
 ```
 
@@ -95,16 +92,24 @@ An example:
 
 ```
 variable "images" {
-    type = "map"
+  type = "map"
-
+  default = {
-	default = {
+    us-east-1 = "image-1234"
-		us-east-1 = "image-1234"
+    us-west-2 = "image-4567"
-		us-west-2 = "image-4567"
+  }
-	}
 }
 ```
 
-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.
 
@@ -114,9 +119,9 @@ The full syntax is:
 
 ```
 variable NAME {
-	[type = TYPE]
+  [type = TYPE]
-	[default = DEFAULT]
+  [default = DEFAULT]
-	[description = DESCRIPTION]
+  [description = DESCRIPTION]
 }
 ```
 
@@ -125,9 +130,14 @@ where `DEFAULT` is:
 ```
 VALUE
 
+[
+  VALUE,
+  ...
+]
+
 {
-	KEY = 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:
@@ -167,8 +219,8 @@ The flag can be used multiple times per command invocation:
 terraform apply -var-file=foo.tfvars -var-file=bar.tfvars
 ```
 
-**Note** If a variable is defined in more than one file passed, the last 
+**Note** If a variable is defined in more than one file passed, the last
-variable file (reading left to right) will be the definition used. Put more 
+variable file (reading left to right) will be the definition used. Put more
 simply, the last time a variable is defined is the one which will be used.
 
 ### Precedence example:
@@ -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.
-
-

website/source/docs/internals/debugging.html.md

@@ -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.
 

website/source/docs/modules/usage.html.markdown

@@ -11,8 +11,8 @@ Using modules in Terraform is very similar to defining resources:
 
 ```
 module "consul" {
-	source = "github.com/hashicorp/consul/terraform/aws"
+  source  = "github.com/hashicorp/consul/terraform/aws"
-	servers = 3
+  servers = 3
 }
 ```
 
@@ -36,12 +36,12 @@ You can instantiate a module multiple times.
 # my_buckets.tf
 module "assets_bucket" {
   source = "./publish_bucket"
-  name = "assets"
+  name   = "assets"
 }
 
 module "media_bucket" {
   source = "./publish_bucket"
-  name = "media"
+  name   = "media"
 }
 ```
 ```
@@ -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`
@@ -71,7 +73,7 @@ The full name of the resulting resources will be `module.assets_bucket.aws_s3_bu
 and `module.assets_bucket.aws_iam_access_key.deploy_user`. So beware, if you
 extract your implementation to a module. The resource names will change and
 this will lead to destroying s3 buckets and creating new ones - so always
-check with `tf plan` before running `tf apply`. 
+check with `tf plan` before running `tf apply`.
 
 ## Source
 
@@ -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
+Additionally, because these map directly to variables, module configuration can
-key/value pairs. Modules can't have complex variable inputs.
+have any data type supported by variables, including maps and lists.
-
-## 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)}"]
-```
 
 ## Outputs
 
@@ -132,8 +114,8 @@ For example:
 
 ```
 resource "aws_instance" "client" {
-  ami = "ami-408c7f28"
+  ami               = "ami-408c7f28"
-  instance_type = "t1.micro"  
+  instance_type     = "t1.micro"
   availability_zone = "${module.consul.server_availability_zone}"
 }
 ```

website/source/docs/providers/docker/r/container.html.markdown

@@ -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

website/source/intro/getting-started/variables.html.md

@@ -25,7 +25,7 @@ since Terraform loads all files ending in `.tf` in a directory.
 variable "access_key" {}
 variable "secret_key" {}
 variable "region" {
-	default = "us-east-1"
+  default = "us-east-1"
 }
 ```
 
@@ -41,9 +41,9 @@ Next, replace the AWS provider configuration with the following:
 
 ```
 provider "aws" {
-	access_key = "${var.access_key}"
+  access_key = "${var.access_key}"
-	secret_key = "${var.secret_key}"
+  secret_key = "${var.secret_key}"
-	region = "${var.region}"
+  region     = "${var.region}"
 }
 ```
 
@@ -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,38 +102,51 @@ $ 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
+Maps 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
+will show this best. Let's extract our AMIs into a map and add
 support for the "us-west-2" region as well:
 
 ```
 variable "amis" {
-    type = "map"
+  type = "map"
-	default = {
+  default = {
-		us-east-1 = "ami-13be557e"
+    us-east-1 = "ami-13be557e"
-		us-west-2 = "ami-06b94666"
+    us-west-2 = "ami-06b94666"
-	}
+  }
 }
 ```
 
-A variable becomes a mapping when it has a type of "map" assigned, or has a
+A variable can have a "map" type assigned explicitly, or it can be implicitly
-default value that is a map like above.
+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:
 
 ```
 resource "aws_instance" "example" {
-	ami = "${lookup(var.amis, var.region)}"
+  ami           = "${lookup(var.amis, var.region)}"
-	instance_type = "t2.micro"
+  instance_type = "t2.micro"
 }
 ```
 
@@ -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>
+<a id="assigning-maps"></a>
-## Assigning Mappings
+## Assigning Maps
 
-We set defaults above, but mappings can also be set using the `-var` and
+We set defaults above, but maps can also be set using the `-var` and
-`-var-file` values. For example, if the user wanted to specify an alternate AMI
+`-var-file` values. For example:
-for us-east-1:
 
 ```
-$ 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 = {
-amis.us-west-2 = "ami-def456"
+  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