Connecting to a non-sharded Valkey™ cluster

You can connect to a non-sharded Valkey™ cluster:

• Using Valkey™ Sentinel.

  Valkey™ Sentinel is a Valkey™ host management system that provides monitoring, notification, automatic failover, and reporting of up-to-date host addresses to the clients.

  Unencrypted connection is supported via port 26379 for clusters with any version of Valkey™.

  If a client application does not support connecting via Sentinel, connect directly to the master host. If there is no need for a direct connection, use Sentinel for more reliable cluster host management.

  For more information about Sentinel, see Replication and fault tolerance and the Valkey™ documentation.

• Directly to the master host.

  Encrypted connection is supported via port 6380 and unencrypted via port 6379.

  Warning

  When using SSL, you can only connect to clusters with TLS support enabled.

  To always connect to the master host in a non-sharded cluster, use a special FQDN that always points to the master host, or track the roles of all the cluster hosts yourself.

Special FQDNs

Yandex Managed Service for Valkey™ provides special FQDNs that can be used instead of regular host FQDNs to connect to non-sharded clusters.

Current master

In a non-sharded cluster, an FQDN of c-<cluster_ID>.rw.mdb.yandexcloud.net format always points to the current master host. You can request the cluster ID with the list of clusters in the folder.

When connecting to this FQDN, both read and write operations are allowed.

Here is an example of an SSL-encrypted connection to a master host for a cluster with the c9qash3nb1v9******** ID:

redis-cli -h c-c9qash3nb1v9********.rw.mdb.yandexcloud.net \
  -p 6380 \
  --tls \
  --cacert ~/.redis/YandexInternalRootCA.crt \
  -a <Valkey™_password>

Connecting from graphical IDEs

The connection was tested in the following environment:

• MacOS Big Sur 11.3.
• DBeaver Enterprise: 21.0.

You can only use graphical IDEs to connect to cluster hosts through an SSL tunnel using a created VM. Before connecting, prepare a certificate.

To avoid connection errors, save the certificate to a local folder that does not require administrator rights to access.

Before you connect from a Docker container

To connect to a Yandex Managed Service for Valkey™ cluster from a Docker container, add the following lines to the Dockerfile:

# Build the redis-tools utility with TLS support manually.
RUN apt-get update && \
    apt-get install make gcc libssl-dev --yes && \
    wget https://download.redis.io/redis-stable.tar.gz && \
    tar -xzvf redis-stable.tar.gz && \
    cd redis-stable && \
    make BUILD_TLS=yes MALLOC=libc && \
    make install && \
    cp ./src/redis-cli /usr/bin/

# Build the redis-tools utility with TLS support manually.
RUN apt-get update && \
    apt-get install wget make gcc libssl-dev --yes && \
    wget https://download.redis.io/redis-stable.tar.gz && \
    tar -xzvf redis-stable.tar.gz && \
    cd redis-stable && \
    make BUILD_TLS=yes MALLOC=libc && \
    make install && \
    cp ./src/redis-cli /usr/bin/ && \
    # Get an SSL certificate.
    mkdir --parents ~/.redis && \
    wget "https://storage.yandexcloud.net/cloud-certs/CA.pem" \
         --output-document ~/.redis/YandexInternalRootCA.crt && \
    chmod 0655 ~/.redis/YandexInternalRootCA.crt

Examples of connection strings

The Linux examples were tested in the following environment:

• Yandex Cloud virtual machine running Ubuntu 20.04 LTS.
• Bash: 5.0.16.
• Python: 3.8.2; pip3: 20.0.2.
• PHP: 7.4.3.
• OpenJDK: 11.0.8; Maven: 3.6.3.
• Node.JS: 10.19.0, npm: 6.14.4.
• Go: 1.13.8.
• Ruby: 2.7.0p0.
• unixODBC: 2.3.6.

The Windows examples were tested in the following environment:

• A local machine with Windows 10 Pro build 19042.1052.
• PowerShell: 5.1.19041.
• cURL: 7.55.1 WinSSL.

To see code examples with the host FQDN filled in, open the cluster page in the management console and click Connect.

Bash

sudo apt update && sudo apt install -y redis-tools

redis-cli \
    -h c-<cluster_ID>.rw.mdb.yandexcloud.net \
    -a <password>

redis-cli \
    -h c-<cluster_ID>.rw.mdb.yandexcloud.net \
    -a <password> \
    -p 6380 \
    --tls \
    --cacert ~/.redis/YandexInternalRootCA.crt

