github.com/koding/terraform@v0.6.4-0.20170608090606-5d7e0339779d/website/source/docs/enterprise/runs/variables-and-configuration.html.md (about)

     1  ---
     2  layout: "enterprise"
     3  page_title: "Variables and Configuration - Runs - Terraform Enterprise"
     4  sidebar_current: "docs-enterprise-runs-variables"
     5  description: |-
     6    How to configure runs and their variables.
     7  ---
     8  
     9  # Terraform Variables and Configuration
    10  
    11  There are several ways to configure Terraform runs:
    12  
    13  1. Terraform variables
    14  2. Environment variables
    15  3. Personal Environment and Personal Organization variables
    16  
    17  You can add, edit, and delete all Terraform, Environment, and Personal
    18  Environment variables from the "Variables" page on your environment:
    19  
    20  ![Terraform Enterprise environment variable configuration](docs/tfe-variables.png)
    21  
    22  Personal Organization variables can be managed in your Account Settings under
    23  "Organization Variables":
    24  
    25  ![Terraform Enterprise personal organization variables](docs/tfe-organization-variables.png)
    26  
    27  ## Variable types 
    28  
    29  ### Terraform Variables
    30  
    31  Terraform variables are first-class configuration in Terraform. They define the
    32  parameterization of Terraform configurations and are important for sharing and
    33  removal of sensitive secrets from version control.
    34  
    35  Variables are sent with the `terraform push` command. Any variables in your local
    36  `.tfvars` files are securely uploaded. Once variables are uploaded, Terraform
    37  will prefer the stored variables over any changes you make locally. Please refer
    38  to the [Terraform push documentation](https://www.terraform.io/docs/commands/push.html)
    39  for more information.
    40  
    41  You can also add, edit, and delete variables. To update Terraform variables,
    42  visit the "variables" page on your environment.
    43  
    44  The maximum size for the value of Terraform variables is `256kb`.
    45  
    46  For detailed information about Terraform variables, please read the
    47  [Terraform variables](https://terraform.io/docs/configuration/variables.html)
    48  section of the Terraform documentation.
    49  
    50  ### Environment Variables
    51  
    52  Environment variables are injected into the virtual environment that Terraform
    53  executes in during the `plan` and `apply` phases.
    54  
    55  You can add, edit, and delete environment variables from the "variables" page
    56  on your environment.
    57  
    58  Additionally, the following environment variables are automatically injected by
    59  Terraform Enterprise. All injected environment variables will be prefixed with `ATLAS_`
    60  
    61  - `ATLAS_TOKEN` - This is a unique, per-run token that expires at the end of
    62    run execution (e.g. `"abcd.atlasv1.ghjkl..."`).
    63  
    64  - `ATLAS_RUN_ID` - This is a unique identifier for this run (e.g. `"33"`).
    65  
    66  - `ATLAS_CONFIGURATION_NAME` - This is the name of the configuration used in
    67    this run. Unless you have configured it differently, this will also be the
    68    name of the environment (e.g `"production"`).
    69  
    70  - `ATLAS_CONFIGURATION_SLUG` - This is the full slug of the configuration used
    71    in this run. Unless you have configured it differently, this will also be the
    72    name of the environment (e.g. `"company/production"`).
    73  
    74  - `ATLAS_CONFIGURATION_VERSION` - This is the unique, auto-incrementing version
    75    for the Terraform configuration (e.g. `"34"`).
    76  
    77  - `ATLAS_CONFIGURATION_VERSION_GITHUB_BRANCH` - This is the name of the branch
    78    that the associated Terraform configuration version was ingressed from
    79    (e.g. `master`).
    80  
    81  - `ATLAS_CONFIGURATION_VERSION_GITHUB_COMMIT_SHA` - This is the full commit hash
    82    of the commit that the associated Terraform configuration version was
    83    ingressed from (e.g. `"abcd1234..."`).
    84  
    85  - `ATLAS_CONFIGURATION_VERSION_GITHUB_TAG` - This is the name of the tag
    86    that the associated Terraform configuration version was ingressed from
    87    (e.g. `"v0.1.0"`).
    88  
    89  For any of the `GITHUB_` attributes, the value of the environment variable will
    90  be the empty string (`""`) if the resource is not connected to GitHub or if the
    91  resource was created outside of GitHub (like using `terraform push`).
    92  
    93  ### Personal Environment and Personal Organization Variables
    94  
    95  Personal variables can be created at the Environment or Organization level and
    96  are private and scoped to the user that created them. Personal Environment
    97  variables are scoped to just the environment they are attached to, while Personal
    98  Organization variables are applied across any environment a user triggers a
    99  Terraform run in. Just like shared Environment variables, they are injected into
   100  the virtual environment during the `plan` and `apply` phases.
   101  
   102  Both Personal Environment and Personal Organization variables can be used to
   103  override Environment variables on a per-user basis. 
   104  
   105  ## Variable Hierarchy 
   106  
   107  It is possible to create the same variable in multiple places for more granular
   108  control. Variables are applied in the following order from least to most
   109  precedence:
   110  
   111  1. Environment
   112  2. Personal Organization
   113  3. Personal Environment
   114  
   115  Here's an example: 
   116  
   117  * For the `SlothCorp/petting_zoo` environment, User 1 creates
   118  an Environment variable called `SECRET_GATE_ACCESS_KEY` and sets the value to
   119  `"orange-turtleneck"`
   120  * User 2 adds a Personal Environment variable for 
   121  `SECRET_GATE_ACCESS_KEY` and sets the value to `"pink-overalls"`
   122  * When User 2 submits a `plan` or `apply`, the `SECRET_GATE_ACCESS_KEY`
   123  will use `"pink-overalls"`
   124  * When User 1, or any other user, submits a `plan` or `apply`, the
   125  `SECRET_GATE_ACCESS_KEY` will use `"orange-turtleneck"`
   126  
   127  ## Managing Secret Multi-Line Files
   128  
   129  Terraform Enterprise has the ability to store multi-line files as variables. The
   130  recommended way to manage your secret or sensitive multi-line files (private key,
   131  SSL cert, SSL private key, CA, etc.) is to add them as
   132  [Terraform Variables](#terraform-variables) or
   133  [Environment Variables](#environment-variables).
   134  
   135  Just like secret strings, it is recommended that you never check in these
   136  multi-line secret files to version control by following the below steps.
   137  
   138  Set the [variables](https://www.terraform.io/docs/configuration/variables.html)
   139  in your Terraform template that resources utilizing the secret file will
   140  reference:
   141  
   142  ```hcl
   143  variable "private_key" {}
   144  
   145  resource "aws_instance" "example" {
   146    # ...
   147  
   148    provisioner "remote-exec" {
   149      connection {
   150        host        = "${self.private_ip}"
   151        private_key = "${var.private_key}"
   152      }
   153  
   154      # ...
   155    }
   156  }
   157  ```
   158  
   159  `terraform push` any "Terraform Variables":
   160  
   161      $ terraform push -name $ATLAS_USERNAME/example -var "private_key=$MY_PRIVATE_KEY"
   162  
   163  `terraform push` any "Environment Variables":
   164  
   165      $ TF_VAR_private_key=$MY_PRIVATE_KEY terraform push -name $ATLAS_USERNAME/example
   166  
   167  Alternatively, you can add or update variables manually by going to the
   168  "Variables" section of your Environment and pasting the contents of the file in
   169  as the value.
   170  
   171  Now, any resource that consumes that variable will have access to the variable value, without having to check the file into version control. If you want to run Terraform locally, that file will still need to be passed in as a variable in the CLI. View the [Terraform Variable Documentation](https://www.terraform.io/docs/configuration/variables.html) for more info on how to accomplish this.
   172  
   173  A few things to note...
   174  
   175  The `.tfvars` file does not support multi-line files. You can still use
   176  `.tfvars` to define variables, however, you will not be able to actually set the
   177  variable in `.tfvars` with the multi-line file contents like you would a
   178  variable in a `.tf` file.
   179  
   180  If you are running Terraform locally, you can pass in the variables at the
   181  command line:
   182  
   183      $ terraform apply -var "private_key=$MY_PRIVATE_KEY"
   184      $ TF_VAR_private_key=$MY_PRIVATE_KEY terraform apply
   185  
   186  You can update variables locally by using the `-overwrite` flag with your `terraform push` command:
   187  
   188      $ terraform push -name $ATLAS_USERNAME/example -var "private_key=$MY_PRIVATE_KEY" -overwrite=private_key
   189      $ TF_VAR_private_key=$MY_PRIVATE_KEY terraform push -name $ATLAS_USERNAME/example -overwrite=private_key
   190  
   191  ## Notes on Security
   192  
   193  Terraform variables and environment variables are encrypted using
   194  [Vault](https://vaultproject.io) and closely guarded and audited. If you have
   195  questions or concerns about the safety of your configuration, please contact
   196  our security team at [security@hashicorp.com](mailto:security@hashicorp.com).