Создание кластера ClickHouse®

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

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

Чтобы создать кластер Managed Service for ClickHouse®:

1. Проверьте, есть ли в каталоге подсети для хостов кластера:

   yc vpc subnet list
   

   Если ни одной подсети в каталоге нет, создайте нужные подсети в сервисе VPC.

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

   yc managed-clickhouse cluster create --help
   

3. Укажите параметры кластера в команде создания (в примере приведены не все доступные параметры):

   yc managed-clickhouse cluster create \
     --name <имя_кластера> \
     --environment <окружение> \
     --network-name <имя_сети> \
     --host type=<тип_хоста>,`
          `zone-id=<зона_доступности>,`
          `subnet-id=<идентификатор_подсети>,`
          `assign-public-ip=<публичный_доступ_к_хосту> \
     --clickhouse-resource-preset <класс_хоста> \
     --clickhouse-disk-type <network-hdd|network-ssd|network-ssd-nonreplicated|local-ssd> \
     --clickhouse-disk-size <размер_хранилища_ГБ> \
     --user name=<имя_пользователя>,password=<пароль_пользователя> \
     --database name=<имя_базы_данных> \
     --security-group-ids <список_идентификаторов_групп_безопасности> \
     --websql-access=<true_или_false> \
     --deletion-protection
   

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

   Где:

   • --environment — окружение кластера: prestable или production.

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

     • type — тип хоста: clickhouse или zookeeper.
     • zone-id — зона доступности.
     • assign-public-ip — доступность хоста из интернета по публичному IP-адресу: true или false.

   • --clickhouse-disk-type — тип диска.

     Важно

     Тип диска нельзя изменить после создания кластера.

   • --user — содержит имя (name) и пароль (password) пользователя ClickHouse®.

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

     Длина пароля от 8 до 128 символов.

   • --websql-access — разрешает выполнять SQL-запросы к базам данных кластера из консоли управления Yandex Cloud. Значение по умолчанию — false.

   • --deletion-protection — защита кластера от непреднамеренного удаления: true или false.

     Включенная защита кластера от удаления не помешает удалить пользователя или базу данных, а также подключиться вручную и удалить содержимое базы данных.

   Пользователями и базами данных в кластере можно управлять через SQL.

   Важно

   Включенные настройки управления пользователями и базами данных через SQL невозможно выключить. При необходимости их можно включить позже при изменении настроек кластера.

   1. Чтобы включить режим управления пользователями через SQL:

      • задайте значение true для параметра --enable-sql-user-management;
      • задайте пароль для пользователя admin в параметре --admin-password.

      yc managed-clickhouse cluster create \
        ...
        --enable-sql-user-management true \
        --admin-password "<пароль_пользователя_admin>"
      

   2. Чтобы включить режим управления базами данных через SQL:

      • задайте значение true для параметров --enable-sql-user-management и --enable-sql-database-management;
      • задайте пароль для пользователя admin в параметре --admin-password.

      yc managed-clickhouse cluster create \
        ...
        --enable-sql-user-management true \
        --enable-sql-database-management true \
        --admin-password "<пароль_пользователя_admin>"
      

   3. Чтобы разрешить доступ к кластеру из сервиса Yandex Cloud Functions, передайте параметр --serverless-access. Подробнее о настройке доступа см. в документации Cloud Functions.

   4. Чтобы разрешить доступ к кластеру из сервиса Yandex Query, передайте параметр --yandexquery-access=true. Функциональность находится на стадии Preview.

   5. Чтобы включить ClickHouse® Keeper в кластере, задайте значение true для параметра --embedded-keeper.

      yc managed-clickhouse cluster create \
        ...
        --embedded-keeper true
      

      Внимание

      ClickHouse® Keeper невозможно выключить после создания кластера. Использование хостов ZooKeeper также станет недоступно.

   6. Чтобы задать настройки гибридного хранилища:

      • Включите гибридное хранилище, задав значение true для параметра --cloud-storage.

        Примечание

        Включенное однажды гибридное хранилище нельзя отключить.

      • Передайте настройки гибридного хранилища в соответствующих параметрах:

        • --cloud-storage-data-cache — разрешает временное хранение файлов в кластерном хранилище. По умолчанию — true (разрешено).
        • --cloud-storage-data-cache-max-size — определяет максимальный объем памяти (в байтах), выделяемый в кластерном хранилище для временного хранения файлов. По умолчанию — 1073741824 (1 ГБ).
        • --cloud-storage-move-factor — устанавливает минимальную долю свободного места в кластерном хранилище. Если доля свободного места меньше этого значения, данные переносятся в Yandex Object Storage. Минимальное значение — 0, максимальное — 1, по умолчанию — 0.01.
        • --cloud-storage-prefer-not-to-merge — отключает слияние кусков данных в кластерном и объектном хранилищах. Чтобы отключить слияние, укажите значение true или передайте параметр без значения. Чтобы оставить слияние включенным, укажите значение false или не передавайте параметр в команде CLI при создании кластера.

      yc managed-clickhouse cluster create \
         ...
         --cloud-storage=true \
         --cloud-storage-data-cache=<хранение_файлов> \
         --cloud-storage-data-cache-max-size=<объем_памяти_в_байтах> \
         --cloud-storage-move-factor=<доля_свободного_места> \
         --cloud-storage-prefer-not-to-merge=<слияние_кусков_данных>
        ...
      

      Где:

      • --cloud-storage-data-cache — хранение файлов в кластерном хранилище: true или false.
      • --cloud-storage-prefer-not-to-merge — отключает слияние кусков данных в кластерном и объектном хранилищах: true или false.

