HashiConf
Join us this September for 3 days of talks, training, product news & more. Book Your Ticket Now

Getting Started - AWS [Updated for 0.12]

Input Variables

You now have enough Terraform knowledge to create useful 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 region into a variable. Create another file variables.tf with the following contents.

variable "region" {
  default = "us-east-1"
}

This defines the region variables within your Terraform configuration. There is a default value, but is optional. Otherwise, If no default is set, the variable is required.

Using Variables in Configuration

Next, replace the AWS provider configuration with the following:

provider "aws" {
  region     = var.region
}

This uses more interpolations, this time prefixed with var.. This tells Terraform that you're accessing variables. This configures the AWS provider with the given variables.

Assigning Variables

There are multiple ways to assign variables. Below is also the order in which variable values are chosen. The following is the descending order of precedence in which variables are considered.

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:

$ terraform apply \
  -var 'region=us-east-2'
# ...

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:

region = "us-east-2"

For all files which match terraform.tfvars or *.auto.tfvars present in the current directory, Terraform automatically loads them 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.

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.

You can use multiple -var-file arguments in a single command, with some checked in to version control and others not checked in. For example:

$ terraform apply \
  -var-file="secret.tfvars" \
  -var-file="production.tfvars"

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_region variable can be set to set the region variable.

UI Input

If you execute terraform apply with certain variables unspecified, Terraform will ask you to input their values interactively. These values are not saved, but this provides a convenient workflow when getting started with Terraform. UI Input is not recommended for everyday use of Terraform.

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.

Lists

Lists are defined either explicitly or implicitly

# implicitly by using brackets [...]
variable "cidrs" { default = [] }

# explicitly
variable "cidrs" { type = list }

You can specify lists in a terraform.tfvars file:

cidrs = [ "10.0.0.0/16", "10.1.0.0/16" ]

Maps

We've replaced our sensitive strings with variables, but we still 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:

variable "amis" {
  type = "map"
  default = {
    "us-east-1" = "ami-b374d5a5"
    "us-west-2" = "ami-4b32be2b"
  }
}

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           = var.amis[var.region]
  instance_type = "t2.micro"
}

The square-bracket index notation used here is an example of how the map type expression is accessed as a variable, with [var.region] referencing the var.amis declaration for dynamic lookup.

Although it is not used in this example, the map type expression can also use a static value lookup directly with var.amis["us-east-1"].

Assigning Maps

We set defaults above, but maps can also be set using the -var and -var-file values. For example:

$ terraform apply -var 'amis={ us-east-1 = "foo", us-west-2 = "bar" }'
# ...

Here is an example of setting a map's keys from a file. Starting with these variable definitions:

variable "region" {}
variable "amis" {
  type = "map"
}

You can specify keys in a terraform.tfvars file:

amis = {
  "us-east-1" = "ami-abc123"
  "us-west-2" = "ami-def456"
}

And access them via resource interpolation:

output "ami" {
  value = aws_instance.example.ami
}

Like so:

$ terraform apply -var region=us-west-2

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

  ami = ami-def456