From d50aeeef0d85d7f1d094fc01d943bd438f2398fe Mon Sep 17 00:00:00 2001 From: Paul Hinze Date: Mon, 11 Jul 2016 17:37:51 -0500 Subject: [PATCH] website: Docs sweep for lists & maps --- .../source/docs/commands/apply.html.markdown | 14 +- .../source/docs/commands/output.html.markdown | 10 +- .../source/docs/commands/plan.html.markdown | 12 +- .../source/docs/commands/push.html.markdown | 2 +- .../docs/commands/refresh.html.markdown | 14 +- .../environment-variables.html.md | 2 + .../docs/configuration/interpolation.html.md | 15 +- .../source/docs/configuration/modules.html.md | 8 +- .../source/docs/configuration/outputs.html.md | 18 +-- .../docs/configuration/resources.html.md | 3 +- .../source/docs/configuration/syntax.html.md | 57 ++++---- .../docs/configuration/variables.html.md | 136 ++++++++++++------ .../source/docs/internals/debugging.html.md | 4 +- .../source/docs/modules/usage.html.markdown | 44 ++---- .../docker/r/container.html.markdown | 2 +- .../intro/getting-started/variables.html.md | 79 +++++----- 16 files changed, 239 insertions(+), 181 deletions(-) diff --git a/website/source/docs/commands/apply.html.markdown b/website/source/docs/commands/apply.html.markdown index 6f9a35e2f..67626df2b 100644 --- a/website/source/docs/commands/apply.html.markdown +++ b/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 - 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. diff --git a/website/source/docs/commands/output.html.markdown b/website/source/docs/commands/output.html.markdown index b284c79a5..7ddd7546a 100644 --- a/website/source/docs/commands/output.html.markdown +++ b/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 -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 diff --git a/website/source/docs/commands/plan.html.markdown b/website/source/docs/commands/plan.html.markdown index 8100a83f3..df0987312 100644 --- a/website/source/docs/commands/plan.html.markdown +++ b/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 - 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 diff --git a/website/source/docs/commands/push.html.markdown b/website/source/docs/commands/push.html.markdown index 8b2f59907..eacf83488 100644 --- a/website/source/docs/commands/push.html.markdown +++ b/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=` - 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. diff --git a/website/source/docs/commands/refresh.html.markdown b/website/source/docs/commands/refresh.html.markdown index 10db2d7f9..064583437 100644 --- a/website/source/docs/commands/refresh.html.markdown +++ b/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 - 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. diff --git a/website/source/docs/configuration/environment-variables.html.md b/website/source/docs/configuration/environment-variables.html.md index 8182f6907..30e3b421a 100644 --- a/website/source/docs/configuration/environment-variables.html.md +++ b/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). diff --git a/website/source/docs/configuration/interpolation.html.md b/website/source/docs/configuration/interpolation.html.md index 71b9e150b..2d3e42672 100644 --- a/website/source/docs/configuration/interpolation.html.md +++ b/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 -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 + + Simple math can be performed in interpolations: ``` diff --git a/website/source/docs/configuration/modules.html.md b/website/source/docs/configuration/modules.html.md index 0cc47461a..3d94b41d0 100644 --- a/website/source/docs/configuration/modules.html.md +++ b/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 -[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 diff --git a/website/source/docs/configuration/outputs.html.md b/website/source/docs/configuration/outputs.html.md index 762e00fcb..f3bc68e6b 100644 --- a/website/source/docs/configuration/outputs.html.md +++ b/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 - 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 @@ -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 - value = VALUE + sensitive = true + 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. diff --git a/website/source/docs/configuration/resources.html.md b/website/source/docs/configuration/resources.html.md index 07cde03a6..8606ef640 100644 --- a/website/source/docs/configuration/resources.html.md +++ b/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: diff --git a/website/source/docs/configuration/syntax.html.md b/website/source/docs/configuration/syntax.html.md index fee54f875..fc9be1faf 100644 --- a/website/source/docs/configuration/syntax.html.md +++ b/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 -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. + + +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 variable "ami" { - description = "the AMI to use" + description = "the AMI to use" } /* A multi line comment. */ resource "aws_instance" "web" { - ami = "${var.ami}" - count = 2 - source_dest_check = false + ami = "${var.ami}" + count = 2 + source_dest_check = false - connection { - user = "root" - } + connection { + 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, - 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 `< + 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 -variable file (reading left to right) will be the definition used. Put more +**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 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. - - diff --git a/website/source/docs/internals/debugging.html.md b/website/source/docs/internals/debugging.html.md index cd50edf5e..b19000b39 100644 --- a/website/source/docs/internals/debugging.html.md +++ b/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. diff --git a/website/source/docs/modules/usage.html.markdown b/website/source/docs/modules/usage.html.markdown index 8dfb742fb..b36e6d89b 100644 --- a/website/source/docs/modules/usage.html.markdown +++ b/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" - servers = 3 + source = "github.com/hashicorp/consul/terraform/aws" + 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 -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 @@ -132,8 +114,8 @@ For example: ``` resource "aws_instance" "client" { - ami = "ami-408c7f28" - instance_type = "t1.micro" + ami = "ami-408c7f28" + instance_type = "t1.micro" availability_zone = "${module.consul.server_availability_zone}" } ``` diff --git a/website/source/docs/providers/docker/r/container.html.markdown b/website/source/docs/providers/docker/r/container.html.markdown index c4beac8cc..4dbffefd8 100644 --- a/website/source/docs/providers/docker/r/container.html.markdown +++ b/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 diff --git a/website/source/intro/getting-started/variables.html.md b/website/source/intro/getting-started/variables.html.md index 156d39fcc..5c5b86f98 100644 --- a/website/source/intro/getting-started/variables.html.md +++ b/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}" - secret_key = "${var.secret_key}" - region = "${var.region}" + access_key = "${var.access_key}" + secret_key = "${var.secret_key}" + 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. + -## Mappings + +## 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: ``` variable "amis" { - type = "map" - default = { - us-east-1 = "ami-13be557e" - us-west-2 = "ami-06b94666" - } + type = "map" + default = { + us-east-1 = "ami-13be557e" + us-west-2 = "ami-06b94666" + } } ``` -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: ``` resource "aws_instance" "example" { - ami = "${lookup(var.amis, var.region)}" - instance_type = "t2.micro" + ami = "${lookup(var.amis, var.region)}" + 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"]}`. - -## Assigning Mappings + +## 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