Virtualization Overview

Unlike a traditional database deployment, where every application that needs an isolated database requires a standalone infrastructure deployment with its own provisioning, billing, and operation, use virtual clusters with the in CockroachDB to quickly deploy multiple isolated databases on shared infrastructure. Create a host cluster in a CockroachDB organization, and you can create virtual clusters on the host cluster’s capacity. Each virtual cluster has its own connection string, users, schemas, and backups, is isolated from its neighbors on the same host cluster, and is governed by configurable policies. Creation of a virtual cluster does not require you to provision new infrastructure, enabling rapid deployment of isolated databases with the .

​

Use cases

Virtual clusters are ideal for organizations that need many isolated databases without the cost and complexity of a provisioned cluster per workload. With a dedicated host cluster created and provisioned with redundant architecture and maximum capacity, any number of virtual clusters can be created that share the total capacity of the host. This architecture supports rapid deployment of secure, isolated, resilient databases with no administrative overhead, maximizing the resource utilization of the provisioned host cluster. Some example use cases served well by this architecture include:

• Engineers and/or agents needing to deploy database instances for business application development with resiliency.
• Organizations that want to run multiple isolated databases of varying sizes and workloads without provisioning new infrastructure for each.
• Administrators of an existing CockroachDB deployment wanting to support application development at agentic speeds without the overhead of provisioning physical cluster and observability infrastructure.

​

Key concepts

• A host cluster is a cluster created with the Cluster Virtualization add-on. This option is only available when you ; an existing cluster cannot be converted to a host cluster. The host cluster provides the hardware that virtual clusters share. A host cluster behaves like any other CockroachDB cluster with its own nodes and the Mission Critical feature set.
• A virtual cluster is an isolated cluster created on a host. Virtual clusters are CockroachDB clusters, with their own connection strings, users, and schemas. A virtual cluster’s usage consumes the host’s capacity and is not billed separately.
• 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.

To deploy a host cluster and prepare a workspace, read . To deploy and use a virtual cluster, read or follow the .

​

Workload isolation

Each virtual cluster is isolated from other virtual clusters on the same host. Its data, SQL runtime, users, and schemas are its own, and connections route only to it, so an application connected to one virtual cluster cannot see or access another’s data. Data is isolated at the database layer, through enforcement at the SQL and admission-control layers. Virtual clusters on the same host share only the underlying physical storage infrastructure.

​

CPU management

CPU is managed automatically. CockroachDB tracks CPU usage per virtual cluster and throttles any that exceeds its isolated share, which is the same approach used by CockroachDB to manage . CPU management on host clusters works at two layers, the SQL layer and KV layer:

• SQL layer: Every virtual cluster has a default “burst limit”, which is the maximum CPU that it can consume at any point. A virtual cluster cannot exceed this limit regardless of how much capacity is available on the host.
• KV layer: When multiple virtual clusters are active simultaneously, CockroachDB distributes CPU fairly among them. No single virtual cluster is allowed to monopolize the host cluster’s resources at the expense of others.

​

Roles and responsibilities

The host and virtual cluster architecture is designed for two roles:

• A platform team that owns the shared host infrastructure. They create and manage host clusters, define workspaces, and set the policies that control what application teams do. The platform team has visibility across all hosts and virtual clusters.
• Application teams and/or agents that create, manage, and use virtual clusters within the workspaces the platform team has configured for them. Their visibility is limited to their own virtual clusters; they cannot see or access other teams’ data or virtual clusters.

These capabilities are controlled through CockroachDB’s privilege system. A user can perform actions associated with the platform or application team based on the privileges granted to their role. For details on roles and privileges in CockroachDB, see the and documentation.

​

See also