Merge pull request #35942 from hashicorp/TF-21933-document-cloud-bloc…

…k-tags-behavior-in-1-10

cloud: document resource k/v tag usage

website/docs/cli/cloud/settings.mdx

@@ -41,9 +41,9 @@ Add a `cloud` block to your Terraform configuration and configure the connection
 Specify the following settings in the `cloud` block:
 
 - `organization`:  Specifies the name of an HCP Terraform organization to connect to.
-- `workspaces.tags`: Specifies a list of single-value string tags. Terraform links the working directory to existing workspaces in the organization that have matching tags. If there are no existing workspaces with matching tags, the Terraform CLI prompts you to create a new workspace that inherits the tags you specify in this field when you initialize the configuration.
+- `workspaces.tags`: Specifies either a map of tag strings or a list of key-only string tags (legacy style). Terraform links the working directory to existing workspaces in the organization that have matching tags. If there are no existing workspaces with matching tags, the Terraform CLI prompts you to create a new workspace that applies the tags you specify in this field when you initialize the configuration.
 - `workspaces.name`: You can specify the name of an existing workspace to associate with the Terraform configuration instead of using tags. If you configure the `name`, you cannot use the `tags` configuration.
-- `workspaces.project`: You can specify the name of an existing project. Terraform associates the configuration with workspaces in the project that match the `name` or `tags`. 
+- `workspaces.project`: You can specify the name of an existing project. Terraform associates the configuration with workspaces in the project that match the `name` or `tags`.
 
 Refer to the [`cloud` block reference](/terraform/language/terraform#terraform-cloud) for details about configuring the `cloud` block.
 
@@ -57,7 +57,11 @@ terraform {
 
     workspaces {
       project = "networking-development"
-      tags = ["networking", "source:cli"]
+
+      tags = {
+        layer = "networking"
+        source = "cli"
+      }
     }
   }
 }
@@ -110,9 +114,9 @@ terraform {
 }
 ```
 
-If the `terraform` block or `terraform.tf` file uses the `prefix` argument to connect to multiple workspaces, you can specify a list of single-value string tags in the `tags` argument instead of using the `name` argument. During `terraform plan` or `terraform apply` operations, Terraform associates the configuration with workspaces that match the specified tags.
+If the `terraform` block or `terraform.tf` file uses the `prefix` argument to connect to multiple workspaces, you can specify a list of key-value string tags in the `tags` argument instead of using the `name` argument. During `terraform plan` or `terraform apply` operations, Terraform associates the configuration with workspaces that match the specified tags.
 
-The following example replaces the `my-app-` prefix with the `app:mine` tag:
+The following example replaces the `my-app-` prefix with the `app=mine` tag:
 
 ```hcl
 terraform {
@@ -122,7 +126,9 @@ terraform {
 
     workspaces {
 -      prefix = "my-app-"
-+      tags = ["app:mine"]
++      tags = {
++        app = "mine"
++      }
     }
    }
  }
@@ -150,4 +156,3 @@ The rules for defining `.terraformignore` are based on
 - Negate a pattern by starting it with an exclamation point `!`. When ignoring large directories, negation patterns can impact performance. Place negation rules as early as possible within `.terraformignore` or avoid using them if possible.
 
 Terraform parses the `.terraformignore` at the root of the configuration directory.
-

website/docs/intro/core-workflow.mdx

@@ -239,7 +239,14 @@ terraform {
     hostname = "app.terraform.io" # Optional; defaults to app.terraform.io
 
     workspaces {
-      tags = ["networking", "source:cli"]
+      tags = {
+        layer = "networking"
+        source = "cli"
+      }
+      
+      # For terraform versions below 1.10, you must specify key-only tags
+      # using a list of strings. Example:
+      # tags = ["networking", "source:cli"]
     }
   }
 }

website/docs/language/terraform.mdx

