Configuring CockroachDB Helm TLS

Guides TLS configuration for operator-managed CockroachDB clusters installed with the Helm v2 charts. The operator API receives externalCertificates; the Helm chart is responsible for translating self-signer, cert-manager, or external certificate values into the CrdbCluster spec.

When to Use This Skill

• A customer asks which TLS mode to use with CockroachDB Helm charts
• A values file needs a secure cockroachdb.tls block
• The install fails with chart TLS validation errors
• The customer already has cert-manager or externally generated certificates
• The customer needs to understand which Secrets and ConfigMaps the chart expects

Safety Considerations

• Do not change cockroachdb.tls.enabled on a running cluster.
• Enable exactly one of selfSigner.enabled, certManager.enabled, or externalCertificates.enabled when cockroachdb.tls.enabled=true.
• Disable all three certificate providers when cockroachdb.tls.enabled=false.
• For production, confirm the certificate rotation owner before install. Self-signer can rotate node/client certs, but a customer-provided CA remains the customer's responsibility.
• Do not print private key contents. Only reference Secret names and required keys.
• For certificate rotation or trust failures on a running operator-managed cluster, collect certificate metadata and cert-reloader logs before changing Secrets, ConfigMaps, or cert-manager resources.

Execution Discipline

• Execute one step at a time and inspect the output before moving on. Certificate mode, Secret names, and issuer state determine which later checks are relevant.
• Do not change TLS mode, replace Secrets, patch cert-manager resources, run debug containers, or perform Helm upgrades unless the user explicitly approves the action for the target cluster.
• Never print private key data. Use metadata checks for expiry, issuer, subject, SANs, and required key presence.
• In production or when certificate ownership is unclear, involve TSE or the operator team before rotation, regeneration, debug containers, or restart actions.

Step 1: Choose the TLS Mode

If the user is unsure, default to self-signer for a first secure non-production deployment and recommend cert-manager or external certificates for production environments with existing PKI.

Self-Signer Values

Chart-managed CA, node certs, and root client certs:

cockroachdb:
  tls:
    enabled: true
    selfSigner:
      enabled: true
      rotateCerts: true
    certManager:
      enabled: false
    externalCertificates:
      enabled: false

Customer-provided CA with chart-generated node and client certs:

cockroachdb:
  tls:
    enabled: true
    selfSigner:
      enabled: true
      caProvided: true
      caSecret: custom-ca-secret
      rotateCerts: true
    certManager:
      enabled: false
    externalCertificates:
      enabled: false

The CA Secret must contain ca.crt and ca.key in the CockroachDB namespace before install.

Validate:

kubectl -n <namespace> get secret custom-ca-secret
helm template crdb ./cockroachdb-parent/charts/cockroachdb -n <namespace> -f values.yaml >/tmp/crdb-rendered.yaml

Cert-Manager Values

Use cert-manager when an Issuer or ClusterIssuer can issue CockroachDB node and root client certificates.

cockroachdb:
  tls:
    enabled: true
    selfSigner:
      enabled: false
    certManager:
      enabled: true
      caConfigMap: cockroachdb-ca
      nodeSecret: cockroachdb-node
      clientRootSecret: cockroachdb-root
      issuer:
        group: cert-manager.io
        kind: Issuer
        name: cockroachdb
    externalCertificates:
      enabled: false

Preflight:

kubectl -n <namespace> get issuer cockroachdb
kubectl -n <namespace> get configmap cockroachdb-ca || true
kubectl -n <namespace> get secret cockroachdb-node cockroachdb-root || true
kubectl get crd certificates.cert-manager.io issuers.cert-manager.io

If cert-manager stores CA material in a Secret but the chart needs a ConfigMap, configure trust-manager or another approved process to publish ca.crt into the namespace.

External Certificate Values

Use external certificates when the customer has already generated Kubernetes resources with the names the operator expects:

cockroachdb:
  tls:
    enabled: true
    selfSigner:
      enabled: false
    certManager:
      enabled: false
    externalCertificates:
      enabled: true
      certificates:
        caConfigMapName: cockroachdb-ca
        nodeSecretName: cockroachdb-node
        httpSecretName: cockroachdb-node
        rootSqlClientSecretName: cockroachdb-root

