Миграция хостов кластера ClickHouse® в другую зону доступности

Статья создана

Yandex Cloud

Улучшена

mmerihsesh

Обновлена 27 июля 2026 г.

Открыть в Markdown

Перенести хосты ClickHouse®
Перенести хосты ZooKeeper
Особенности миграции в сервисе Yandex Data Transfer

Примечание

В регионе Казахстан доступна только зона доступности kz1-a.

Хосты ClickHouse® и ZooKeeper кластера Managed Service for ClickHouse® располагаются в зонах доступности Yandex Cloud. Хосты ClickHouse® и ZooKeeper можно перенести из одной зоны в другую с помощью этой инструкции, а хосты со встроенным ClickHouse® Keeper — с помощью обращения в службу поддержки.

Примечание

Для кластеров, хосты которых располагаются в зоне доступности kz1-d, недоступно:

использование платформы Intel Broadwell;
хранилище на локальных SSD-дисках при использовании платформы Intel Cascade Lake.

Перенести хосты ClickHouse®

Убедитесь, что в результате миграции будут перенесены только реплицируемые таблицы на движке семейства ReplicatedMergeTree.

Нереплицируемые таблицы будут потеряны во время миграции.
Если в кластере нет сервиса координации, включите его. Без сервиса координации вы не сможете добавить новые хосты в шарды и выполнить миграцию.
Создайте подсеть в зоне доступности, в которую вы переносите хосты.
Добавьте хост в кластер:
Консоль управления

CLI

Terraform

REST API

gRPC API
1. В консоли управления выберите каталог, в котором находится кластер.
2. Перейдите в сервис Managed Service for ClickHouse.
3. Нажмите на имя нужного кластера и перейдите на вкладку Хосты.
4. Нажмите кнопку Создать хост.
5. Укажите параметры хоста:
  - Зону доступности, куда переносятся хосты.
  - Новую подсеть.
  - Выберите опцию Публичный доступ, если хост должен быть доступен извне Yandex Cloud.
6. Нажмите Сохранить.
Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

Выполните команду:
```
yc managed-clickhouse host add \
   --cluster-name <имя_кластера> \
   --host type=clickhouse,`
         `zone-id=<зона_доступности>,`
         `subnet-id=<идентификатор_новой_подсети>,`
         `assign-public-ip=<разрешить_публичный_доступ_к_хосту>
```
Имя кластера можно получить со списком кластеров в каталоге. В параметре zone-id укажите зону, куда вы переносите хосты.
1. В конфигурационном файле Terraform с планом инфраструктуры в блок hosts добавьте новый хост ClickHouse®:
  resource "yandex_mdb_clickhouse_cluster_v2" "<имя_кластера>" { ... hosts = { ... <имя_хоста> = { type = "CLICKHOUSE" zone = "<зона_доступности>" subnet_id = "<идентификатор_новой_подсети>" assign_public_ip = <разрешить_публичный_доступ_к_хосту> shard_name = "<имя_шарда>" } } }
  В параметре zone укажите зону, куда вы переносите хосты.
2. Проверьте корректность настроек.
  1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
  2. Выполните команду:
    
    terraform validate
    
    Если в файлах конфигурации есть ошибки, Terraform на них укажет.
3. Подтвердите изменение ресурсов.
  1. Выполните команду для просмотра планируемых изменений:
    
    terraform plan
    
    Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
  2. Если вас устраивают планируемые изменения, внесите их:
    
    Выполните команду:
    
    terraform apply
    
    Подтвердите изменение ресурсов.
    
    Дождитесь завершения операции.
1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
  export IAM_TOKEN="<IAM-токен>"
