| name | configuring-cockroachdb-helm-tls |
| description | Selects and validates TLS settings for CockroachDB Helm chart deployments, including self-signer, cert-manager, and external certificate modes. Use when a customer needs secure CockroachDB Helm values, certificate secret mapping, cert-manager integration, or TLS install troubleshooting before deploying the chart. |
| compatibility | CockroachDB Helm v2 charts. Requires Kubernetes Secret or cert-manager access for externally managed certificates. TLS mode must be chosen before initial cluster creation. |
| metadata | {"author":"cockroachdb","version":"1.1"} |
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
| Mode | Use When | Required Inputs |
|---|
| Self-signer | Fastest secure install, dev/test, or customer accepts chart-managed cert generation | Optional CA Secret if customer provides CA |
| Cert-manager | Customer already runs cert-manager and wants Kubernetes-native renewal | Issuer or ClusterIssuer, CA ConfigMap, node Secret, root client Secret |
| External certificates | Customer PKI owns all certificates and rotation | CA ConfigMap, node Secret, HTTP Secret, root SQL client Secret |
| Insecure | Non-production test only | Explicit user confirmation |
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:
| Resource | Required Keys |
|---|
| CA ConfigMap | ca.crt |
| Node TLS Secret | tls.crt, tls.key |
| HTTP TLS Secret | tls.crt, tls.key |
| Root SQL client Secret | tls.crt, tls.key or chart-compatible root client cert 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
| Symptom | Likely Cause | Action |
|---|
Exactly one of selfSigner, certManager or externalCertificates must be enabled when TLS is on | Multiple or zero providers enabled | Set exactly one provider true |
selfSigner, certManager and externalCertificates must all be disabled when TLS is off | Provider enabled while TLS disabled | Disable all providers or enable TLS |
caProvided with empty caSecret | Customer CA mode missing Secret name | Set cockroachdb.tls.selfSigner.caSecret |
| Pods fail with certificate trust errors | CA and issued certs do not match | Verify CA ConfigMap/Secret and regenerate certs from the same CA |
| Cert rotation does not take effect | cert-reloader sidecar issue, stale mounted Secret, or cert-manager failure | Check cert-reloader logs, cert-manager Certificate status, and node cert expiry/SAN metadata |
| Pods fail after migration with TLS errors | Migrated cert resources or CA names do not match operator references | Use the migration debugging skill and verify the CrdbCluster certificate references |
References