Expected data keys:

Validate names and keys without printing secret values:

kubectl -n <namespace> get configmap cockroachdb-ca -o jsonpath='{.data.ca\.crt}' >/dev/null
kubectl -n <namespace> get secret cockroachdb-node -o jsonpath='{.data.tls\.crt}' >/dev/null
kubectl -n <namespace> get secret cockroachdb-node -o jsonpath='{.data.tls\.key}' >/dev/null
kubectl -n <namespace> get secret cockroachdb-root -o jsonpath='{.data.tls\.crt}' >/dev/null
kubectl -n <namespace> get secret cockroachdb-root -o jsonpath='{.data.tls\.key}' >/dev/null

Insecure Non-Production Values

Only use for local testing or temporary non-production validation:

cockroachdb:
  tls:
    enabled: false
    selfSigner:
      enabled: false
    certManager:
      enabled: false
    externalCertificates:
      enabled: false

State clearly that insecure mode has no TLS or authentication protections and is not suitable for production.

Post-Install Verification

kubectl -n <namespace> get crdbcluster <release-name> -o yaml | grep -A12 certificates
kubectl -n <namespace> get secret,configmap | grep -E 'cockroach|crdb'
kubectl -n <namespace> get pods

For self-signer, confirm the self-signer job ran and the generated CA, node, and client resources exist. For cert-manager, confirm Certificate resources are Ready. For external certificates, confirm the CrdbCluster references the expected names.

Certificate Debugging and Rotation Evidence

Use this section when pods report x509 errors, certificate rotation is not reflected in pods, the cert-reloader sidecar fails, or TSC asks for certificate evidence. Collect metadata only; do not print private keys.

kubectl -n <namespace> get crdbcluster <release-name> -o yaml | grep -A20 certificates
kubectl -n <namespace> get secret,configmap | grep -E 'ca|node|client|tls|cert|cockroach|crdb'
kubectl -n <namespace> get pod <pod-name> -o jsonpath='{.spec.containers[*].name}{"\n"}'
kubectl -n <namespace> logs <pod-name> -c cert-reloader --tail=100

Inspect the node certificate:

kubectl -n <namespace> get secret <node-tls-secret> -o jsonpath='{.data.tls\.crt}' | base64 -d | \
  openssl x509 -noout -dates -subject -issuer -ext subjectAltName

Inspect cert-manager resources, if cert-manager is used:

kubectl -n <namespace> get certificate,issuer -o wide
kubectl get clusterissuer -o wide 2>/dev/null || true
kubectl -n <namespace> describe certificate <certificate-name>
kubectl -n <namespace> describe issuer <issuer-name>

If the CockroachDB image does not include network or OpenSSL tooling, use an approved debug image according to the customer's policy. In air-gapped environments, mirror the approved image into the customer's registry and use that registry path instead of pulling a public image directly.

kubectl -n <namespace> debug <pod-name> --image=<approved-network-debug-image> --target=cockroachdb -it -- \
  openssl s_client -connect <pod-ip>:26257 \
    -CAfile /cockroach/cockroach-certs/ca.crt \
    -cert /cockroach/cockroach-certs/node.crt \
    -key /cockroach/cockroach-certs/node.key

For full in-pod certificate metadata:

kubectl -n <namespace> debug <pod-name> --image=<approved-network-debug-image> --target=cockroachdb -it -- bash -c '
for DIR in /cockroach/cockroach-certs /certs /cockroach-certs; do
  if [ -d "$DIR" ]; then
    echo "=== Cert directory: $DIR ==="
    ls -la "$DIR" 2>/dev/null
    for CERT in "$DIR"/*.crt; do
      if [ -f "$CERT" ]; then
        echo "--- $CERT ---"
        openssl x509 -in "$CERT" -noout -subject -issuer -dates -ext subjectAltName 2>&1
      fi
    done
  fi
done'

Escalate with collecting-cockroachdb-operator-escalation-packet if certificates look correct but pods still cannot join, rotate, or become Ready.

Common TLS Failures

References

• Self-signer certificate management
• cert-manager certificate management
• CockroachDB Helm Chart README
• CockroachDB Docs: Authentication
• Operator escalation packet collection