2. Воспользуйтесь методом Cluster.AddHosts и выполните запрос, например, с помощью cURL:
  curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/hosts:batchCreate' \ --data '{ "hostSpecs": [ { "type": "CLICKHOUSE", "zoneId": "<зона_доступности>", "subnetId": "<идентификатор_подсети>", "assignPublicIp": <разрешить_публичный_доступ_к_хосту> } ] }'
  Где hostSpecs — массив, содержащий настройки создаваемых хостов. Один элемент массива содержит настройки для одного хоста и имеет следующую структуру:
  - type — тип хоста, всегда CLICKHOUSE для хостов ClickHouse®;
  - zoneId — зона доступности;
  - subnetId — идентификатор подсети;
  - assignPublicIp — доступность хоста из интернета по публичному IP-адресу: true или false.
  Идентификатор кластера можно запросить со списком кластеров в каталоге.
3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
  export IAM_TOKEN="<IAM-токен>"
2. Клонируйте репозиторий cloudapi:
  cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
  Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.
3. Воспользуйтесь вызовом ClusterService.AddHosts и выполните запрос, например, с помощью 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": "<идентификатор_кластера>", "host_specs": [ { "type": "CLICKHOUSE", "zone_id": "<зона_доступности>", "subnet_id": "<идентификатор_подсети>", "assign_public_ip": <разрешить_публичный_доступ_к_хосту> } ] }' \ mdb.api.yandexcloud.kz:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.AddHosts
  Где host_specs — массив, содержащий настройки создаваемых хостов. Один элемент массива содержит настройки для одного хоста и имеет следующую структуру:
  - type — тип хоста, всегда CLICKHOUSE для хостов ClickHouse®;
  - zone_id — зона доступности;
  - subnet_id — идентификатор подсети;
  - assign_public_ip — доступность хоста из интернета по публичному IP-адресу: true или false.
  Идентификатор кластера можно запросить со списком кластеров в каталоге.
4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Чтобы успешно выполнять подключение к базе данных после миграции, укажите FQDN нового хоста в вашем бэкенде или клиенте (например, в коде или графической IDE). Удалите FQDN прежнего хоста в первоначальной зоне.

Чтобы узнать FQDN, получите список хостов в кластере:
```
yc managed-clickhouse host list --cluster-name <имя_кластера>
```
FQDN указан в выводе команды, в столбце NAME. Также вы можете использовать особый FQDN для подключения.
Удалите хосты в первоначальной зоне доступности:
Консоль управления

CLI

Terraform

REST API

gRPC API
1. В консоли управления выберите каталог, в котором находится кластер.
2. Перейдите в сервис Managed Service for ClickHouse.
3. Нажмите на имя нужного кластера и выберите вкладку Хосты.
4. Нажмите на значок в строке нужного хоста, выберите пункт Удалить и подтвердите удаление.
Выполните команду для каждого хоста:
```
yc managed-clickhouse host delete <FQDN_хоста> --cluster-name <имя_кластера>
```
1. В конфигурационном файле Terraform с планом инфраструктуры удалите из блока hosts хост ClickHouse® с первоначальной зоной доступности.
2. Проверьте корректность настроек.
  1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
  2. Выполните команду:
    
    terraform validate
    
    Если в файлах конфигурации есть ошибки, Terraform на них укажет.
3. Введите слово yes и нажмите Enter.
  1. Выполните команду для просмотра планируемых изменений:
    
    terraform plan
    
    Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
  2. Если вас устраивают планируемые изменения, внесите их:
    
    Выполните команду:
    
    terraform apply
    
    Подтвердите изменение ресурсов.
    
    Дождитесь завершения операции.
1. Воспользуйтесь методом Cluster.DeleteHosts и выполните запрос, например, с помощью cURL:
  curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/hosts:batchDelete' \ --data '{ "hostNames": [ "<FQDN_хоста>" ] }'
  Где hostNames — массив с удаляемым хостом.
  
  В одном запросе можно передать только один FQDN хоста. Если нужно удалить несколько хостов, выполните запрос для каждого хоста.
2. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
1. Воспользуйтесь вызовом ClusterService.DeleteHosts и выполните запрос, например, с помощью 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": "<идентификатор_кластера>", "host_names": [ "<FQDN_хоста>" ] }' \ mdb.api.yandexcloud.kz:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteHosts
  Где host_names — массив с удаляемым хостом.
  
  В одном запросе можно передать только один FQDN хоста. Если нужно удалить несколько хостов, выполните запрос для каждого хоста.
2. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Дождитесь, когда кластер перейдет в состояние Alive. В консоли управления перейдите в сервис Managed Service for ClickHouse. Состояние кластера отображается в столбце Доступность.

Перенести хосты ZooKeeper

Создайте подсеть в зоне доступности, в которую вы переносите хосты.
Добавьте хост в кластер:
Консоль управления

CLI

Terraform

REST API

gRPC API
1. В консоли управления выберите каталог, в котором находится кластер.
2. Перейдите в сервис Managed Service for ClickHouse.
3. Нажмите на имя нужного кластера и перейдите на вкладку Хосты.
4. Нажмите кнопку Создать хост ZooKeeper.
5. Укажите новую подсеть и зону доступности, куда переносятся хосты.
6. Нажмите Сохранить.
Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

Выполните команду:
```
yc managed-clickhouse host add \
   --cluster-name <имя_кластера> \
   --host type=zookeeper,`
         `zone-id=<зона_доступности>,`
         `subnet-id=<идентификатор_новой_подсети>,`
         `assign-public-ip=<разрешить_публичный_доступ_к_хосту>
```
Имя кластера можно получить со списком кластеров в каталоге. В параметре zone-id укажите зону, куда вы переносите хосты.
1. В конфигурационном файле Terraform с планом инфраструктуры в блок hosts добавьте новый хост ZooKeeper:
  resource "yandex_mdb_clickhouse_cluster_v2" "<имя_кластера>" { ... hosts = { ... <имя_хоста> = { type = "ZOOKEEPER" zone = "<зона_доступности>" subnet_id = "<идентификатор_новой_подсети>" } } }
  В параметре zone укажите зону, куда вы переносите хосты.
2. Проверьте корректность настроек.
  1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
  2. Выполните команду:
    
    terraform validate
    
    Если в файлах конфигурации есть ошибки, Terraform на них укажет.
3. Подтвердите изменение ресурсов.
  1. Выполните команду для просмотра планируемых изменений:
    
    terraform plan
    
    Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
  2. Если вас устраивают планируемые изменения, внесите их:
    
    Выполните команду:
    
    terraform apply
    
    Подтвердите изменение ресурсов.
    
    Дождитесь завершения операции.
1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
  export IAM_TOKEN="<IAM-токен>"
2. Воспользуйтесь методом Cluster.AddHosts и выполните запрос, например, с помощью cURL:
  curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/hosts:batchCreate' \ --data '{ "hostSpecs": [ { "type": "ZOOKEEPER", "zoneId": "<зона_доступности>", "subnetId": "<идентификатор_подсети>", "assignPublicIp": <разрешить_публичный_доступ_к_хосту> } ] }'
  Где hostSpecs — массив, содержащий настройки создаваемого хоста. Один элемент массива содержит настройки для одного хоста и имеет следующую структуру:
  - type — тип хоста ZOOKEEPER;
  - zoneId — зона доступности;
  - subnetId — идентификатор подсети;
  - assignPublicIp — доступность хоста из интернета по публичному IP-адресу: true или false.
  Идентификатор кластера можно запросить со списком кластеров в каталоге.
3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
  export IAM_TOKEN="<IAM-токен>"
2. Клонируйте репозиторий cloudapi:
  cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
  Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.
3. Воспользуйтесь вызовом ClusterService.AddHosts и выполните запрос, например, с помощью 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": "<идентификатор_кластера>", "host_specs": [ { "type": "ZOOKEEPER", "zone_id": "<зона_доступности>", "subnet_id": "<идентификатор_подсети>", "assign_public_ip": <разрешить_публичный_доступ_к_хосту> } }' \ mdb.api.yandexcloud.kz:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.AddHosts
  Где host_specs — массив, содержащий настройки создаваемых хостов. Один элемент массива host_specs содержит настройки для одного хоста и имеет следующую структуру:
  - type — тип хоста ZOOKEEPER;
  - zone_id — зона доступности;
  - subnet_id — идентификатор подсети;
  - assign_public_ip — доступность хоста из интернета по публичному IP-адресу: true или false.
  Идентификатор кластера можно запросить со списком кластеров в каталоге.