Terraform позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.

Terraform распространяется под лицензией Business Source License, а провайдер Yandex Cloud для Terraform — под лицензией MPL-2.0.

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

Чтобы создать кластер Managed Service for ClickHouse®:

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

2. Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

3. Создайте конфигурационный файл с описанием облачной сети и подсетей.

   • Сеть — описание облачной сети, в которой будет расположен кластер. Если подходящая сеть у вас уже есть, описывать ее повторно не нужно.
   • Подсети — описание подсетей, к которым будут подключены хосты кластера. Если подходящие подсети у вас уже есть, описывать их повторно не нужно.

   Пример структуры конфигурационного файла, в котором описывается облачная сеть с одной подсетью:

   resource "yandex_vpc_network" "<имя_сети_в_Terraform>" { name = "<имя_сети>" }
   
   resource "yandex_vpc_subnet" "<имя_подсети_в_Terraform>" {
     name           = "<имя_подсети>"
     zone           = "<зона_доступности>"
     network_id     = yandex_vpc_network.<имя_сети_в_Terraform>.id
     v4_cidr_blocks = ["<подсеть>"]
   }
   

4. Создайте конфигурационный файл с описанием ресурсов кластера, которые необходимо создать:

   • Кластер базы данных — описание кластера и его хостов. Здесь же при необходимости:

     • Задайте настройки СУБД на уровне сервера. Их также можно указать позднее.

     • Включите защиту кластера от непреднамеренного удаления.

       Включенная защита кластера от удаления не помешает удалить пользователя или базу данных, а также подключиться вручную и удалить содержимое базы данных.

   • База данных — описание БД кластера.

   • Пользователь — описание пользователя кластера. Здесь же при необходимости задайте настройки СУБД на уровне пользователя. Их также можно указать позднее.

     Через интерфейсы Yandex Cloud можно управлять ограниченным набором настроек. С помощью SQL-запросов можно установить настройки ClickHouse® на уровне запроса.

   Пример структуры конфигурационного файла, в котором описывается кластер из одного хоста:

   resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
     name                = "<имя_кластера>"
     environment         = "<окружение>"
     network_id          = yandex_vpc_network.<имя_сети_в_Terraform>.id
     security_group_ids  = ["<список_идентификаторов_групп_безопасности>"]
     deletion_protection = <защита_кластера_от_удаления>
   
     clickhouse {
       resources {
         resource_preset_id = "<класс_хоста>"
         disk_type_id       = "<тип_диска>"
         disk_size          = <размер_хранилища_ГБ>
       }
     }
   
     host {
       type             = "CLICKHOUSE"
       zone             = "<зона_доступности>"
       subnet_id        = yandex_vpc_subnet.<имя_подсети_в_Terraform>.id
       assign_public_ip = <публичный_доступ_к_хосту>
     }
   
     lifecycle {
       ignore_changes = [database, user]
     }
   }
   
   resource "yandex_mdb_clickhouse_database" "<имя_БД>" {
     cluster_id = yandex_mdb_clickhouse_cluster.<имя_кластера>.id
     name       = "<имя_БД>"
   }
   
   resource "yandex_mdb_clickhouse_user" "<имя_пользователя>" {
     cluster_id = yandex_mdb_clickhouse_cluster.<имя_кластера>.id
     name       = "<имя_пользователя>"
     password   = "<пароль_пользователя>"
     permission {
       database_name = yandex_mdb_clickhouse_database.<имя_БД>.name
     }
     settings {
       <имя_параметра_1> = <значение_1>
       <имя_параметра_2> = <значение_2>
       ...
     }
   }
   

   Где:

   • deletion_protection — защита кластера от непреднамеренного удаления: true или false.
   • assign_public_ip — публичный доступ к хосту: true или false.
   • lifecycle.ignore_changes — устраняет конфликты ресурсов при операциях с пользователями и базами данных, созданными с помощью отдельных ресурсов.

   Для пользователя указываются:

   • nameи password— имя и пароль пользователя ClickHouse®.

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

     Длина пароля от 8 до 128 символов.

   • permission — список БД, к которым пользователь должен иметь доступ.

   1. Чтобы настроить время технического обслуживания (в т. ч. для выключенных кластеров), добавьте к описанию кластера блок maintenance_window:

      resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
        ...
        maintenance_window {
          type = <тип_технического_обслуживания>
          day  = <день_недели>
          hour = <час_дня>
        }
        ...
      }
      

      Где:

      • type — тип технического обслуживания. Принимает значения:
        • ANYTIME — в любое время.
        • WEEKLY — по расписанию.
      • day — день недели для типа WEEKLY в формате DDD. Например, MON.
      • hour — час дня по UTC для типа WEEKLY в формате HH. Например, 21.

   2. Чтобы разрешить доступ из других сервисов и выполнение SQL-запросов из консоли управления, добавьте блок access с нужными вам настройками:

      resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
        ...
        access {
          data_lens    = <доступ_из_DataLens>
          metrika      = <доступ_из_Метрики_и_AppMetrika>
          serverless   = <доступ_из_Cloud_Functions>
          yandex_query = <доступ_из_Yandex_Query>
          web_sql      = <выполнение_SQL-запросов_из_консоли_управления>
        }
        ...
      }
      

      Где:

      • data_lens — доступ из DataLens: true или false.

      • metrika — доступ из Метрики и AppMetrika: true или false.

      • serverless — доступ из Cloud Functions: true или false.

      • yandex_query — доступ из Yandex Query: true или false.

      • web_sql — выполнение SQL-запросов из консоли управления: true или false.

   3. Пользователями и базами данных в кластере можно управлять через SQL.

      Важно

      Включенные настройки управления пользователями и базами данных через SQL невозможно выключить. При необходимости их можно включить позже при изменении настроек кластера.

      • Чтобы включить режим управления пользователями через SQL, добавьте к описанию кластера поле sql_user_management со значением true и поле admin_password с паролем пользователя admin:

        resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
          name                = "<имя_кластера>"
          ...
          admin_password      = "<пароль_пользователя_admin>"
          sql_user_management = true
          ...
        }
        

      • Чтобы включить режим управления базами данных через SQL, добавьте к описанию кластера поля sql_user_management и sql_database_management со значением true, а также поле admin_password с паролем пользователя admin:

        resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
          name                    = "<имя_кластера>"
          ...
          admin_password          = "<пароль_пользователя_admin>"
          sql_database_management = true
          sql_user_management     = true
          ...
        }
        

   Более подробную информацию о ресурсах, которые вы можете создать с помощью Terraform, см. в документации провайдера.

