Contact UsGet started

Migrating MongoDB cluster hosts to a different availability zone

Written by
Updated at May 5, 2025

Managed Service for MongoDB cluster hosts reside in availability zones Yandex Cloud. To move hosts from one availability zone to another:

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

  2. Add a host to your cluster:

    1. Go to the folder page and select Managed Service for MongoDB.

    2. Click the name of the Managed Service for MongoDB cluster you need 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 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.

    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=<public_access_to_host:_true_or_false>

    Command specifics:

    • You can get the cluster name with the list of clusters in the folder.
    • Possible type values: mongod, mongos, mongocfg, or mongoinfra. The host type depends on the sharding type.
    • 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_mongodb_cluster" "<cluster_name>" {
  ...
  host {
    type             = "<host_type>"
    zone_id          = "<availability_zone>"
    subnet_id        = "<new_subnet_ID>"
    assign_public_ip = <public_access_to_host:_true_or_false>
    ...
  }
}

      Possible type values: MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. The host type depends on the sharding type.

      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 put it into the environment variable:

      export IAM_TOKEN="<IAM_token>"

    2. Use the Cluster.AddHosts method and send the following 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-mongodb/v1/clusters/<cluster_ID>/hosts:batchCreate' \
   --data '{
            "hostSpecs": [
              {
                "zoneId": "<availability_zone>",
                "subnetId": "<subnet_ID>",
                "assignPublicIp": <public_host_address:_true_or_false>,
                "type": "<host_type>",
                "shardName": "<shard_name>",
                "hidden": <host_visibility:_true_or_false>,
                "secondaryDelaySecs": "<lag_in_seconds>",
                "priority": "<host_priority_for_assignment_as_master>",
                "tags": "<host_labels>"
              }
            ]
          }'

      Where hostSpecs is an array of new hosts. One array element contains settings for a single host:

      • zoneId: Availability zone.
      • subnetId: Subnet ID.
      • assignPublicIp: Internet access to the host via a public IP address.
      • 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: The host will either be visible or hidden.
      • secondaryDelaySecs: Host's lag behind the master.
      • priority: Host priority for assignment as a master if the primary master fails.
      • tags: Host labels.

      You can request the cluster ID with the 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.AddHosts call and send the following request, e.g., via gRPCurl:

      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": <public_host_address:_true_or_false>,
             "type": "<host_type>",
             "shard_name": "<shard_name>",
             "hidden": <host_visibility:_true_or_false>,
             "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. One array element contains settings for a single host:

      • zone_id: Availability zone.
      • subnet_id: Subnet ID.
      • assign_public_ip: Internet access to the host via a public IP address.
      • 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: The host will either be visible or hidden.
      • secondary_delay_secs: Host's lag behind the master.
      • priority: Host priority for assignment as a master if the primary master fails.
      • tags: Host labels.

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

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

  3. 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-mongodb host list --cluster-name <cluster_name>

    The FQDN is specified in the command output under NAME.

    To learn how to get a host FQDN in the management console, see this guide.

  4. Delete the hosts in the source availability zone:

    1. Go to the folder page and select Managed Service for MongoDB.
    2. Click the name of the Managed Service for MongoDB cluster you need and select the Hosts tab.
    3. Click in the required host 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 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 send the following 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-mongodb/v1/clusters/<cluster_ID>/hosts:batchDelete' \
   --data '{
             "hostNames": [
               "<host_name>"
             ]
           }'

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

      You can request the cluster ID with the 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 send the following request, e.g., via gRPCurl:

      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 with the names of hosts to delete. To find out the host name, get a list of hosts in the cluster.

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

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

  5. Wait until the cluster status changes to Alive. In the management console, go to the folder page and select Managed Service for MongoDB. You can see the cluster status in the Availability column.

Note

Not available for clusters with hosts residing in the ru-central1-d availability zone:

  • Intel Broadwell platform
  • 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:

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

Previous
Managing cluster hosts
Next
Managing backups