Switching the master

Written by

Updated at May 13, 2025

In a failover Yandex Managed Service for Valkey™ cluster with multiple hosts, you can switch the master role from the current master host to the replica host. After this operation, the current master host becomes the replica host of the new master.

It takes several minutes on average to switch, and the cluster is available during that time.

A sharded cluster contains one or more master hosts: one per shard. Switching the master for a sharded cluster is done for each shard one by one.

Management console

CLI

REST API

gRPC API

To switch the master in a non-sharded cluster:

In the management console, go to the folder containing the non-sharded cluster.
Select Yandex Managed Service for Valkey™.
Click the name of the cluster you need 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 the I want to switch the master option and click Switch.

To switch the master in a sharded cluster:

In the management console, go to the folder containing the sharded cluster.
Select Yandex Managed Service for Valkey™.
Click the name of the cluster you need 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) command line interface yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

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

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

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

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

You can request the cluster name with a list of clusters in the folder and the name of the master host for the desired shard with a list of hosts in the cluster.

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

Use the Cluster.StartFailover method and make a request, e.g., via cURL:

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

View the server response to make sure the request was successful.

Get an IAM token for API authentication and put it into the 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 the repository contents are stored in the ~/cloudapi/ directory.

Use the ClusterService.StartFailover call and make a request, e.g., via gRPCurl:

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.

View the server response to make sure the request was successful.

Switching the master

Was the article helpful?