5. Проверьте корректность файлов конфигурации Terraform:

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

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

      terraform validate
      

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

6. Создайте кластер:

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

      terraform plan
      

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

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

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

         terraform apply
         

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

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

   В указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления.

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

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

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

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

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

      Примечание

      В примере приведены не все доступные параметры.

      {
        "folderId": "<идентификатор_каталога>",
        "name": "<имя_кластера>",
        "environment": "<окружение>",
        "networkId": "<идентификатор_сети>",
        "securityGroupIds": [
          "<идентификатор_группы_безопасности_1>",
          "<идентификатор_группы_безопасности_2>",
          ...
          "<идентификатор_группы_безопасности_N>"
        ],
        "configSpec": {
          "version": "<версия_ClickHouse®>",
          "embeddedKeeper": <использование_ClickHouse®_Keeper>,
          "clickhouse": {
            "resources": {
              "resourcePresetId": "<класс_хостов_ClickHouse®>",
              "diskSize": "<размер_хранилища_в_байтах>",
              "diskTypeId": "<тип_диска>"
            }
          },
          "zookeeper": {
            "resources": {
              "resourcePresetId": "<класс_хостов_ZooKeeper>",
              "diskSize": "<размер_хранилища_в_байтах>",
              "diskTypeId": "<тип_диска>"
            }
          },
          "access": {
            "dataLens": <доступ_из_DataLens>,
            "webSql": <выполнение_SQL-запросов_из_консоли_управления>,
            "metrika": <доступ_из_Метрики_и_AppMetrika>,
            "serverless": <доступ_из_Cloud_Functions>,
            "dataTransfer": <доступ_из_Data_Transfer>,
            "yandexQuery": <доступ_из_Yandex_Query>
          },
          "cloudStorage": {
            "enabled": <использование_гибридного_хранилища>,
            "moveFactor": "<доля_свободного_места>",
            "dataCacheEnabled": <временное_хранение_файлов>,
            "dataCacheMaxSize": "<максимальный_объем_памяти_для_хранения_файлов>",
            "preferNotToMerge": <отключение_слияния_кусков_данных>
          },
          "adminPassword": "<пароль_пользователя_admin>",
          "sqlUserManagement": <управление_пользователями_через_SQL>,
          "sqlDatabaseManagement": <управление_базами_данных_через_SQL>
        },
        "databaseSpecs": [
          {
            "name": "<имя_базы_данных>"
          },
          { <аналогичный_набор_настроек_для_базы_данных_2> },
          { ... },
          { <аналогичный_набор_настроек_для_базы_данных_N> }
        ],
        "userSpecs": [
          {
            "name": "<имя_пользователя>",
            "password": "<пароль_пользователя>",
            "permissions": [
              {
                "databaseName": "<имя_базы_данных>"
              }
            ]
          },
          { <аналогичный_набор_настроек_для_пользователя_2> },
          { ... },
          { <аналогичный_набор_настроек_для_пользователя_N> }
        ],
        "hostSpecs": [
          {
            "zoneId": "<зона_доступности>",
            "type": "<тип_хоста>",
            "subnetId": "<идентификатор_подсети>",
            "assignPublicIp": <публичный_доступ_к_хосту>,
            "shardName": "<имя_шарда>"
          },
          { <аналогичный_набор_настроек_для_хоста_2> },
          { ... },
          { <аналогичный_набор_настроек_для_хоста_N> }
        ],
        "deletionProtection": <защита_кластера_от_удаления>
      }
      

      Где:

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

      • environment — окружение кластера: PRODUCTION или PRESTABLE.

      • networkId — идентификатор сети, в которой будет размещен кластер.

      • securityGroupIds — идентификаторы групп безопасности в виде массива строк. массив Каждая строка — идентификатор группы безопасности.

      • configSpec — конфигурация кластера:

        • version — версия ClickHouse®: 24.3, 24.8, 24.12, 25.1 или 25.2.

        • embeddedKeeper — использовать ClickHouse® Keeper вместо ZooKeeper: true или false.

          Эта настройка определяет, как будет происходить управление репликацией в кластере из нескольких хостов ClickHouse®:

          • Если указано значение true, то для управления репликацией будет использоваться ClickHouse® Keeper.

            Внимание

            ClickHouse® Keeper невозможно выключить после создания кластера. Использование хостов ZooKeeper также станет недоступно.

          • Если значение не задано или равно false, то для управления репликацией и распределением запросов будет использоваться ZooKeeper.

        • clickhouse — конфигурация ClickHouse®:

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

        • zookeeper — конфигурация ZooKeeper:

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

          Если вы включили использование ClickHouse® Keeper с помощью настройки embeddedKeeper: true, то необязательно указывать конфигурацию ZooKeeper в configSpec: эта конфигурация не будет применена.

        • access — настройки, которые разрешают доступ к кластеру из других сервисов и выполнение SQL-запросов из консоли управления:

          • dataLens — разрешить доступ из DataLens: true или false. Значение по умолчанию — false. Подробнее о настройке подключения см. в разделе Подключение из DataLens.

          • webSql — разрешить выполнять SQL-запросы к базам данных кластера из консоли управления Yandex Cloud: true или false. Значение по умолчанию — false.

          • metrika — разрешить импорт данных из AppMetrika в кластер: true или false. Значение по умолчанию — false.

          • serverless — разрешить доступ к кластеру из сервиса Yandex Cloud Functions: true или false. Значение по умолчанию — false. Подробнее о настройке доступа см. в документации Cloud Functions.

          • dataTransfer — разрешить доступ к кластеру из сервиса Yandex Data Transfer в Serverless-режиме: true или false. Значение по умолчанию — false.

            Это позволит через специальную сеть подключаться к Yandex Data Transfer, запущенному в Kubernetes. В результате будут быстрее выполняться, например, запуск и деактивация трансфера.

          • yandexQuery — разрешить доступ к кластеру из сервиса Yandex Query: true или false. Функциональность находится на стадии Preview. Значение по умолчанию — false.

        • cloudStorage — настройки гибридного хранилища:

          • enabled — включить гибридное хранилище в кластере, если оно выключено: true или false. Значение по умолчанию — false (выключено).

            Примечание

            Включенное однажды гибридное хранилище нельзя отключить.

          • moveFactor — минимальная доля свободного места в кластерном хранилище. Если доля свободного места меньше этого значения, данные переносятся в Yandex Object Storage.

            Минимальное значение — 0, максимальное — 1, по умолчанию — 0.01.

          • dataCacheEnabled — разрешить временное хранение файлов в кластерном хранилище: true или false.

            По умолчанию — true (разрешено).

          • dataCacheMaxSize — максимальный объем памяти (в байтах), выделяемый в кластерном хранилище для временного хранения файлов.

            По умолчанию — 1073741824 (1 ГБ).

          • preferNotToMerge — отключить слияние кусков данных в кластерном и объектном хранилищах: true или false.

            Чтобы отключить слияние, укажите значение true. Чтобы оставить слияние включенным, укажите значение false.

        • sql... и adminPassword — группа настроек для управления пользователями и базами данных через SQL:

          • adminPassword — пароль пользователя admin.
          • sqlUserManagement — режим управления пользователями через SQL: true или false.
          • sqlDatabaseManagement — режим управления базами данных через SQL: true или false. Необходимо, чтобы был включен режим управления пользователями через SQL.

          Важно

          Включенные настройки управления пользователями и базами данных через SQL невозможно выключить. При необходимости их можно включить позже при изменении настроек кластера.

      • databaseSpecs — настройки баз данных в виде массива параметров элементов name. Один параметр содержит имя отдельной БД.

      • userSpecs — настройки пользователей в виде массива элементов. Каждый элемент соответствует отдельному пользователю и имеет следующую структуру:

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

        • password — пароль пользователя. Длина пароля от 8 до 128 символов.

        • permissions — список БД, к которым пользователь должен иметь доступ.

          Список организован в виде массива параметров databaseName. Один параметр содержит имя отдельной БД.

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

        • type — тип хоста: CLICKHOUSE или ZOOKEEPER.

          Если вы включили использование ClickHouse® Keeper с помощью настройки embeddedKeeper: true, то в hostSpecs нужно указать только настройки хостов ClickHouse®.

        • zoneId — зона доступности.

        • subnetId — идентификатор подсети.

        • shardName — имя шарда. Эта настройка имеет смысл только для хостов типа CLICKHOUSE.

        • assignPublicIp — доступность хоста из интернета по публичному IP-адресу: true или false.

        Если вы создаете кластер из нескольких хостов и не используете ClickHouse® Keeper, то для хостов ZooKeeper действуют следующие правила:

        • Если в облачной сети кластера есть подсети в каждой из зон доступности, а настройки хостов ZooKeeper не заданы, то в каждую подсеть будет автоматически добавлено по одному такому хосту.

        • Если подсети в сети кластера есть только в некоторых зонах доступности, то необходимо указать настройки хостов ZooKeeper явно.

      • deletionProtection — защита кластера от непреднамеренного удаления: true или false. Значение по умолчанию — 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' \
        --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.Create и выполните запрос, например, с помощью gRPCurl:

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

      Примечание

      В примере приведены не все доступные параметры.

      {
        "folder_id": "<идентификатор_каталога>",
        "name": "<имя_кластера>",
        "environment": "<окружение>",
        "network_id": "<идентификатор_сети>",
        "security_group_ids": [
          "<идентификатор_группы_безопасности_1>",
          "<идентификатор_группы_безопасности_2>",
          ...
          "<идентификатор_группы_безопасности_N>"
        ],
        "config_spec": {
          "version": "<версия_ClickHouse®>",
          "embedded_keeper": <использование_ClickHouse® Keeper>,
          "clickhouse": {
            "resources": {
              "resource_preset_id": "<класс_хостов_ClickHouse®>",
              "disk_size": "<размер_хранилища_в_байтах>",
              "disk_type_id": "<тип_диска>"
            }
          },
          "zookeeper": {
            "resources": {
              "resource_preset_id": "<класс_хостов_ZooKeeper>",
              "disk_size": "<размер_хранилища_в_байтах>",
              "disk_type_id": "<тип_диска>"
            }
          },
          "access": {
            "data_lens": <доступ_из_DataLens>,
            "web_sql": <выполнение_SQL-запросов_из_консоли_управления>,
            "metrika": <доступ_из_Метрики_и_AppMetrika>,
            "serverless": <доступ_из_Cloud_Functions>,
            "data_transfer": <доступ_из_Data_Transfer>,
            "yandex_query": <доступ_из_Yandex_Query>
          },
          "cloud_storage": {
            "enabled": <использование_гибридного_хранилища>,
            "move_factor": "<доля_свободного_места>",
            "data_cache_enabled": <временное_хранение_файлов>,
            "data_cache_max_size": "<максимальный_объем_памяти_для_хранения_файлов>",
            "prefer_not_to_merge": <отключение_слияния_кусков_данных>
          },
          "admin_password": "<пароль_пользователя_admin>",
          "sql_user_management": <управление_пользователями_через_SQL>,
          "sql_database_management": <управление_базами_данных_через_SQL>
        },
        "database_specs": [
          {
            "name": "<имя_базы_данных>"
          },
          { <аналогичный_набор_настроек_для_базы_данных_2> },
          { ... },
          { <аналогичный_набор_настроек_для_базы_данных_N> }
        ],
        "user_specs": [
          {
            "name": "<имя_пользователя>",
            "password": "<пароль_пользователя>",
            "permissions": [
              {
                "database_name": "<имя_базы_данных>"
              }
            ]
          },
          { <аналогичный_набор_настроек_для_пользователя_2> },
          { ... },
          { <аналогичный_набор_настроек_для_пользователя_N> }
        ],
        "host_specs": [
          {
            "zone_id": "<зона_доступности>",
            "type": "<тип_хоста>",
            "subnet_id": "<идентификатор_подсети>",
            "assign_public_ip": <публичный_доступ_к_хосту>,
            "shard_name": "<имя_шарда>"
          },
          { <аналогичный_набор_настроек_для_хоста_2> },
          { ... },
          { <аналогичный_набор_настроек_для_хоста_N> }
        ],
        "deletion_protection": <защита_кластера_от_удаления>
      }
      

      Где:

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

      • environment — окружение кластера: PRODUCTION или PRESTABLE.

      • network_id — идентификатор сети, в которой будет размещен кластер.

      • security_group_ids — идентификаторы групп безопасности в виде массива строк. массив Каждая строка — идентификатор группы безопасности.

      • config_spec — конфигурация кластера:

        • version — версия ClickHouse®: 24.3, 24.8, 24.12, 25.1 или 25.2.

        • embedded_keeper — использовать ClickHouse® Keeper вместо ZooKeeper: true или false.

          Эта настройка определяет, как будет происходить управление репликацией в кластере из нескольких хостов ClickHouse®:

          • Если указано значение true, то для управления репликацией будет использоваться ClickHouse® Keeper.

            Внимание

            ClickHouse® Keeper невозможно выключить после создания кластера. Использование хостов ZooKeeper также станет недоступно.

          • Если значение не задано или равно false, то для управления репликацией и распределением запросов будет использоваться ZooKeeper.

        • clickhouse — конфигурация ClickHouse®:

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

        • zookeeper — конфигурация ZooKeeper:

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

          Если вы включили использование ClickHouse® Keeper с помощью настройки embedded_keeper: true, то необязательно указывать конфигурацию ZooKeeper в config_spec: эта конфигурация не будет применена.

        • access — настройки, которые разрешают доступ к кластеру из других сервисов и выполнение SQL-запросов из консоли управления:

          • data_lens — разрешить доступ из DataLens: true или false. Значение по умолчанию — false. Подробнее о настройке подключения см. в разделе Подключение из DataLens.

          • web_sql — разрешить выполнять SQL-запросы к базам данных кластера из консоли управления Yandex Cloud: true или false. Значение по умолчанию — false.

          • metrika — разрешить импорт данных из AppMetrika в кластер: true или false. Значение по умолчанию — false.

          • serverless — разрешить доступ к кластеру из сервиса Yandex Cloud Functions: true или false. Значение по умолчанию — false. Подробнее о настройке доступа см. в документации Cloud Functions.

          • data_transfer — разрешить доступ к кластеру из сервиса Yandex Data Transfer в Serverless-режиме: true или false. Значение по умолчанию — false.

            Это позволит через специальную сеть подключаться к Yandex Data Transfer, запущенному в Kubernetes. В результате будут быстрее выполняться, например, запуск и деактивация трансфера.

          • yandex_query — разрешить доступ к кластеру из сервиса Yandex Query: true или false. Функциональность находится на стадии Preview. Значение по умолчанию — false.

        • cloud_storage — настройки гибридного хранилища:

          • enabled — включить гибридное хранилище в кластере, если оно выключено: true или false. Значение по умолчанию — false (выключено).

            Примечание

            Включенное однажды гибридное хранилище нельзя отключить.

          • move_factor — минимальная доля свободного места в кластерном хранилище. Если доля свободного места меньше этого значения, данные переносятся в Yandex Object Storage.

            Минимальное значение — 0, максимальное — 1, по умолчанию — 0.01.

          • data_cache_enabled — разрешить временное хранение файлов в кластерном хранилище: true или false.

            По умолчанию — true (разрешено).

          • data_cache_max_size — максимальный объем памяти (в байтах), выделяемый в кластерном хранилище для временного хранения файлов.

            По умолчанию — 1073741824 (1 ГБ).

          • prefer_not_to_merge — отключить слияние кусков данных в кластерном и объектном хранилищах: true или false.

            Чтобы отключить слияние, укажите значение true. Чтобы оставить слияние включенным, укажите значение false.

        • sql... и admin_password — группа настроек для управления пользователями и базами данных через SQL:

          • admin_password — пароль пользователя admin.
          • sql_user_management — режим управления пользователями через SQL: true или false.
          • sql_database_management — режим управления базами данных через SQL: true или false. Необходимо, чтобы был включен режим управления пользователями через SQL.

          Важно

          Включенные настройки управления пользователями и базами данных через SQL невозможно выключить. При необходимости их можно включить позже при изменении настроек кластера.

      • database_specs — настройки баз данных в виде массива параметров элементов name. Один параметр содержит имя отдельной БД.

      • user_specs — настройки пользователей в виде массива элементов. Каждый элемент соответствует отдельному пользователю и имеет следующую структуру:

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

        • password — пароль пользователя. Длина пароля от 8 до 128 символов.

        • permissions — список БД, к которым пользователь должен иметь доступ.

          Список организован в виде массива параметров database_name. Один параметр содержит имя отдельной БД.

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

        • type — тип хоста: CLICKHOUSE или ZOOKEEPER.

          Если вы включили использование ClickHouse® Keeper с помощью настройки embedded_keeper: true, то в host_specs нужно указать только настройки хостов ClickHouse®.

        • zone_id — зона доступности.

        • subnet_id — идентификатор подсети.

        • shard_name — имя шарда. Эта настройка имеет смысл только для хостов типа CLICKHOUSE.

        • assign_public_ip — доступность хоста из интернета по публичному IP-адресу: true или false.

        Если вы создаете кластер из нескольких хостов и не используете ClickHouse® Keeper, то для хостов ZooKeeper действуют следующие правила:

        • Если в облачной сети кластера есть подсети в каждой из зон доступности, а настройки хостов ZooKeeper не заданы, то в каждую подсеть будет автоматически добавлено по одному такому хосту.

        • Если подсети в сети кластера есть только в некоторых зонах доступности, то необходимо указать настройки хостов ZooKeeper явно.

      • deletion_protection — защита кластера от непреднамеренного удаления: true или false. Значение по умолчанию — 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.Create \
        < body.json
      

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

