This feature is in and subject to change. To share feedback and/or issues, contact Support.
cockroach process on a node handles all system and user activity, and manages the cluster’s control plane and data plane. When cluster virtualization is enabled, the cockroach process on a node runs both a system virtual cluster and one or more virtual clusters.
- The system virtual cluster manages the cluster’s control plane and virtual clusters. Administrative access to the system virtual cluster can be restricted. Certain low-level cluster settings can be modified only on the system virtual cluster.
- A virtual cluster manages its own data plane. Administrative access on a virtual cluster does not grant any access to the system virtual cluster. Some settings are scoped to a virtual cluster rather than the system virtual cluster.
Differences when cluster virtualization is enabled
When cluster virtualization is enabled, CockroachDB’s behavior changes in several key areas, as described in the following sections. For details about working with a cluster with cluster virtualization enabled, refer to .Connecting to a cluster
When cluster virtualization is enabled, when you connect usingcockroach sql or the , you are connected to the default virtual cluster. To connect to the system virtual cluster, you set -ccluster=system in the connection string (for SQL clients) or the DB Console URL. For details, refer to .
Cluster settings
When is enabled, each is scoped to either a virtual cluster or the system virtual cluster. For more details, including the scope of each cluster setting, refer to .Security
By default, when connecting to a cluster using a SQL client or the DB Console, if a user does not specify whether to connect to a virtual cluster or the system virtual cluster, they are connected to the default virtual cluster. To grant access to the system virtual cluster, you must connect to the system virtual cluster as a user with theadmin role, then grant the admin role to the SQL user. For details, refer to .
Upgrades
To upgrade to a new major version when cluster virtualization is enabled, you must first replace the binary on each node and restart the node, the upgrade on the system virtual cluster to upgrade it, then finalize the upgrade on a virtual cluster to upgrade it. This allows you to roll back an upgrade of the system virtual cluster without impacting schemas or data in virtual clusters. The system virtual cluster can be at most one major version ahead of virtual clusters. For example, a system virtual cluster on CockroachDB v24.1 can have virtual clusters on CockroachDB v23.2. For details, refer to .Observability
When cluster virtualization is enabled, cluster log messages and metrics are scoped to a virtual cluster or to the system virtual cluster, and are labeled with the name of the virtual cluster they relate to. For details and examples, refer to:- Most pages and views are scoped to a virtual cluster.
- Metrics which measure SQL and related activity show data scoped to the virtual cluster. All other metrics are collected system-wide and display the same data on all virtual clusters including the system virtual cluster.
- DB Console pages related to SQL activity and jobs for a given virtual cluster are visible only when logged in to that virtual cluster.
- Some pages and views are by default viewable only from the system virtual cluster, including those pertaining to overall cluster health.
Replication
can be configured only in a virtual cluster, and are not applicable to thesystem virtual cluster.
Node draining
When cluster virtualization is enabled, can cause a temporary SQL latency spike.See also
Known Limitations
In CockroachDB v24.1, cluster virtualization has the following limitations:- Currently, a single physical cluster can have a maximum of one system virtual cluster and one virtual cluster.