github.com/kcburge/terraform@v0.11.12-beta1/website/docs/configuration/variables.html.md (about)

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