To learn how to get a host FQDN, see this guide.

When you are connected to the cluster, run the commands:

SET foo bar
GET foo

If the connection to the cluster and the test query are successful, the bar string is output.

Go

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y golang git && \
  go mod init github.com/go-redis/redis && \
  go get github.com/go-redis/redis/v7

package main

import (
	"fmt"
	"github.com/go-redis/redis/v7"
)

func main() {
	conn := redis.NewUniversalClient(
		&redis.UniversalOptions{
			Addrs: []string{
				"<Valkey™_host_1_FQDN>:26379",
				...
				"<Valkey™_host_N_FQDN>:26379"},
			MasterName: "<Valkey™_cluster_name>",
			Password:   "<password>",
			ReadOnly:   false,
		},
	)
	err := conn.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	result, err := conn.Get("foo").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println(result)

	conn.Close()
}

package main

import (
	"fmt"
	"github.com/go-redis/redis/v7"
)

func main() {
	conn := redis.NewUniversalClient(
		&redis.UniversalOptions{
			Addrs:    []string{"c-<cluster_ID>.rw.mdb.yandexcloud.net:6379"},
			Password: "<password>",
			ReadOnly: false,
		},
	)
	err := conn.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	result, err := conn.Get("foo").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println(result)

	conn.Close()
}

package main

import (
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"github.com/go-redis/redis/v7"
	"io/ioutil"
)

const (
	cert = "/home/<home_directory>/.redis/YandexInternalRootCA.crt"
)

func main() {
	rootCertPool := x509.NewCertPool()
	pem, err := ioutil.ReadFile(cert)
	if err != nil {
		panic(err)
	}

	if ok := rootCertPool.AppendCertsFromPEM(pem); !ok {
		panic("Failed to append PEM.")
	}

	conn := redis.NewUniversalClient(
		&redis.UniversalOptions{
			Addrs:    []string{"c-<cluster_ID>.rw.mdb.yandexcloud.net:6380"},
			Password: "<password>",
			ReadOnly: false,
			TLSConfig: &tls.Config{
				RootCAs:            rootCertPool,
			},
		},
	)
	err = conn.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	result, err := conn.Get("foo").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println(result)

	conn.Close()
}

To learn how to get a host FQDN, see this guide.

Connecting:

go run connect.go

If the connection to the cluster and the test query are successful, the bar string is output.

Java

Before connecting:

1. Install the dependencies:

   sudo apt update && sudo apt install --yes default-jdk maven
   

2. Create a folder for the Maven project:

   cd ~/ && mkdir --parents project/src/java/com/example && cd project/
   

3. Create a configuration file for Maven:

   pom.xml

   <?xml version="1.0" encoding="utf-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
   
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.example</groupId>
     <artifactId>app</artifactId>
     <packaging>jar</packaging>
     <version>0.1.0</version>
     <properties>
       <maven.compiler.source>1.8</maven.compiler.source>
       <maven.compiler.target>1.8</maven.compiler.target>
     </properties>
     <dependencies>
       <dependency>
         <groupId>redis.clients</groupId>
         <artifactId>jedis</artifactId>
         <version>3.7.0</version>
       </dependency>
       <dependency>
         <groupId>org.slf4j</groupId>
         <artifactId>slf4j-simple</artifactId>
         <version>1.7.30</version>
       </dependency>
     </dependencies>
     <build>
       <finalName>${project.artifactId}-${project.version}</finalName>
       <sourceDirectory>src</sourceDirectory>
       <resources>
         <resource>
           <directory>src</directory>
         </resource>
       </resources>
       <plugins>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-assembly-plugin</artifactId>
           <executions>
             <execution>
               <goals>
                 <goal>attached</goal>
               </goals>
               <phase>package</phase>
               <configuration>
                 <descriptorRefs>
                   <descriptorRef>
                   jar-with-dependencies</descriptorRef>
                 </descriptorRefs>
                 <archive>
                   <manifest>
                     <mainClass>com.example.App</mainClass>
                   </manifest>
                 </archive>
               </configuration>
             </execution>
           </executions>
         </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-jar-plugin</artifactId>
           <version>3.1.0</version>
           <configuration>
             <archive>
               <manifest>
                 <mainClass>com.example.App</mainClass>
               </manifest>
             </archive>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>
   

   Up-to-date versions of dependencies for Maven:

   • jedis
   • slf4j-simple

