[Yandex Cloud documentation](../../index.md) > [Yandex StoreDoc](../index.md) > [Step-by-step guides](index.md) > Clusters > Migrating hosts to a different availability zone

# Migrating Yandex StoreDoc cluster hosts to a different availability zone

Yandex StoreDoc cluster hosts reside in Yandex Cloud [availability zones](../../overview/concepts/geo-scope.md). To migrate hosts from one availability zone to another, do the following:

1. [Create a subnet](../../vpc/operations/subnet-create.md) in your target availability zone.
1. Add a host to your cluster:

   {% list tabs group=instructions %}

   - Management console {#console}

      1. Open the [folder dashboard](https://console.yandex.cloud).
      1. Navigate to **Yandex StoreDoc**.
      1. Click the name of your Yandex StoreDoc cluster and open the **Hosts** tab.
      1. Click ![image](../../_assets/console-icons/plus.svg) **Create host**.
      1. 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**.

      1. Click **Save**.

   - CLI {#cli}

      If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

      The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

      Run this command:

      ```bash
      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](cluster-list.md#list-clusters).
      * Possible `type` values are `mongod`, `mongos`, `mongocfg`, and `mongoinfra`. The host type depends on the [sharding type](../concepts/sharding.md#shard-management).
      * In the `zone-id` argument, provide the target availability zone for your hosts.

   - Terraform {#tf}

      1. Add the host manifest to the Terraform configuration file describing your infrastructure:

         ```hcl
         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](../concepts/sharding.md#shard-management).

         In the `zone` argument, provide the target availability zone for your hosts.

      1. 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.
         1. Run this command:
         
            ```bash
            terraform validate
            ```
         
            Terraform will show any errors found in your configuration files.

      1. Confirm updating the resources.

         1. Run this command to view the planned changes:
         
            ```bash
            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.
         
         1. If everything looks correct, apply the changes:
            1. Run this command:
         
               ```bash
               terraform apply
               ```
         
            1. Confirm updating the resources.
            1. Wait for the operation to complete.

   - REST API {#api}

      1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

            ```bash
            export IAM_TOKEN="<IAM_token>"
            ```

      1. Call the [Cluster.AddHosts](../api-ref/Cluster/addHosts.md) method, e.g., via the following [cURL](https://curl.se/) request:

            ```bash
            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. One array element contains settings for a single host:

            * `zoneId`: [Availability zone](../../overview/concepts/geo-scope.md).
            * `subnetId`: [Subnet ID](../../vpc/concepts/network.md#subnet).
            * `assignPublicIp`: Internet access to the host 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](../concepts/replication.md#master-failover).
            * `tags`: Host tags.

            You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

      1. Check the [server response](../api-ref/Cluster/addHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

   - gRPC API {#grpc-api}

      1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

            ```bash
            export IAM_TOKEN="<IAM_token>"
            ```

      1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
         
         ```bash
         cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
         ```
         
         Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
      1. Call the [ClusterService.AddHosts](../api-ref/grpc/Cluster/addHosts.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

            ```bash
            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](../../overview/concepts/geo-scope.md).
            * `subnet_id`: [Subnet ID](../../vpc/concepts/network.md#subnet).
            * `assign_public_ip`: Internet access to the host 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](../concepts/replication.md#master-failover).
            * `tags`: Host tags.

            You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

      1. Check the [server response](../api-ref/grpc/Cluster/addHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

   {% endlist %}

1. 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 the source availability zone.

   You can get this FQDN from the list of hosts in your cluster:

   ```bash
   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](https://console.yandex.cloud), see [this guide](connect/index.md#get-fqdn).

1. Delete the hosts in the source availability zone:

   {% list tabs group=instructions %}

   - Management console {#console}

      1. Open the [folder dashboard](https://console.yandex.cloud).
      1. Navigate to **Yandex StoreDoc**.
      1. Locate the Yandex StoreDoc cluster you need in the list, click its name, and select the **Hosts** tab.
      1. Find the host you need in the list, click ![image](../../_assets/console-icons/ellipsis.svg) in its row, select **Delete**, and confirm the deletion.

   - CLI {#cli}

      Run the following command for each host:

      ```bash
      yc managed-mongodb host delete <host_FQDN> --cluster-name <cluster_name>
      ```

   - Terraform {#tf}

      1. In your Terraform infrastructure configuration file, locate your cluster description and delete the `host` sections with the source availability zone.
      1. 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.
         1. Run this command:
         
            ```bash
            terraform validate
            ```
         
            Terraform will show any errors found in your configuration files.

      1. Type `yes` and press **Enter**.

         1. Run this command to view the planned changes:
         
            ```bash
            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.
         
         1. If everything looks correct, apply the changes:
            1. Run this command:
         
               ```bash
               terraform apply
               ```
         
            1. Confirm updating the resources.
            1. Wait for the operation to complete.

   - REST API {#api}

      1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

            ```bash
            export IAM_TOKEN="<IAM_token>"
            ```

      1. Call the [Cluster.DeleteHosts](../api-ref/Cluster/deleteHosts.md) method, e.g., via the following [cURL](https://curl.se/) request:

            ```bash
            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](hosts.md#list-hosts).

            You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

      1. Check the [server response](../api-ref/Cluster/deleteHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

   - gRPC API {#grpc-api}

      1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

            ```bash
            export IAM_TOKEN="<IAM_token>"
            ```

      1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
         
         ```bash
         cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
         ```
         
         Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
      1. Call the [ClusterService.DeleteHosts](../api-ref/grpc/Cluster/deleteHosts.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

            ```bash
            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](hosts.md#list-hosts).

            You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

      1. Check the [server response](../api-ref/grpc/Cluster/deleteHosts.md#yandex.cloud.operation.Operation) to make sure your request was successful.

   {% endlist %}

1. Wait for the cluster state to change to **Alive**. In the [management console](https://console.yandex.cloud), navigate to the folder containing your cluster. Navigate to **Yandex StoreDoc**. You can check the cluster state in the **Availability** column.

{% note info %}

Clusters with hosts residing in the `ru-central1-d` [availability zone](../../overview/concepts/geo-scope.md) do not support:

- Intel Broadwell
- Local SSD storage if using Intel Cascade Lake

{% endnote %}

## Specifics of migration in Yandex Data Transfer {#data-transfer}

If your cluster is used as an [endpoint](../../data-transfer/concepts/index.md#endpoint) when transferring data with Data Transfer, and the [transfer type](../../data-transfer/concepts/transfer-lifecycle.md#transfer-types) 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 upon their activation.

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

* [Deactivate](../../data-transfer/operations/transfer.md#deactivate) the transfer and wait for its status to change to **Stopped**. Next, [reactivate](../../data-transfer/operations/transfer.md#activate) the transfer and wait for its status to change to **Replicating**.
* Update any [setting for the transfer](../../data-transfer/operations/transfer.md#update) or [endpoint](../../data-transfer/operations/endpoint/index.md#update).

For more information, see [Migrating a Data Transfer transfer and endpoints to a different availability zone](../../data-transfer/operations/endpoint/migration-to-an-availability-zone.md).