TF-9289 document priority varsets (#458)

rberecka · web-flow · commit 15bd29f6d97c · 2023-10-30T10:01:26.000-07:00
* TF-9289 document priority variable sets.
Co-authored-by: rita &lt;8647768+ritsok@users.noreply.github.com&gt;
diff --git a/website/docs/cloud-docs/api-docs/changelog.mdx b/website/docs/cloud-docs/api-docs/changelog.mdx
@@ -9,6 +9,9 @@ description: >-
 
 Keep track of changes to the API for Terraform Cloud and Terraform Enterprise.
 
+## 2023-10-30
+* Add `priority` attribute to the [Variable Sets API](/terraform/cloud-docs/api-docs/variable-sets).
+* 
 ## 2023-10-04
 * Updates to [run task integration API](/terraform/cloud-docs/api-docs/run-tasks/run-tasks-integration)
   * Fix invalid JSON in the example payload.
diff --git a/website/docs/cloud-docs/api-docs/variable-sets.mdx b/website/docs/cloud-docs/api-docs/variable-sets.mdx
@@ -27,6 +27,7 @@ Properties without a default value are required.
 | `data.name`                     | string  |         | The name of the variable set.                                                                                               |
 | `data.description`              | string  | `""`    | Text displayed in the UI to contextualize the variable set and its purpose.                                                 |
 | `data.global`                   | boolean | `false` | When true, Terraform Cloud automatically applies the variable set to all current and future workspaces in the organization. |
+| `data.priority`                 | boolean | `false` | When true, the variables in the set override any other variable values with a more specific scope, including values set on the command line. |
 | `data.relationships.workspaces` | array   | \`[]`     | Array of references to workspaces that the variable set should be assigned to.                                              |
 | `data.relationships.projects`   | array   | \`[]`    | Array of references to projects that the variable set should be assigned to.                                                |
 | `data.relationships.vars`       | array   | \`[]`     | Array of complete variable definitions that comprise the variable set.                                                      |
@@ -48,7 +49,8 @@ Terraform Cloud does not allow different global variable sets to contain conflic
     "attributes": {
       "name": "MyVarset",
       "description": "Full of vars and such for mass reuse",
-      "global": false
+      "global": false,
+      "priority": false,
     },
     "relationships": {
       "workspaces": {
@@ -97,7 +99,8 @@ curl \
     "attributes": {
       "name": "MyVarset",
       "description": "Full of vars and such for mass reuse",
-      "global": false
+      "global": false,
+      "priority": false,
     },
     "relationships": {
       "workspaces": {
@@ -151,6 +154,7 @@ Terraform Cloud does not allow global variable sets to contain conflicting varia
 | `data.name`                     | string  |         | The name of the variable set.                                                                                                                        |
 | `data.description`              | string  |         | Text displayed in the UI to contextualize the variable set and its purpose.                                                                          |
 | `data.global`                   | boolean |         | When true, Terraform Cloud automatically applies the variable set to all current and future workspaces in the organization.                          |
+| `data.priority`                 | boolean | `false` | When true, the variables in the set override any other variable values set with a more specific scope, including values set on the command line. |
 | `data.relationships.workspaces` | array   |         | **Optional** Array of references to workspaces that the variable set should be assigned to. Sending an empty array clears all workspace assignments. |
 | `data.relationships.projects`   | array   |         | **Optional** Array of references to projects that the variable set should be assigned to. Sending an empty array clears all project assignments.     |
 | `data.relationships.vars`       | array   |         | **Optional** Array of complete variable definitions to add to the variable set.                                                                      |
@@ -170,7 +174,8 @@ Terraform Cloud does not allow global variable sets to contain conflicting varia
     "attributes": {
       "name": "MyVarset",
       "description": "Full of vars and such for mass reuse. Now global!",
-      "global": true
+      "global": true,
+      "priority": true,
     },
     "relationships": {
       "workspaces": {
@@ -226,7 +231,8 @@ curl \
     "attributes": {
       "name": "MyVarset",
       "description": "Full of vars and such for mass reuse. Now global!",
-      "global": true
+      "global": true,
+      "priority": true
     },
     "relationships": {
       "vars": {
@@ -298,6 +304,7 @@ curl \
       "name": "MyVarset",
       "description": "Full of vars and such for mass reuse",
       "global": false,
+      "priority": false,
       "updated-at": "2023-03-06T21:48:33.588Z",
       "var-count": 5,
       "workspace-count": 2,
@@ -411,6 +418,7 @@ All of the list endpoints support pagination [with standard URL query parameters
         "name": "MyVarset",
         "description": "Full of vars and such for mass reuse",
         "global": false,
+        "priority": false,
         "updated-at": "2023-03-06T21:48:33.588Z",
         "var-count": 5,
         "workspace-count": 2,
diff --git a/website/docs/cloud-docs/workspaces/variables/index.mdx b/website/docs/cloud-docs/workspaces/variables/index.mdx
@@ -82,27 +82,39 @@ There may be cases when a workspace contains conflicting variables of the same t
 
 Terraform Cloud prioritizes and overwrites conflicting variables according to the following precedence:
 
-### 1. Command Line Argument Variables
+### 1. Priority Global Variable Sets
+
+If prioritized [prioritized](/terraform/cloud-docs/workspaces/variables/index#precedence-with-priority-variable-sets), variables in a global variable set have precedence over all other variables with the same key.
+
+### 2. Priority Project-Scoped Variable Sets
+
+If prioritized [prioritized](/terraform/cloud-docs/workspaces/variables/index#precedence-with-priority-variable-sets), variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope.
+
+### 3. Priority Workspace-Scoped Variable Sets
+
+If prioritized [prioritized](/terraform/cloud-docs/workspaces/variables/index#precedence-with-priority-variable-sets), variables in a priority workspace-scoped variable set have precedence over variables with the same key set at a more specific scope.
+
+### 4. Command Line Argument Variables
 
 When using a CLI workflow, variables applied to a run with either `-var` or `-var-file` overwrite workspace-specific and variable set variables that have the same key.
 
-### 2. Local Environment Variables Prefixed with `TF_VAR_`
+### 5. Local Environment Variables Prefixed with `TF_VAR_`
 
 When using a CLI workflow, local environment variables prefixed with `TF_VAR_` (e.g., `TF_VAR_replicas`) overwrite workspace-specific, variable set, and `.auto.tfvars` file variables that have the same key.
 
-### 3. Workspace-Specific Variables
+### 6. Workspace-Specific Variables
 
 Workspace-specific variables always overwrite variables from variable sets that have the same key. Refer to [overwrite variables from variable sets](/terraform/cloud-docs/workspaces/variables/managing-variables#overwrite-variable-sets) for details.
 
-### 4. Workspace-Scoped Variable Sets
+### 7. Workspace-Scoped Variable Sets
 
 Variables in workspace-scoped variable sets are only applied to a subset of workspaces in an organization.
 
 When workspace-scoped variable sets have conflicting variables, Terraform Cloud compares the variable set names and uses values from the variable set with lexical precedence. Terraform and Terraform Cloud operate on UTF-8 strings, and Terraform Cloud sorts variable set names based on the lexical order of Unicode code points.
 
 For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same workspace, Terraform Cloud will use any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. Terraform Cloud only considers the lexical ordering of variable set names when determining precedence.
 
-### 5. Project-Scoped Variable Sets
+### 8. Project-Scoped Variable Sets
 
 Workspace-specific variables and workspace-scoped variable sets always take precedence over project-scoped variable sets that are applied to workspaces within a project. 
 
@@ -112,15 +124,15 @@ When project-scoped variable sets have conflicting variables, Terraform Cloud co
 
 For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same project, Terraform Cloud uses any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. Terraform Cloud only considers the lexical ordering of variable set names when determining precedence.
 
-### 6. Global Variable Sets
+### 9. Global Variable Sets
 
 Workspace and project-scoped variable sets always take precedence over global variable sets that are applied to all workspaces within an organization. Terraform does not allow global variable sets to contain variables with the same key, so they cannot conflict.
 
-### 7. `*.auto.tfvars` Variable Files
+### 10. `*.auto.tfvars` Variable Files
 
 Variables in the Terraform Cloud workspace and variables provided through the command line always overwrite variables with the same key from files ending in `.auto.tfvars`.
 
-### 8. `terraform.tfvars` Variable File
+### 11. `terraform.tfvars` Variable File
 
 Variables in the `.auto.tfvars` files take precedence over variables in the `terraform.tfvars` file.
 
@@ -130,18 +142,23 @@ Variables in the `.auto.tfvars` files take precedence over variables in the `ter
 
 Consider an example workspace that has the following variables applied:
 
-| Source                | Scope                  | ACCESS_KEY | ACCESS_ID  | VAR1 | KEY1 | VAR2 | KEY2 | replicas |
-| --------------------- | ---------------------- | ---------- | ---------- | ---- | ---- | ---- | ---- | -------- |
-| Command Line Argument | Run-Specific           |            |            |      |      |      |      | `9`      |
-| Local Environment     | Run-Specific           |            |            |      |      |      |      | `8`      |
-| Variables             | Workspace-Specific     |            |            | `h`  |      |      |      | `1`      |
-| A_Variable_Set        | Workspace-Scoped       |            |            | `y`  | `x`  |      |      | `2`      |
-| B_Variable_Set        | Project-Scoped         | `g47fh474` | `874hf7u4` |      | `b`  | `z`  |      | `3`      |
-| C_Variable_Set        | Global                 |            |            |      |      | `a`  | `c`  | `4`      |
+| Source                | Scope                      | REGION        | ACCESS_KEY | ACCESS_ID  | VAR1 | KEY1 | VAR2 | KEY2 | replicas |
+| --------------------- | -------------------------- | ------------  | ---------- | ---------- | ---- | ---- | ---- | ---- | -------- |
+| 1_Variable_Set        | Priority Global            | "us-east-1"   |            |            |      |      |      |      |          |
+| 2_Variable_Set        | Priority Project-Scoped    | "us-east-2"   |            |            |      |      |      |      |          |
+| 3_Variable_Set        | Priority Workspace-Scoped  | "us-west-1"   |            |            |      |      |      |      |          |
+| Command Line Argument | Run-Specific               | "us-west-2"   |            |            |      |      |      |      | `9`      |
+| Local Environment     | Run-Specific               |               |            |            |      |      |      |      | `8`      |
+| Variables             | Workspace-Specific         |               |            |            | `h`  |      |      |      | `1`      |
+| A_Variable_Set        | Workspace-Scoped           |               |            |            | `y`  | `x`  |      |      | `2`      |
+| B_Variable_Set        | Project-Scoped             |               | `g47fh474` | `874hf7u4` |      | `b`  | `z`  |      | `3`      |
+| C_Variable_Set        | Global                     |               |            |            |      |      | `a`  | `c`  | `4`      |
 
 When you trigger a run through the command line, Terraform Cloud applies the following variables:
 
-- **Run-Specific:** `replicas` from the command line. That means `replicas` equals `9` for this run. Variables set from the command line take precedence over all other values, including the run-specific `TF_VAR_replicas` value set in your local environment.
+- **1_Variable_Set:** `REGION`. For this run, `REGION` equals `us-east-1`, overwriting the value in all other run-specific, workspace-specific, and variable set same key variables.
+
+- **Run-Specific:** `replicas` from the command line. That means `replicas` equals `9` for this run. If a variable set is priority, it takes precedence over all other values set with a more specific scope. Here the TF_VAR_region is "us-east-1", because the variable from the priority global 1_Variable_Set takes precedence. Without priority variable sets, variables set from the command line take precedence over all other values, including the run-specific `TF_VAR_replicas` value set in your local environment.
 
 - **Workspace-Specific:** `VAR1`. For this run, `VAR1` equals `h`, overwriting the value in A_Variable_Set.
 
@@ -152,3 +169,15 @@ When you trigger a run through the command line, Terraform Cloud applies the fol
 - **C_Variable_Set:** `KEY2`. For this run, `KEY2` equals `c`. This is a global variable set with no overwritten values.
 
 ![An example scenario demonstrating variable precedence in Terraform Cloud](/img/docs/variable-precedence-example.png)
+
+
+## Precedence with Priority Variable Sets
+
+You can select to prioritize all values of the variables in a variable set.
+When a variable set is priority, the values take precedence over any variables with the same key set at a more specific scope.
+
+For example, variables in a priority global variable set would take precedence over all variables with the same key.
+
+If two priority variable sets with the same scope include the same variable key, Terraform Cloud will determine precedence by the alphabetical order of the variable sets' names.
+
+While a priority variable set can enforce that Terraform variables use designated values, it does not guarantee that the configuration uses the variable. A user can still directly modify the Terraform configuration to remove usage of a variable and replace it with a hard-coded value. For stricter enforcement, we recommend using policy checks or run tasks.
diff --git a/website/docs/cloud-docs/workspaces/variables/managing-variables.mdx b/website/docs/cloud-docs/workspaces/variables/managing-variables.mdx
@@ -148,6 +148,13 @@ To overwrite a variable from a variable set, [create a new workspace-specific va
 
 Variables within a variable set can also automatically overwrite variables with the same key in other variable sets applied to the same workspace. Though variable sets are created for the organization, these overwrites occur within each workspace. Refer to [variable precedence](/terraform/cloud-docs/workspaces/variables#precedence) for more details.
 
+## Priority Variable Sets
+
+The values in priority variable sets overwrite any variables with the same key set at more specific scopes. This includes variables set using command line flags, or through`.*auto.tfvars` and `terraform.tfvars` files.
+
+It is still possible for a user to directly modify the Terraform configuration and remove usage of a variable and replace it with a hard coded value. For stricter enforcement, we recommend using policy checks or run tasks.
+Refer to [variable precedence](/terraform/cloud-docs/workspaces/variables#precedence-with-priority-variable-sets) for more details.
+
 ## Variable Values and Format
 
 The limits, allowable values, and required format are the same for both workspace-specific variables and variable sets.
diff --git a/website/img/docs/variable-precedence-example.png b/website/img/docs/variable-precedence-example.png
