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)
}

C#

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

var config = new ClusterClientConfigurationBuilder()
    .WithAddress("address.example.com", 6379)
    .WithTls()
    .Build();

await using var client = await GlideClusterClient.CreateClient(config);

PHP

$addresses = [
    ['host' => 'address.example.com', 'port' => 6379]
];

$client = new ValkeyGlideCluster(
    addresses: $addresses,
    use_tls: true
);

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)
}

C#

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

var config = new StandaloneClientConfigurationBuilder()
    .WithAddress("primary.example.com", 6379)
    .WithAddress("replica1.example.com", 6379)
    .WithAddress("replica2.example.com", 6379)
    .WithTls()
    .Build();

await using var client = await GlideClient.CreateClient(config);

PHP

$addresses = [
    ['host' => 'primary.example.com', 'port' => 6379],
    ['host' => 'replica1.example.com', 'port' => 6379],
    ['host' => 'replica2.example.com', 'port' => 6379]
];

$client = new ValkeyGlide();
$client->connect(addresses: $addresses, use_tls: true);

Advanced TLS Configurations

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

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

Python

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)

Java

Coming soon

Insecure TLS configuration documentation for Java is coming soon.

Node

Coming soon

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

Go

Coming soon

Insecure TLS configuration documentation for Go is coming soon.

C#

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

var config = new ClusterClientConfigurationBuilder()
    .WithAddress("address.example.com", 6379)
    .WithTls()
    .WithInsecureTls()
    .Build();

await using var client = await GlideClusterClient.CreateClient(config);

PHP

$client = new ValkeyGlideCluster(
    addresses: [['host' => 'address.example.com', 'port' => 6379]],
    use_tls: true,
    advanced_config: ['tls_config' => ['use_insecure_tls' => true]]
);

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.

Python

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)

Java

Coming soon

Custom root certificate documentation for Java is coming soon.

Node

Coming soon

Custom root certificate documentation for Node.js is coming soon.

Go

Coming soon

Custom root certificate documentation for Go is coming soon.

C#

Certificate Behavior:

• If no trusted certificates are provided, the system’s default certificate trust store is used.
• Empty certificate data will throw an ArgumentException.
• Certificate data exceeding 10 MB will throw an ArgumentException
• Multiple certificates can be added by calling WithTrustedCertificate multiple times

Example - Connecting with Custom Root Certificate from File

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

var config = new ClusterClientConfigurationBuilder()
    .WithAddress("address.example.com", 6379)
    .WithTls()
    .WithTrustedCertificate("/path/to/ca-cert.pem")
    .Build();

await using var client = await GlideClusterClient.CreateClient(config);

Example - Using Certificate as Bytes

using System.Text;
using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

byte[] certData = Encoding.UTF8.GetBytes(
    "-----BEGIN CERTIFICATE-----\n"
    + "MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKmzMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\n"
    + "...\n"
    + "-----END CERTIFICATE-----\n"
);

var config = new StandaloneClientConfigurationBuilder()
    .WithAddress("primary.example.com", 6379)
    .WithTls()
    .WithTrustedCertificate(certData)
    .Build();

await using var client = await GlideClient.CreateClient(config);

Example - Multiple Certificates (Certificate Chain)

using Valkey.Glide;
using static Valkey.Glide.ConnectionConfiguration;

var config = new ClusterClientConfigurationBuilder()
    .WithAddress("address.example.com", 6379)
    .WithTls()
    .WithTrustedCertificate("/path/to/cert1.pem")
    .WithTrustedCertificate("/path/to/cert2.pem")
    .WithTrustedCertificate("/path/to/cert3.pem")
    .Build();

await using var client = await GlideClusterClient.CreateClient(config);

PHP

Example - Connecting with Custom Root Certificate

// Read certificate file
$rootCert = file_get_contents('/path/to/ca-cert.pem');

$client = new ValkeyGlide();
$client->connect(
    addresses: [['host' => 'address.example.com', 'port' => 6379]],
    use_tls: true,
    advanced_config: ['tls_config' => ['root_certs' => $rootCert]]
);

Example - Using Certificate as String

$certData = <<<'CERT'
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKmzMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----
CERT;

$client = new ValkeyGlideCluster(
    addresses: [['host' => 'address.example.com', 'port' => 6379]],
    use_tls: true,
    advanced_config: ['tls_config' => ['root_certs' => $certData]]
);

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 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