Create workspace tags

This topic describes how to create and attach tags to your workspaces.

Overview

Tagging workspaces helps organization administrators organize, sort, and filter workspaces so that they can track resource consumption. For example, you could add a cost-center tag so that administrators can sort workspaces according to cost center.

HCP Terraform stores tags as key-value pairs or as key-only tags. Key-only tags enable you to associate a single Terraform configuration file with several workspaces according to tag. Refer to the following topics in the Terraform CLI and configuration language documentation for additional information:

• terraform{}.cloud{}.workspaces reference
• Define connection settings

Reserved tags

You can reserve a set of tag keys for each organization. Reserved tag keys appear as suggestions when people create tags for projects and workspaces so that you can use consistent terms for tags. Refer to Create and manage reserved tags for additional information.

Single-value tags

Your system may contain single-value tags created using Terraform v1.10 and older. You can migrate existing single-value tags to the key-value scheme. Refer to Migrate single-value tags for instructions.

Requirements

• You must be member of a team with the Write permission group enabled for the workspace to create tags for a workspace.
• You must be member of a team with the Admin permission group enabled for the workspace to delete tags on a workspace.

You cannot create tags for a workspace using the CLI.

Define tags

1. Open your workspace.

2. Click either the count link for the Tags label or Manage Tags in the Tags card on the right-sidebar to open the Manage workspace tags drawer.

3. Click +Add tag and perform one of the following actions:

   • Specify a key-value pair: Lets you sort, filter, and search on either key or value.
   • Specify a tag key and leave the Value field empty: Lets you sort, filter, and search on only the key name.
   • Choose a reserved key from the suggested tag key list and specify a value: Ensures that you are using the key name consistently and lets you sort, filter, and search on either key or value.
   • Choose a reserved key from the suggested tag key list and leave the Value field empty: Ensures that you are using the key name consistently and lets you sort, filter, and search on only the key name.

   Refer to Tag syntax for information about supported characters.

4. Tags inherited from the project appear in the Inherited Tags section. You can attach new key-value pairs to their projects to override inherited tags. Refer to Manage projects for additional information about using tags in projects.

   You cannot override reserved tag keys when the Disable overrides option is enabled. Refer to Create and manage reserved tags for additional information.

   You can also click on tag links in the Inherited Tags section to view workspaces that use the same tag.

5. Click Save.

Tags that you create appear in the tags management screen in the organization settings. Refer to Organizations for additional information.

Update tags

1. Open your workspace.
2. Click either the count link for the Tags label or Manage Tags in the Tags card on the right-sidebar to open the Manage workspace tags drawer.
3. In the Tags applied to this resource section, modify a key, value, or both and click Save.

Migrate single-value tags

You can use the API to convert existing single-value tags to key-value tags. You must have permissions in the workspace to perform the following task. Refer to Requirements for additional information.

Terraform v1.10 and older adds single-value workspace tags defined in the associated Terraform configuration to workspaces selected by the configuration. As result, your workspace may include duplicate tags. Refer to the Terraform reference documentation for additional information.

Re-create existing workspace tags as resource tags

1. Send a GET request to the /organizations/:organization_name/tags endpoint to request all workspaces for your organization. The response may span several pages.
2. For each workspace, check the tag-names attribute for existing tags.
3. Send a PATCH request to the /workspaces/:workspace_id endpoint and include the tag-binding relationship in the request body for each workspace tag.

Delete single-value workspace tags

1. Send a GET request to the /organizations/:organization_name/tags endpoint to request all workspaces for your organization.
2. Enumerate the external IDs for all tags.
3. Send a DELETE request to the /organizations/:organization_name/tags endpoint to delete tags.

Tag syntax

The following rules apply to tags:

• Tags must be one or more characters.
• Tags have a 255 character limit.
• Tags can include letters, numbers, colons, hyphens, and underscores.
• For tags stored as key-value pairs, tag values are optional.