> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cluster Virtualization Overview

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This page gives an overview of *cluster virtualization* in CockroachDB . Cluster virtualization allows you to separate a cluster's *control plane* from its *data plane*. The cluster's control plane manages cluster nodes and node-to-node traffic, while its data plane reads data from and writes data to the cluster's storage.

Cluster virtualization is only necessary if you want to use <InternalLink path="physical-cluster-replication-overview">physical cluster replication (PCR)</InternalLink>. For details on how PCR works, refer to the <InternalLink path="physical-cluster-replication-technical-overview">Technical Overview</InternalLink>.

When cluster virtualization is disabled, the control plane and data plane are unified, and the `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.

<Tip>
  Cluster virtualization is enabled automatically when you configure <InternalLink path="physical-cluster-replication-overview">PCR</InternalLink>.
</Tip>

## 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 <InternalLink path="work-with-virtual-clusters">Work with virtual clusters</InternalLink>.

### Connecting to a cluster

When cluster virtualization is enabled, when you connect using `cockroach sql` or the <InternalLink path="ui-overview">DB Console</InternalLink>, 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 <InternalLink path="work-with-virtual-clusters#connect-to-a-virtual-cluster">Work with virtual clusters</InternalLink>.

<Tip>
  If a SQL user has been added to the system virtual cluster and one or more virtual clusters with the same username and password, that user can select which to connect to from the top of the DB Console.
</Tip>

### Cluster settings

When <InternalLink path="cluster-virtualization-overview">cluster virtualization</InternalLink> is enabled, each <InternalLink path="cluster-settings">cluster setting</InternalLink> is scoped to either a virtual cluster or the system virtual cluster.

For more details, including the scope of each cluster setting, refer to <InternalLink path="cluster-virtualization-setting-scopes">Cluster Setting Scopes with Cluster Virtualization enabled</InternalLink>.

### 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 the `admin` role, then grant the `admin` role to the SQL user. For details, refer to <InternalLink path="work-with-virtual-clusters#grant-access-to-the-system-virtual-cluster">Work with virtual clusters</InternalLink>.

### Upgrades

The system virtual cluster can be at most one <InternalLink version="releases" path="index#release-schedule">Regular release</InternalLink> ahead of virtual clusters. For example, a system virtual cluster on CockroachDB v24.3 can have virtual clusters on CockroachDB v24.1 (a Regular release) or v24.2 (an Innovation release). This allows you to roll back an upgrade of the system virtual cluster without impacting schemas or data in virtual clusters.

To upgrade to a new major version when cluster virtualization is enabled, you must:

1. Replace the binary on each node and restart the node.
2. <InternalLink path="upgrade-cockroach-version#finalize-a-major-version-upgrade-manually">Finalize</InternalLink> the upgrade on the system virtual cluster to upgrade it (if auto-finalization is disabled).
3. Finalize the upgrade on a virtual cluster to upgrade it (if auto-finalization is disabled).

For details, refer to <InternalLink path="work-with-virtual-clusters#upgrade-a-cluster">Work with virtual clusters</InternalLink>.

### Disaster recovery

When cluster virtualization is enabled, <InternalLink path="backup">backup</InternalLink> and <InternalLink path="restore">restore</InternalLink> commands are scoped to a virtual cluster. This means that:

* A backup taken from a virtual cluster contains all data for that virtual cluster, but does not contain modifications made via the system virtual cluster such as system-level cluster settings.
* If your deployment contains system-level customizations, you can take a separate backup of the system virtual cluster to capture them.
* A backup of a virtual cluster can be restored as a virtual cluster in any CockroachDB cluster with cluster virtualization enabled.

For more details about backing up and restoring a cluster with cluster virtualization enabled, refer to <InternalLink path="work-with-virtual-clusters#disaster-recovery">Work with virtual clusters</InternalLink>.

<Tip>
  For details about configuring and using PCR for disaster recovery, refer to <InternalLink path="physical-cluster-replication-overview">Physical Cluster Replication Overview</InternalLink>.
</Tip>

### 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:

* <InternalLink path="work-with-virtual-clusters#observability">Work with virtual clusters</InternalLink>
* <InternalLink path="cluster-virtualization-setting-scopes">Cluster setting scopes with Cluster Virtualization enabled</InternalLink>
* <InternalLink path="cluster-virtualization-metric-scopes">Cluster metric scopes with Cluster Virtualization enabled</InternalLink>

When connected to a virtual cluster from the DB Console:

* 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.

For more details, including how to adjust the DB Console's behavior, refer to <InternalLink path="work-with-virtual-clusters#observability">Work with virtual clusters</InternalLink>.

### Replication

<InternalLink path="configure-replication-zones">Replication zones</InternalLink> can be configured only in a virtual cluster, and are not applicable to the `system` virtual cluster.

## See also

* <InternalLink path="work-with-virtual-clusters">Work with virtual clusters</InternalLink>
* <InternalLink path="cluster-virtualization-setting-scopes">Cluster Setting Scopes</InternalLink>
* <InternalLink path="cluster-virtualization-metric-scopes">Cluster Metric Scopes</InternalLink>
* <InternalLink path="physical-cluster-replication-overview">Physical Cluster Replication</InternalLink>

## Known Limitations

In CockroachDB , cluster virtualization has the following limitations:

* Currently, a single physical cluster can have a maximum of one system virtual cluster and one virtual cluster.