Migrating Yandex StoreDoc cluster hosts to a different availability zone

Written by

Updated at February 6, 2026

Yandex StoreDoc cluster hosts reside in Yandex Cloud availability zones. To migrate hosts from one availability zone to another, do the following:

Create a subnet in your target availability zone.
Add a host to your cluster:
Management console

CLI

Terraform

REST API

gRPC API
1. Open the folder dashboard.
2. Navigate to the Yandex StoreDoc service.
3. Click the name of your Yandex StoreDoc cluster and open the Hosts tab.
4. Click Create host.
5. Specify the following host settings:
  - Target availability zone for your hosts.
  - New subnet.
  - To make the host accessible from outside Yandex Cloud, select Public access.
6. 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-mongodb host add \
   --cluster-name <cluster_name> \
   --host type=<host_type>,`
         `zone-id=<availability_zone>,`
         `subnet-id=<new_subnet_ID>,`
         `assign-public-ip=<allow_public_access_to_host>
```
Command specifics:
- You can get the cluster name from the list of clusters in your folder.
- Possible type values are mongod, mongos, mongocfg, and mongoinfra. The host type depends on the sharding type.
- In the zone-id argument, provide the target availability zone for your hosts.
1. Add the host manifest to the Terraform configuration file describing your infrastructure:
  resource "yandex_mdb_mongodb_cluster" "<cluster_name>" { ... host { type = "<host_type>" zone_id = "<availability_zone>" subnet_id = "<new_subnet_ID>" assign_public_ip = <allow_public_access_to_host> ... } }
  Possible type values are MONGOD, MONGOINFRA, MONGOS, and MONGOCFG. The host type depends on the sharding type.
  
  In the zone argument, provide the target availability zone for your hosts.
2. Validate your configuration.
  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 resource changes.
  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:
    
    Run this command:
    
    terraform apply
    
    Confirm updating the resources.
    
    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. Call the Cluster.AddHosts method, e.g., via the following cURL request:
  curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>/hosts:batchCreate' \ --data '{ "hostSpecs": [ { "zoneId": "<availability_zone>", "subnetId": "<subnet_ID>", "assignPublicIp": <allow_public_access_to_host>, "type": "<host_type>", "shardName": "<shard_name>", "hidden": <hide_host>, "secondaryDelaySecs": "<lag_in_seconds>", "priority": "<host_priority_for_assignment_as_master>", "tags": "<host_labels>" } ] }'
  Where hostSpecs is an array of new hosts, in which each element contains the settings for a single host:
  - zoneId: Availability zone.
  - subnetId: Subnet ID.
  - assignPublicIp: Controls whether the host is accessible via a public IP address, true or false.
  - type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. For a non-sharded cluster, use MONGOD.
  - shardName: Shard name in a sharded cluster.
  - hidden: Determines whether the host is hidden, true or false.
  - secondaryDelaySecs: Host's replication lag behind the master.
  - priority: Host priority for master promotion during failover.
  - tags: Host tags.
  You can get the cluster ID from the list of clusters in your folder.
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 that the repository contents reside in the ~/cloudapi/ directory.
3. Call the ClusterService.AddHosts method, e.g., via the following gRPCurl request:
  grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/mongodb/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>", "assign_public_ip": <allow_public_access_to_host>, "type": "<host_type>", "shard_name": "<shard_name>", "hidden": <hide_host>, "secondary_delay_secs": "<lag_in_seconds>", "priority": "<host_priority_for_assignment_as_master>", "tags": "<host_labels>" } ] }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.mongodb.v1.ClusterService.AddHosts
  Where host_specs is an array of new hosts, in which each element contains the settings for a single host:
  - zone_id: Availability zone.
  - subnet_id: Subnet ID.
  - assign_public_ip: Controls whether the host is accessible via a public IP address, true or false.
  - type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. For a non-sharded cluster, use MONGOD.
  - shard_name: Shard name in a sharded cluster.
  - hidden: Determines whether the host is hidden, true or false.
  - secondary_delay_secs: Host’s replication lag behind the master.
  - priority: Host priority for master promotion during failover.
  - tags: Host tags.
  You can get the cluster ID from the list of clusters in your folder.
4. Check the server response to make sure your request was successful.
To connect to the database after migration, specify the new host’s FQDN in your backend or client, e.g., in your application code or graphical IDE. Delete the original host's FQDN in your source availability zone.

You can get this FQDN from the list of hosts in your cluster:
```
yc managed-mongodb host list --cluster-name <cluster_name>
```
You will see the FQDN under NAME in the command output.

For details on how to get a host’s FQDN in the management console, see this guide.
Delete the hosts in the source availability zone:
Management console

CLI

Terraform

REST API

gRPC API
1. Open the folder dashboard.
2. Navigate to the Yandex StoreDoc service.
3. Locate the Yandex StoreDoc cluster you need in the list, click its name, and select the Hosts tab.
4. Find the host you need in the list, click in its row, select Delete, and confirm the deletion.
Run the following command for each host:
```
yc managed-mongodb host delete <host_FQDN> --cluster-name <cluster_name>
```
1. In your Terraform infrastructure configuration file, locate your cluster description and delete the host sections with the source availability zone.
2. Validate your configuration.
  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:
    
    Run this command:
    
    terraform apply
    
    Confirm updating the resources.
    
    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. Call the Cluster.DeleteHosts method, e.g., via the following cURL request:
  curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>/hosts:batchDelete' \ --data '{ "hostNames": [ "<host_name>" ] }'
  Where hostNames is the array containing the host you want to delete. You can get the host name from the list of hosts in your cluster.
  
  You can get the cluster ID from the list of clusters in your folder.
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 that the repository contents reside in the ~/cloudapi/ directory.
3. Call the ClusterService.DeleteHosts method, e.g., via the following gRPCurl request:
  grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/mongodb/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.mongodb.v1.ClusterService.DeleteHosts
  Where host_names is an array containing the host names you want to delete. You can get the host name from the list of hosts in your cluster.
  
  You can get the cluster ID from the list of clusters in your folder.
4. Check the server response to make sure your request was successful.
Wait for the cluster state to change to Alive. In the management console, navigate to the folder containing your cluster. Navigate to the Yandex StoreDoc service. You can check the cluster state in the Availability column.

Note

Clusters with hosts residing in the ru-central1-d availability zone do not support:

Intel Broadwell
Local SSD storage if using Intel Cascade Lake

Specifics of migration in Yandex Data Transfer

If your cluster is used as an endpoint when transferring data with Data Transfer, and the transfer type is Replication or Snapshot and increment, restart the transfer after migrating the cluster. This way, the transfer will get data about the cluster's new topology.

You do not need to restart Snapshot transfers, as information about the new topology is provided automatically while activating them.

To restart a transfer, choose one of the two methods:

Deactivate the transfer and wait for its status to change to Stopped. Next, reactivate the transfer and wait for its status to change to Replicating.
Update any setting for the transfer or endpoint.

For more information, see Migrating a Data Transfer transfer and endpoints to a different availability zone.

Migrating Yandex StoreDoc cluster hosts to a different availability zone

Specifics of migration in Yandex Data TransferSpecifics of migration in Yandex Data Transfer

Was the article helpful?

Specifics of migration in Yandex Data Transfer