Guides customer-facing installation of CockroachDB on Kubernetes using the CockroachDB split Helm charts and operator-managed v1beta1 resources. Use when installing CockroachDB with Helm, choosing between published and local split charts, verifying a new install, or helping an agent complete first-time Kubernetes onboarding.
Guides customer-facing installation of CockroachDB on Kubernetes using the CockroachDB split Helm charts and operator-managed v1beta1 resources. Use when installing CockroachDB with Helm, choosing between published and local split charts, verifying a new install, or helping an agent complete first-time Kubernetes onboarding.
compatibility
CockroachDB Helm v2 charts with crdb.cockroachlabs.com/v1beta1 CrdbCluster resources. Requires Kubernetes 1.30+, Helm 3+, and cluster permissions to install CRDs and cluster-scoped RBAC unless pre-provisioned by a platform team.
metadata
{"author":"cockroachdb","version":"1.1"}
Installing CockroachDB with Helm
Guides an agent through a customer-facing CockroachDB install on Kubernetes using the CockroachDB split Helm charts. Prefer the published split charts for customers. Do not use the unsupported parent or umbrella chart path for customer installs.
When to Use This Skill
A customer asks to install CockroachDB on Kubernetes using Helm
An agent needs to decide whether to install the published split charts or local split charts
A first install needs structured preflight, chart values, and post-install verification
A deployment has partially completed and needs the next Helm step
Multi-region requires complete regions entries and cross-region DNS/networking
Safety Considerations
Confirm the target Kubernetes context with the user before running helm install, helm upgrade, or kubectl apply.
Do not toggle cockroachdb.tls.enabled on an existing cluster. The chart documents this as unsafe and unrecoverable for a running cluster.
Do not configure multiple operators with overlapping watchNamespaces; both can reconcile the same CrdbCluster resources.
If the customer cannot create ClusterRoles or ClusterRoleBindings, coordinate split-chart node-reader RBAC with the platform team before installing the CockroachDB chart.
Do not use unsupported parent or umbrella chart installs for customer-facing deployment guidance.
Execution Discipline
Execute one step at a time and inspect the output before moving on. Preflight output determines whether installation can continue.
Do not run helm install, helm upgrade, kubectl apply, or any mutating command unless the user explicitly approves it for the target Kubernetes context and namespace.
Stop before installing if cluster-scoped RBAC, node labels, storage class, TLS mode, registry access, or multi-region prerequisites are unclear.
In production or restricted environments, involve TSE, the platform team, or the operator team before changing RBAC, webhook, operator, certificate, storage, or network configuration.
Step 1: Preflight the Kubernetes Context
Run read-only checks first:
kubectl config current-context
kubectl version --short
helm version --short
kubectl auth can-i create customresourcedefinitions.apiextensions.k8s.io
kubectl auth can-i create clusterroles.rbac.authorization.k8s.io
kubectl auth can-i create clusterrolebindings.rbac.authorization.k8s.io
kubectl get nodes -o wide
kubectl get nodes --show-labels | grep -E 'topology.kubernetes.io/(region|zone)' || true
Interpretation:
Kubernetes must be 1.30 or newer for the current v2 chart line.
Helm must be v3.
Node labels topology.kubernetes.io/region and topology.kubernetes.io/zone should exist before relying on default locality behavior.
Missing cluster-scoped RBAC is not automatically fatal, but it changes the install path. Use operator-chart nodeReader values or have a platform team pre-create the required bindings.
Step 2: Choose the Install Path
Published Split Charts (Recommended for Customers)
Adjust code, cloudProvider, namespace, storage size, and storage class to the customer environment. The region code should match the Kubernetes node region label and the operator chart cloudRegion.
Step 4: Verify the Install
Check Kubernetes resources:
kubectl -n cockroach-operator-system get deploy cockroach-operator
kubectl -n cockroach-operator-system logs deploy/cockroach-operator --tail=100
kubectl -n cockroachdb get crdbcluster,crdbnode,pods,svc
kubectl -n cockroachdb get crdbcluster crdb -o jsonpath='{.status.readyNodes}{" ready, reconciled="}{.status.reconciled}{" version="}{.status.version}{"\n"}'
kubectl -n cockroachdb get crdbnodes -o custom-columns=NAME:.metadata.name,NODE_ID:.status.nodeID,CONDITIONS:.status.conditions[*].type,TOPOLOGY:.status.topologyValues
Expected state:
cockroach-operator Deployment is available.
CRDs crdbclusters.crdb.cockroachlabs.com and crdbnodes.crdb.cockroachlabs.com exist.
CrdbCluster.status.reconciled is true and readyNodes equals the regional node count.
Each CrdbNode has a nodeID and Ready/Running conditions.
Kubernetes context, namespace, and chart path used
Operator release, CockroachDB release, and chart versions
Values file path or inline values that were applied
CRD registration status
CrdbCluster ready/reconciled status and node count
SQL verification result or the exact blocker if SQL could not be verified
Troubleshooting Handoff
If any command fails, stop the install flow and use diagnosing-cockroachdb-helm-deployments. Preserve the exact command, stderr, namespace, release names, and values file path. If the failure remains unresolved or the operator appears stuck, gather the operator escalation packet before restarting or changing operator state.
