Troubleshooting TLS Failures in Redis on Kubernetes (K8s) – Redis Knowledge Base

Redis Enterprise for Kubernetes secures communication between clients, databases, and cluster nodes using TLS (Transport Layer Security). TLS is enabled in RedisEnterpriseCluster (REC) and RedisEnterpriseDatabase (REDB) manifests and depends on Kubernetes secrets for certificates and keys.

Failures usually occur when secrets are missing or misconfigured, certificates are invalid, webhook or service settings are wrong, or the client isn't TLS-enabled. This article provides a Quick Fix table, a step-by-step troubleshooting checklist, and best practices for resolving TLS problems in Kubernetes, including OpenShift.

Prerequisites

Redis Enterprise Operator installed on Kubernetes or OpenShift.
Access to kubectl in the cluster namespace.
Redis CLI with TLS support (make BUILD_TLS=yes).
Valid Kubernetes secrets containing ca.crt, tls.crt, and tls.key.

Quick Fix Table

Symptom / Error Message	Likely Cause	Action
`certificate verify failed`	Missing or unmounted secret	Check `tls-secret` contents and confirm mounts in pods.
`SSL handshake failed`	Certificate mismatch or webhook issue	Verify admission webhook TLS config and re-import correct secret.
`wrong version number` / no cipher	TLS protocol or cipher mismatch	Align TLS version/cipher in REC/REDB spec and client configuration.
`Unrecognized option --tls`	redis-cli not built with TLS support	Rebuild redis-cli with `BUILD_TLS=yes`.
Connection refused / timeout	Service port or LoadBalancer termination	Validate Kubernetes service type/port, DNS, and LB passthrough config.
Handshake error in operator logs	Wrong certificate type or secret missing	Ensure secret contains correct keys and is referenced in manifests.

Step-by-Step Troubleshooting

Validate Secrets
Confirm that your TLS secret exists and contains all required keys:
```
kubectl get secret redis-enterprise-tls -o yaml
```
Required keys: ca.crt, tls.crt, tls.key.
Confirm Pod Mounts
Verify that secrets are mounted under:
```
/opt/redislabs/config
```
If mounts are missing, check REC/REDB spec for correct tlsSecret references.
Check Admission Controller / Webhook
- Admission service must be ClusterIP, not LoadBalancer.
- Ensure the certificate referenced in the webhook matches the Kubernetes secret.
- Misconfigured webhooks are a frequent cause of SSL handshake failed.

Test Client TLS from a Pod

redis-cli -h <hostname> -p <port> --tls --cacert /opt/redislabs/config/ca.crt

For mTLS, also pass --cert and --key.

Review Load Balancer TLS Handling
- Passthrough mode: LB must not terminate TLS.
- Termination mode: Add LB certificate to the client’s trust store.
- For OpenShift, configure Routes in passthrough mode, see OpenShift Routes for External Database Access
Validate Certificates
Check certificate expiry and key strength:
```
openssl x509 -in tls.crt -noout -enddate
```
Keys must be at least 2048 bits (required for OpenSSL v3 / RHEL9+).
Inspect Operator and Pod Logs
Look for TLS-related errors:
```
kubectl logs <redis-pod>
kubectl logs deployment/redis-enterprise-operator
kubectl exec -it <redis-pod> -- rladmin status
```
Common indicators include handshake failures, missing secrets, or admission webhook errors.

Best Practices for TLS on Kubernetes

Always manage TLS in manifests: Set tlsMode: enabled in REDB YAML. UI/API changes are reverted during reconciliation.
Use Kubernetes secrets for all certs and keys; reference them explicitly in REC (proxy, api, syncer) and REDB (tlsSecret, clientAuthenticationCertificates).
Automate certificate renewal to prevent outages due to expiry.
Use CA-signed certificates in production environments for stronger trust. See Enable TLS in Redis Software.
External access: Configure ingress with SSL passthrough (NGINX/HAProxy) or OpenShift Routes with passthrough termination. See Configure Ingress for External Routing.
Stay current with supported Kubernetes versions — see Supported Kubernetes Distributions.

Advanced Diagnostics

Operator logs: TLS errors here often point to secret mismatches or webhook issues.
Pod restarts: Repeated TLS-related pod restarts may signal resource misconfiguration or RBAC/SCC issues.
Support packages: For unresolved TLS failures, collect cluster logs with Uploading Support Packages & Cluster Health Analysis.

FAQs

Q: How do I rotate TLS certificates in Kubernetes?
Create a new Kubernetes secret with the updated cert/key, update the REC or REDB manifest to reference the new secret, and reapply. The operator reconciles automatically.

Q: Why are TLS changes in the UI or API reverted?
The Kubernetes operator enforces manifest settings. Update the CRD YAML and reapply.

Q: How can I confirm TLS is enabled?
Run:

kubectl exec -it <redis-pod> -- rladmin status endpoints

Endpoints with SSL: All confirm TLS is active.

Q: My redis-cli shows Unrecognized option --tls. What now?
Rebuild with TLS support:

make BUILD_TLS=yes

Additional Resources

Related to