diff --git a/website/README.md b/website/README.md index 4dad05e120..4dbad10d21 100644 --- a/website/README.md +++ b/website/README.md @@ -12,7 +12,10 @@ like any normal GitHub project, and we'll merge it in. ## Running the Site Locally -Running the site locally is simple. Clone this repo and run `make website`. +Running the site locally is simple: + +1. Install [Docker](https://docs.docker.com/engine/installation/) if you have not already done so +2. Clone this repo and run `make website` Then open up `http://localhost:4567`. Note that some URLs you may need to append ".html" to make them work (in the navigation). diff --git a/website/source/assets/images/docs/tfe-organization-variables.png b/website/source/assets/images/docs/tfe-organization-variables.png new file mode 100644 index 0000000000..0980c60c08 Binary files /dev/null and b/website/source/assets/images/docs/tfe-organization-variables.png differ diff --git a/website/source/assets/images/docs/tfe-variables.png b/website/source/assets/images/docs/tfe-variables.png new file mode 100644 index 0000000000..7b0e735a0e Binary files /dev/null and b/website/source/assets/images/docs/tfe-variables.png differ diff --git a/website/source/docs/enterprise/runs/variables-and-configuration.html.md b/website/source/docs/enterprise/runs/variables-and-configuration.html.md index 1ebeb7a923..7f7711fc1f 100755 --- a/website/source/docs/enterprise/runs/variables-and-configuration.html.md +++ b/website/source/docs/enterprise/runs/variables-and-configuration.html.md @@ -8,19 +8,34 @@ description: |- # Terraform Variables and Configuration -There are two ways to configure Terraform runs – with Terraform variables or -environment variables. +There are several ways to configure Terraform runs: -## Terraform Variables +1. Terraform variables +2. Environment variables +3. Personal Environment and Personal Organization variables + +You can add, edit, and delete all Terraform, Environment, and Personal +Environment variables from the "Variables" page on your environment: + +![Terraform Enterprise environment variable configuration](docs/tfe-variables.png) + +Personal Organization variables can be managed in your Account Settings under +"Organization Variables": + +![Terraform Enterprise personal organization variables](docs/tfe-organization-variables.png) + +## Variable types + +### Terraform Variables Terraform variables are first-class configuration in Terraform. They define the parameterization of Terraform configurations and are important for sharing and removal of sensitive secrets from version control. Variables are sent with the `terraform push` command. Any variables in your local -`.tfvars` files are securely uploaded. Once variables are uploaded, Terraform will prefer the stored variables over any changes you -make locally. Please refer to the -[Terraform push documentation](https://www.terraform.io/docs/commands/push.html) +`.tfvars` files are securely uploaded. Once variables are uploaded, Terraform +will prefer the stored variables over any changes you make locally. Please refer +to the [Terraform push documentation](https://www.terraform.io/docs/commands/push.html) for more information. You can also add, edit, and delete variables. To update Terraform variables, @@ -32,7 +47,7 @@ For detailed information about Terraform variables, please read the [Terraform variables](https://terraform.io/docs/configuration/variables.html) section of the Terraform documentation. -## Environment Variables +### Environment Variables Environment variables are injected into the virtual environment that Terraform executes in during the `plan` and `apply` phases. @@ -75,9 +90,47 @@ For any of the `GITHUB_` attributes, the value of the environment variable will be the empty string (`""`) if the resource is not connected to GitHub or if the resource was created outside of GitHub (like using `terraform push`). +### Personal Environment and Personal Organization Variables + +Personal variables can be created at the Environment or Organization level and +are private and scoped to the user that created them. Personal Environment +variables are scoped to just the environment they are attached to, while Personal +Organization variables are applied across any environment a user triggers a +Terraform run in. Just like shared Environment variables, they are injected into +the virtual environment during the `plan` and `apply` phases. + +Both Personal Environment and Personal Organization variables can be used to +override Environment variables on a per-user basis. + +## Variable Hierarchy + +It is possible to create the same variable in multiple places for more granular +control. Variables are applied in the following order from least to most +precedence: + +1. Environment +2. Personal Organization +3. Personal Environment + +Here's an example: + +* For the `SlothCorp/petting_zoo` environment, User 1 creates +an Environment variable called `SECRET_GATE_ACCESS_KEY` and sets the value to +`"orange-turtleneck"` +* User 2 adds a Personal Environment variable for +`SECRET_GATE_ACCESS_KEY` and sets the value to `"pink-overalls"` +* When User 2 submits a `plan` or `apply`, the `SECRET_GATE_ACCESS_KEY` +will use `"pink-overalls"` +* When User 1, or any other user, submits a `plan` or `apply`, the +`SECRET_GATE_ACCESS_KEY` will use `"orange-turtleneck"` + ## Managing Secret Multi-Line Files -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). +Terraform Enterprise has the ability to store multi-line files as variables. The +recommended way to manage your secret or 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). Just like secret strings, it is recommended that you never check in these multi-line secret files to version control by following the below steps.