Workspaces and Host Clusters

This feature is in and subject to change. To share feedback and/or issues, contact Support.

This page describes how to create workspaces and host clusters, and how they act as containers of virtual clusters.

Key concepts

A workspace groups virtual clusters on a host cluster and defines default configurations for the virtual clusters created within, such as setting the default max compute. Developers select a workspace when creating a virtual cluster. A host cluster is a Mission Critical cluster created with the Cluster Virtualization add-on, which enables virtualization. Virtualization can only be enabled on cluster creation; an existing cluster cannot be converted into a host. In every other respect a host behaves like a Mission Critical cluster, and you scale and operate it like any dedicated cluster hardware. You pay for the host and the Cluster Virtualization add-on. The virtual clusters on it carry no separate charge. Each host cluster has one workspace, created with the host, with permissive default policies.

Capacity planning and utilization

Host clusters have a minimum size of 3 nodes with 4 vCPUs each. You may want to increase capacity and node count based on the anticipated growth of virtual cluster count and usage within your organization, but because virtual clusters themselves scale automatically and have a controlled vCPU burst limit, you can provision a smaller configuration and use observability tools on the host to determine if growth is necessary.

Virtual clusters are not recommended for tier 0 applications and workloads such as payments, authorizations, and order processing. Consider a dedicated Mission Critical cluster for these workloads.

Cockroach Continuum tracks the host’s total capacity against the capacity reserved by its virtual clusters, which shows the headroom remaining before you create more virtual clusters or scale the host.

Host configuration inheritance

When a virtual cluster is created, it inherits some configuration details from the host cluster that can not be configured on the virtual cluster itself. Note the following before creating a host cluster:

Supported regions: A virtual cluster can have a custom-set primary region bespoke for that cluster, but a virtual cluster cannot add regions not supported on the host.
Running CockroachDB version: The CockroachDB version is inherited from the host. Upgrades to a new version are performed on the host cluster and apply to all virtual clusters on that host.

These host configuration inheritance restrictions are different from workspaces, which assign a default configuration to clusters created within but can also be adjusted on a per-cluster basis.

Workspace policies

Workspaces can be configured to enforce the maximum compute per virtual cluster. Each virtual cluster created in a workspace is assigned a default compute ceiling of 50% of the host cluster’s total capacity. Ceilings are defaults, not reservations, and the sum of ceilings can exceed the host’s capacity. A workspace’s policies are enforced when a virtual cluster is created in the workspace.

Create a host cluster and workspace

You can create a host cluster in the Cloud Console, with the ccloud CLI, or with the CockroachDB Cloud API.

Cloud Console

To create a host cluster in the Cloud Console, follow these steps:

Log in to your Cockroach Continuum organization.
On the Clusters page, click New cluster -> Create cluster.
Select the Mission Critical edition.
Enable the Dedicated host toggle.
Configure your host cluster as desired, considering how you want to provision the host capacity and configuration inheritance.
Click Create cluster.

After cluster creation is started, you will be prompted to name the workspace on this host cluster. This workspace name is how users creating a virtual cluster will select a host, not the host name itself, so best practice is to give this workspace a descriptive name such as a team or project. By default the vCPU burst limit is set to 1/2 of the total provisioned vCPU on the host cluster. This value can be modified for a workspace using the ccloud CLI or the Cloud API.

ccloud CLI

To create a host cluster using the ccloud CLI, follow these steps:

Log into your organization with ccloud auth:
ccloud auth
Run ccloud cluster create mission-critical with the --dedicated-host flag to create a host cluster, and the desired values for the cluster configuration with consideration for how you want to provision the host capacity and configuration inheritance:
ccloud cluster create mission-critical {cluster-name} us-east-1:3 --cloud AWS --vcpus 4 --storage-gib 110 --dedicated-host
When a host cluster is created, a default workspace is created that inherits the host cluster’s name and sets the default vCPU burst limit to 1/2 of the total provisioned vCPU on the host cluster. To modify the workspace name and configuration:
1. List workspaces in the organization to get the of the newly-created workspace:
  ccloud workspace list
