name: clickhouse
service_id: 120
service_display_name: ClickHouse
service_short_name: clickhouse
service_man: '# Инструкция по управлению кластерами и пользователями ClickHouse<br/><br/>---<br/><br/>## Общая информация<br/><br/>ClickHouse — это колоночная система управления базами данных, предназначенная для обработки аналитических запросов в реальном времени. Платформа позволяет создавать, удалять, приостанавливать и возобновлять кластеры ClickHouse, а также управлять базами данных и пользователями.<br/><br/>Кластер создаётся через оператор Altinity (`https://github.com/Altinity/clickhouse-operator`) в ресурсной платформе типа `k8s`<br/><br/>Кластеры могут создаваться шардированными с произвольным количеством реплик. Для обеспечения отказоустойчивости и координации обязательно включение параметра `Создать ClickHouse-Keeper`.<br/><br/>Кластера создаются с обязательным бекапом. Для этого необходимо предварительно создать услугу `S3 Object Storage`.<br/>---<br/><br/>## Доступные операции<br/><br/>* **create**  — Создание кластера<br/>* **delete**  — Удаление кластера<br/>* **suspend** — Приостановка работы кластера<br/>* **resume**  — Возобновление работы кластера<br/>* **create_database** — Создание базы данных<br/>* **delete_database** — Удаление базы данных<br/>* **create_user** — Создание пользователя и настройка прав доступа к базе данных<br/>* **delete_user** — Удаление пользователя<br/><br/>## Процесс создания и первого подключения<br/><br/>1. Выполнить операцию `create` - будет создан кластер<br/>2. Выполнить операцию `create_database` - будет создана база данных<br/>3. Выполнить операцию `create_user` - будет создан пользователь (выбрать доступ подключения к БД, созданной в п.2)<br/><br/>## Примеры подключения<br/><br/>### Подключение через HTTP-интерфейс<br/><br/>```bash<br/># Проверка доступности кластера<br/>curl &quot;http://&lt;username&gt;:&lt;password&gt;@&lt;host&gt;:8123/&quot; -d &quot;SELECT 1&quot;<br/><br/># Выполнение запроса<br/>curl &quot;http://&lt;username&gt;:&lt;password&gt;@&lt;host&gt;:8123/&quot; -d &quot;SHOW DATABASES&quot;<br/>```<br/><br/>## Простые кейсы<br/>*Создать БД и обычной таблицы*<br/>```clickhouse<br/>CREATE TABLE database.table<br/>(<br/>    id UInt64,<br/>    value String<br/>)<br/>ENGINE = MergeTree()<br/>ORDER BY id;<br/><br/>INSERT INTO database.table SELECT number, toString(number) FROM numbers(10000000);<br/><br/>SELECT count() FROM database.table;<br/>```<br/>Базы и таблицы не реплицируются без специального ключа (`ON CLUSTER ''clickhousek8s''`)<br/>В случае создания в стиле, описанным выше, необходимо будет выполнять действия на всех шардах/репликах<br/><br/><br/>*Создание БД и шардированной таблицы*<br/>```clickhouse<br/>CREATE TABLE database.localUsers<br/>(<br/>    id UInt64,<br/>    value String<br/>)<br/>ENGINE = MergeTree()<br/>ORDER BY id;<br/><br/>CREATE TABLE database.shardedTable<br/>AS localUsers<br/>ENGINE = Distributed(''clickhousek8s'', ''database'', ''localUsers'', id);<br/><br/>INSERT INTO shardedTable SELECT number, toString(number) FROM numbers(10000000);<br/><br/>SELECT count() FROM shardedTable;<br/>```<br/>Важный момент - в данном примере таблицы придётся также выполнять на всех нодах ClickHouse<br/><br/>*Создание реплицируемой и шардированной таблицы*<br/>```clickhouse<br/>CREATE TABLE IF NOT EXISTS database.localUsers ON cluster ''clickhousek8s''<br/>(<br/>    user_id UInt64,<br/>    name String,<br/>    email String<br/>)<br/>ENGINE = ReplicatedMergeTree(<br/>    ''/clickhouse/tables/{shard}/localUsers'',<br/>    ''{replica}''<br/>)<br/>ORDER BY user_id;<br/><br/>CREATE TABLE IF NOT EXISTS database.users ON cluster ''clickhousek8s''<br/>AS database.localUsers<br/>ENGINE = Distributed(''clickhousek8s'', ''database'', ''localUsers'', rand());<br/><br/>INSERT INTO database.users VALUES (1, ''Alice'', ''alice@example.com'');<br/>INSERT INTO database.users VALUES (2, ''Bob'', ''bob@example.com'');<br/>INSERT INTO database.users VALUES (3, ''Charlie'', ''charlie@example.com'');<br/>INSERT INTO database.users VALUES (4, ''David'', ''david@example.com'');<br/>INSERT INTO database.users VALUES (5, ''Gosha'', ''gosha@example.com'');<br/>INSERT INTO database.users VALUES (6, ''Eve'', ''eve@example.com'');<br/>INSERT INTO database.users VALUES (7, ''Frank'', ''frank@example.com'');<br/>INSERT INTO database.users VALUES (8, ''Grace'', ''grace@example.com'');<br/>INSERT INTO database.users VALUES (9, ''Hannah'', ''hannah@example.com'');<br/>INSERT INTO database.users VALUES (10, ''Ivan'', ''ivan@example.com'');<br/><br/>SELECT * FROM database.localUsers;<br/>SELECT * FROM database.users;<br/><br/>SELECT COUNT(*) AS total_users       FROM database.users;<br/>SELECT COUNT(*) AS total_users_local FROM database.localUsers;<br/>```'
lifecycle:
    suspend_on_destroy_default: true
    adopt_existing_on_create_default: false