Создайте кластер Managed Service for ClickHouse® и сеть для него с тестовыми характеристиками:

• Имя mych.

• Окружение PRESTABLE.

• Облако с идентификатором b1gq90dgh25********.

• Каталог с идентификатором b1gia87mbaom********.

• Новая облачная сеть cluster-net.

• Новая группа безопасности по умолчанию cluster-sg (в сети cluster-net), разрешающая подключение к любому хосту кластера из любой сети (в том числе из интернета) по портам 8443, 9440.

• Один хост класса s2.micro в новой подсети cluster-subnet-ru-central1-a.

  Параметры подсети:

  • диапазон адресов — 172.16.1.0/24;
  • сеть — cluster-net;
  • зона доступности — ru-central1-a.

• Хранилище на сетевых SSD-дисках (network-ssd) размером 32 ГБ.

• Имя базы данных db1.

• Пользователь user1 с паролем user1user1.

Конфигурационные файлы для такого кластера выглядят так:

1. Конфигурационный файл с описанием настроек провайдера:

   provider.tf

   terraform {
     required_providers {
       yandex = {
         source = "yandex-cloud/yandex"
       }
     }
   }
   
   provider "yandex" {
     token     = "<OAuth_или_статический_ключ_сервисного_аккаунта>"
     cloud_id  = "b1gq90dgh25********"
     folder_id = "b1gia87mbaom********"
   }
   

   Для получения токена OAuth или статического ключа доступа см. инструкции Yandex Identity and Access Management.

