Merge pull request #14185 from hashicorp/liz/tfe-variables

[website] docs for TFE personal env + org variables

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).

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.