4. To connect using SSL:

   1. Get an SSL certificate.

   2. Create secure storage for certificates:

      keytool -importcert \
          -alias YARootCrt \
          -file ~/.redis/YandexInternalRootCA.crt \
          -keystore ~/.redis/YATrustStore \
          -storepass <password_of_secure_certificate_storage> \
          --noprompt && chmod 0655 ~/.redis/YATrustStore
      

package com.example;

import java.util.HashSet;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisSentinelPool;

public class App {
  public static void main(String[] args) {
    String redisName = "<Valkey™_cluster_name>";
    String redisPass = "<password>";

    HashSet sentinels = new HashSet();
    sentinels.add("<Valkey™_host_1_FQDN>:26379");
    ...
    sentinels.add("<Valkey™_host_N_FQDN>:26379");

    try {
      JedisSentinelPool pool = new JedisSentinelPool(redisName, sentinels);
      Jedis conn = pool.getResource();

      conn.auth(redisPass);
      conn.set("foo", "bar");
      System.out.println(conn.get("foo"));

      pool.close();
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

package com.example;

import redis.clients.jedis.Jedis;

public class App {
  public static void main(String[] args) {
    String redisHost = "c-<cluster_ID>.rw.mdb.yandexcloud.net";
    String redisPass = "<password>";

    try {
      Jedis conn = new Jedis(redisHost);

      conn.auth(redisPass);
      conn.set("foo", "bar");
      System.out.println(conn.get("foo"));

      conn.close();
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

package com.example;

import redis.clients.jedis.DefaultJedisClientConfig;
import redis.clients.jedis.HostAndPort;
import redis.clients.jedis.Jedis;

import javax.net.ssl.SSLParameters;

public class App {
  public static void main(String[] args) {
    String redisHost = "c-<cluster_ID>.rw.mdb.yandexcloud.net";
    String redisPass = "<cluster_password>";

    System.setProperty("javax.net.ssl.trustStore", "/home/<home_directory>/.redis/YATrustStore");
    System.setProperty("javax.net.ssl.trustStorePassword", "<secure_certificate_storage_password>");

    SSLParameters sslParameters = new SSLParameters();
    DefaultJedisClientConfig jedisClientConfig = DefaultJedisClientConfig.builder().
            password(redisPass).
            ssl(true).
            sslParameters(sslParameters).
            build();

    try {
      Jedis conn = new Jedis(new HostAndPort(redisHost, 6380), jedisClientConfig);

      conn.set("foo", "bar");
      System.out.println(conn.get("foo"));
      conn.close();
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

To learn how to get a host FQDN, see this guide.

Connecting:

mvn clean package && \
  java -jar target/app-0.1.0-jar-with-dependencies.jar

If the connection to the cluster and the test query are successful, the bar string is output.

Node.js

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y nodejs npm && \
  npm install ioredis

"use strict";
const Redis = require("ioredis");

const conn = new Redis({
    sentinels: [
        { host: "<Valkey™_host_1_FQDN>", port: 26379 },
        ...
        { host: "<Valkey™_host_N_FQDN>", port: 26379 },
    ],
    name: "<Valkey™_cluster_name>",
    password: "<password>"
});

conn.set("foo", "bar", function (err) {
    if (err) {
        console.error(err);
        conn.disconnect();
    }
});

conn.get("foo", function (err, result) {
    if (err) {
        console.error(err);
    } else {
        console.log(result);
    }

    conn.disconnect();
});

"use strict";

const Redis = require("ioredis");

const conn = new Redis({
    host: "c-<cluster_ID>.rw.mdb.yandexcloud.net",
    port: 6379,
    password: "<password>"
});

conn.set("foo", "bar", function (err) {
    if (err) {
        console.error(err);
        conn.disconnect();
    }
});

conn.get("foo", function (err, result) {
    if (err) {
        console.error(err);
    } else {
        console.log(result);
    }

    conn.disconnect();
});

"use strict";

const fs = require("fs");
const Redis = require("ioredis");

const conn = new Redis({
    host: "c-<cluster_ID>.rw.mdb.yandexcloud.net",
    port: 6380,
    password: "<password>",
    tls: {
        ca: fs.readFileSync("/home/<home_directory>/.redis/YandexInternalRootCA.crt"),
    }
});

conn.set("foo", "bar", function (err) {
    if (err) {
        console.error(err);
        conn.disconnect();
    }
});

conn.get("foo", function (err, result) {
    if (err) {
        console.error(err);
    } else {
        console.log(result);
    }

    conn.disconnect();
});

To learn how to get a host FQDN, see this guide.

Connecting:

node app.js

If the connection to the cluster and the test query are successful, the bar string is output.

PHP

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y php php-dev php-pear && \
    sudo pear channel-discover pear.nrk.io && \
    sudo pear install nrk/Predis

<?php
require "Predis/Autoloader.php";
Predis\Autoloader::register();

$sentinels = [
    "<Valkey™_host_1_FQDN>:26379>",
    ...
    "<Valkey™_host_N_FQDN>:26379>",
];
$options = [
    "replication" => "sentinel",
    "service" => "<Valkey™_cluster_name>",
    "parameters" => [
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($sentinels, $options);

$conn->set("foo", "bar");
var_dump($conn->get("foo"));

$conn->disconnect();
?>

<?php
require "Predis/Autoloader.php";
Predis\Autoloader::register();

$host = ["c-<cluster_ID>.rw.mdb.yandexcloud.net:6379"];
$options = [
    "parameters" => [
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($host, $options);

$conn->set("foo", "bar");
var_dump($conn->get("foo"));

$conn->disconnect();
?>

<?php
require "Predis/Autoloader.php";
Predis\Autoloader::register();

$host = ["c-<cluster_ID>.rw.mdb.yandexcloud.net:6380"];
$options = [
    "parameters" => [
        "scheme" => "tls",
        "ssl" => [
            "cafile" => "/home/<home_directory>/.redis/YandexInternalRootCA.crt",
            "verify_peer" => true,
            "verify_peer_name" => false,
        ],
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($host, $options);

$conn->set("foo", "bar");
var_dump($conn->get("foo"));

$conn->disconnect();
?>

To learn how to get a host FQDN, see this guide.

Connecting:

php connect.php

If the connection to the cluster and the test query are successful, the bar string is output.

Python

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y python3 python3-pip && \
pip3 install redis

from redis.sentinel import Sentinel

sentinels = [
    "<Valkey™_host_1_FQDN>",
    ...
    "<Valkey™_host_N_FQDN>"
]
name = "<Valkey™_cluster_name>"
pwd = "<password>"

sentinel = Sentinel([(h, 26379) for h in sentinels], socket_timeout=0.1)
master = sentinel.master_for(name, password=pwd)
slave = sentinel.slave_for(name, password=pwd)

master.set("foo", "bar")
print(slave.get("foo"))

import redis

r = redis.StrictRedis(
    host="c-<cluster_ID>.rw.mdb.yandexcloud.net",
    port=6379,
    password="<password>",
)

r.set("foo", "bar")
print(r.get("foo"))

import redis

r = redis.StrictRedis(
    host="c-<cluster_ID>.rw.mdb.yandexcloud.net",
    port=6380,
    password="<password>",
    ssl=True,
    ssl_ca_certs="/home/<home_directory>/.redis/YandexInternalRootCA.crt",
)

r.set("foo", "bar")
print(r.get("foo"))

To learn how to get a host FQDN, see this guide.

Connecting:

python3 connect.py

If the connection to the cluster and the test query are successful, the bar string is output.

Ruby

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y ruby && \
  sudo gem install redis

# coding: utf-8

require 'redis'

SENTINELS = [
  { host: '<Valkey™_host_1_FQDN>', port: 26379 },
  ...
  { host: '<Valkey™_host_N_FQDN>', port: 26379 }
]

conn = Redis.new(
  host: '<Valkey™_cluster_name>',
  sentinels: SENTINELS,
  role: 'master',
  password: '<password>'
)

conn.set('foo', 'bar')
puts conn.get('foo')

conn.close

# coding: utf-8

require 'redis'

conn = Redis.new(
  host: 'c-<cluster_ID>.rw.mdb.yandexcloud.net',
  port: 6379,
  password: '<password>'
)

conn.set('foo', 'bar')
puts conn.get('foo')

conn.close

# coding: utf-8

require 'redis'

conn = Redis.new(
  host: 'c-<cluster_ID>.rw.mdb.yandexcloud.net',
  port: 6380,
  password: '<password>',
  ssl: true,
  ssl_params: { ca_file: '/home/<home_directory>/.redis/YandexInternalRootCA.crt' },
)

conn.set('foo', 'bar')
puts conn.get('foo')

conn.close

To learn how to get a host FQDN, see this guide.

Connecting:

ruby connect.rb

If the connection to the cluster and the test query are successful, the bar string is output.