installing-cockroachdb-with-helm

name	installing-cockroachdb-with-helm
description	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

Related skills: Use configuring-cockroachdb-helm-tls for TLS decisions, validating-cockroachdb-helm-multiregion before multi-region installs, debugging-cockroachdb-operator-migrations for StatefulSet or v1alpha1 migrations, and diagnosing-cockroachdb-helm-deployments when any step fails.

Inputs

Collect these before changing the cluster:

Input	Example	Why It Matters
Kubernetes context and namespace	prod-us-east1, cockroachdb	Avoids installing into the wrong cluster or namespace
Install path	Published split charts or local split charts	Determines Helm commands and dependency order
Operator release and CockroachDB release names	crdb-operator, crdb	Resource names and generated services depend on release names
Region and cloud provider	us-east1, gcp	operator.cloudRegion must match the region reconciled by this operator
TLS mode	self-signer, cert-manager, external certificates, insecure non-prod	Determines chart values and required secrets
Topology	single-region or multi-region	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)

Use this path for normal customer installs.

helm repo add cockroachdb-v2 https://charts.cockroachdb.com/v2 --force-update
helm repo update cockroachdb-v2
helm search repo cockroachdb-v2 --devel

Install the operator first:

helm upgrade --install crdb-operator cockroachdb-v2/cockroachdb-operator-chart \
  --namespace cockroach-operator-system \
  --create-namespace \
  --version <operator-chart-version> \
  --set cloudRegion=<current-region>

kubectl -n cockroach-operator-system rollout status deploy/cockroach-operator --timeout=5m
kubectl get crd crdbclusters.crdb.cockroachlabs.com crdbnodes.crdb.cockroachlabs.com

Then install CockroachDB:

helm upgrade --install crdb cockroachdb-v2/cockroachdb-chart \
  --namespace cockroachdb \
  --create-namespace \
  --version <cockroachdb-chart-version> \
  -f values.yaml

Local Split Charts

Use this path when working from a checkout of this repository:

helm upgrade --install crdb-operator ./cockroachdb-parent/charts/operator \
  --namespace cockroach-operator-system \
  --create-namespace \
  --set cloudRegion=<current-region>

kubectl -n cockroach-operator-system rollout status deploy/cockroach-operator --timeout=5m

helm upgrade --install crdb ./cockroachdb-parent/charts/cockroachdb \
  --namespace cockroachdb \
  --create-namespace \
  -f values.yaml

Step 3: Create a Minimal Values File

For a single-region secure install using the chart self-signer:

cockroachdb:
  clusterDomain: cluster.local
  tls:
    enabled: true
    selfSigner:
      enabled: true
    certManager:
      enabled: false
    externalCertificates:
      enabled: false
  crdbCluster:
    regions:
      - code: us-east1
        nodes: 3
        cloudProvider: gcp
        namespace: cockroachdb
    dataStore:
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 100Gi
          volumeMode: Filesystem

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.
• CockroachDB pods are Running and Ready.

For SQL verification, connect with the certificate mode selected by configuring-cockroachdb-helm-tls, then run:

SELECT version();
SHOW REGIONS;
SHOW JOBS;

Outputs

Return a concise install report:

• 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.

References

• CockroachDB Helm Chart Versioning
• Operator Helm Chart README
• CockroachDB Helm Chart README
• CockroachDB Docs: Deploy with Kubernetes
• Helm Docs: Role-based Access Control