2. Конфигурационный файл с описанием облачной сети и подсети:

   networks.tf

   resource "yandex_vpc_network" "cluster-net" { name = "cluster-net" }
   
   resource "yandex_vpc_subnet" "cluster-subnet-a" {
     name           = "cluster-subnet-ru-central1-a"
     zone           = "ru-central1-a"
     network_id     = yandex_vpc_network.cluster-net.id
     v4_cidr_blocks = ["172.16.1.0/24"]
   }
   

3. Конфигурационный файл с описанием группы безопасности:

   security-groups.tf

   resource "yandex_vpc_default_security_group" "cluster-sg" {
     network_id = yandex_vpc_network.cluster-net.id
   
     ingress {
       description    = "HTTPS (secure)"
       port           = 8443
       protocol       = "TCP"
       v4_cidr_blocks = ["0.0.0.0/0"]
     }
   
     ingress {
       description    = "clickhouse-client (secure)"
       port           = 9440
       protocol       = "TCP"
       v4_cidr_blocks = ["0.0.0.0/0"]
     }
   
     egress {
       description    = "Allow all egress cluster traffic"
       protocol       = "TCP"
       v4_cidr_blocks = ["0.0.0.0/0"]
     }
   }
   

4. Конфигурационный файл с описанием кластера и его хоста:

   cluster.tf

   resource "yandex_mdb_clickhouse_cluster" "mych" {
     name               = "mych"
     environment        = "PRESTABLE"
     network_id         = yandex_vpc_network.cluster-net.id
     security_group_ids = [yandex_vpc_default_security_group.cluster-sg.id]
   
     clickhouse {
       resources {
         resource_preset_id = "s2.micro"
         disk_type_id       = "network-ssd"
         disk_size          = 32
       }
     }
   
     host {
       type      = "CLICKHOUSE"
       zone      = "ru-central1-a"
       subnet_id = yandex_vpc_subnet.cluster-subnet-a.id
     }
   
     lifecycle {
       ignore_changes = [database, user]
     }
   }
   
   resource "yandex_mdb_clickhouse_database" "db1" {
     cluster_id = yandex_mdb_clickhouse_cluster.mych.id
     name       = "db1"
   }
   
   resource "yandex_mdb_clickhouse_user" "user1" {
     cluster_id = yandex_mdb_clickhouse_cluster.mych.id
     name       = "user1"
     password   = "user1user1"
     permission {
       database_name = yandex_mdb_clickhouse_database.db1.name
     }
   }