CockroachDB Cloud is a fully-managed deployment of CockroachDB. This page describes CockroachDB Cloud's architecture and how it relates to CockroachDB.
For an intro to CockroachDB's core architecture and capabilities, see CockroachDB Architecture or take the free Introduction to Distributed SQL and CockroachDB course on Cockroach University.
CockroachDB Cloud terms
Organization
In CockroachDB Cloud, an organization corresponds to an authorization hierarchy rooted linked to a billing account. The admins of the organization can add or invite other users to it.
To learn more, refer to Overview of the CockroachDB Cloud authorization model.
User
A CockroachDB Cloud user can belong to one or more organizations.
Organization users are granted permissions to perform organization and cluster administration functions through one or more roles: Organization user roles.
The concept of Organization user is distinct from SQL user/role in any given cluster.
Learn more: Overview of the CockroachDB Cloud authorization model.
Service Account
A service account is a type of identity similar to an Organization user, but is intended to be used for automation.
Service accounts authenticate with API keys to the CockroachDB Cloud API, rather than to the CockroachDB Cloud Console UI.
Service accounts operate under a unified authorization model with organization users, and can be assigned all of the same organization roles as users.
To learn more, refer to Manage Service Accountsmanaging-access.html#manage-service-accounts)
CockroachDB Serverless cluster
A CockroachDB Cloud cluster deployed on request for a specific customer in shared network and compute infrastructure.
CockroachDB Dedicated cluster
A CockroachDB Cloud cluster deployed on request for a specific customer, in a cloud provider's network and compute infrastructure dedicated to that customer, which can be distributed over multiple regions for added disaster-resilience. In addition to infrastructure isolation, dedicated clusters can be customized with advanced network, identity-management, and encryption-related security features.
Request Unit (RU)
Represents the compute and I/O resources used by a query. All database operations in CockroachDB Serverless cost a certain amount of RUs depending on the resources used. For example, a "small read" might cost 2 RUs, and a "large read" such as a full table scan with indexes could cost a large number of RUs. You can see how many Request Units your cluster has used on the Cluster Overview page.
Resource limits
The maximum amounts of storage and RUs a CockroachDB Serverless cluster can use in a particular billing period. The amount you are billed is based on the actual resources the cluster used during that billing period.
Storage
Disk space for permanently storing data over time. All data in CockroachDB Serverless is automatically replicated three times and distributed across Availability Zones to survive outages. Storage is measured in units of GiB-months, which is the amount of data stored multiplied by how long it was stored. Storing 10 GiB for a month and storing 1 GiB for 10 months are both 10 GiB-months. The storage you see in the Cluster Overview page is the amount of data before considering the replication multiplier.
CockroachDB Dedicated
If you need a single tenant cluster with no shared resources, we recommend CockroachDB Dedicated. CockroachDB Dedicated supports single and multi-region clusters in Amazon Web Services and Google Cloud Platform. CockroachDB Dedicated is recommended for all workloads: lightweight and critical production.
Hardware
We use the Kubernetes offerings in AWS, GCP, and Azure (EKS, GKE, and AKS respectively) to run CockroachDB Cloud offerings.
Each single-region cluster has a minimum of three nodes spread across three availability zones (AZ) in a cloud provider region. Multi-region clusters are similar to single-region clusters, with nodes spread across three or more AZs in each region.
Security and Connection
CockroachDB Dedicated clusters are single tenant. This means that each new cluster gets its own virtual network, compute (cluster nodes), data storage (cluster disks) and IAM resources. Users connect to a CockroachDB Dedicated cluster by using a load balancer in front of each region which leads to one connection string per region. Clusters use TLS 1.3 for encrypting inter-node and client-node communication. VPC peering and AWS PrivateLink optionally ensure that cluster traffic does not flow to cloud infrastructure over public networks.
Azure Private Link is not yet available for CockroachDB Dedicated on Azure.
CockroachDB Cloud clusters also use digital certificates for inter-node authentication, SSL modes for node identity verification, and password authentication or digital certificates can be used for client identity verification. Refer to Authentication for more details.
Backups are encrypted in S3 and GCS buckets using the cloud provider keys.
Multi-region architecture
The diagram below shows a high-level representation of a CockroachDB Dedicated multi-region cluster:
CockroachDB Serverless
CockroachDB Serverless is a fully-managed, auto-scaling deployment of CockroachDB. Being familiar with the following concepts will help you understand our Serverless architecture. CockroachDB Serverless is ideal for lightweight applications, starter projects, development environments, and proofs of concept.
Architecture
CockroachDB Serverless is a managed multi-tenant deployment of CockroachDB. A Serverless cluster is an isolated, virtualized tenant running on a much larger physical CockroachDB deployment.
CockroachDB Serverless has separate compute and storage layers. The storage pods (KV pods) can be shared across users, and the compute pods (SQL pods) are unique to each user. These shared resources make CockroachDB Serverless architecture "multi-tenant," in contrast to the single tenant architecture of CockroachDB Dedicated.
Traffic comes in from the public internet and is routed by the cloud provider’s load balancer to a Kubernetes (K8s) cluster that hosts CockroachDB. K8s pods allow CockroachDB Serverless to limit SQL resource consumption for each user. They also minimize interference between pods that are scheduled on the same machine, giving each user a high-quality experience even when other users are running heavy workloads.
The following diagram is a high-level representation of what a typical Serverless cluster looks like:
Proxy pods allow many users to share the same IP address, balance loads across a user's available SQL pods, and automatically resume clusters that have been paused due to inactivity. They also detect and respond to suspected abuse of the service.
After the cloud load balancer routes a new connection to one of the proxy pods, the proxy pod will in turn forward that connection to a SQL pod owned by the connecting user. Each SQL pod is dedicated to just one user, and multiple SQL pods can be owned by the same user. Network security rules prevent SQL pods from communicating with one another unless they are owned by the same user.
Finally, the SQL pods communicate with the KV layer to access data managed by the shared storage pods, each of which stores that data in an AWS or GCP block storage system.
Performance
Your cluster's resource limits are the maximum amount of storage and RUs you can use in a month. If you reach your storage limit, your cluster will be throttled and you will only be able to delete data or increase your storage limit. If you reach your RU limit, your cluster will be disabled until the end of the billing cycle unless you increase your RU limit.
Free
All CockroachDB Cloud organizations are given 50 million Request Units and 10 GiB of storage for free each month. Free resources can be spent across all CockroachDB Serverless clusters in an organization and will appear as a deduction on your monthly invoice.
Paid
You must enter billing information and set resource limits if you've already created one free CockroachDB Serverless cluster. Higher resource limits will allow your cluster to scale to meet your application's needs and maintain a high level of performance. You can set your storage and RU limits separately to reflect your usage, or choose an unlimited amount of resources to prevent your cluster from ever being throttled or disabled.
Autoscaling
Serverless clusters also have the ability to scale to zero and consume no compute resources when there are no active queries. When there are no active queries, you will pay for the storage your app is using, but not for Request Units. To avoid wasted resources, CockroachDB Cloud automatically pauses Serverless clusters that are inactive, which is defined by having no connection to the cluster for five consecutive minutes. Once the user attempts to reconnect to the cluster, the cluster will automatically resume. Pausing, resuming, and scaling clusters is a fully-managed process and will not disrupt or affect the user experience. However, it is important for your application to have connection retry logic in the event of node restarts or network disruptions. For more information, see the Production Checklist.
The diagrams below shows how CockroachDB Serverless autoscales with your application's traffic:
Learn more
See the CockroachDB architecture documentation for more information.
Was this helpful?
