Migrating ClickHouse® cluster hosts to a different availability zone

ClickHouse® and ZooKeeper hosts of the Managed Service for ClickHouse® cluster are located in Yandex Cloud availability zones. Follow this guide to migrate ClickHouse® and ZooKeeper hosts to a different availability zone. If you want to migrate ClickHouse® Keeper hosts, contact support.

Migrating ClickHouse® hostsMigrating ClickHouse® hosts

1. Make sure the migration will only include replicated tables on the ReplicatedMergeTree family engine.

   Non-replicated tables will be lost during migration.

2. If you have created a cluster without ClickHouse® Keeper support, enable fault tolerance using ZooKeeper hosts. Otherwise, you will not be able to add new hosts to shards and perform migration.

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

4. Add a host to your cluster:

   Management console

   CLI

   Terraform

   REST API

   gRPC API

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

   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 command line interface yet, install and initialize it.

   The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

   Run this command:

   yc managed-clickhouse host add \
      --cluster-name <cluster_name> \
      --host type=clickhouse,`
            `zone-id=<availability_zone>,`
            `subnet-id=<new_subnet_ID>,`
            `assign-public-ip=<public_access_to_host:_true_or_false>
   

   You can retrieve the cluster name with a 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_clickhouse_cluster" "<cluster_name>" {
        ...
        host {
          type             = "CLICKHOUSE"
          zone             = "<availability_zone>"
          subnet_id        = "<new_subnet_ID>"
          assign_public_ip = <public_access_to_host:_true_or_false>
        }
      }
      

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

   2. Make sure the settings are correct.

      1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

      2. Run the command:

         terraform validate
         

         If there are errors in the configuration files, Terraform will point to them.

   3. Confirm updating the resources.

      1. Run the command to view planned changes:

         terraform plan
         

         If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

      2. If you are happy with the planned changes, apply them:

         1. Run the command:

            terraform apply
            

         2. Confirm the update of 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-clickhouse/v1/clusters/<cluster_ID>/hosts:batchCreate' \
          --data '{
                    "hostSpecs": [
                      {
                        "type": "CLICKHOUSE",
                        "zoneId": "<availability_zone>",
                        "subnetId": "<subnet_ID>",
                        "assignPublicIp": <public_access_to_host>
                      }
                    ]
                  }'
      

      Where hostSpecs is an array with settings for the new hosts. One array element contains settings for a single host and has the following structure:

      • type: Host type, which is always CLICKHOUSE for ClickHouse® hosts.
      • zoneId: Availability zone.
      • subnetId: Subnet ID.
      • assignPublicIp: Internet access to the host via a public IP address, true or false.

      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.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/clickhouse/v1/cluster_service.proto \
          -rpc-header "Authorization: Bearer $IAM_TOKEN" \
          -d '{
                  "cluster_id": "<cluster_ID>",
                  "host_specs": [
                      {
                          "type": "CLICKHOUSE",
                          "zone_id": "<availability_zone>",
                          "subnet_id": "<subnet_ID>",
                          "assign_public_ip": <public_access_to_host>
                      }
                  ]
              }' \
          mdb.api.cloud.yandex.net:443 \
          yandex.cloud.mdb.clickhouse.v1.ClusterService.AddHosts
      

      Where host_specs is an array with settings for the new hosts. One array element contains settings for a single host and has the following structure:

      • type: Host type, which is always CLICKHOUSE for ClickHouse® hosts.
      • zone_id: Availability zone.
      • subnet_id: Subnet ID.
      • assign_public_ip: Internet access to the host via a public IP address, true or false.

      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.

5. 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-clickhouse host list --cluster-name <cluster_name>
   

   The FQDN is specified in the command output under NAME. You can also use a special FQDN for a connection.

6. Delete the hosts in the source availability zone:

   Management console

   CLI

   Terraform

   REST API

   gRPC API

   1. Go to the folder page and select Managed Service for ClickHouse.
   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-clickhouse 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. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

      2. Run the command:

         terraform validate
         

         If there are errors in the configuration files, Terraform will point to them.

   3. Type yes and press Enter.

      1. Run the command to view planned changes:

         terraform plan
         

         If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

      2. If you are happy with the planned changes, apply them:

         1. Run the command:

            terraform apply
            

         2. Confirm the update of resources.

         3. Wait for the operation to complete.

   1. 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-clickhouse/v1/clusters/<cluster_ID>/hosts:batchDelete' \
         --data '{
                   "hostNames": [
                     "<host_FQDN>"
                   ]
                 }'
      

      Where hostNames is the array with the host to delete.

      You can provide only one host FQDN in a single request. If you need to delete multiple hosts, make a separate request for each of them.

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

   1. 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/clickhouse/v1/cluster_service.proto \
         -rpc-header "Authorization: Bearer $IAM_TOKEN" \
         -d '{
               "cluster_id": "<cluster_ID>",
               "host_names": [
                 "<host_FQDN>"
               ]
             }' \
         mdb.api.cloud.yandex.net:443 \
         yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteHosts
      

      Where host_names is the array with the host to delete.

      You can provide only one host FQDN in a single request. If you need to delete multiple hosts, make a separate request for each of them.

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

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

