github.com/trawler/terraform@v0.10.8-0.20171106022149-4b1c7a1d9b48/website/docs/configuration/variables.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Configuring Variables"
     4  sidebar_current: "docs-config-variables"
     5  description: |-
     6    Variables define the parameterization of Terraform configurations. Variables can be overridden via the CLI. Variable usage is covered in more detail in the getting started guide. This page covers configuration syntax for variables.
     7  ---
     8  
     9  # Variable Configuration
    10  
    11  Variables define the parameterization of Terraform configurations.
    12  Variables can be overridden via the CLI. Variable usage is
    13  covered in more detail in the
    14  [getting started guide](/intro/getting-started/variables.html).
    15  This page covers configuration syntax for variables.
    16  
    17  This page assumes you're familiar with the
    18  [configuration syntax](/docs/configuration/syntax.html)
    19  already.
    20  
    21  ## Example
    22  
    23  A variable configuration looks like the following:
    24  
    25  ```hcl
    26  variable "key" {
    27    type = "string"
    28  }
    29  
    30  variable "images" {
    31    type = "map"
    32  
    33    default = {
    34      us-east-1 = "image-1234"
    35      us-west-2 = "image-4567"
    36    }
    37  }
    38  
    39  variable "zones" {
    40    default = ["us-east-1a", "us-east-1b"]
    41  }
    42  ```
    43  
    44  ## Description
    45  
    46  The `variable` block configures a single input variable for
    47  a Terraform configuration. Multiple variables blocks can be used to
    48  add multiple variables.
    49  
    50  The `name` given to the variable block is the name used to
    51  set the variable via the CLI as well as reference the variable
    52  throughout the Terraform configuration.
    53  
    54  Within the block (the `{ }`) is configuration for the variable.
    55  These are the parameters that can be set:
    56  
    57  - `type` (optional) - If set this defines the type of the variable. Valid values
    58    are `string`, `list`, and `map`. If this field is omitted, the variable type
    59    will be inferred based on the `default`. If no `default` is provided, the type
    60    is assumed to be `string`.
    61  
    62  - `default` (optional) - This sets a default value for the variable. If no
    63    default is provided, the variable is considered required and Terraform will
    64    error if it is not set. The default value can be any of the data types
    65    Terraform supports. This is covered in more detail below.
    66  
    67  - `description` (optional) - A human-friendly description for the variable. This
    68    is primarily for documentation for users using your Terraform configuration. A
    69    future version of Terraform will expose these descriptions as part of some
    70    Terraform CLI command.
    71  
    72  The name of a variable can be any valid identifier. However, due to the
    73  interpretation of [module configuration blocks](/docs/configuration/modules.html),
    74  the names `source`, `version` and `providers` are reserved for Terraform's own
    75  use and are thus not recommended for any module intended to be used as a
    76  child module.
    77  
    78  -> **Note**: Default values can be strings, lists, or maps. If a default is
    79  specified, it must match the declared type of the variable.
    80  
    81  ### Strings
    82  
    83  String values are simple and represent a basic key to value
    84  mapping where the key is the variable name. An example is:
    85  
    86  ```hcl
    87  variable "key" {
    88    type    = "string"
    89    default = "value"
    90  }
    91  ```
    92  
    93  A multi-line string value can be provided using heredoc syntax.
    94  
    95  ```hcl
    96  variable "long_key" {
    97    type = "string"
    98    default = <<EOF
    99  This is a long key.
   100  Running over several lines.
   101  EOF
   102  }
   103  ```
   104  
   105  ### Maps
   106  
   107  A map allows a key to contain a lookup table. This is useful
   108  for some values that change depending on some external pivot.
   109  A common use case for this is mapping cloud images to regions.
   110  An example:
   111  
   112  ```hcl
   113  variable "images" {
   114    type = "map"
   115    default = {
   116      us-east-1 = "image-1234"
   117      us-west-2 = "image-4567"
   118    }
   119  }
   120  ```
   121  
   122  ### Lists
   123  
   124  A list can also be useful to store certain variables. For example:
   125  
   126  ```hcl
   127  variable "users" {
   128    type    = "list"
   129    default = ["admin", "ubuntu"]
   130  }
   131  ```
   132  
   133  The usage of maps, lists, strings, etc. is documented fully in the
   134  [interpolation syntax](/docs/configuration/interpolation.html)
   135  page.
   136  
   137  ## Syntax
   138  
   139  The full syntax is:
   140  
   141  ```text
   142  variable NAME {
   143    [type = TYPE]
   144    [default = DEFAULT]
   145    [description = DESCRIPTION]
   146  }
   147  ```
   148  
   149  where `DEFAULT` is:
   150  
   151  ```text
   152  VALUE
   153  
   154  [
   155    VALUE,
   156    ...
   157  ]
   158  
   159  {
   160    KEY = VALUE
   161    ...
   162  }
   163  ```
   164  
   165  ### Booleans
   166  
   167  Although it appears Terraform supports boolean types, they are instead
   168  silently converted to string types. The implications of this are subtle and
   169  should be completely understood if you plan on using boolean values.
   170  
   171  It is instead recommended you avoid using boolean values for now and use
   172  explicit strings. A future version of Terraform will properly support booleans
   173  and using the current behavior could result in backwards-incompatibilities in
   174  the future.
   175  
   176  For a configuration such as the following:
   177  
   178  ```hcl
   179  variable "active" {
   180    default = false
   181  }
   182  ```
   183  
   184  The false is converted to a string `"0"` when running Terraform.
   185  
   186  Then, depending on where you specify overrides, the behavior can differ:
   187  
   188  - Variables with boolean values in a `tfvars` file will likewise be converted to
   189    "0" and "1" values.
   190  
   191  - Variables specified via the `-var` command line flag will be literal strings
   192    "true" and "false", so care should be taken to explicitly use "0" or "1".
   193  
   194  - Variables specified with the `TF_VAR_` environment variables will be literal
   195    string values, just like `-var`.
   196  
   197  A future version of Terraform will fully support first-class boolean
   198  types which will make the behavior of booleans consistent as you would
   199  expect. This may break some of the above behavior.
   200  
   201  When passing boolean-like variables as parameters to resource configurations
   202  that expect boolean values, they are converted consistently:
   203  
   204  - "1", "true", "t" all become `true`
   205  - "0", "false", "f" all become `false`
   206  
   207  The behavior of conversion above will likely not change in future
   208  Terraform versions. Therefore, simply using string values rather than
   209  booleans for variables is recommended.
   210  
   211  ## Environment Variables
   212  
   213  Environment variables can be used to set the value of a variable.
   214  The key of the environment variable must be `TF_VAR_name` and the value
   215  is the value of the variable.
   216  
   217  For example, given the configuration below:
   218  
   219  ```hcl
   220  variable "image" {}
   221  ```
   222  
   223  The variable can be set via an environment variable:
   224  
   225  ```shell
   226  $ TF_VAR_image=foo terraform apply
   227  ```
   228  
   229  Maps and lists can be specified using environment variables as well using
   230  [HCL](/docs/configuration/syntax.html#HCL) syntax in the value.
   231  
   232  For a list variable like so:
   233  
   234  ```hcl
   235  variable "somelist" {
   236    type = "list"
   237  }
   238  ```
   239  
   240  The variable could be set like so:
   241  
   242  ```shell
   243  $ TF_VAR_somelist='["ami-abc123", "ami-bcd234"]' terraform plan
   244  ```
   245  
   246  Similarly, for a map declared like:
   247  
   248  ```hcl
   249  variable "somemap" {
   250    type = "map"
   251  }
   252  ```
   253  
   254  The value can be set like this:
   255  
   256  ```shell
   257  $ TF_VAR_somemap='{foo = "bar", baz = "qux"}' terraform plan
   258  ```
   259  
   260  ## Variable Files
   261  
   262  Variables can be collected in files and passed all at once using the
   263  `-var-file=foo.tfvars` flag.
   264  
   265  For all files which match `terraform.tfvars` or `*.auto.tfvars` present in the
   266  current directory, Terraform automatically loads them to populate variables. If
   267  the file is located somewhere else, you can pass the path to the file using the
   268  `-var-file` flag.
   269  
   270  Variables files use HCL or JSON to define variable values. Strings, lists or
   271  maps may be set in the same manner as the default value in a `variable` block
   272  in Terraform configuration. For example:
   273  
   274  ```hcl
   275  foo = "bar"
   276  xyz = "abc"
   277  
   278  somelist = [
   279    "one",
   280    "two",
   281  ]
   282  
   283  somemap = {
   284    foo = "bar"
   285    bax = "qux"
   286  }
   287  ```
   288  
   289  The `-var-file` flag can be used multiple times per command invocation:
   290  
   291  ```shell
   292  $ terraform apply -var-file=foo.tfvars -var-file=bar.tfvars
   293  ```
   294  
   295  -> **Note**: Variable files are evaluated in the order in which they are
   296  specified on the command line. If a variable is defined in more than one
   297  variable file, the last value specified is effective.
   298  
   299  ### Variable Merging
   300  
   301  When variables are conflicting, map values are merged and all other values are
   302  overridden. Map values are always merged.
   303  
   304  For example, if you set a variable twice on the command line:
   305  
   306  ```shell
   307  $ terraform apply -var foo=bar -var foo=baz
   308  ```
   309  
   310  Then the value of `foo` will be `baz` since it was the last value seen.
   311  
   312  However, for maps, the values are merged:
   313  
   314  ```shell
   315  $ terraform apply -var 'foo={quux="bar"}' -var 'foo={bar="baz"}'
   316  ```
   317  
   318  The resulting value of `foo` will be:
   319  
   320  ```shell
   321  {
   322    quux = "bar"
   323    bar = "baz"
   324  }
   325  ```
   326  
   327  There is no way currently to unset map values in Terraform. Whenever a map
   328  is modified either via variable input or being passed into a module, the
   329  values are always merged.
   330  
   331  ### Variable Precedence
   332  
   333  Both these files have the variable `baz` defined:
   334  
   335  _foo.tfvars_
   336  
   337  ```hcl
   338  baz = "foo"
   339  ```
   340  
   341  _bar.tfvars_
   342  
   343  ```hcl
   344  baz = "bar"
   345  ```
   346  
   347  When they are passed in the following order:
   348  
   349  ```shell
   350  $ terraform apply -var-file=foo.tfvars -var-file=bar.tfvars
   351  ```
   352  
   353  The result will be that `baz` will contain the value `bar` because `bar.tfvars`
   354  has the last definition loaded.
   355  
   356  Definitions passed using the `-var-file` flag will always be evaluated after
   357  those in the working directory.