github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/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 two ways to configure Terraform runs – with Terraform variables or
    12  environment variables.
    13  
    14  ## Terraform Variables
    15  
    16  Terraform variables are first-class configuration in Terraform. They define the
    17  parameterization of Terraform configurations and are important for sharing and
    18  removal of sensitive secrets from version control.
    19  
    20  Variables are sent with the `terraform push` command. Any variables in your local
    21  `.tfvars` files are securely uploaded. Once variables are uploaded, Terraform will prefer the stored variables over any changes you
    22  make locally. Please refer to the
    23  [Terraform push documentation](https://www.terraform.io/docs/commands/push.html)
    24  for more information.
    25  
    26  You can also add, edit, and delete variables. To update Terraform variables,
    27  visit the "variables" page on your environment.
    28  
    29  The maximum size for the value of Terraform variables is `256kb`.
    30  
    31  For detailed information about Terraform variables, please read the
    32  [Terraform variables](https://terraform.io/docs/configuration/variables.html)
    33  section of the Terraform documentation.
    34  
    35  ## Environment Variables
    36  
    37  Environment variables are injected into the virtual environment that Terraform
    38  executes in during the `plan` and `apply` phases.
    39  
    40  You can add, edit, and delete environment variables from the "variables" page
    41  on your environment.
    42  
    43  Additionally, the following environment variables are automatically injected by
    44  Terraform Enterprise. All injected environment variables will be prefixed with `ATLAS_`
    45  
    46  - `ATLAS_TOKEN` - This is a unique, per-run token that expires at the end of
    47    run execution (e.g. `"abcd.atlasv1.ghjkl..."`).
    48  
    49  - `ATLAS_RUN_ID` - This is a unique identifier for this run (e.g. `"33"`).
    50  
    51  - `ATLAS_CONFIGURATION_NAME` - This is the name of the configuration used in
    52    this run. Unless you have configured it differently, this will also be the
    53    name of the environment (e.g `"production"`).
    54  
    55  - `ATLAS_CONFIGURATION_SLUG` - This is the full slug of the configuration used
    56    in this run. Unless you have configured it differently, this will also be the
    57    name of the environment (e.g. `"company/production"`).
    58  
    59  - `ATLAS_CONFIGURATION_VERSION` - This is the unique, auto-incrementing version
    60    for the Terraform configuration (e.g. `"34"`).
    61  
    62  - `ATLAS_CONFIGURATION_VERSION_GITHUB_BRANCH` - This is the name of the branch
    63    that the associated Terraform configuration version was ingressed from
    64    (e.g. `master`).
    65  
    66  - `ATLAS_CONFIGURATION_VERSION_GITHUB_COMMIT_SHA` - This is the full commit hash
    67    of the commit that the associated Terraform configuration version was
    68    ingressed from (e.g. `"abcd1234..."`).
    69  
    70  - `ATLAS_CONFIGURATION_VERSION_GITHUB_TAG` - This is the name of the tag
    71    that the associated Terraform configuration version was ingressed from
    72    (e.g. `"v0.1.0"`).
    73  
    74  For any of the `GITHUB_` attributes, the value of the environment variable will
    75  be the empty string (`""`) if the resource is not connected to GitHub or if the
    76  resource was created outside of GitHub (like using `terraform push`).
    77  
    78  ## Managing Secret Multi-Line Files
    79  
    80  Terraform Enterprise has the ability to store multi-line files as variables. The recommended way to manage your secret/sensitive multi-line files (private key, SSL cert, SSL private key, CA, etc.) is to add them as [Terraform Variables](#terraform-variables) or [Environment Variables](#environment-variables).
    81  
    82  Just like secret strings, it is recommended that you never check in these
    83  multi-line secret files to version control by following the below steps.
    84  
    85  Set the [variables](https://www.terraform.io/docs/configuration/variables.html)
    86  in your Terraform template that resources utilizing the secret file will
    87  reference:
    88  
    89  ```hcl
    90  variable "private_key" {}
    91  
    92  resource "aws_instance" "example" {
    93    # ...
    94  
    95    provisioner "remote-exec" {
    96      connection {
    97        host        = "${self.private_ip}"
    98        private_key = "${var.private_key}"
    99      }
   100  
   101      # ...
   102    }
   103  }
   104  ```
   105  
   106  `terraform push` any "Terraform Variables":
   107  
   108      $ terraform push -name $ATLAS_USERNAME/example -var "private_key=$MY_PRIVATE_KEY"
   109  
   110  `terraform push` any "Environment Variables":
   111  
   112      $ TF_VAR_private_key=$MY_PRIVATE_KEY terraform push -name $ATLAS_USERNAME/example
   113  
   114  Alternatively, you can add or update variables manually by going to the
   115  "Variables" section of your Environment and pasting the contents of the file in
   116  as the value.
   117  
   118  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.
   119  
   120  A few things to note...
   121  
   122  The `.tfvars` file does not support multi-line files. You can still use
   123  `.tfvars` to define variables, however, you will not be able to actually set the
   124  variable in `.tfvars` with the multi-line file contents like you would a
   125  variable in a `.tf` file.
   126  
   127  If you are running Terraform locally, you can pass in the variables at the
   128  command line:
   129  
   130      $ terraform apply -var "private_key=$MY_PRIVATE_KEY"
   131      $ TF_VAR_private_key=$MY_PRIVATE_KEY terraform apply
   132  
   133  You can update variables locally by using the `-overwrite` flag with your `terraform push` command:
   134  
   135      $ terraform push -name $ATLAS_USERNAME/example -var "private_key=$MY_PRIVATE_KEY" -overwrite=private_key
   136      $ TF_VAR_private_key=$MY_PRIVATE_KEY terraform push -name $ATLAS_USERNAME/example -overwrite=private_key
   137  
   138  ## Notes on Security
   139  
   140  Terraform variables and environment variables are encrypted using
   141  [Vault](https://vaultproject.io) and closely guarded and audited. If you have
   142  questions or concerns about the safety of your configuration, please contact
   143  our security team at [security@hashicorp.com](mailto:security@hashicorp.com).