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 Connections

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.

Cluster Mode

Python

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(addresses, use_tls=True)

client = await GlideClusterClient.create(client_config)

Java

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();

Node

import {GlideClusterClient} from "@valkey/valkey-glide";

const addresses = [
    {
        host: "address.example.com",
        port: 6379
    }
];

const client = await GlideClusterClient.createClient({
    addresses: addresses,
    useTLS: true
});

Go

import (
    glide "github.com/valkey-io/valkey-glide/go/v2"
    "github.com/valkey-io/valkey-glide/go/v2/config"
)

func ConnectClusterWithTLS() {
    myConfig := config.NewClusterClientConfiguration().
        WithAddress(&config.NodeAddress{Host: "address.example.com", Port: 6379}).
        WithUseTLS(true)

    client, err := glide.NewClusterClient(myConfig)
}

Standalone

Python

from glide import (
    GlideClient,
    GlideClientConfiguration,
    NodeAddress
)

addresses = [
    NodeAddress(host="primary.example.com", port=6379),
    NodeAddress(host="replica1.example.com", port=6379),
    NodeAddress(host="replica2.example.com", port=6379)
  ]
client_config = GlideClientConfiguration(addresses, use_tls=True)

client = await GlideClient.create(client_config)

Java

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();

Node

import {GlideClient} from "@valkey/valkey-glide";

const addresses = [
    {
        host: "address.example.com",
        port: 6379
    }
];

const client = await GlideClient.createClient({
    addresses: addresses,
    useTLS: true
});

Go

import (
    glide "github.com/valkey-io/valkey-glide/go/v2"
    "github.com/valkey-io/valkey-glide/go/v2/config"
)

func ConnectStandaloneWithTLS() {
    myConfig := config.NewClientConfiguration().
        WithAddress(&config.NodeAddress{Host: "primary.example.com", Port: 6379}).
        WithUseTLS(true)

    client, err := glide.NewClient(myConfig)
}

Advanced TLS Configurations

The TlsAdvancedConfiguration object provides advanced TLS settings for both standalone and cluster clients.

Python

Insecure TLS Mode

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.

Caution

Insecure mode is only for development and testing environments. It is strongly discouraged in production as it introduces security risks such as man-in-the-middle attacks.

Example

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClusterClientConfiguration
)

tls_config = TlsAdvancedConfiguration(use_insecure_tls=True)

advanced_config = AdvancedGlideClusterClientConfiguration(
    tls_config=tls_config
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClusterClient.create(client_config)

Custom Root Certificates

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 root_pem_cacerts is None (default), the system’s default certificate trust store is used
• If root_pem_cacerts is an empty bytes object, an error will be returned
• Certificates must be in PEM format as a bytes object
• Multiple certificates can be provided by concatenating them in PEM format

Example - Connecting with Custom Root Certificate from File

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClusterClientConfiguration
)

# Read certificate file
with open("/path/to/ca-cert.pem", "rb") as f:
    root_cert = f.read()

tls_config = TlsAdvancedConfiguration(root_pem_cacerts=root_cert)

advanced_config = AdvancedGlideClusterClientConfiguration(
    tls_config=tls_config
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClusterClient.create(client_config)

Example - Using Certificate as Bytes

from glide import (
    GlideClient,
    GlideClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClientConfiguration
)

cert_data = b"""-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKmzMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----"""

tls_config = TlsAdvancedConfiguration(root_pem_cacerts=cert_data)

advanced_config = AdvancedGlideClientConfiguration(
    tls_config=tls_config
)

addresses = [NodeAddress(host="primary.example.com", port=6379)]
client_config = GlideClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClient.create(client_config)

Example - Multiple Certificates (Certificate Chain)

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClusterClientConfiguration
)

# Read multiple certificate files
with open("/path/to/cert1.pem", "rb") as f:
    cert1 = f.read()
with open("/path/to/cert2.pem", "rb") as f:
    cert2 = f.read()
with open("/path/to/cert3.pem", "rb") as f:
    cert3 = f.read()

# Concatenate certificates
combined_certs = cert1 + cert2 + cert3

tls_config = TlsAdvancedConfiguration(root_pem_cacerts=combined_certs)

advanced_config = AdvancedGlideClusterClientConfiguration(
    tls_config=tls_config
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClusterClient.create(client_config)

Example - Combining Insecure Mode with Custom Certificates

from glide import (
    GlideClient,
    GlideClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClientConfiguration
)

with open("/path/to/ca-cert.pem", "rb") as f:
    root_cert = f.read()

tls_config = TlsAdvancedConfiguration(
    use_insecure_tls=True,
    root_pem_cacerts=root_cert
)

advanced_config = AdvancedGlideClientConfiguration(
    tls_config=tls_config
)

addresses = [NodeAddress(host="primary.example.com", port=6379)]
client_config = GlideClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClient.create(client_config)

TLS Certificate Format

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

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

Troubleshooting TLS Connections

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 an empty bytes object for root_pem_cacerts
   • Either provide valid certificates or leave it as None to use system certificates

4. File Not Found

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

Java

Coming soon

Advanced TLS configuration documentation for Java is coming soon.

Node

Coming soon

Advanced TLS configuration documentation for Node.js is coming soon.

Go

Coming soon

Advanced TLS configuration documentation for Go is coming soon.