TF-9289 document priority variable sets.

Co-authored-by: rita <[email protected]>

Author: rberecka

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-11
+* Add `priority` attribute to the [Variable Sets API](/terraform/cloud-docs/api-docs/variable-sets).
+
 ## 2023-09-25
 * Add `intermediate` boolean attribute to the [State Versions API](/terraform/cloud-docs/api-docs/state-versions).
 

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,

website/docs/cloud-docs/workspaces/variables/index.mdx

@@ -102,6 +102,8 @@ When workspace-scoped variable sets have conflicting variables, Terraform Cloud
 
 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.
 
+If [prioritized](/terraform/cloud-docs/workspaces/variables/index#precedence-with-priority-variable-sets), variables in a workspace variable set have precedence over workspace or run applied variables with the same key.
+
 ### 5. 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,10 +114,14 @@ 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.
 
+If prioritized [prioritized](/terraform/cloud-docs/workspaces/variables/index#precedence-with-priority-variable-sets), variables in a project variable set have precedence over project and workspace scoped variable sets, workspace applied, and run applied variables with the same key.
+
 ### 6. 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.
 
+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.
+
 ### 7. `*.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`.
@@ -130,18 +136,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 +163,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 in a priority project or workspace scoped variable set. Variables in a priority variable set will take precedence over any variables with the same key set through the CLI on a run.
+
+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.

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. If you are looking for stricter enforcement than this, 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.