Kubernetes Deployment

Kubernetes is a portable, extensible platform for managing containerized workloads. You can deploy CockroachDB on Kubernetes using multiple approaches.

Deployment methods

CockroachDB Operator

Recommended for production. Automates cluster creation and management.

Helm Charts

Package manager for Kubernetes. Good for customizable deployments.

Manual StatefulSet

Maximum control with manual configuration files.

This guide focuses on the CockroachDB Operator method, which is recommended for most deployments.

Prerequisites

Kubernetes version

Kubernetes 1.30 or higher (for CockroachDB v25.1+)
Use a version with active patch support from the Kubernetes project

Resource requirements

Minimum per pod: 2 vCPUs and 8 GiB memory
Recommended for production: 4 vCPUs and 16 GiB memory
At least 3 nodes for a production cluster

Storage

Use local SSDs for best performance
Configure persistent volume provisioning
Avoid network-attached storage when possible

Network

PostgreSQL wire protocol is incompatible with SNI-based routing
Use a dedicated TCP load balancer for CockroachDB
Configure VPC peering for multi-region deployments

Start Kubernetes cluster

Google Kubernetes Engine (GKE)
Amazon EKS
Azure Kubernetes Service (AKS)

Install prerequisites

Install gcloud and kubectl:

# Follow Google Cloud SDK installation instructions
gcloud components install kubectl

Create cluster

gcloud container clusters create cockroachdb \
  --machine-type n2-standard-4 \
  --region us-east1 \
  --num-nodes 1

This creates a regional cluster with:

Machine type: n2-standard-4 (4 vCPUs, 16 GB memory)
One node per zone across 3 zones

Configure RBAC

Get your Google Cloud email:

gcloud info | grep Account

Create cluster role binding:

kubectl create clusterrolebinding $USER-cluster-admin-binding \
  --clusterrole=cluster-admin \
  [email protected]

Install prerequisites

Install AWS CLI, eksctl, and kubectl:

# Follow AWS CLI and eksctl installation instructions

Create cluster

eksctl create cluster \
  --name cockroachdb \
  --nodegroup-name standard-workers \
  --node-type m6i.xlarge \
  --nodes 3 \
  --nodes-min 1 \
  --nodes-max 4 \
  --node-ami auto

Cluster creation takes 10-15 minutes.

Verify cluster

Check the AWS CloudFormation console for successful stack creation:

eksctl-cockroachdb-cluster
eksctl-cockroachdb-nodegroup-standard-workers

Set environment variables

export MY_RESOURCE_GROUP_NAME=my-resource-group
export MY_AKS_CLUSTER_NAME=cockroachdb

Create cluster

az aks create \
  --resource-group $MY_RESOURCE_GROUP_NAME \
  --name $MY_AKS_CLUSTER_NAME \
  --node-count 3 \
  --generate-ssh-keys

Configure authentication

For non-managed identity deployments, create a secret:

apiVersion: v1
kind: Secret
metadata:
  name: azure-cluster-identity-credentials-secret
type: Opaque
stringData:
  azure-credentials: |
    azure_tenant_id: {tenant-id}
    azure_client_id: {client-id}
    azure_client_secret: {client-secret}

Deploy CockroachDB with Operator

Clone Helm repository

git clone https://github.com/cockroachdb/helm-charts.git

Set environment variables

export CRDBOPERATOR=crdb-operator
export CRDBCLUSTER=cockroachdb
export NAMESPACE=cockroach-ns

Install the Operator

kubectl create namespace $NAMESPACE
helm install $CRDBOPERATOR ./cockroachdb-parent/charts/operator -n $NAMESPACE

Configure cluster values

Edit cockroachdb-parent/charts/cockroachdb/values.yaml:

cockroachdb:
  crdbCluster:
    regions:
      - code: us-central1
        nodes: 3
        cloudProvider: gcp
        namespace: cockroach-ns

GCP
AWS
Azure
Bare metal

cloudProvider: gcp

cloudProvider: aws

cloudProvider: azure

Remove the cloudProvider field entirely.

Configure resources

Set CPU and memory limits:

cockroachdb:
  crdbCluster:
    podTemplate:
      spec:
        resources:
          limits:
            cpu: 4000m
            memory: 16Gi
          requests:
            cpu: 4000m
            memory: 16Gi

Configure TLS certificates

Choose a certificate method:

Self-signed (default)
Custom CA
Manual certificates

cockroachdb:
  tls:
    enabled: true

Certificates are automatically generated.

Create CA certificate:

mkdir certs my-safe-directory
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

Configure values:

cockroachdb:
  tls:
    enabled: true
    selfSigner:
      enabled: true
      caProvided: true
      caSecret: {ca-secret-name}

Create all certificates:

mkdir certs my-safe-directory
cockroach cert create-ca --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-client root --certs-dir=certs --ca-key=my-safe-directory/ca.key
kubectl create secret generic cockroachdb-root --from-file=certs

Create node certificates:

cockroach cert create-node \
  localhost 127.0.0.1 \
  my-release-cockroachdb-public \
  my-release-cockroachdb-public.cockroach-ns \
  *.my-release-cockroachdb \
  *.my-release-cockroachdb.cockroach-ns.svc.cluster.local \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key
