DOC-11438 Docs for cc/console: Grouping clusters by labels

src/current/_data/redirects.yml

@@ -873,6 +873,10 @@
   sources: ['cockroachcloud/serverless-cluster-management.md']
   versions: ['cockroachcloud']
 
+- destination: cockroachcloud/advanced-cluster-management.md
+  sources: ['cockroachcloud/cluster-management-advanced.md']
+  versions: ['cockroachcloud']
+
 - destination: cockroachcloud/connect-to-a-basic-cluster.md
   sources: ['cockroachcloud/connect-to-a-serverless-cluster.md']
 

src/current/_includes/cockroachcloud/filter-tabs/cluster-management.md

@@ -1,4 +1,4 @@
 {% assign tab_names_html = "CockroachDB Basic;CockroachDB Standard;CockroachDB Advanced" %}
-{% assign html_page_filenames = "basic-cluster-management.html;cluster-management.html;cluster-management-advanced.html;advanced-cluster-management.html" %}
+{% assign html_page_filenames = "basic-cluster-management.html;cluster-management.html;advanced-cluster-management.html" %}
 
 {% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder="cockroachcloud" %}

src/current/_includes/cockroachcloud/org-roles/folder-admin.md

@@ -1,4 +1,4 @@
-    A {% if page.name == 'authorization.md' %}**Folder Admin**{% else %}[**Folder Admin**]({% link cockroachcloud/authorization.md %}#folder-admin){% endif %} can create, rename, and move, or delete folders where they are granted the role, and they can also manage access to these folders. This role can be granted at the level of the organization or on a specific folder. If granted at the level of the organization, the role grants the ability to view all users and service accounts in the organization. If granted on a specific folder, the role is inherited by descendant folders.
+    A {% if page.name == 'authorization.md' %}**Folder Admin**{% else %}[**Folder Admin**]({% link cockroachcloud/authorization.md %}#folder-admin){% endif %} can create, rename, and move, or delete folders where they are granted the role, and they can also manage access to these folders. They can also [edit folder labels]({% link cockroachcloud/labels.md %}). This role can be granted at the level of the organization or on a specific folder. If granted at the level of the organization, the role grants the ability to view all users and service accounts in the organization. If granted on a specific folder, the role is inherited by descendant folders.
 
     A user with the {% if page.name == 'authorization.md' %}[Org Administrator](#org-administrator){% else %}[Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator){% endif %} role can grant themselves, another user, or a service account the Folder Admin role.
 

src/current/_includes/v25.1/sidebar-data/cloud-deployments.json

@@ -292,10 +292,16 @@
                         ]
                     },
                     {
-                    "title": "Organize CockroachDB Cloud Clusters Using Folders",
-                    "urls": [
-                        "/cockroachcloud/folders.html"
-                    ]
+                        "title": "Organize CockroachDB Cloud Clusters Using Folders",
+                        "urls": [
+                            "/cockroachcloud/folders.html"
+                        ]
+                    },
+                    {
+                        "title": "Organize CockroachDB Cloud Resources Using Labels",
+                        "urls": [
+                            "/cockroachcloud/labels.html"
+                        ]
                     }
                 ]
             },

src/current/_includes/v25.2/sidebar-data/cloud-deployments.json

@@ -292,10 +292,16 @@
                         ]
                     },
                     {
-                    "title": "Organize CockroachDB Cloud Clusters Using Folders",
-                    "urls": [
-                        "/cockroachcloud/folders.html"
-                    ]
+                        "title": "Organize CockroachDB Cloud Clusters Using Folders",
+                        "urls": [
+                            "/cockroachcloud/folders.html"
+                        ]
+                    },
+                    {
+                        "title": "Organize CockroachDB Cloud Resources Using Labels",
+                        "urls": [
+                            "/cockroachcloud/labels.html"
+                        ]
                     }
                 ]
             },

src/current/cockroachcloud/advanced-cluster-management.md

@@ -25,6 +25,10 @@ The [**Overview** page]({% link cockroachcloud/cluster-overview-page.md %}) disp
 
 From the **Overview** page, you can connect to your cluster. For more information, see [Connect to Your CockroachDB {{ site.data.products.advanced }} Cluster]({% link cockroachcloud/connect-to-your-cluster.md %}).
 
