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  21 22 Personal Organization variables can be managed in your Account Settings under 23 "Organization Variables": 24 25  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).