CockroachDB on Kubernetes with Helm is not just about running a distributed database; it’s about running a database that expects to be distributed within an orchestration system that also expects to be distributed.
Let’s see it in action. Imagine you’ve got a Kubernetes cluster ready, and you’ve installed Helm.
helm repo add cockroachdb https://charts.cockroachdb.com/
helm repo update
Now, to deploy a basic, single-node CockroachDB cluster for testing:
helm install my-release cockroachdb/cockroachdb \
--namespace default \
--set clusterName="my-test-cluster" \
--set replicas=1 \
--set statefulset.volumeClaimTemplate.resources.requests.storage="10Gi"
This command tells Helm to pull the cockroachdb chart and install it as my-release in the default namespace. We’re explicitly setting the clusterName to my-test-cluster (though Helm often defaults this reasonably), ensuring we have 1 replica (for a single-node test setup), and requesting 10Gi of persistent storage.
After a few minutes, you can check the status:
kubectl get pods -l app.kubernetes.io/instance=my-release
kubectl get svc -l app.kubernetes.io/instance=my-release
You should see a pod like my-release-cockroachdb-0 running, and a service named my-release-cockroachdb that you can use to connect to your cluster. The default port for CockroachDB is 26257.
The problem this solves is the sheer operational overhead of managing a distributed database like CockroachDB manually. Kubernetes, with its declarative nature and self-healing capabilities, is a natural fit. Helm, as a package manager for Kubernetes, simplifies the deployment and management of complex applications like CockroachDB by abstracting away the underlying Kubernetes manifests (Deployments, StatefulSets, Services, ConfigMaps, Secrets, etc.) into a single, versionable chart.
Internally, the CockroachDB Helm chart orchestrates several Kubernetes resources. A StatefulSet is used to manage the database nodes, ensuring stable network identifiers and persistent storage for each replica. A Service provides a stable endpoint to access the cluster. ConfigMaps and Secrets are used to manage configuration and credentials. The chart also includes options for setting resource requests/limits, enabling TLS, configuring storage classes, and more.
When you run helm install, Helm renders the chart’s templates with your specified values, creating these Kubernetes objects. If a pod dies, Kubernetes will restart it. If a node fails, Kubernetes can reschedule the pod onto a healthy node. CockroachDB itself is designed to handle these disruptions gracefully, rebalancing data and maintaining quorum.
The levers you control are primarily through the values.yaml file or --set flags during helm install or helm upgrade. You can configure things like the number of replicas (replicas), resource allocation for pods (statefulset.resources), storage configuration (statefulset.volumeClaimTemplate), whether to enable secure communication (tls.enabled), and even custom CockroachDB configurations via extra.config.
A key detail often overlooked is how CockroachDB’s clusterName interacts with Kubernetes. While you set a clusterName in the Helm chart, CockroachDB itself uses this to identify the cluster within its own distributed system. Kubernetes, on the other hand, uses labels (like app.kubernetes.io/instance=my-release) to manage and select its resources. The Helm chart ensures these align correctly so that Kubernetes knows which pods belong to your CockroachDB cluster.
The next step is usually securing your CockroachDB deployment, perhaps by enabling TLS and managing certificates.