Migrating ZooKeeper hostsMigrating ZooKeeper hosts

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

2. Add a host to your cluster:

   Management console

   CLI

   Terraform

   REST API

   gRPC API

   1. Go to the folder page and select Managed Service for ClickHouse.
   2. Click the cluster name and go to the Hosts tab.
   3. Click Add ZooKeeper hosts.
   4. Specify the new subnet and the availability zone to move the hosts to.
   5. Click Save.

   If you do not have the Yandex Cloud command line interface yet, install and initialize it.

   The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

   Run this command:

   yc managed-clickhouse host add \
      --cluster-name <cluster_name> \
      --host type=zookeeper,`
            `zone-id=<availability_zone>,`
            `subnet-id=<new_subnet_ID>,`
            `assign-public-ip=<public_access_to_host:_true_or_false>
   

   You can retrieve the cluster name with a 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_clickhouse_cluster" "<cluster_name>" {
        ...
        host {
          type             = "ZOOKEEPER"
          zone             = "<availability_zone>"
          subnet_id        = "<new_subnet_ID>"
          assign_public_ip = <public_access_to_host:_true_or_false>
        }
      }
      

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

   2. Make sure the settings are correct.

      1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

      2. Run the command:

         terraform validate
         

         If there are errors in the configuration files, Terraform will point to them.

   3. Confirm updating the resources.

      1. Run the command to view planned changes:

         terraform plan
         

         If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

      2. If you are happy with the planned changes, apply them:

         1. Run the command:

            terraform apply
            

         2. Confirm the update of 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-clickhouse/v1/clusters/<cluster_ID>/hosts:batchCreate' \
          --data '{
                    "hostSpecs": [
                      {
                        "type": "ZOOKEEPER",
                        "zoneId": "<availability_zone>",
                        "subnetId": "<subnet_ID>",
                        "assignPublicIp": <public_access_to_host>
                      }
                    ]
                  }'
      

      Where host_specs is an array with settings for the new host. One array element contains settings for a single host and has the following structure:

      • type: ZOOKEEPER host type.
      • zoneId: Availability zone.
      • subnetId: Subnet ID.
      • assignPublicIp: Internet access to the host via a public IP address, true or false.

      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.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/clickhouse/v1/cluster_service.proto \
          -rpc-header "Authorization: Bearer $IAM_TOKEN" \
          -d '{
                  "cluster_id": "<cluster_ID>",
                  "host_specs": [
                      {
                          "type": "ZOOKEEPER",
                          "zone_id": "<availability_zone>",
                          "subnet_id": "<subnet_ID>",
                          "assign_public_ip": <public_access_to_host>
                      }
              }' \
          mdb.api.cloud.yandex.net:443 \
          yandex.cloud.mdb.clickhouse.v1.ClusterService.AddHosts
      

      Where host_specs is an array with settings for the new hosts. One host_specs array element contains settings for a single host and has the following structure:

      • type: ZOOKEEPER host type.
      • zone_id: Availability zone.
      • subnet_id: Subnet ID.
      • assign_public_ip: Internet access to the host via a public IP address, true or false.

      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.

3. Delete the hosts in the source availability zone:

   Management console

   CLI

   Terraform

   REST API

   gRPC API

   1. Go to the folder page and select Managed Service for ClickHouse.
   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-clickhouse 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. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

      2. Run the command:

         terraform validate
         

         If there are errors in the configuration files, Terraform will point to them.

   3. Type yes and press Enter.

      1. Run the command to view planned changes:

         terraform plan
         

         If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

      2. If you are happy with the planned changes, apply them:

         1. Run the command:

            terraform apply
            

         2. Confirm the update of resources.

         3. Wait for the operation to complete.

   1. 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-clickhouse/v1/clusters/<cluster_ID>/hosts:batchDelete' \
         --data '{
                   "hostNames": [
                     "<host_FQDN>"
                   ]
                 }'
      

      Where hostNames is the array with the host to delete.

      You can provide only one host FQDN in a single request. If you need to delete multiple hosts, make a separate request for each of them.

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

   1. 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/clickhouse/v1/cluster_service.proto \
         -rpc-header "Authorization: Bearer $IAM_TOKEN" \
         -d '{
               "cluster_id": "<cluster_ID>",
               "host_names": [
                 "<host_FQDN>"
               ]
             }' \
         mdb.api.cloud.yandex.net:443 \
         yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteHosts
      

      Where host_names is the array with the host to delete.

      You can provide only one host FQDN in a single request. If you need to delete multiple hosts, make a separate request for each of them.

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

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

Specifics of migration in Yandex Data TransferSpecifics 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.

ClickHouse® is a registered trademark of ClickHouse, Inc.