For self-hosted organizations running Kubernetes, StatefulSets are powerful, but they aren't CockroachDB-aware. They don't know how to decommission a node safely, manage a multi-region topology, or make rolling upgrade decisions with the cluster's health in mind. The result is operational glue: scripts, manual upgrade sequences, certificate rotations and work that has to be re-run every time there’s changes. It's not a CockroachDB problem or a Kubernetes problem; it's that these two worlds were never properly connected.
Today we are excited to announce that we are bridging these two worlds with the launch of the CockroachDB Kubernetes Operator. With this, we are also announcing the deprecation/EOL timeline of the legacy Public Kubernetes Operator (see more information below).
The new operator is fully battle-tested and ready for production workloads. It's the same operator Cockroach Labs has run alongside CockroachDB Cloud to manage 600+ clusters for nearly three years. That production experience helped shape the General Availability (GA) release and demonstrated that the operator is designed for real operational workflows, not just day-0 cluster creation.
Why use the CockroachDB Kubernetes Operator?
The operator uses CockroachDB-specific custom resources and separates cluster-level from node-level reconciliation, giving it the context to make safe operational decisions automatically. Where StatefulSets can run CockroachDB, the operator is built to operate it — giving your platform team time back and a consistent model across dev, staging, and production. With it, you can:
Automate recurring work: deployment, rolling upgrades, scaling, certificate rotation, and storage management
Cover the full lifecycle, day 0 through day 2, through Kubernetes-native configuration
Fit your existing workflow for Helm, GitOps, private registries, and air-gapped environments are all supported
Run multi-region natively, mapping CockroachDB locality to Kubernetes node labels
What does full lifecycle management actually look like?
Production success depends just as much on what happens after the first deployment, and the operator is built for this. For platform engineers who want the details, here's what the CockroachDB Kubernetes Operator covers across the full operational lifecycle.
Day 0 — Secure deployment: TLS via cert-manager, externally managed, or self-signed certificates, plus post-init SQL for declarative bootstrap of users, databases, and cluster settings.
Day 1 — Upgrades and scaling: Zero-downtime rolling upgrades through the reconciliation loop, pre-upgrade validations that block unsafe changes, and scaling that respects node health, replication, and topology.
Day 2 — Storage, topology, and observability: Dedicated log stores, WAL failover, and storage expansion; native multi-region orchestration; Prometheus-format metrics; and advanced capabilities like CMEK and physical cluster replication, surfaced as configuration rather than custom scripts.
See it in action: An example of adding a region to a CockroachDB cluster
Adding a second region to a live cluster used to mean runbooks, maintenance windows, manual configuration, and risk. This scenario shows how the operator makes it fast, scalable, and safe within production environments.
Say you're running in us-central1 and the business needs a second region in us-east1:
With the CockroachDB operator, adding that second region is a declarative change to one field:
apiVersion: crdb.cockroachlabs.com/v1beta1
kind: CrdbCluster
metadata:
name: cockroachdb
namespace: cockroachdb
spec:
tlsEnabled: true
regions:
- code: us-central1
cloudProvider: gcp
domain: cluster.gke.gcp-us-central1
namespace: cockroachdb
nodes: 3
- code: us-east1
cloudProvider: gcp
domain: cluster.gke.gcp-us-east1
namespace: cockroachdb
nodes: 3
rollingRestartDelay: 30s
template:
spec:
image: cockroachdb/cockroach:v26.2.3
localityMappings:
- nodeLabel: topology.kubernetes.io/region
localityLabel: region
- nodeLabel: topology.kubernetes.io/zone
localityLabel: zoneYou apply the same manifest in each cluster and confirm the result with familiar tooling:
kubectl -n cockroachdb get crdbclusters,crdbnodes,pods CockroachDB handles data distribution, replication, and SQL consistency across both regions. Your team keeps using standard Kubernetes controls for scheduling, RBAC, storage, and observability. What used to be a runbook is now a few lines of config.
Complete a zero-downtime migration migrate (for existing customers)
Customers running the earlier public operator or StatefulSet-based Helm charts can adopt the GA operator through an opt-in, automatic migration controller that:
Replaces nodes one at a time, not all at once
Keeps your application online throughout, with no maintenance windows required
Verifies CockroachDB cluster health between each step before proceeding
Preserves your data (disks and certificate configuration are migrated, not replaced)
Supports full rollback at any phase if you need to stop and reverse
For customers that prefer to do a manual migration, there's documentation for that as well:
Old public operator → new operator - automatic (recommended) or manual
StatefulSet Helm deployment → new operator - automatic (recommended) or manual
Get started with packaging that fits your workflow (for new customers)
The GA operator meets Kubernetes teams where they already work, with two ways to install and manage it: Helm, or Kubernetes manifests applied directly with kubectl, Argo CD, or Flux. Pick whichever matches your release, approval, and automation model.
With Helm, the operator ships as two independent charts, so you can version and patch the database on its own schedule, pin releases in GitOps repos, and promote across environments at your own pace:
cockroachdb-operator-chart— installs and upgrades the operatorcockroachdb-chart— installs and upgrades the CockroachDB clusters it manages
Prefer not to use Helm? Apply the checked-in Kubernetes manifests directly: standalone CRDs, v1beta1 API spec, and a rendered operator bundle you install with kubectl and customize with Kustomize or a GitOps overlay.
End-of-life timeline for the legacy Public Kubernetes Operator
If you are running the legacy Public Kubernetes Operator, we recommend migrating soon, ahead of the CockroachDB 27.3 launch (summer 2027).
The legacy Public Operator (cockroachdb/cockroach-operator) and the legacy StatefulSet Helm charts will remain fully supported until 27.3. When 27.3 launches, both will enter a 12-month maintenance period. During this time, they will receive critical bug fixes, security patches, and CVE fixes, but no new features and no support for CockroachDB 27.3 or later.
At the end of the 12-month maintenance period, both the legacy Public Operator and the legacy StatefulSet Helm charts will reach end-of-life.
From 27.3 onward, the CockroachDB Operator will be the standard way to run and manage CockroachDB in self-hosted Kubernetes environments.
Production-proven at scale
Kubernetes is the standard platform for running production infrastructure, yet distributed databases have long been the exception, demanding specialized operational knowledge and hand-built automation. The CockroachDB Kubernetes Operator ends that trade-off. It gives platform teams a Kubernetes-native way to deploy, operate, and scale CockroachDB safely, from your first cluster to hundreds in production.
Whether you are launching a new application or migrating an existing fleet, the operational work that once lived in runbooks and brittle scripts is now automated, so your team can focus on building software instead of babysitting databases.
To get started, read the documentation. To start your zero-downtime migration, review the migration documentation.
Happy building!