@@ -20,7 +20,7 @@ The following list outlines attribute hierarchy, data types, and requirements in
   - [`cloud`](#terraform-cloud): map
     - [`organization`](#terraform-cloud-organization): string | required when connecting to HCP Terraform
     - [`workspaces`](#terraform-cloud-workspaces): map | required when connecting to HCP Terraform
-      - [`tags`](#terraform-cloud-workspaces): list of strings
+      - [`tags`](#terraform-cloud-workspaces): list of strings or map of strings
       - [`name`](#terraform-cloud-workspaces): string
       - [`project`](#terraform-cloud-workspaces): string
     - [`hostname`](#terraform-cloud-workspaces): string | `app.terraform.io`
@@ -95,9 +95,9 @@ Specifies metadata for matching workspaces in HCP Terraform. Terraform associate
 
 | Attribute | Description | Data type |
 | --- | --- | --- |
-| `tags` | Specifies a list of flat single-value tags. Terraform associates the configuration with workspaces that have all matching flat single-value tags. New workspaces created from the working directory inherit the tags. This attribute does not support key-value tags. You cannot set this attribute and the `name` attribute in the same configuration.  | Array of strings |
+| `tags` | Specifies either a map of strings as key/value tags or a list of single-value, key-only tags. Terraform associates the configuration with workspaces that have all matching tags. New workspaces created from the working directory inherit the tags. You cannot set this attribute and the `name` attribute in the same configuration. Using a map type with both keys and values requires Terraform 1.10+. | Array of strings or Map of strings |
 | `name` | Specifies an HCP Terraform workspace name to associate the Terraform configuration with. You can only use the working directory with the workspace named in the configuration. You cannot manage the workspace from the Terraform CLI. You cannot set this attribute and the `tags` attribute in the same configuration. <p>Instead of hardcoding a single workspace as a string, you can alternatively use the [`TF_WORKSPACE`](#tf_workspace) environment variable. </p> | String |
-| `project` | Specifies the name of an HCP Terraform project. Terraform creates all workspaces that use this configuration in the project. Using the [`terraform workspace list` command](/terraform/cli/commands/workspace/list) in the working directory returns only workspaces in the specified project. <p>Instead of hardcoding the project as a string, you can alternatively use the [`TF_CLOUD_PROJECT`](#tf_cloud_project) environment variable.</p>| String |
+| `project` | Specifies the name of an HCP Terraform project. Terraform creates all workspaces that use this configuration in the project. Using the [`terraform workspace list` command](/terraform/cli/commands/workspace/list) in the working directory returns only workspaces in the specified project. <p>Instead of hardcoding the project as a string, you can alternatively use the [`TF_CLOUD_PROJECT`](#tf_cloud_project) environment variable.</p> | String |
 
 - Data type: Map
 - Required when connecting to HCP Terraform
@@ -169,22 +169,24 @@ terraform {
 
 ### Connect to HCP Terraform
 
-In the following example, the configuration links the working directory to workspaces in the `example_corp` organization that contain the `app` tag:
+In the following example, the configuration links the working directory to workspaces in the `example_corp` organization that contain the `layer=app` tag:
 
 ```hcl
 terraform {
   cloud {
     organization = "example_corp"
     workspaces {
-      tags = ["app"]
+      tags = {
+        layer = "app"
+      }
     }
   }
 }
 ```
 
 ### Connect to Terraform Enterprise
 
-In the following example, the configuration links the working directory to workspaces in the `example_corp` organization that contain the `app` tag. The `hostname` field is required in the configuration unless you use the `TF_CLOUD_HOSTNAME` environment variable:
+In the following example, the configuration links the working directory to workspaces in the `example_corp` organization that contain the `app` key-only tag. Key-only tags must be used with versions of Terraform Enterprise prior to v202411-1 or versions of Terraform prior to v1.10. The `hostname` field is required in the configuration unless you use the `TF_CLOUD_HOSTNAME` environment variable:
 
 ```hcl
 terraform {
@@ -210,4 +212,4 @@ terraform {
     }
   }
 }
-```
+```