Skip to main content

​
Overview

CockroachDB is a distributed SQL database that provides automatic replication, horizontal scalability, and built-in fault tolerance across multiple regions. This template deploys a multi-region CockroachDB cluster on Control Plane as a stateful workload with replica-direct load balancing. Each location runs a configurable number of replicas that discover and join one another using Control Plane’s internal DNS. On first deployment, the cluster initializes itself, creates a database and user, registers all regions, and sets the survival goal to SURVIVE REGION FAILURE.

​
What Gets Created

  • GVC — A dedicated GVC across the specified locations.
  • Stateful Workload — CockroachDB (v25.4.0) with per-location replica scaling and replica-direct load balancing.
  • Volume Set — Persistent ext4 storage (general-purpose-ssd) with final snapshot creation and 7-day retention.
  • Identity & Policy — An identity bound to the workload with reveal access to the startup and user secrets.
  • Secrets — A startup script for cluster join/initialization and an opaque secret for the database user credential.

​
Architecture

CockroachDB uses the Raft consensus protocol to replicate data across nodes. Each Control Plane location maps to a CockroachDB locality region, and replicas advertise their address via internal DNS (replica-N.WORKLOAD.LOCATION.GVC.cpln.local). With 3 or more regions and the SURVIVE REGION FAILURE survival goal, the cluster tolerates the complete loss of one region without impacting availability.

​
Installation

This template has no external prerequisites. To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

​
Configuration

The default values.yaml for this template: 
gvc:
  name: cockroach-gvc
  locations:
    - name: aws-us-east-2
      replicas: 3
    - name: aws-eu-central-1
      replicas: 3
    - name: aws-us-west-2
      replicas: 3

resources:
  cpu: 2000m
  memory: 4096Mi

database:
  name: mydb
  user: myuser

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)

cockroach_defaults:
  sql_port: 26257
  http_port: 8080

internal_access:
  type: same-gvc # options: same-gvc, same-org, workload-list
  workloads: # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

​
Locations and Replicas

Configure the gvc.locations section to control which regions the cluster spans and how many replicas run in each.
While CockroachDB can run on 2 locations, a minimum of 3 locations with 3 replicas per location is recommended. This is the minimum required for CockroachDB to survive a full region failure.
Setting a location’s replicas to 0 suspends the workload in that location without removing it from the configuration.

​
Database Initialization

The database section specifies a database and user to create automatically when the cluster first initializes: 
database:
  name: mydb
  user: myuser
The created user is granted full access to the specified database. These values are only applied on the first initialization — they are skipped if the cluster has already been initialized (e.g., after a restart or upgrade).

​
Resources and Storage

  • resources.cpu and resources.memory set the CPU and memory allocated to each CockroachDB replica.
  • volumeset.capacity sets the initial persistent volume size in GiB (minimum 10).

​
Internal Access

The internal_access section controls which workloads can reach the CockroachDB cluster internally:
TypeDescription
same-gvcAllow access from all workloads in the same GVC
same-orgAllow access from all workloads in the same organization
workload-listAllow access only from specific workloads listed in workloads (can be combined with same-gvc)
When using workload-list, specify each workload using its full link format: 
internal_access:
  type: workload-list
  workloads:
    - //gvc/GVC_NAME/workload/WORKLOAD_NAME

​
Connecting to CockroachDB

Once deployed, the SQL interface is available on port 26257 (default). You can connect from a workload within the same GVC using: 
cockroach sql --insecure
The DB Console (HTTP UI) is available on port 8080 for monitoring cluster health, query performance, and node status.
This template deploys CockroachDB in insecure mode (no TLS). It is intended for internal workloads that connect through Control Plane’s internal network.
This template creates a GVC with a default name defined in the values file. If you plan to deploy multiple instances, you must assign a unique GVC name for each deployment.

​
External References

CockroachDB Documentation

Official CockroachDB documentation

Multi-Region Overview

Learn about multi-region deployments

Survive Region Failure

Configure region failure survival goals

CockroachDB Template

View the source files, default values, and chart definition