outputs:
    params:
        - code: state_params
          type: map
        - code: state_out
          type: map
        - code: state_params_flat
          type: map
        - code: state_out_flat
          type: map
        - code: vault_secrets
          type: map
          sensitive: true
        - code: vault_url
          type: string
        - code: vault_user_path
          type: string
        - code: vault_fields
          type: list
operations:
    - name: create
      id: 181
      kind: instance
      action: create
      man: Операция создания кластера ClickHouse<br/><br/>Для подключения к кластеру также необходимо создать базу данных через операцию `create_database` и создание пользователя через операцию `create_user`
      params:
        - id: 837
          code: startupConfiguration
          data_type: map-fixed
          required: true
          sort: 10
          sub_params:
            - id: 194
              code: resourceRealm
              data_type: string
              required: true
              default: ""
              value_list:
                - k8s-3-sandbox-nubes-ru
                - k8s-4-sandbox-nubes-ru
              man: Кластер Kubernetes, на котором будет развернут экземпляр
              is_modifiable: false
        - id: 838
          code: clusterConfiguration
          data_type: map-fixed
          required: true
          sort: 20
          is_modifiable: true
          sub_params:
            - id: 195
              code: cpu
              data_type: integer &gt; 0
              required: true
              default: "1000"
              man: Указывается в Milicores<br/>`1000` Mili == `1` Ядро
              is_modifiable: false
            - id: 196
              code: memory
              data_type: integer &gt; 0
              required: true
              default: "2048"
              man: Указывается в Megabytes
              is_modifiable: false
            - id: 197
              code: replicas
              data_type: integer &gt; 0
              required: true
              default: "1"
              value_list:
                - "1"
                - "3"
                - "5"
                - "7"
              is_modifiable: false
            - id: 199
              code: shards
              data_type: integer &gt; 0
              required: true
              default: "1"
              value_list:
                - "1"
                - "2"
                - "3"
              man: '**Шард** - это часть данных, разделенная на разные узлы (серверы) для горизонтального масштабирования и обработки больших объемов информации. <br/>**Реплика** - это точная копия данных внутри одного шарда'
              is_modifiable: false
            - id: 198
              code: disk
              data_type: integer &gt; 0
              required: true
              default: "10"
              man: Указывается в GIGAbytes
              is_modifiable: false
        - id: 839
          code: accessConfiguration
          data_type: map-fixed
          required: true
          sort: 40
          is_modifiable: true
          sub_params:
            - id: 200
              code: masterIpSpace
              data_type: string
              required: true
              default: ""
              man: Из какого Ip-Space резервировать внешний IP<br/>Список предоставляется из Организации, в котором развёрнута ресурсная платформа
              is_modifiable: false
            - id: 201
              code: masterAccessList
              data_type: json
              required: true
              default: '[]'
              man: Необходимо настраивать, когда зарезервирован внешний адрес<br/>Если передан пустой массив, доступ выделяется всем
              is_modifiable: false
        - id: 840
          code: clickhouseKeeperConfiguration
          data_type: map-fixed
          required: true
          sort: 30
          is_modifiable: true
          sub_params:
            - id: 202
              code: cpu
              data_type: integer &gt; 0
              required: true
              default: "500"
              man: Указывается в Milicores<br/>`1000` Mili == `1` Ядро
              is_modifiable: false
            - id: 203
              code: memory
              data_type: integer &gt; 0
              required: true
              default: "512"
              man: Указывается в Megabytes
              is_modifiable: false
            - id: 204
              code: replicas
              data_type: integer &gt;= 0
              required: true
              default: "0"
              value_list:
                - "0"
                - "1"
                - "3"
              man: Если указан 0, то инстансы ClickHouse Keeper развёрнуты не будут
              is_modifiable: false
        - id: 841
          code: clickhouseConfiguration
          data_type: map-fixed
          required: true
          sort: 50
          is_modifiable: true
          sub_params:
            - id: 205
              code: version
              data_type: string
              required: true
              default: "25.10"
              value_list:
                - "25.10"
              is_modifiable: false
        - id: 842
          code: backupConfiguration
          data_type: map-fixed
          required: true
          sort: 70
          is_modifiable: true
          sub_params:
            - id: 208
              code: schedule
              data_type: string
              required: true
              default: 0 0 * * *
              regex: ^((((\d+,)+\d+|(\d+(\/|-|#)\d+)|(\d+L?)|(\*(\/\d+)?)|(L(-\d+)?)|(\?)|([A-Z]{3}(-[A-Z]{3})?)) ?){5,7})|(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|(@every (\d+(ns|us|µs|ms|s|m|h))+)$
              is_modifiable: false
            - id: 206
              code: s3Uid
              data_type: uuid
              required: true
              default: ""
              man: Экземпляр S3 обязателен
              is_modifiable: false
            - id: 207
              code: retain
              data_type: integer &gt; 0
              required: true
              default: "7"
              is_modifiable: false
        - id: 843
          code: autoscaleConfiguration
          data_type: map-fixed
          required: true
          sort: 80
          is_modifiable: true
          sub_params:
            - id: 210
              code: schedule
              data_type: integer &gt;= 0
              required: true
              default: "0"
              value_list:
                - "0"
                - "5"
                - "12"
                - "23"
              man: Требует включения autoScale. Окно обновления (пока не реализовано). Указывается час в виде Integer (0 / 5 / 12 / 23)
              is_modifiable: false
            - id: 211
              code: quota
              data_type: integer &gt; 0
              required: true
              default: "100"
              man: До какого размера возможно увеличивать диск, когда включен Autoscale
              is_modifiable: false
            - id: 212
              code: percent
              data_type: integer &gt; 0
              required: true
              default: "10"
              value_list:
                - "10"
                - "15"
                - "20"
              man: Требует включения autoScale. Позволяет указать в процентах расширение от текущего макс объема<br/>Минимальный размер на который расширяется - **1Gb**
              is_modifiable: false
            - id: 209
              code: enabled
              data_type: boolean
              required: true
              default: "false"
              value_list:
                - "false"
                - "true"
              man: Включает автоскейлинг PV. При включении параметра необходимо настроить autoScalePercentage и autoScaleTechWindow. Алерт при срабатывании вызывает modify у текущей услуги
              is_modifiable: false
        - id: 851
          code: clickhouseFilesConfiguration
          data_type: array-map-fixed
          required: false
          man: 'Формат:<br/> - path: somethings3.xml<br/>   xmlConfig: ''&lt;clickhouse&gt;......&lt;/clickhouse&gt;'''
          sort: 60
          is_modifiable: true
          sub_params:
            - id: 234
              code: path
              data_type: string
              required: true
              default: something.xml
              regex: ^[a-zA-Z0-9]+\.xml$
              is_modifiable: false
            - id: 235
              code: xmlConfig
              data_type: string
              required: true
              default: '&lt;clickhouse&gt;&lt;/clickhouse&gt;'
              man: Предварительно xml необходимо отформатировать через<br/>```<br/>$ tr -d '\n \t' &lt; input.xml &gt; output.xml<br/>```<br/><br/>Позже будет исправлено
              is_modifiable: false
              is_sensitive: true
    - name: create_database
      id: 186
      kind: subresource
      action: create
      subresource: database
      man: База данных создаётся на всех репликах кластера ClickHouse
      params:
        - id: 600
          code: dbName
          data_type: string
          required: true
          default: db01
          regex: ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$
          descr: 'Пример: `db01`'
          sort: 10
    - name: create_user
      id: 185
      kind: subresource
      action: create
      subresource: user
      params:
        - id: 596
          code: username
          data_type: string
          required: true
          default: myusername
          regex: ^(?![0-9_])[a-zA-Z_][a-zA-Z0-9_]{0,62}$
          maxlength: 62
          minlength: 2
          descr: 'Пример: `myusername`'
          sort: 10
        - id: 598
          code: dbName
          data_type: array-map-fixed
          required: true
          default: '[{}]'
          sort: 30
          sub_params:
            - id: 233
              code: dbName
              data_type: string
              required: true
              default: ""
              is_modifiable: false
        - id: 599
          code: accessHosts
          data_type: string
          required: true
          default: ::/0
          descr: 'Пример: `::/0`'
          sort: 40
    - name: delete
      id: 184
      kind: instance
      action: delete
      man: Удаление возможно только после остановки сервиса через операцию `suspend`<br/>После выполнения операции необходимо выждать определенное кол-во времени
      params: []
    - name: delete_database
      id: 188
      kind: subresource
      action: delete
      subresource: database
      man: Необратимое действие!!!<br/>Трижды подумай, заблокируй телефон тимлида и не выполняй это действие
      params:
        - id: 602
          code: dbName
          data_type: string
          required: true
          descr: ВСЕ ДАННЫЕ ВНУТРИ БД БУДУТ УДАЛЕНЫ
    - name: delete_user
      id: 187
      kind: subresource
      action: delete
      subresource: user
      params:
        - id: 601
          code: username
          required: true
          descr: Имя пользователя, созданное через операцию `create_user`
    - name: modify
      id: 189
      kind: instance
      action: modify
      params:
        - id: 844
          code: clusterConfiguration
          data_type: map-fixed
          required: true
          sort: 10
          sub_params:
            - id: 216
              code: shards
              data_type: integer &gt; 0
              required: true
              default: ""
              value_list:
                - "1"
                - "2"
                - "3"
              man: '**Шард** - это часть данных, разделенная на разные узлы (серверы) для горизонтального масштабирования и обработки больших объемов информации. <br/>**Реплика** - это точная копия данных внутри одного шарда'
              is_modifiable: false
            - id: 217
              code: disk
              data_type: integer &gt; 0
              required: true
              default: ""
              man: Указывается в GIGAbytes
              is_modifiable: false
            - id: 213
              code: cpu
              data_type: integer &gt; 0
              required: true
              default: ""
              man: Указывается в Milicores<br/>`1000` Mili == `1` Ядро
              is_modifiable: false
            - id: 214
              code: memory
              data_type: integer &gt; 0
              required: true
              default: ""
              man: Указывается в Megabytes
              is_modifiable: false
            - id: 215
              code: replicas
              data_type: integer &gt; 0
              required: true
              default: ""
              value_list:
                - "1"
                - "3"
                - "5"
                - "7"
              is_modifiable: false
        - id: 845
          code: clickhouseKeeperConfiguration
          data_type: map-fixed
          required: true
          sort: 20
          sub_params:
            - id: 220
              code: replicas
              data_type: integer &gt;= 0
              required: true
              default: ""
              value_list:
                - "0"
                - "1"
                - "3"
              man: Если указан 0, то инстансы ClickHouse Keeper развёрнуты не будут
              is_modifiable: false
            - id: 218
              code: cpu
              data_type: integer &gt; 0
              required: true
              default: ""
              man: Указывается в Milicores<br/>`1000` Mili == `1` Ядро
              is_modifiable: false
            - id: 219
              code: memory
              data_type: integer &gt; 0
              required: true
              default: ""
              man: Указывается в Megabytes
              is_modifiable: false
        - id: 846
          code: accessConfiguration
          data_type: map-fixed
          required: true
          sort: 30
          sub_params:
            - id: 221
              code: masterIpSpace
              data_type: string
              required: true
              default: ""
              man: Из какого Ip-Space резервировать внешний IP<br/>Список предоставляется из Организации, в котором развёрнута ресурсная платформа
              is_modifiable: false
            - id: 222
              code: masterAccessList
              data_type: json
              required: true
              default: ""
              man: Необходимо настраивать, когда зарезервирован внешний адрес<br/>Если передан пустой массив, доступ выделяется всем
              is_modifiable: false
        - id: 847
          code: clickhouseConfiguration
          data_type: map-fixed
          required: true
          sort: 40
          sub_params:
            - id: 223
              code: version
              data_type: string
              required: true
              default: ""
              value_list:
                - "25.10"
              is_modifiable: false
        - id: 848
          code: backupConfiguration
          data_type: map-fixed
          required: true
          sort: 60
          sub_params:
            - id: 224
              code: s3Uid
              data_type: uuid
              required: true
              default: ""
              man: Экземпляр S3 обязателен
              is_modifiable: false
            - id: 225
              code: retain
              data_type: integer &gt; 0
              required: true
              default: ""
              is_modifiable: false
            - id: 226
              code: schedule
              data_type: string
              required: true
              default: ""
              regex: ^((((\d+,)+\d+|(\d+(\/|-|#)\d+)|(\d+L?)|(\*(\/\d+)?)|(L(-\d+)?)|(\?)|([A-Z]{3}(-[A-Z]{3})?)) ?){5,7})|(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|(@every (\d+(ns|us|µs|ms|s|m|h))+)$
              is_modifiable: false
        - id: 849
          code: autoscaleConfiguration
          data_type: map-fixed
          required: true
          sort: 70
          sub_params:
            - id: 227
              code: enabled
              data_type: boolean
              required: true
              default: false,true
              man: Включает автоскейлинг PV. При включении параметра необходимо настроить autoScalePercentage и autoScaleTechWindow. Алерт при срабатывании вызывает modify у текущей услуги
              is_modifiable: false
            - id: 228
              code: schedule
              data_type: integer &gt;= 0
              required: true
              default: ""
              value_list:
                - "0"
                - "5"
                - "12"
                - "23"
              man: Требует включения autoScale. Окно обновления (пока не реализовано). Указывается час в виде Integer (0 / 5 / 12 / 23)
              is_modifiable: false
            - id: 229
              code: quota
              data_type: integer &gt; 0
              required: true
              default: ""
              man: До какого размера возможно увеличивать диск, когда включен Autoscale
              is_modifiable: false
            - id: 230
              code: percent
              data_type: integer &gt; 0
              required: true
              default: ""
              value_list:
                - "10"
                - "15"
                - "20"
              man: Требует включения autoScale. Позволяет указать в процентах расширение от текущего макс объема<br/>Минимальный размер на который расширяется - **1Gb**
              is_modifiable: false
        - id: 850
          code: clickhouseFilesConfiguration
          data_type: array-map-fixed
          required: false
          man: 'Формат:<br/> - path: somethings3.xml<br/>   xmlConfig: ''&lt;clickhouse&gt;......&lt;/clickhouse&gt;'''
          sort: 50
          sub_params:
            - id: 231
              code: path
              data_type: string
              required: true
              default: something.xml
              regex: ^[a-zA-Z0-9]+\.xml$
              is_modifiable: false
            - id: 232
              code: xmlConfig
              data_type: string
              required: true
              default: '&lt;clickhouse&gt;&lt;/clickhouse&gt;'
              man: Предварительно xml необходимо отформатировать через<br/>```<br/>$ tr -d '\n \t' &lt; input.xml &gt; output.xml<br/>```<br/><br/>Позже будет исправлено
              is_modifiable: false
              is_sensitive: true
    - name: reconcile
      id: 276
      kind: action
      action: reconcile
      params: []
    - name: resume
      id: 183
      kind: instance
      action: resume
      params: []
    - name: suspend
      id: 182
      kind: instance
      action: suspend
      man: Операция приводит к удалению всех подов<br/>Persistent Volume остаются нетронутыми
      params: []