4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Удалите хосты в первоначальной зоне доступности:
Консоль управления

CLI

Terraform

REST API

gRPC API
1. В консоли управления выберите каталог, в котором находится кластер.
2. Перейдите в сервис Managed Service for ClickHouse.
3. Нажмите на имя нужного кластера и выберите вкладку Хосты.
4. Нажмите на значок в строке нужного хоста, выберите пункт Удалить и подтвердите удаление.
Выполните команду для каждого хоста:
```
yc managed-clickhouse host delete <FQDN_хоста> --cluster-name <имя_кластера>
```
1. В конфигурационном файле Terraform с планом инфраструктуры удалите из блока hosts хост ZooKeeper с первоначальной зоной доступности.
2. Проверьте корректность настроек.
  1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
  2. Выполните команду:
    
    terraform validate
    
    Если в файлах конфигурации есть ошибки, Terraform на них укажет.
3. Введите слово yes и нажмите Enter.
  1. Выполните команду для просмотра планируемых изменений:
    
    terraform plan
    
    Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
  2. Если вас устраивают планируемые изменения, внесите их:
    
    Выполните команду:
    
    terraform apply
    
    Подтвердите изменение ресурсов.
    
    Дождитесь завершения операции.
1. Воспользуйтесь методом Cluster.DeleteHosts и выполните запрос, например, с помощью cURL:
  curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/hosts:batchDelete' \ --data '{ "hostNames": [ "<FQDN_хоста>" ] }'
  Где hostNames — массив с удаляемым хостом.
  
  В одном запросе можно передать только один FQDN хоста. Если нужно удалить несколько хостов, выполните запрос для каждого хоста.
2. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
1. Воспользуйтесь вызовом ClusterService.DeleteHosts и выполните запрос, например, с помощью 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": "<идентификатор_кластера>", "host_names": [ "<FQDN_хоста>" ] }' \ mdb.api.yandexcloud.kz:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteHosts
  Где host_names — массив с удаляемым хостом.
  
  В одном запросе можно передать только один FQDN хоста. Если нужно удалить несколько хостов, выполните запрос для каждого хоста.
2. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Дождитесь, когда кластер перейдет в состояние Alive. В консоли управления перейдите в сервис Managed Service for ClickHouse. Состояние кластера отображается в столбце Доступность.

Особенности миграции в сервисе Yandex Data Transfer

Если кластер выступает в роли эндпоинта при передаче данных с помощью сервиса Data Transfer и используется тип трансфера Репликация или Копирование и репликация, перезапустите трансфер после миграции кластера. Так трансфер получит сведения о новой топологии кластера.

Трансферы типа Копирование перезапускать не нужно, так как во время их активации информация о новой топологии передается автоматически.

Чтобы перезапустить трансфер, выберите один из двух способов:

Деактивируйте трансфер и дождитесь его перехода в статус Остановлен. Затем активируйте трансфер и дождитесь его перехода в статус Реплицируется.
Измените какую-либо настройку трансфера или эндпоинта.

Подробнее читайте в разделе Миграция эндпоинтов и трансфера Data Transfer в другую зону доступности.

ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc.

Миграция хостов кластера ClickHouse® в другую зону доступности

Перенести хосты ClickHouse®Перенести хосты ClickHouse®

Перенести хосты ZooKeeperПеренести хосты ZooKeeper

Особенности миграции в сервисе Yandex Data TransferОсобенности миграции в сервисе Yandex Data Transfer

Была ли статья полезна?

Перенести хосты ClickHouse®

Перенести хосты ZooKeeper

Особенности миграции в сервисе Yandex Data Transfer