TF-9289 document priority varsets

Author: rberecka

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 set in 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 in 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

@@ -152,3 +152,26 @@ 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 the values of variables in a variable set in the UI and or mark a variable set as `priority: true`.
+When a variable set is prioritized the values take precedence over any variables with the same key set at a _more specific_ scope.
+
+* A project scope is more specific than a global scope.
+* A workspace variable set scope is more specific than a project scope.
+* A workspace variable scope is more specific than a workspace variable set scope.
+* A variable set on the command line a more specific scope than a workspace variable.
+
+Therefore a prioritized global variable set variable takes precedence over even a variable set by a command line argument.
+
+A variable from a prioritized global variable set takes precedence over any variables set by any of the methods above except for
+those set directly in the terraform configuration code itself.
+
+If two prioritized variable sets include the same variable key, precedence is determined by the alphabetical order of variable
+set name.
+
+The only variable that a prioritized variable set variable cannot overwrite is one with a value set directly in the terraform
+configuration code itself. If you want to ensure what a variable value is including the terraform configuration code itself,
+we recommend using a Policy Check or Run Task.

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

@@ -148,6 +148,12 @@ 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
+
+You can select to prioritize variable values from a variable set over any other variables with the same key set at more specific scopes. Variables from prioritized variable sets will also overwrite variables with the same key that are set from the command line, .*auto.tfvars files, and terraform.tfvars files.
+
+The only variable values that a prioritized variable set cannot overwrite are values set directly in the terraform configuration itself. If you want to fully ensure the values of variables including values in your terraform configuration code, we recommend using a Policy Check or Run Task.
+
 ## Variable Values and Format
 
 The limits, allowable values, and required format are the same for both workspace-specific variables and variable sets.