Virtualization Architecture

This page describes how Cockroach Continuum virtualization works: how virtual clusters share a host cluster’s hardware while keeping data, schema, and workloads isolated, and where the platform enforces the policies attached to a workspace.

​

Overview

A host cluster is a CockroachDB cluster whose nodes provide storage and compute for many tenants. Each virtual cluster is a tenant: it has its own portion of the keyspace, its own catalog and users, and its own SQL runtime, while sharing the host’s replicated storage layer. The Continuum control plane creates virtual clusters on hosts, routes each connection to the target virtual cluster, and applies the workspace’s policies when a virtual cluster is created or changed.

​

Host clusters

A host is a Mission Critical cluster with virtualization enabled at creation. A host cluster’s capacity is accounted in vCPUs. The platform tracks total capacity against the capacity reserved by its virtual clusters. Host clusters have a minimum size of 3 nodes and 4 vCPUs per node, run on AWS or GCP, and are limited to 3 per organization.

​

Virtual cluster internals

Each virtual cluster’s data lives in its own keyspace prefix on the host, so one virtual cluster cannot name, read, or write another’s tables. Schema metadata, users, and privileges are per virtual cluster. SQL execution for a virtual cluster runs in its own processes, which start on demand and stop when the virtual cluster is idle. Connection routing inspects the connection and delivers it to the target virtual cluster’s SQL layer. A virtual cluster supports on the order of 10,000 schema objects. This limit is per virtual cluster, not shared across the host.

​

Resource management and admission control

Virtual clusters draw compute from the host on demand. Admission control meters CPU time per virtual cluster, so a high-traffic virtual cluster cannot starve its neighbors. Each virtual cluster has a default compute ceiling set by its workspace. The sum of all ceilings across virtual clusters can exceed the host’s total capacity. This is by design; a ceiling is not a reservation, and no resources are pre-allocated. Virtual clusters only consume what they actively use.

​

Data placement, backups, and replication

A virtual cluster’s data is replicated by the host like any other data on the host, and inherits the host’s regional footprint. Backups are taken per virtual cluster, each to its own destination. Restores are scoped to a single virtual cluster without affecting its neighbors. Moving a virtual cluster to a different host is a backup and restore operation and involves downtime. No online migration tooling is available.

​

Observability boundaries

Application teams see metrics for their own virtual cluster: CPU, queries per second, storage, and connections. Platform teams additionally see the host-level view. Customer access to the host’s system tenant is read-only. Metrics can be exported to Prometheus or Datadog.

​

Known limitations

• 3 host clusters per organization.
• Hosts run on AWS and GCP only.
• Virtualization is chosen at host creation. An existing cluster cannot be converted into a host.
• On the order of 10,000 schema objects per virtual cluster.
• No per-virtual-cluster minimum-CPU guarantees.
• Moving a virtual cluster between hosts requires backup and restore with downtime.