HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

Create workspace tags

This topic describes how to attach tags to your workspaces so that you can organize workspaces. Tagging workspaces also helps you sort and filter workspaces in the UI and enable you to associate Terraform configurations with several workspaces.

Overview

You can create tags and attach them to your workspaces. 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 either single-value tags or key-value pairs. You can also migrate existing single-value tags to the key-value scheme. Refer to Migrating to key-value tags for instructions.

Adding tags stored as key-value pairs is in private beta and unavailable for some users. Contact your HashiCorp representative for information about participating in the private beta.

Single-value 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:

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.

Reserved tags and project tags are in private beta and unavailable for some users. Contact your HashiCorp representative for information about participating in the private beta.

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

Complete the following steps to define workspace 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 to define a new key-value pair. 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 created by the organization administrator. 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 Direct Tags section, modify either a key, value, or both and click Save.

Migrating to key-value tags

You can use the API to migrate single-value tags that may already be in your workspace tags to tag stored as key-value pairs. You must have permissions in the workspace to perform the following task. Refer to Requirements for additional information.

Note that Terraform adds single-value workspace tags that are defined in the associated Terraform cloud block 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.
Edit this page on GitHub