Управление шардами в кластере ClickHouse®

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

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

Чтобы создать один или несколько шардов:

1. Посмотрите описание команды CLI для создания шардов:

   yc managed-clickhouse shards add --help
   

2. Выполните команду создания шардов.

   Укажите в команде один или несколько параметров --shard: по одному параметру на каждый шард, который нужно создать.

   Пример команды для создания одного шарда (приведены не все доступные параметры):

   yc managed-clickhouse shards add \
     --cluster-name=<имя_кластера> \
     --shard name=<имя_нового_шарда>,`
            `weight=<вес_шарда> \
     --host zone-id=<зона_доступности>,`
           `subnet-name=<имя_подсети>,`
           `shard-name=<имя_шарда> \
     --copy-schema
   

   Где:

   • --cluster-name — имя кластера.

     Имя кластера можно запросить со списком кластеров в каталоге.

   • --shard — параметры шарда:

     • name — имя шарда. Должно быть уникальным в кластере.

       Может содержать латинские буквы, цифры, дефис и подчеркивание. Максимальная длина — 63 символа.

     • weight — вес шарда.

   • --host — параметры хоста, который будет добавлен в шард:

     • zone-id — зона доступности.

     • subnet-name — имя подсети.

     • shard-name — имя шарда, в который будет добавлен хост.

   • --copy-schema — опциональный параметр, который инициирует копирование схемы данных со случайной реплики одного из шардов на хосты нового шарда.

     Важно

     Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.

1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

   О том, как создать такой файл, см. в разделе Создание кластера.

2. Добавьте к описанию кластера Managed Service for ClickHouse® один или несколько блоков shard и блоков host типа CLICKHOUSE с заполненным полем shard_name:

   resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
     ...
     shard {
       name   = "<имя_шарда>"
       weight = <вес_шарда>
     }
   
     host {
       type       = "CLICKHOUSE"
       zone       = "<зона_доступности>"
       subnet_id  = yandex_vpc_subnet.<подсеть_в_зоне_доступности>.id
       shard_name = "<имя_шарда>"
     }
   }
   

3. (Опционально) Чтобы скопировать схему со случайной реплики одного из шардов на хосты новых шардов, добавьте к описанию кластера поле copy_schema_on_new_hosts со значением true.

   Важно

   Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.

4. Проверьте корректность настроек.

   1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

   2. Выполните команду:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

