Migrating Valkey™ cluster hosts to a different availability zone

Yandex Managed Service for Valkey™ cluster hosts reside in availability zones Yandex Cloud. To move hosts from one zone to another, add hosts residing in the target availability zone to the cluster and delete the hosts in the source availability zone:

1. Create a subnet in the availability zone you want to move your hosts to.

2. If your cluster uses the b2.medium or b3-c1-m4 host class, change it. Otherwise, you will not be able to add hosts to the cluster and perform migration.

   The cluster is unavailable for about five to seven minutes after changing the host class.

   You can restore the original class after migration.

3. Add a host to your cluster:

   Management console

   CLI

   Terraform

   REST API

   gRPC API

   1. Navigate to the folder dashboard and select Yandex Managed Service for Valkey™.

   2. Click the cluster name and go to the Hosts tab.

   3. Click  Create host.

   4. Specify the host parameters:

      • Availability zone to which you want to move the hosts.
      • New subnet.
      • Select Public access if the host must be accessible from outside Yandex Cloud.

   5. Click Save.

   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.

   Run this command:

   yc managed-redis host add \
      --cluster-name <cluster_name> \
      --host zone-id=<availability_zone>,`
            `subnet-id=<new_subnet_ID>,`
            `assign-public-ip=<allow_public_access_to_host>
   

   You can get the cluster name with the list of clusters in the folder.

   In the zone-id parameter, specify the availability zone you are moving the hosts to.

   1. Add a host manifest to the Terraform configuration file with the infrastructure plan:

      resource "yandex_mdb_redis_cluster" "<cluster_name>" {
        ...
        host {
          zone             = "<availability_zone>"
          subnet_id        = "<new_subnet_ID>"
          assign_public_ip = <allow_public_access_to_host>
        }
      }
      

      In the zone parameter, specify the availability zone you are moving the hosts to.

   2. Make sure the settings are correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

         terraform validate
         

         Terraform will show any errors found in your configuration files.

   3. Confirm updating the resources.

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

   1. Get an IAM token for API authentication and place it in an environment variable:

      export IAM_TOKEN="<IAM_token>"
      

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

      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>/hosts:batchCreate' \
          --data '{
                    "hostSpecs": [
                      {
                        "zoneId": "<availability_zone>",
                        "subnetId": "<subnet_ID>",
                        "shardName": "<shard_name>",
                        "replicaPriority": "<host_priority>",
                        "assignPublicIp": <allow_public_access_to_host>
                      }
                    ]
                  }'
      

      Where hostSpecs sets the host parameters:

      • zoneId: Availability zone.
      • subnetId: Subnet ID. Specify it if the selected availability zone has two or more subnets.
      • shardName: Shard name for the host. Only used if cluster sharding is enabled.
      • replicaPriority: Host priority for assignment as a master if the primary master fails.
      • assignPublicIp: Internet access to the host via a public IP address, true or false. Public access is only a possibility if the cluster has TLS support enabled.

      You can get the cluster ID from the folder’s cluster list.

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

   1. Get an IAM token for API authentication and place it in an environment variable:

      export IAM_TOKEN="<IAM_token>"
      

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

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

      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_specs": [
                  {
                    "zone_id": "<availability_zone>",
                    "subnet_id": "<subnet_ID>",
                    "shard_name": "<shard_name>",
                    "replica_priority": "<host_priority>",
                    "assign_public_ip": <allow_public_access_to_host>
                  }
                ] 
              }' \
          mdb.api.cloud.yandex.net:443 \
          yandex.cloud.mdb.redis.v1.ClusterService.AddHosts
      

      Where host_specs represents the host parameters:

      • zone_id: Availability zone.
      • subnet_id: Subnet ID. Specify it if the selected availability zone has two or more subnets.
      • shard_name: Shard name for the host. Only used if cluster sharding is enabled.
      • replica_priority: Host priority for assignment as a master if the primary master fails.
      • assign_public_ip: Internet access to the host via a public IP address, true or false. Public access is only a possibility if the cluster has TLS support enabled.

      You can get the cluster ID from the folder’s cluster list.

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

4. To successfully connect to the database after the migration is complete, specify the new host's FQDN in your backend or client (for example, in the code or graphical IDE). Delete the original host's FQDN in the source availability zone.

   To find out the FQDN, get a list of hosts in the cluster:

   yc managed-redis host list --cluster-name <cluster_name>
   

   The FQDN is specified in the command output under NAME.

5. Delete the hosts in the source availability zone:

   Management console

   CLI

   Terraform

   REST API

   gRPC API

   1. Navigate to the folder dashboard and select Yandex Managed Service for Valkey™.
   2. Click the cluster name and open the Hosts tab.
   3. Click in the host's row, select Delete, and confirm the deletion.

   Run the following command for each host:

   yc managed-redis host delete <host_FQDN> --cluster-name <cluster_name>
   

   1. In the Terraform configuration file with the infrastructure plan, remove the host sections with the source availability zone from the cluster description.

   2. Make sure the settings are correct.

      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

         terraform validate
         

         Terraform will show any errors found in your configuration files.

   3. Type yes and press Enter.

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

   1. Get an IAM token for API authentication and put it into the environment variable:

      export IAM_TOKEN="<IAM_token>"
      

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

      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>/hosts:batchDelete' \
          --data '{
                    "hostNames": [ "<host_name>" ]
                  }'
      

      Where hostNames is the name of the host to delete. To find out the name, get a list of hosts in the cluster.

      You can get the cluster ID with a list of clusters in the folder.

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

   1. Get an IAM token for API authentication and put it into the environment variable:

      export IAM_TOKEN="<IAM_token>"
      

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

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

      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": [ "<host_name>" ]
              }' \
          mdb.api.cloud.yandex.net:443 \
          yandex.cloud.mdb.redis.v1.ClusterService.DeleteHosts
      

      Where host_names is the name of the host to delete. To find out the name, get a list of hosts in the cluster.

      You can get the cluster ID with a list of clusters in the folder.

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

6. Wait until the cluster status changes to Alive. In the management console, go to the folder dashboard and select Yandex Managed Service for Valkey™. You can see the cluster status in the Availability column.