Master failover

Written by

Updated at February 3, 2026

In a fault-tolerant multi-host Yandex Managed Service for Valkey™ cluster, you can perform a manual failover from the current master host to a replica host. After the failover, the current master host becomes a replica for the new master.

Master failover normally takes a few minutes, with no downtime for the cluster.

A sharded cluster contains one or more master hosts: one per shard. Master failover in a sharded cluster is performed sequentially for each shard.

Management console

CLI

REST API

gRPC API

To switch the master in a non-sharded cluster:

In the management console, navigate to the folder with the non-sharded cluster.
Navigate to the Yandex Managed Service for Valkey™ service.
Click the name of your cluster and select the Hosts tab.
Next to the host with the MASTER role, click and select Switch master host.
In the window that opens, select I want to switch the master and click Switch.

To switch the master in a sharded cluster:

In the management console, navigate to the folder with the sharded cluster.
Navigate to the Yandex Managed Service for Valkey™ service.
Click the name of your cluster and select the Hosts tab.
Next to the host with the MASTER role, click and select Switch master host.
In the window that opens, click Switch.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To switch the master in a non-sharded cluster, run this command:

yc managed-redis cluster start-failover \
  --name <cluster_name>

To switch the master in a sharded cluster, run this command:

yc managed-redis cluster start-failover \
  --name <cluster_name> \
  --hostnames <current_master_name>

You can get the cluster name with the list of clusters in the folder, and the master name for the shard, with the list of hosts in the cluster.

Get an IAM token for API authentication and place it in an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```

Call the Cluster.StartFailover method, e.g., via the following cURL request:

To switch the master in a non-sharded cluster:

curl \
    --request POST \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --url 'https://mdb.api.cloud.yandex.net/managed-redis/v1/clusters/<cluster_ID>:startFailover'

To switch the master in a sharded cluster:

curl \
    --request POST \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-redis/v1/clusters/<cluster_ID>:startFailover' \
    --data '{
              "hostNames": [
                "<current_master_name>"
              ]
            }'

You can get the cluster ID with the list of clusters in the folder, and the name of the current master, with the list of hosts in the cluster.

Check the server response to make sure your request was successful.

Get an IAM token for API authentication and place it in an environment variable:
```
export IAM_TOKEN="<IAM_token>"
```
Clone the cloudapi repository:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

Call the ClusterService.StartFailover method, e.g., via the following gRPCurl request:

To switch the master in a non-sharded cluster:

grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/redis/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
          "cluster_id": "<cluster_ID>"
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.redis.v1.ClusterService.StartFailover

To switch the master in a sharded cluster:

grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/redis/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
          "cluster_id": "<cluster_ID>",
          "host_names": [
            "<current_master_name>"
          ]
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.redis.v1.ClusterService.StartFailover

You can request the cluster ID with the list of clusters in the folder, and the name of the current master with the list of hosts in the cluster.

Check the server response to make sure your request was successful.

Master failover

Was the article helpful?