Controller

Controller — это сервис, который берет на себя задачи по администрированию и поддержанию работоспособности приватных клик.

Решаемые задачи

• Персистентное хранение конфигурации клики.
• Правильная генерация конфигурации инстансов из предоставленной конфигурации клики и из конфигурации кластера YTsaurus.
• Запуск и перезапуск Vanilla-операций клики в случае их аварийного завершения из-за неполадок или работ на кластере.

Controller CLI

Работать с контроллером можно через Command Line Interface (CLI), предоставляемый в составе пакета ytsaurus-client.

У всех команд присутствует опциональный параметр --proxy, через который можно задать кластер YTsaurus, на котором происходит работа с кликами:

yt --proxy <cluster_name> clickhouse ctl list

Если аргумент пропущен, будет использовано значение по умолчанию из переменной окружения YT_PROXY.

Права на клику

Права на клику хранятся по пути //sys/access_control_object_namespaces/chyt/<alias>/@principal_acl. Атрибут @principal_acl замените на необходимые права:

• use — использовать клику (делать запросы);
• read — читать конфигурацию клики;
• manage — менять конфигурацию клики;
• remove — удалять клику.

Команды

Create

yt clickhouse ctl create <alias> — создать клику с заданным алиасом (названием). Алиас клики должен удовлетворять свойствам идентификатора, т.е. состоять только из символов латинского алфавита, цифр и знака подчеркивания (_), при этом алиас не может начинаться с цифры. Также допускается использование знака * в начале (он просто игнорируется) и знака -.

После успешного выполнения команды в Кипарисе будет создан узел //sys/strawberry/chyt/<alias>/speclet, в котором будет храниться конфигурация клики.

Также в веб интерфейсе у узла //sys/strawberry/chyt/<alias> будет отображаться текущее состояние клики, в том числе возможные ошибки, из-за которых не может быть запущена Vanilla-операция с инстансами клики.

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

Remove

yt clickhouse ctl remove <alias> — полностью удалить клику и ее персистентное состояние. После успешного завершения операции восстановить клику будет невозможно. Для выполнения операции необходимо обладать ролью Manage на данную клику.

Exists

yt clickhouse ctl exists <alias> — проверить существование клики на кластере. Результатом работы команды будет значение типа bool.

Пример результата:

$ yt clickhouse ctl exists test_clique_name
%true

Status

yt clickhouse ctl status <alias> — вернуть текущий статус клики.

Пример результата:

$ yt clickhouse ctl status test_clique_name
{
    "status" = "Waiting for restart: speclet changed";
    "operation_state" = "running";
    "operation_url" = "https://ytsaurus.ru/<cluster_name>/operations/de569537-f8cded7d-3fe03e8-b5278252";
    "speclet_diff" = {
        "enable_geodata" = {
            "new_value" = %true;
            "old_value" = %false;
        };
    };
}

List

yt clickhouse ctl list — посмотреть алиасы все существующих на кластере клик.

Пример результата:

$ yt clickhouse ctl list
[
    "<clique_name_1>";
    "<clique_name_2>";
    "<clique_name_3>";
]

Set-option

yt clickhouse ctl set-option <key> <value> [--alias <alias>] — установить опцию key в спеклете клики в значение value. Для выполнения команды необходимо обладать ролью Manage на данную клику.

Значение value задается в виде произвольного YSON-значения. В частности, значение может быть:

• числом:

yt clickhouse ctl set-option instance_count 1

• boolean-значением. В синтаксисе YSON такие значения начинаются со знака %:

yt clickhouse ctl set-option enable_geodata %false

• строкой-идентификатором:

yt clickhouse ctl set-option query_settings/chyt.execution.join_policy local

• произвольной строкой. Если строка содержит символы, отличные от символов алфавита/цифр и знаков _ и -, то чтобы значение было корректно распаршено как строка, необходимо обернуть его в двойные кавычки ("vot tak"). При этом большинство популярных реализаций командной строки, такие как bash, zsh и т. д., парсят символ " как управляющий и могут передать в CLI значение без обрамляющих двойных кавычек. Чтобы обойти данную проблему, необходимо дополнительно обернуть аргумент в одинарные кавычки:

yt clickhouse ctl set-option chyt_version '"stable-2.08"'

Опциональный аргумент --alias <alias> задает алиас клики, к которой необходимо применить изменения. Данный аргумент может быть опущен, в таком случае его значение будет взято из переменной окружения CHYT_ALIAS. Если и оно пусто, то будет возвращена ошибка.

Все выставленные опции можно посмотреть с помощью команды get-speclet. Описание всех доступных опций приведено в разделе Конфигурация.

Remove-option

yt clickhouse ctl remove-option <key> [--alias <alias>] — удалить выставленное ранее значение опции в конфигурации клики. Отсутствующие опции в конфигурации клики будут заданы значениями по умолчанию при запуске операции клики.

Get-speclet

yt clickhouse ctl get-speclet [--alias <alias>] — получить все выставленные для клики опции.

Пример результата:

$ yt clickhouse ctl get-speclet --alias test_clique_name
{
    "family" = "chyt";
    "stage" = "production";
    "instance_count" = 8;
    "active" = %true;
    "pool" = "chyt";
    ...
}

Set-speclet

yt clickhouse ctl set-speclet <speclet> [--alias <alias>] — задать спеклет клики в формате YSON-строки. Для выполнения команды необходимо обладать ролью manage на данную клику.

Пример:

yt clickhouse ctl set-speclet '{instance_count=2;pool="chyt";}' --alias test_clique_name

Start

yt clickhouse ctl start <alias> [--untracked] — запустить ранее созданную клику.

Опция untracked позволяет запустить клику без привязки к контроллеру и без каких-либо гарантий. Опция предназначена для запуска тестовых клик без использования вычислительного пула. Запуск production клик без указания вычислительного пула крайне не рекомендуется, так как клика может работать нестабильно. Клика будет запущена из-под имени пользователя. Контроллер не будет следить за состоянием такой клики и перезапускать ее в случае ошибок. В случае завершения операции клики с какими-либо ошибками необходимо будет самостоятельно перезапустить клику повторным выполнением данной команды.

Для выполнения команды необходимо обладать ролью manage на данную клику.

Пример результата:

$ yt clickhouse ctl start test_clique_name
{
    "status" = "Ok";
    "operation_state" = "initializing";
    "operation_url" = ...;
}

Stop

yt clickhouse ctl stop <alias> — остановить клику. Операция клики будет остановлена, все выделенные под клику ресурсы из пула будут освобождены. Конфигурация клики не будет удалена, в дальнейшем клика может быть перезапущена пользователем с помощью команды start. Для выполнения команды необходимо обладать ролью manage на данную клику.

Доступные опции

Опции клики, доступные для установки через команду set-option, можно посмотреть в разделе Конфигурация.