+## Edit labels
+
+You can [organize CockroachDB {{ site.data.products.cloud }} clusters using labels]({% link cockroachcloud/labels.md %}).
+
 ## Scale your cluster
 
 These sections show how to scale a {{ site.data.products.advanced }} cluster horizontally by adding or removing nodes or vertically by changing each node's storage and compute resources.

src/current/cockroachcloud/authorization.md

@@ -89,6 +89,7 @@ Cluster Operators can perform a variety of cluster functions:
   - Configure single sign-on (SSO) enforcement.
   - Access the [DB Console]({% link cockroachcloud/network-authorization.md %}#db-console).
   - Configure a cluster's [maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window).
+  - [Edit a cluster's labels]({% link cockroachcloud/labels.md %}).
 
 - *Service accounts* with this role can perform the following *API operations*:
 

src/current/cockroachcloud/basic-cluster-management.md

@@ -19,6 +19,10 @@ To view and manage a specific cluster, click the name of the cluster. The [**Ove
 
 The **Overview** page displays details about the selected CockroachDB {{ site.data.products.basic }} cluster. For more information, see [Cluster Overview Page]({% link cockroachcloud/cluster-overview-page.md %}).
 
+## Edit labels
+
+You can [organize CockroachDB {{ site.data.products.cloud }} clusters using labels]({% link cockroachcloud/labels.md %}).
+
 ## Estimate usage cost
 
 {{site.data.alerts.callout_info}}

src/current/cockroachcloud/billing-management.md

@@ -133,7 +133,7 @@ If your organization has an annual contract with CockroachDB {{ site.data.produc
 
 Under the **Credits** section, you can see more information about each of your organization's contracts. Contracts are listed in the order in which they will be used.
 
-Under the **Spend over time** section, you can see a table of each of your organization's clusters and the costs they have accrued.
+The **Current billing period** section displays a table listing your organization's clusters and the Credits they have accrued. The table also includes the cluster type and associated [labels]({% link cockroachcloud/labels.md %}).
 
 ## View invoices
 

src/current/cockroachcloud/cluster-management.md

@@ -29,6 +29,10 @@ The [**Overview** page]({% link cockroachcloud/cluster-overview-page.md %}) disp
 
 From the **Overview** page, you can connect to your cluster. For more information, refer to [Connect to Your CockroachDB {{ site.data.products.standard }} Cluster]({% link cockroachcloud/connect-to-your-cluster.md %}).
 
+## Edit labels
+
+You can [organize CockroachDB {{ site.data.products.cloud }} clusters using labels]({% link cockroachcloud/labels.md %}).
+
 ## Add a region to your cluster
 
 1. Navigate to the cluster's **Overview** page.

src/current/cockroachcloud/cluster-overview-page.md

@@ -16,13 +16,14 @@ The **Cluster Overview** page displays key metrics about your CockroachDB {{ sit
 
 ## Cluster settings
 
-The **Cluster settings** panel displays the settings you chose during [cluster creation]({% link cockroachcloud/create-a-basic-cluster.md %}).
+The **Cluster settings** panel shows the settings selected during [cluster creation]({% link cockroachcloud/create-a-basic-cluster.md %}), as well as any [labels]({% link cockroachcloud/labels.md %}) added to the cluster after its creation.
 
 | Field     | Description                                                                                             |
 |-----------|---------------------------------------------------------------------------------------------------------|
 | Cloud     | The cluster's [cloud provider]({% link cockroachcloud/create-a-basic-cluster.md %}#step-2-select-the-cloud-provider). |
 | Plan type | The plan type used to create the cluster.                                                               |
-| Regions    | The cluster's [regions]({% link cockroachcloud/create-a-basic-cluster.md %}#step-3-select-the-regions).         |
+| Regions   | The cluster's [regions]({% link cockroachcloud/create-a-basic-cluster.md %}#step-3-select-the-regions). |
+| Labels    | The [labels]({% link cockroachcloud/labels.md %}) added to the cluster.       |
 
 ## Capacity used this month
 

src/current/cockroachcloud/labels.md

@@ -0,0 +1,78 @@
+---
+title: Organize CockroachDB Cloud Resources Using Labels
+summary: Learn how to use labels to organize CockroachDB Cloud clusters and folders.
+toc: true
+docs_area: manage
+---
+
+CockroachDB {{ site.data.products.cloud }} supports labels as a flexible way to categorize and manage your [clusters]({% link cockroachcloud/cluster-management.md %}) and [folders]({% link cockroachcloud/folders.md %}). Labels help you track usage, analyze [billing]({% link cockroachcloud/billing-management.md %}#view-credits-balance), automate operations, and streamline reporting across your organization.
+
+## What are labels?
+
+Labels are customizable key-value pairs you can attach to CockroachDB {{ site.data.products.cloud }} resources. Unlike folders, which allow only one-to-many relationships, labels support many-to-many relationships—ideal for complex environments with overlapping ownership or multiple tagging criteria.
+
+### Example
+
+You might apply these labels to a cluster:
+
+- `team:payments`
+- `env:production`
+- `application:checkout-service`
+
+These labels help filter resources, allocate costs, and integrate with automated workflows.
+
+## Why use labels?
+
+- **Flexible Organization**: Tag clusters and folders by team, environment, application, or any category relevant to your workflows.
+- **Cost Allocation**: Analyze your invoice data by label values to track spending across departments or services.
+- **Automation**: Use labels in API calls and Terraform configurations to automate operations.
+- **Enhanced Reporting**: Export label metadata for use in external analytics tools.
+
+## Label structure
+
+- Labels use key-value pairs.
+- Each key can have multiple values.
+- Labels are visible across your organization once created.
+
+## Edit labels
+
+You can apply labels to your cluster or folder through the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud/).
+
+Adding or deleting labels on a cluster requires the [Cluster Admin]({% link cockroachcloud/authorization.md %}#cluster-administrator) or [Cluster Operator]({% link cockroachcloud/authorization.md %}#cluster-operator) role.
+
+    1. Navigate to the cluster on the [**Clusters** page]({% link cockroachcloud/cluster-management.md %}#view-clusters-page) and click the menu button in the **Action** column. Alternatively, navigate to the [**Overview** page]({% link cockroachcloud/cluster-management.md %}#view-cluster-overview) for the cluster and click **Actions** in the top right corner.
+    1. In the dropdown menu, select **Edit labels** to open the **Edit labels** window.
+
+Adding or deleting labels on a folder requires the [Folder Admin]({% link cockroachcloud/authorization.md %}#folder-admin) role. 
+
+    1. Navigate to the folder on the [**Clusters** page]({% link cockroachcloud/cluster-management.md %}#view-clusters-page) and click the menu button in the **Action** column.
+    1. In the dropdown menu, select **Edit labels** to open the **Edit labels** window.
+
+### Add labels
+
+To add a label in the **Edit labels** window:
+
+1. Enter a label key and an optional label value. Autocomplete helps avoid typos and duplicates.
+1. Click **+ Add**. The label appears under **Labels applied**.
+1. Repeat steps 1 and 2 to add more labels.
+1. Click **Add/Update Labels** to apply the labels.
+
+### Delete labels
+
+To delete a label in the **Edit labels** window:
+
+1. Under **Labels applied**, click the **X** on the right of the label you want to delete.
+1. Repeat step 1 to delete more labels.
+1. Click **Update Labels** to remove the labels.
+
+To change a label, delete the existing label and add a new one.
+
+## Cost and billing integration
+
+Labels appear in invoices on the [Billing page]({% link cockroachcloud/billing-management.md %}#view-credits-balance).
+
+## Best Practices
+
+- Define a consistent labeling taxonomy (e.g., `team`, `env`, `app`) across your organization.
+- Use autocomplete in the console to prevent key duplication.
+- Review and remove unused or outdated labels regularly.

src/current/releases/cloud.md

@@ -14,6 +14,10 @@ Get future release notes emailed to you:
 
 {% include marketo.html formId=1083 %}
 
+## TBD
+
+You can now use the CockroachDB {{ site.data.products.cloud }} Console to [edit the labels of a cluster or folder]({% link cockroachcloud/labels.md %}).
+
 ## April 3, 2025
 
 You can now [change cluster plans between {{ site.data.products.basic }} and {{ site.data.products.standard }}]({% link cockroachcloud/change-plan-between-basic-and-standard.md %}) from the CockroachDB {{ site.data.products.cloud }} Console.