kubectl create secret generic cockroachdb-node --from-file=certs

Configure values:

cockroachdb:
  tls:
    enabled: true
    externalCertificates:
      enabled: true
      certificates:
        nodeSecretName: cockroachdb-node
        nodeClientSecretName: cockroachdb-root

Configure localities

Define locality mappings for replica distribution:

cockroachdb:
  crdbCluster:
    localityMappings:
      - nodeLabel: "topology.kubernetes.io/region"
        localityLabel: "region"
      - nodeLabel: "topology.kubernetes.io/zone"
        localityLabel: "zone"

For custom localities:

cockroachdb:
  crdbCluster:
    localityMappings:
      - nodeLabel: "topology.kubernetes.io/region"
        localityLabel: "region"
      - nodeLabel: "topology.kubernetes.io/zone"
        localityLabel: "zone"
      - nodeLabel: "example.datacenter.locality"
        localityLabel: "dc"

Install CockroachDB

helm install $CRDBCLUSTER ./cockroachdb-parent/charts/cockroachdb -n $NAMESPACE

Verify pods are running:

kubectl get pods -n $NAMESPACE

Expected output:

NAME                          READY   STATUS    RESTARTS   AGE
crdb-operator-655fbf7847-xxx  1/1     Running   0          10m
cockroachdb-0                 2/2     Running   0          45s
cockroachdb-1                 2/2     Running   0          45s
cockroachdb-2                 2/2     Running   0          45s

Access the cluster

Use SQL client

Create client pod

Download the client configuration:

curl -O https://raw.githubusercontent.com/cockroachdb/helm-charts/master/examples/client-secure.yaml

Edit the file and apply:

kubectl create -f client-secure.yaml

Connect to cluster

kubectl exec -it cockroachdb-client-secure \
  -- ./cockroach sql \
  --certs-dir=/cockroach/cockroach-certs \
  --host=cockroachdb-public

Run SQL commands

CREATE DATABASE bank;
CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);
INSERT INTO bank.accounts VALUES (1, 1000.50);
SELECT * FROM bank.accounts;

Access DB Console

Create admin user

CREATE USER roach WITH PASSWORD 'Q7gc8rEdS';
GRANT admin TO roach;

Port forward to service

kubectl port-forward service/cockroachdb-public 8080

Access console

Navigate to https://localhost:8080 and log in with your credentials.

Multi-region deployment

For multi-region clusters, configure multiple region definitions:

cockroachdb:
  clusterDomain: cluster.gke.gcp-us-east1
  crdbCluster:
    regions:
      - code: us-central1
        nodes: 3
        cloudProvider: gcp
        domain: cluster.gke.gcp-us-central1
        namespace: cockroach-ns
      - code: us-east1
        nodes: 3
        cloudProvider: gcp
        domain: cluster.gke.gcp-us-east1
        namespace: cockroach-ns

Multi-region deployments require:

VPC peering between regions
CoreDNS for cross-region service discovery
Single CA certificate across all regions
One operator deployment per region

Best practices

Storage

Use local SSDs instead of network-attached storage
Provision sufficient IOPS for your workload
Monitor disk usage regularly

Resources

Set resource requests equal to limits
Don’t use burstable or shared-core instances
Plan for 4 GiB RAM per vCPU

Topology

Spread pods across availability zones
Use topology spread constraints
Configure anti-affinity rules

Security

Always enable TLS for production
Rotate certificates before expiration
Use network policies to restrict access

Stop the cluster

To delete the cluster:

helm uninstall $CRDBCLUSTER -n $NAMESPACE
helm uninstall $CRDBOPERATOR -n $NAMESPACE
kubectl delete namespace $NAMESPACE

To delete the Kubernetes cluster:

gcloud container clusters delete cockroachdb --region us-east1

Deleting the Kubernetes cluster without removing persistent volumes will leave them in your cloud project.

Get Started

Architecture

Core Concepts

Deployment

SQL Reference

Operations

Migration

Developer Guide

Kubernetes Deployment

Deployment methods

CockroachDB Operator

Helm Charts

Manual StatefulSet

Prerequisites

Kubernetes version

Resource requirements

Storage

Network

Start Kubernetes cluster

Deploy CockroachDB with Operator

Access the cluster

Use SQL client

Access DB Console

Multi-region deployment

Best practices

Storage

Resources

Topology

Security

Stop the cluster

Next steps

Build docs developers (and LLMs) love

Get Started

Architecture

Core Concepts

Deployment

SQL Reference

Operations

Migration

Developer Guide

​Deployment methods

CockroachDB Operator

Helm Charts

Manual StatefulSet

​Prerequisites

​Kubernetes version

​Resource requirements

​Storage

​Network

​Start Kubernetes cluster

​Deploy CockroachDB with Operator

​Access the cluster

​Use SQL client

​Access DB Console

​Multi-region deployment

​Best practices

Storage

Resources

Topology

Security

​Stop the cluster

​Next steps

Build docs developers (and LLMs) love

Deployment methods

Prerequisites

Kubernetes version

Resource requirements

Storage

Network

Start Kubernetes cluster

Deploy CockroachDB with Operator

Access the cluster

Use SQL client

Access DB Console

Multi-region deployment

Best practices

Stop the cluster

Next steps