Skip to content

Configure TLS

Valkey GLIDE supports secure TLS connections to a data store.

It’s important to note that TLS support in Valkey GLIDE relies on rustls. Currently, Valkey GLIDE employs the default rustls settings with no option for customization.

Enabling TLS is as simple as setting use_tls=True in your configuration. The client will use your system’s default certificate trust store to verify the server.

import glide.api.GlideClusterClient;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder()
.host("address.example.com")
.port(6379)
.build())
.useTLS(true)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();
import glide.api.GlideClient;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;
GlideClientConfiguration config = GlideClientConfiguration.builder()
.address(NodeAddress.builder()
.host("primary.example.com")
.port(6379)
.build())
.useTLS(true)
.build();
GlideClient client = GlideClient.createClient(config).get();

Insecure TLS mode bypasses certificate verification. This is useful when connecting to servers using self-signed certificates or when DNS entries don’t match certificate hostnames.

import glide.api.GlideClusterClient;
import glide.api.models.configuration.AdvancedGlideClusterClientConfiguration;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.useInsecureTLS(true)
.build();
AdvancedGlideClusterClientConfiguration advancedConfig =
AdvancedGlideClusterClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder().host("address.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();
import glide.api.GlideClient;
import glide.api.models.configuration.AdvancedGlideClientConfiguration;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.useInsecureTLS(true)
.build();
AdvancedGlideClientConfiguration advancedConfig = AdvancedGlideClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClientConfiguration config = GlideClientConfiguration.builder()
.address(NodeAddress.builder().host("primary.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClient client = GlideClient.createClient(config).get();

You can provide custom root certificates for TLS connections. This is useful when connecting to servers with self-signed certificates or corporate certificate authorities.

Certificate Behavior:

  • If rootCertificates is not set (default), the system’s default certificate trust store is used
  • If rootCertificates is an empty byte array, an error will be returned
  • Certificates must be in PEM format as a byte array
  • Multiple certificates can be provided by concatenating them in PEM format

Example - Connecting with Custom Root Certificate from File

Section titled “Example - Connecting with Custom Root Certificate from File”
import glide.api.GlideClusterClient;
import glide.api.models.configuration.AdvancedGlideClusterClientConfiguration;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
import java.nio.file.Files;
import java.nio.file.Paths;
byte[] rootCaBytes = Files.readAllBytes(Paths.get("/path/to/ca-cert.pem"));
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.rootCertificates(rootCaBytes)
.build();
AdvancedGlideClusterClientConfiguration advancedConfig =
AdvancedGlideClusterClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder().host("address.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();
import glide.api.GlideClient;
import glide.api.models.configuration.AdvancedGlideClientConfiguration;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
import java.nio.charset.StandardCharsets;
byte[] rootCert = "-----BEGIN CERTIFICATE-----MIIDXTCCAkWg...".getBytes(StandardCharsets.UTF_8);
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.rootCertificates(rootCert)
.build();
AdvancedGlideClientConfiguration advancedConfig = AdvancedGlideClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClientConfiguration config = GlideClientConfiguration.builder()
.address(NodeAddress.builder().host("primary.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClient client = GlideClient.createClient(config).get();

Example - Connecting with Custom Root Certificates from KeyStore

Section titled “Example - Connecting with Custom Root Certificates from KeyStore”

TlsAdvancedConfiguration.fromKeyStore is a static factory that pulls trusted certificate entries out of a Java KeyStore (JKS or PKCS12) and returns a fully-configured TlsAdvancedConfiguration.

import glide.api.GlideClusterClient;
import glide.api.models.configuration.AdvancedGlideClusterClientConfiguration;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.fromKeyStore(
"/path/to/truststore.p12",
"changeit".toCharArray(),
"PKCS12");
AdvancedGlideClusterClientConfiguration advancedConfig =
AdvancedGlideClusterClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder().host("address.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();

Mutual TLS has the client present its own certificate and private key to the server, so the server can authenticate the client in addition to the client authenticating the server. GLIDE supports in-memory PEM bytes, path-based PEM with automatic reload, and, in Java, a static client identity loaded from a JKS or PKCS12 keystore.

mTLS still requires TLS to be enabled on the top-level client configuration (use_tls=True in Python, .useTLS(true) in Java, useTLS: true in Node.js, .WithUseTLS(true) in Go, or use_tls: true in PHP). The advanced TLS configuration only supplies the client-side material; it does not enable TLS on its own. In PHP, configure mTLS through advanced_config['tls_config']; client certificates and keys in a PHP stream context are not used for mTLS.

Reload behavior applies to path-based modes only. The GLIDE core reads the certificate and key from disk at connect time and re-reads them on a schedule so a rotated certificate is picked up on the next reconnect. Open connections keep their current material. If a reload fails (missing file, mismatched key, unreadable), the last known-good material is kept until a subsequent read succeeds. Byte-based mTLS is inherently static: the material is read once at connect time and does not reload.

Path-based and byte-based mTLS are mutually exclusive within a single configuration. Supplying both is rejected at configuration time in every SDK.

A custom reload interval must be a positive whole number of seconds no greater than 4,294,967,295 (the maximum value of an unsigned 32-bit integer, roughly 136 years). Sub-second, zero, negative, and oversized values are rejected at configuration time.

Java can load the client private key and certificate chain directly from a JKS or PKCS12 keystore. The keystore must contain exactly one private-key entry with a certificate chain. This mode loads the identity once and does not reload it; use path-based PEM when automatic certificate rotation is required.

import glide.api.models.configuration.TlsAdvancedConfiguration;
char[] password = System.getenv("GLIDE_KEYSTORE_PASSWORD").toCharArray();
TlsAdvancedConfiguration trustStore =
TlsAdvancedConfiguration.fromKeyStore(
"/etc/glide/truststore.p12", password, "PKCS12");
TlsAdvancedConfiguration tlsConfig =
TlsAdvancedConfiguration.builder()
.rootCertificates(trustStore.getRootCertificates())
.useMutualTlsFromKeyStore(
"/etc/glide/client-identity.p12", password, "PKCS12")
.build();

Pass tlsConfig through the client’s advanced configuration and enable TLS on the top-level configuration. fromKeyStore() loads trusted roots; useMutualTlsFromKeyStore() loads the client identity.

Use the byte-based entry point when the client certificate and key are already loaded as PEM bytes (for example, fetched from a secret store). The material is read once at connect time and does not reload.

import glide.api.GlideClusterClient;
import glide.api.models.configuration.AdvancedGlideClusterClientConfiguration;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
import java.nio.charset.StandardCharsets;
// Load PEM bytes from a secret store.
byte[] clientCert = "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgode...".getBytes(StandardCharsets.UTF_8);
byte[] clientKey = "-----BEGIN PRIVATE KEY-----\nMIIEvQIBAD...".getBytes(StandardCharsets.UTF_8);
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.useMutualTls(clientCert, clientKey)
.build();
AdvancedGlideClusterClientConfiguration advancedConfig =
AdvancedGlideClusterClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder().host("address.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();

Point at PEM files on disk and let the core reload them at its default cadence. Rotated material is picked up on the next reconnect after a successful reload.

import glide.api.GlideClusterClient;
import glide.api.models.configuration.AdvancedGlideClusterClientConfiguration;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.useMutualTlsWithReload("/etc/glide/client.pem", "/etc/glide/client.key")
.build();
AdvancedGlideClusterClientConfiguration advancedConfig =
AdvancedGlideClusterClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder().host("address.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();

Pass a positive whole number of seconds to override the core default cadence.

import glide.api.GlideClusterClient;
import glide.api.models.configuration.AdvancedGlideClusterClientConfiguration;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.useMutualTlsWithReload("/etc/glide/client.pem", "/etc/glide/client.key", 60)
.build();
AdvancedGlideClusterClientConfiguration advancedConfig =
AdvancedGlideClusterClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
.address(NodeAddress.builder().host("address.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();

When static, byte-based mTLS is desired but the material lives on disk, each SDK offers a helper that reads the PEM files and returns the bytes. Feed those bytes into the byte-based entry point shown above.

The same file-loading helpers work for both GlideClient (standalone) and GlideClusterClient (cluster-mode). The examples below show the standalone client; substitute the cluster variant if you are connecting to a cluster.

import glide.api.GlideClient;
import glide.api.models.configuration.AdvancedGlideClientConfiguration;
import glide.api.models.configuration.GlideClientConfiguration;
import glide.api.models.configuration.NodeAddress;
import glide.api.models.configuration.TlsAdvancedConfiguration;
import glide.api.models.configuration.TlsAdvancedConfiguration.TlsAdvancedConfigurationBuilder;
byte[] cert = TlsAdvancedConfigurationBuilder.loadClientCertificateFromFile("/etc/glide/client.pem");
byte[] key = TlsAdvancedConfigurationBuilder.loadClientKeyFromFile("/etc/glide/client.key");
TlsAdvancedConfiguration tlsConfig = TlsAdvancedConfiguration.builder()
.useMutualTls(cert, key)
.build();
AdvancedGlideClientConfiguration advancedConfig = AdvancedGlideClientConfiguration.builder()
.tlsAdvancedConfiguration(tlsConfig)
.build();
GlideClientConfiguration config = GlideClientConfiguration.builder()
.address(NodeAddress.builder().host("primary.example.com").port(6379).build())
.useTLS(true)
.advancedConfiguration(advancedConfig)
.build();
GlideClient client = GlideClient.createClient(config).get();
  • mTLS still needs TLS enabled at the top level. The advanced TLS configuration only supplies the client-side material; without TLS on the base client configuration (use_tls=True, .useTLS(true), useTLS: true, .WithUseTLS(true), or use_tls: true in PHP), the client connects in plaintext and the mTLS material is not used.
  • Path-based and byte-based mTLS are mutually exclusive. Supplying both a certificate/key path and inline PEM bytes on the same configuration is a configuration error in every SDK.
  • Sub-second, zero, negative, and oversized reload intervals are rejected. The custom interval is validated at configuration time: it must be a positive whole number of seconds no greater than 4,294,967,295 (the maximum value of an unsigned 32-bit integer, roughly 136 years). If you want static mTLS from files, load the bytes yourself with the file-loading helper and use the byte-based mode.
  • Byte-based mTLS is static. The material is read once at connect time and never reloads. Use a path-based mode when the certificate rotates.
  • Reload cadence is a lower bound. The interval bounds how stale the on-disk material can be before the next reload attempt; the next successful reload takes effect on the next reconnect, not on open connections.
  • Reload failures keep the last known-good material. A path that becomes unreadable, a mismatched key, or a corrupt certificate causes the reload to fail. The core keeps the last successfully loaded material and retries at the next tick.
  • File permissions matter. The process user must have read access to the certificate and key files. Restrict the key file to that user; do not commit it or log it.

All certificates must be in PEM format. A PEM certificate looks like this:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKmzMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----

Common Issues:

  1. Certificate Verification Failed

    • Ensure the certificate is valid and not expired
    • Verify the hostname matches the certificate’s Common Name (CN) or Subject Alternative Name (SAN)
    • Check that the certificate chain is complete
  2. Connection Refused

    • Verify the server is configured to accept TLS connections
    • Ensure the port number is correct (typically 6379 for TLS)
  3. Empty Certificate Error

    • Do not provide empty certificate data
    • Either provide valid certificates or use the default system certificates
  4. File Not Found

    • Verify the certificate file path is correct
    • Ensure the file is accessible with proper read permissions