diff --git a/website/source/docs/configuration/variables.html.md b/website/source/docs/configuration/variables.html.md index 5fe192472..c306d8577 100644 --- a/website/source/docs/configuration/variables.html.md +++ b/website/source/docs/configuration/variables.html.md @@ -72,8 +72,8 @@ These are the parameters that can be set: ------ -**Default values** can be strings, lists, or maps. If a default is specified, -it must match the declared type of the variable. +**Note**: 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: @@ -162,7 +162,7 @@ $ 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: +For a list variable like so: ``` variable "somelist" { @@ -195,12 +195,12 @@ $ TF_VAR_somemap='{foo = "bar", baz = "qux"}' terraform plan Variables can be collected in files and passed all at once using the -`-var-file=foo.tfvars` flag. +`-var-file=foo.tfvars` flag. If a file named `terraform.tfvars` is present in the current directory, Terraform automatically loads it to populate variables. If the file is named -something else, you can pass the path to the file using the the `-var-file` -flag. +something else, you can pass the path to the file using the `-var-file` +flag. Variables files use HCL or JSON to define variable values. Strings, lists or maps may be set in the same manner as the default value in a `variable` block @@ -219,13 +219,13 @@ somemap = { } ``` -The flag can be used multiple times per command invocation: +The `-var-file` flag can be used multiple times per command invocation: ``` terraform apply -var-file=foo.tfvars -var-file=bar.tfvars ``` -**Note** Variable files are evaluated in the order in which they are specified +**Note**: Variable files are evaluated in the order in which they are specified on the command line. If a variable is defined in more than one variables file, the last value specified is effective. @@ -234,11 +234,13 @@ the last value specified is effective. Both these files have the variable `baz` defined: _foo.tfvars_ + ``` baz = "foo" ``` _bar.tfvars_ + ``` baz = "bar" ``` diff --git a/website/source/intro/getting-started/variables.html.md b/website/source/intro/getting-started/variables.html.md index 5c5b86f98..512e88872 100644 --- a/website/source/intro/getting-started/variables.html.md +++ b/website/source/intro/getting-started/variables.html.md @@ -9,17 +9,19 @@ description: |- # Input Variables You now have enough Terraform knowledge to create useful -configurations, but we're still hardcoding access keys, -AMIs, etc. To become truly shareable and committable to version -control, we need to parameterize the configurations. This page +configurations, but we're still hard-coding access keys, +AMIs, etc. To become truly shareable and version +controlled, we need to parameterize the configurations. This page introduces input variables as a way to do this. ## Defining Variables Let's first extract our access key, secret key, and region into a few variables. Create another file `variables.tf` with -the following contents. Note that the file can be named anything, -since Terraform loads all files ending in `.tf` in a directory. +the following contents. + +**Note**: that the file can be named anything, since Terraform loads all +files ending in `.tf` in a directory. ``` variable "access_key" {} @@ -57,7 +59,9 @@ 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. -**Command-line flags:** You can set it directly on the command-line with the +#### Command-line flags + +You can set variables 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`: @@ -71,24 +75,29 @@ $ terraform plan \ Once again, setting variables this way will not save them, and they'll have to be input repeatedly as commands are executed. -**From a file:** To persist variable values, create -a file and assign variables within this file. Create a file named -"terraform.tfvars" with the following contents: +#### From a file + +To persist variable values, create a file and assign variables within +this file. Create a file named `terraform.tfvars` with the following +contents: ``` access_key = "foo" secret_key = "bar" ``` -If a "terraform.tfvars" file is present in the current directory, +If a `terraform.tfvars` file is present in the current directory, Terraform automatically loads it to populate variables. If the file is named something else, you can use the `-var-file` flag directly to -specify a file. These files are the same syntax as Terraform configuration -files. And like Terraform configuration files, these files can also be JSON. +specify a file. These files are the same syntax as Terraform +configuration files. And like Terraform configuration files, these files +can also be JSON. -**From environment variables:** Terraform will read environment variables -in the form of `TF_VAR_name` to find the value for a variable. For example, -the `TF_VAR_access_key` variable can be set to set the `access_key` variable. +#### From environment variables + +Terraform will read environment variables in the form of `TF_VAR_name` +to find the value for a variable. For example, the `TF_VAR_access_key` +variable can be set to set the `access_key` variable. We don't recommend saving usernames and password to version control, But you can create a local secret variables file and use `-var-file` to load it. @@ -102,30 +111,35 @@ $ 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. +#### UI Input -**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. +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. + +**Note**: 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. ## Maps We've replaced our sensitive strings with variables, but we still -are hardcoding AMIs. Unfortunately, AMIs are specific to the region +are hard-coding 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 _maps_. 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: +support for the `us-west-2` region as well: ``` variable "amis" { @@ -137,11 +151,11 @@ variable "amis" { } ``` -A variable can have a "map" type assigned explicitly, or it can be implicitly +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: +Then, replace the `aws\_instance` with the following: ``` resource "aws_instance" "example" { @@ -170,7 +184,7 @@ $ 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 +**Note**: Even if every key will be assigned as input, the variable must be established as a map by setting its default to `{}`. Here is an example of setting a map's keys from a file. Starting with these