5. Подтвердите изменение ресурсов.

   1. Выполните команду для просмотра планируемых изменений:

      terraform plan
      

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

   2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

         terraform apply
         

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.AddShards и выполните запрос, например с помощью cURL:

   1. Создайте файл body.json и добавьте в него следующее содержимое:

      {
        "shardSpecs": [
          {
            "name": "<имя_шарда>",
            "configSpec": {
              "clickhouse": {
                "resources": {
                  "resourcePresetId": "<класс_хостов>",
                  "diskSize": "<размер_хранилища_в_байтах>",
                  "diskTypeId": "<тип_диска>"
                },
                "weight": "<вес_шарда>"
              }
            }
          }
        ],
        "hostSpecs": [
          {
            "zoneId": "<зона_доступности>",
            "type": "CLICKHOUSE",
            "subnetId": "<идентификатор_подсети>",
            "assignPublicIp": <публичный_доступ_к_хосту>,
            "shardName": "<имя_шарда>"
          }
        ],
        "copySchema": <копирование_схемы_данных>
      }
      

      Где:

      • shardSpecs — настройки шардов, которые будут добавлены в кластер. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному шарду и имеет следующую структуру:

        • name — имя шарда.

        • configSpec.clickhouse.resources — ресурсы хостов, которые добавляются в создаваемый шард:

          • resourcePresetId — идентификатор класса хостов. Список доступных классов хостов с их идентификаторами можно запросить с помощью метода ResourcePreset.List.
          • diskSize — размер диска в байтах.
          • diskTypeId — тип диска.

      • configSpec.clickhouse.weight — вес шарда.

        По умолчанию каждому шарду назначается вес 1. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

        При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес 1, а у другого — 3, то у первого шарда приоритет 1/4, а у второго — 3/4. Чем выше приоритет, тем больше данных окажется на шарде.

        Подробнее см. в документации ClickHouse®.

      • hostSpecs — настройки хостов, которые будут добавлены в шард. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному хосту и имеет следующую структуру:

        • zoneId — зона доступности.
        • type — тип хоста. В шарды добавляются только хосты CLICKHOUSE.
        • subnetId — идентификатор подсети.
        • assignPublicIp — доступность хоста из интернета по публичному IP-адресу: true или false.
        • shardName — имя шарда.

      • copySchema — копирование схемы данных со случайной реплики одного из шардов на хосты нового шарда. Возможные значения: true или false.

        Важно

        Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.

   2. Выполните запрос:

      curl \
        --request POST \
        --header "Authorization: Bearer $IAM_TOKEN" \
        --header "Content-Type: application/json" \
        --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards:batchCreate' \
        --data '@body.json'
      

      Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом ClusterService.AddShards и выполните запрос, например с помощью gRPCurl:

   1. Создайте файл body.json и добавьте в него следующее содержимое:

      {
        "cluster_id": "<идентификатор_кластера>",
        "shard_specs": [
          {
            "name": "<имя_шарда>",
            "config_spec": {
              "clickhouse": {
                "resources": {
                  "resource_preset_id": "<класс_хостов>",
                  "disk_size": "<размер_хранилища_в_байтах>",
                  "disk_type_id": "<тип_диска>"
                },
                "weight": "<вес_шарда>"
              }
            }
          }
        ],
        "host_specs": [
          {
            "zone_id": "<зона_доступности>",
            "type": "CLICKHOUSE",
            "subnet_id": "<идентификатор_подсети>",
            "assign_public_ip": <публичный_доступ_к_хосту>,
            "shard_name": "<имя_шарда>"
          }
        ],
        "copy_schema": <копирование_схемы_данных>
      }
      

      Где:

      • cluster_id — идентификатор кластера. Его можно запросить со списком кластеров в каталоге.

      • shard_specs — настройки шардов, которые будут добавлены в кластер. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному шарду и имеет следующую структуру:

        • name — имя шарда.

        • config_spec.clickhouse.resources — ресурсы хостов, которые добавляются в создаваемый шард:

          • resource_preset_id — идентификатор класса хостов. Список доступных классов хостов с их идентификаторами можно запросить с помощью метода ResourcePresetService.List.
          • disk_size — размер диска в байтах.
          • disk_type_id — тип диска.

        • config_spec.clickhouse.weight — вес шарда.

          По умолчанию каждому шарду назначается вес 1. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

          При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес 1, а у другого — 3, то у первого шарда приоритет 1/4, а у второго — 3/4. Чем выше приоритет, тем больше данных окажется на шарде.

          Подробнее см. в документации ClickHouse®.

      • host_specs — настройки хостов, которые будут добавлены в шард. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному хосту и имеет следующую структуру:

        • zone_id — зона доступности.
        • type — тип хоста. В шарды добавляются только хосты CLICKHOUSE.
        • subnet_id — идентификатор подсети.
        • assign_public_ip — доступность хоста из интернета по публичному IP-адресу: true или false.
        • shard_name — имя шарда.

      • copy_schema — копирование схемы данных со случайной реплики одного из шардов на хосты нового шарда. Возможные значения: true или false.

        Важно

        Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.

   2. Выполните запрос:

      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 @ \
        mdb.api.yandexcloud.kz:443 \
        yandex.cloud.mdb.clickhouse.v1.ClusterService.AddShards \
        < body.json
      

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

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

Чтобы получить список шардов в кластере, выполните команду:

yc managed-clickhouse shards list --cluster-name=<имя_кластера>

Имя кластера можно запросить со списком кластеров в каталоге.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.ListShards и выполните запрос, например с помощью cURL:

   curl \
     --request GET \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards'
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом ClusterService.ListShards и выполните запрос, например с помощью 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": "<идентификатор_кластера>"
         }' \
     mdb.api.yandexcloud.kz:443 \
     yandex.cloud.mdb.clickhouse.v1.ClusterService.ListShards
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

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

Чтобы изменить шард в кластере:

1. Посмотрите описание команды CLI для изменения шарда:

   yc managed-clickhouse shards update --help
   

