Troubleshooting Customer‑Managed Certificates in Redis Software 8 – Redis Knowledge Base

Use this guide to diagnose internode encryption (INE) certificate issues such as cluster communication errors, TLS handshake failures, or node join/replace errors after enabling Customer-Managed Certificates (CMCs) in Redis Software 8.

Starting with Redis Software version 7.22.2, the ability to upload your own CA-issued certificates for both the Control Plane Internode Encryption (CPINE) and Data Plane Internode Encryption (DPINE). If these certificates are invalid, inconsistent, or expired, symptoms include communication failures, “bad certificate” errors, or automatic fallback to self-signed certificates.

Certificate Requirements

Certificates must include the full chain (leaf, intermediate, and root).
Certificates must be created with the TLS Web Client Authentication attribute enabled.
Redis Software supports RSA keys only.

Quick Fix Table

Symptom	Fast Check	Action
TLS handshake errors	Is the certificate RSA? Is the client using supported TLS versions?	Redis Software supports RSA keys only. Confirm client TLS version compatibility. If issues persist, open a Support ticket to review server-side compatibility.
Certificate upload rejected	Does the certificate include a full chain (leaf + intermediate + root)? Does the key match the certificate?	Correct the certificate bundle and key pairing, then re-upload. The API validates these before use.
Certificate rotation completes, but connectivity issues remain	Did the API return any validation errors during upload?	If upload succeeded, certificates are valid and propagated. Post-rotation connectivity issues require Support investigation.
Unexpected fallback to self-signed	Are customer certificates within 5 days of expiry?	Renew certificates. Add monitoring for near-expiry certs.
Certificate verify failed: key too weak	Is the RSA key < 2048 bits?	Replace with a 2048-bit or greater RSA key.

Who Is Affected / When to Use

Who	When
Operators after certificate rotation	Immediately after "Save & Rotate" if the cluster shows communication errors.
Admins adding/replacing nodes	When join or replace operations fail due to certificate or CA chain issues.
Teams near expiry	When alerts show certificates expiring or Redis unexpectedly falls back to self-signed.

Common Error Strings

Error	What It Usually Means
x509: certificate signed by unknown authority	Missing or incorrect CA chain on node or client trust store.
remote error: tls: bad certificate	Key/cert mismatch or incomplete chain.
tls: handshake failure	TLS version or cipher mismatch.
certificate verify failed	Expired certificate or wrong SAN/hostname.
cluster join failed: unable to establish secure channel	Joining node missing CA chain or certificate material.
certificate verify failed: key too weak	RSA key < 2048 bits (blocked by RHEL 9 / OpenSSL 3.0+).
no shared cipher	Cipher mismatch between client and server.
wrong version number	Protocol mismatch or client invoked without TLS (missing `--tls`).
Unrecognized option --tls	redis-cli not built with TLS; must be rebuilt with `BUILD_TLS=yes`.

Step-by-Step Troubleshooting Flow

1. Certificate Upload and Validation

Upload via UI, CLI, or REST API (PUT /v1/cluster/certificates).
Ensure certificate and private key match and are in PEM format.
Validate the chain: leaf → intermediate → root.
Redis rejects invalid or expired certificates.

2. Certificate Expiration and Renewal

Monitor expiration using Prometheus (node_cert_expiration_seconds).
UI alerts begin 45 days before expiry.
Renew before expiry to avoid fallback. Redis automatically reverts to self-signed 5 days before expiry if not renewed.

3. Cluster Connectivity and Propagation

Confirm all nodes share the same CA chain.
When switching from self-signed to CA-issued, update trust stores on all nodes.
During rotation, both old and new certs are trusted until all nodes complete update.

4. Certificate Replacement and Rollback

Rotation is asynchronous and non-disruptive.
If issues appear, re-upload the previous working certificate.
If no valid cert is available, allow Redis to revert to self-signed for continuity.

Monitoring and Alerts

Metric / Alert	Purpose
node_cert_expiration_seconds	Shows seconds until certificate expiry per node.
customer_managed_ine_certificates	Indicates whether custom INE certificates are active (0 = No, 1 = Yes).
UI alerts (45-day window)	Warn of upcoming certificate expiration.
Fallback alerts	Triggered when Redis auto-reverts to self-signed certificates.

Best monitoring practice: Integrate metrics into Prometheus / Grafana and set threshold alerts (e.g., warn ≥ 45 days, critical ≤ 10 days).

Best Practices

Centralize certificate management
Use Vault, Ansible, or CI/CD pipelines to issue and rotate certificates consistently across all nodes.
Monitor certificate expiry early
Set alerts well before the 5-day fallback window to avoid unexpected reversion to self-signed certificates.
Test updates in staging first
Validate new certificates, CA chains, and SANs in a non-production environment before rolling changes to production.
Document certificate details
Track issuance dates, expiry, subject/issuer, and full CA chains to simplify renewal and troubleshooting.
Use strong cryptographic keys
Ensure RSA keys are ≥ 2048-bit (or stronger) to meet modern security and compliance requirements.
Plan for fallback behavior
Redis automatically reverts to self-signed certificates if customer certificates expire, so ensure monitoring can detect this.
Maintain backups of prior certificates
Keep previous PEM/key pairs securely stored for rapid rollback if deployment issues occur.

Key Takeaways

Most certificate issues stem from incomplete CA chains or mismatched keys.
Monitor proactively—set alerts at least 45 days before expiry.
Redis automatically reverts to self-signed certs 5 days before expiry if you don’t renew.
REK 8.0.2-2 currently does not support custom INE certificates.
Keep backups of every working PEM and key pair.

Related to