2. Update the name and configuration as desired. This workspace name is how users creating a virtual cluster will select a host, not the host name itself, so best practice is to give this workspace a descriptive name such as a team or project:
  ccloud workspace update {workspace-id} --name {new-workspace-name} --default-virtual-cpu-burst-limit {new-burst-limit}

You can omit --name or --default-virtual-cpu-burst-limit to leave their value as-is. Note that modifying the workspace configuration only updates the default configuration applied to newly-created virtual clusters in the workspace, not any virtual clusters that are already deployed.

Cloud API

To create a host cluster with the Cloud API, send a POST request to the /v1/clusters endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","edition":"MISSION_CRITICAL","spec":{"host":{"region_nodes":{"{region_name}":3},"hardware":{"machine_spec":{"num_virtual_cpus":{num_vcpus}}},"cockroach_version":"{version}"}}}'

{
  "name":"{cluster_name}",
  "provider":"{cloud_provider}",
  "edition":"MISSION_CRITICAL",
  "spec":{
    "host":{
      "region_nodes":{
        "{region_name}":3
      },
      "hardware":{
        "machine_spec":{
          "num_virtual_cpus":{num_vcpus}
        }
      },"cockroach_version":"{version}"
    }
  }
}

Set the parameter fields as desired for your configuration, with consideration for how you want to provision the host capacity and configuration inheritance:

{cluster_name} is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
{cloud_provider} is the name of the cloud provider on which you want your cluster to run: AWS or GCP.
edition is set to MISSION_CRITICAL for a host cluster.
{region_name} is the name of a CockroachDB Cloud region. Region names are set by the cloud provider. For example, us-east-1 is an AWS region. Available regions vary based on the cloud provider.
region_nodes specifies the number of nodes in each region. The minimum is 3 nodes per region for a Mission Critical/host cluster.
{num_vcpus} is the number of virtual CPUs per node in the cluster. This value determines the machine type that is provisioned. Host clusters require a minimum of 4 vCPUs.
{version} is the CockroachDB version for the cluster.

When a host cluster is created, a default workspace is created that inherits the host cluster’s name and sets the default vCPU burst limit to 1/2 of the total provisioned vCPU on the host cluster. To modify the workspace name and configuration, first send a GET request to the /v1/virtual-cluster-workspaces endpoint to get the {workspace-id} of the newly-created workspace

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces \
  --header "Authorization: Bearer {secret_key}"

Send a PATCH request to the /v1/virtual-cluster-workspaces/{workspace-id} endpoint to modify the name and configuration of the workspace as desired. This workspace name is how users creating a virtual cluster will select a host, not the host name itself, so best practice is to give this workspace a descriptive name such as a team or project:

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces/{workspace-id} \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{new_workspace_name}","default_virtual_cpu_burst_limit":"{value}"}'

{
  "name":"{new-workspace-name}",
  "default_virtual_cpu_burst_limit":"{value}"
}

You can omit any of the workspace parameters to leave the value as-is. Note that modifying the workspace configuration only updates the default configuration applied to newly-created virtual clusters in the workspace, not any virtual clusters that are already deployed.

Access control

Host clusters use Cockroach Cloud cluster roles and permissions, there are no bespoke access controls for cluster virtualization.

Lifecycle and limits

An organization can have up to 3 host clusters.
Hosts run on AWS and GCP only.
A host cluster cannot be deleted while virtual clusters exist on it.
Virtualization cannot be added to or removed from an existing cluster.
A host cluster can only support one workspace.

Onboard Data and Build Applications

Scale Production Workloads

Monitor and Optimize Performance

Integrate and Govern Your Ecosystem

Workspaces and Host Clusters

Key concepts

Capacity planning and utilization

Host configuration inheritance

Workspace policies

Create a host cluster and workspace

Cloud Console

ccloud CLI

Cloud API

Access control

Lifecycle and limits

​Key concepts

​Capacity planning and utilization

​Host configuration inheritance

​Workspace policies

​Create a host cluster and workspace

​Cloud Console

​ccloud CLI

​Cloud API

​Access control

​Lifecycle and limits

Key concepts

Capacity planning and utilization

Host configuration inheritance

Workspace policies

Create a host cluster and workspace

Cloud Console

ccloud CLI

Cloud API

Access control

Lifecycle and limits