2. Передайте в команде параметры, которые вы хотите изменить:

   yc managed-clickhouse shards update <имя_шарда> \
     --cluster-name <имя_кластера> \
     --weight <вес_шарда> \
     --clickhouse-resource-preset <класс_хостов> \
     --clickhouse-disk-size <размер_хранилища> \
     --clickhouse-disk-type <тип_диска>
   

   Где:

   • --cluster-name — имя кластера. Его можно запросить со списком кластеров в каталоге.
   • --weight — вес шарда. Минимальное значение — 0.
   • --clickhouse-resource-preset — класс хостов.
   • --clickhouse-disk-size — размер хранилища в гигабайтах.
   • --clickhouse-disk-type — тип диска.

   Имя шарда можно запросить со списком шардов в кластере.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.UpdateShard и выполните запрос, например с помощью cURL:

   Важно

   Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).

   curl \
       --request PATCH \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --header "Content-Type: application/json" \
       --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards/<имя_шарда>' \
       --data '{
                 "updateMask": "configSpec.clickhouse.config.<настройка_ClickHouse®>,configSpec.clickhouse.resources,configSpec.clickhouse.weight",
                 "configSpec": {
                   "clickhouse": {
                     "config": {
                       <настройки_ClickHouse®>
                     },
                     "resources": {
                       "resourcePresetId": "<класс_хостов>",
                       "diskSize": "<размер_хранилища_в_байтах>",
                       "diskTypeId": "<тип_диска>"
                     },
                     "weight": "<вес_шарда>"
                   }
                 }
               }'
   

   Где:

   • updateMask — перечень изменяемых параметров в одну строку через запятую.

   • configSpec.clickhouse — изменяемые параметры шарда:

     • config — настройки ClickHouse®. Список доступных настроек приведен в описании метода.

     • resources — ресурсы хостов, которые добавляются в создаваемый шард:

       • resourcePresetId — идентификатор класса хостов. Список доступных классов хостов с их идентификаторами можно запросить с помощью метода ResourcePreset.List.
       • diskSize — размер диска в байтах.
       • diskTypeId — тип диска.

     • weight — вес шарда.

       По умолчанию каждому шарду назначается вес 1. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

       При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес 1, а у другого — 3, то у первого шарда приоритет 1/4, а у второго — 3/4. Чем выше приоритет, тем больше данных окажется на шарде.

       Подробнее см. в документации ClickHouse®.

   Идентификатор кластера можно запросить со списком кластеров в каталоге, а имя шарда — со списком шардов в кластере.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом ClusterService.UpdateShard и выполните запрос, например с помощью gRPCurl:

   Важно

   Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре update_mask (в виде массива строк paths[]).

   Формат перечисления настроек

   "update_mask": {
       "paths": [
           "<настройка_1>",
           "<настройка_2>",
           ...
           "<настройка_N>"
       ]
   }
   

   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": "<идентификатор_кластера>",
           "shard_name": "<имя_шарда>",
           "update_mask": {
             "paths": [
               "config_spec.clickhouse.config.<настройка_ClickHouse®>",
               "config_spec.clickhouse.resources",
               "config_spec.clickhouse.weight"
             ]
           },
           "config_spec": {
             "clickhouse": {
               "config": {
                 <настройки_ClickHouse®>
               },
               "resources": {
                 "resource_preset_id": "<класс_хостов>",
                 "disk_size": "<размер_хранилища_в_байтах>",
                 "disk_type_id": "<тип_диска>"
               },
               "weight": "<вес_шарда>"
             }
           }
         }' \
     mdb.api.yandexcloud.kz:443 \
     yandex.cloud.mdb.clickhouse.v1.ClusterService.UpdateShard
   

   Где:

   • update_mask — перечень изменяемых параметров в виде массива строк paths[].

   • config_spec.clickhouse — изменяемые параметры шарда:

     • config — настройки ClickHouse®. Список доступных настроек приведен в описании метода.

     • resources — ресурсы хостов, которые добавляются в создаваемый шард:

       • resource_preset_id — идентификатор класса хостов. Список доступных классов хостов с их идентификаторами можно запросить с помощью метода ResourcePreset.List.
       • disk_size — размер диска в байтах.
       • disk_type_id — тип диска.

     • weight — вес шарда.

       По умолчанию каждому шарду назначается вес 1. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

       При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес 1, а у другого — 3, то у первого шарда приоритет 1/4, а у второго — 3/4. Чем выше приоритет, тем больше данных окажется на шарде.

       Подробнее см. в документации ClickHouse®.

   Идентификатор кластера можно запросить со списком кластеров в каталоге, а имя шарда — со списком шардов в кластере.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

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

Чтобы удалить один или несколько шардов из кластера, выполните команду, передав нужные имена шардов. Используйте пробел в качестве разделителя.

Команда для удаления одного шарда имеет вид:

yc managed-clickhouse shards delete \
  --cluster-name=<имя_кластера> \
  <имя_шарда>

Имена шардов можно запросить со списком шардов в кластере, имя кластера — со списком кластеров в каталоге.

1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

   О том, как создать такой файл, см. в разделе Создание кластера.

2. Удалите из описания кластера Managed Service for ClickHouse® нужные блоки shard и host.

3. Проверьте корректность настроек.

   1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

   2. Выполните команду:

      terraform validate
      

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

4. Введите слово yes и нажмите Enter.

   1. Выполните команду для просмотра планируемых изменений:

      terraform plan
      

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

   2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

         terraform apply
         

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.DeleteShards и выполните запрос, например с помощью cURL:

   curl \
     --request DELETE \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards:batchDelete' \
     --data '{
               "shardNames": [
                 <перечень_имен_шардов>
               ]
             }'
   

   Где shardNames — массив строк. Каждая строка — имя шарда, который нужно удалить. Имена шардов можно запросить со списком шардов в кластере.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом ClusterService.DeleteShards и выполните запрос, например с помощью 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": "<идентификатор_кластера>",
           "shard_names": [
             <перечень_имен_шардов>
           ]
         }' \
     mdb.api.yandexcloud.kz:443 \
     yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteShards
   

   Где shard_names — массив строк. Каждая строка — имя шарда, который нужно удалить. Имена шардов можно запросить со списком шардов в кластере.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.