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,83 @@
+---
+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 that you can attach to CockroachDB {{ site.data.products.cloud }} resources. Unlike folders, which allow one-to-many relationships, labels support many-to-many relationships, ideal for complex environments which require a variety of tagging criteria.
+
+## Common use cases
+
+You can set labels for:
+
+- **Environment tracking**: Distinguish between stages like `environment:production`, `environment:staging`, or `environment:test` to simplify deployment workflows and access control.
+- **Cost allocation**: Use labels like `team:analytics` or `cost_center:finance` to track usage and spending across departments in billing exports.
+- **Ownership and accountability**: Assign operational responsibility with labels such as `team:order-management` or `owner:platform-engineering`.
+- **Automation and lifecycle management**: Automate actions using labels like `state:active`, `state:archive`, or `state:ready-to-delete` in scripts and infrastructure-as-code tools.
+- **Custom organization**: Apply labels based on application, region, or any other criteria relevant to your workflows, e.g. the application, workload, or region applicable to a cluster.
+
+These labels can then be used to:
+
+- Filter and group resources in the Console.
+- Power cost reports and analytics.
+- Drive automation through APIs or Terraform.
+- Provide consistent metadata across teams and environments.
+
+## Requirements for labels
+
+The labels applied to a resource must meet the following requirements:
+
+- Each resource can have up to 50 labels.
+- Label keys are required, and must start with a lowercase letter and can include lowercase letters, numbers, underscores, and dashes (up to 63 characters).
+- Label values can include only lowercase letters, numbers, dashes, and must be between 0 and 63 characters.
+- Keys are unique per resource. For example, if cluster A has a label `environment:production`, it cannot also have a label `environment:development`.
+- Across the organization, each key can have multiple values. For example, folder A can have a label `environment:development`, folder B can have a label `environment:testing`, and folder C can have a label `environment:production`.
+- 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/) or using the CockroachDB Cloud API (refer to the schema for creating a [cluster](https://www.cockroachlabs.com/docs/api/cloud/v1#post-/api/v1/clusters) or [folder](https://www.cockroachlabs.com/docs/api/cloud/v1#post-/api/v1/folders)) or [Terraform provider](https://registry.terraform.io/providers/cockroachdb/cockroach/latest/docs).
+
+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 cluster 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 folder 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 changes. A success or failure notification will appear at the top right.
+
+### 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 apply the changes. A success or failure notification will appear at the top right.
+
+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 the duplication of keys.
+- Regularly review and remove unused or outdated labels.

src/current/releases/cloud.md

@@ -14,6 +14,10 @@ Get future release notes emailed to you:
 
 {% include marketo.html formId=1083 %}
 
+## April 30, 2025
+
+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.