Organize CockroachDB Cloud Resources Using Labels

CockroachDB Cloud supports labels as a flexible way to categorize and manage your clusters and folders. Labels help you track usage, analyze billing, automate operations, and streamline reporting across your organization.

What are labels?

Labels are customizable key-value pairs that you can attach to CockroachDB Cloud resources. Unlike folders, which allow only one-to-many relationships, labels support many-to-many relationships which is ideal for complex environments with overlapping ownership or multiple tagging criteria.

Examples

• Team or cost center labels: Add labels based on team or cost center to distinguish resources owned by different teams (for example, team:research and team:analytics). You can use this type of label for cost accounting or budgeting.

• Environment or stage labels: For example, environment:production and environment:test.

• State labels: For example, state:active, state:readytodelete, and state:archive.

• Ownership labels: Used to identify the teams that are responsible for operations, for example, team:shopping-cart.

Why use labels?

• Flexible Organization: Tag clusters and folders by team, environment, application, or another 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.

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 Cloud Console.

Adding or deleting labels on a cluster requires the Cluster Admin or Cluster Operator role.

1. Navigate to the cluster on the Clusters page and click the menu button in the Action column. Alternatively, navigate to the Overview page 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 role.

1. Navigate to the folder on the 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.
2. Click + Add. The label appears under Labels applied.
3. Repeat steps 1 and 2 to add more labels.
4. 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.
2. Repeat step 1 to delete more labels.
3. 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.

Best Practices

• Define a consistent labeling taxonomy (e.g., team, env, app) across your organization.
• Use autocomplete in the console to prevent key duplication.
• Regularly review and remove unused or outdated labels.