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

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

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

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

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

Где:

• <имя_нового_шарда> — должно быть уникальным в кластере.

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

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

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

• --host — параметры хоста:

  • zone-id — зона доступности.
  • subnet-name — имя подсети.

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

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

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

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

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

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

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

      terraform validate
      

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

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

   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.AddShard и выполните запрос, например, с помощью cURL:

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

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

      Где:

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

      • 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.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards' \
        --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.AddShard и выполните запрос, например, с помощью gRPCurl:

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

      {
        "cluster_id": "<идентификатор_кластера>",
        "shard_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": <копирование_схемы_данных>
      }
      

      Где:

      • shard_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.cloud.yandex.net:443 \
        yandex.cloud.mdb.clickhouse.v1.ClusterService.AddShard \
        < 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.cloud.yandex.net/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.cloud.yandex.net: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=<вес_шарда>
   

   Где:

   • <имя_шарда> — можно запросить со списком шардов в кластере.

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

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

   • --weight — вес шарда. Минимальное значение — 0.

   После успешного завершения операции CLI выведет информацию об измененном шарде.

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.cloud.yandex.net/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.cloud.yandex.net: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® блок 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.DeleteShard и выполните запрос, например, с помощью cURL:

   curl \
     --request DELETE \
     --header "Authorization: Bearer $IAM_TOKEN" \
     --url 'https://mdb.api.cloud.yandex.net/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.DeleteShard и выполните запрос, например, с помощью 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_name": "<имя_шарда>"
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteShard
   

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

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