Workspace Tags appear in multiple sections and are missing from the API responses in HCP Terraform

Avatar
Dimpy Chugh
  • Updated

 

Introduction

When managing workspace tags in HCP Terraform, you may observe inconsistent behavior between the UI and API responses. This article explains why workspace tags may appear in multiple UI sections or be missing from certain API endpoints, and outlines the recommended approach to ensure consistent tagging behaviour.

Problem

You may encounter one or more of the following issues when working with workspace tags in HCP Terraform:

  • Workspace tags appear in two different sections in the HCP Terraform UI.

  • Tags created by automation are missing from the effective-tag-bindings API response.

  • Automation tools must read tags from multiple locations in the workspace JSON.

  • Tags added by automation are visible in the UI but are not editable.

This commonly occurs in environments where workspaces are created or managed using automation, SDKs, or legacy APIs.

 

Cause

HCP Terraform currently supports two tagging models, and mixing them leads to inconsistent UI and API behaviour:

1. Enhanced Tags 

  • Key-value tags (e.g., env:Dev)

  • Key-only tags (e.g., cloud)

  • Stored under:

        "relationships": {

.             "tag-bindings": […]

        }

  • Fully supported by:

    • HCP Terraform UI

    • effective-tag-bindings API

2. Flat-String Tags

  • Single string tags (e.g., s)

  • Created using the attributes.tag-names field

           "attributes": {
                  "tag-names": […]

            }

  • Not returned by the effective-tag-bindings API

  • Displayed in a separate section in the UI and typically not editable

When both models are used on the same workspace, tags appear split across the UI and APIs.

 

Solutions:

  • Standardise on enhanced tags (key-value or key-only) using tag bindings 

    • Update automation to create tags under: (If supported by the current SDK or APIs used)

      relationships.tag-bindings

      Avoid using attributes.tag-names for new workspaces.

    •  List workspace tag bindings API currently returns only enhanced (key:value) tags. Flat-string tags are still applied successfully to the workspace, but they are not surfaced through this newer endpoint.
       
      If you need to retrieve all flat-string tags associated with a workspace, you have to use the list workspace tags API instead in your automation.

       

Additional Information

Articles in this section

See more

Related articles