Управляемые сервисы

Создание, наблюдение и вывод из эксплуатации сервисов ClickHouse, которыми ClickHouse Cloud управляет в вашем кластере через исполнитель коннектора

В режиме Managed коннектор запускает третий компонент — исполнитель. Через него ClickHouse Cloud управляет сервисами ClickHouse в вашем кластере Kubernetes. На этой странице рассматривается создание сервиса, получение его status, действия ClickHouse Cloud с ним, а также его вывод из эксплуатации.

​

Что делает режим Managed

Исполнитель — это демон в том же бинарном файле clicklink, что и scraper со средством диагностики. Он поддерживает исходящий канал WebSocket к конечной точке вашего коннектора и получает команды жизненного цикла от ClickHouse Cloud. Каждую команду он применяет к единственному кластеру Kubernetes, для которого настроен, и сообщает результат по этому каналу. Как и остальные компоненты, он устанавливает только исходящие подключения: ClickHouse Cloud никогда не подключается к вашему кластеру, а локальный API исполнителя привязан к loopback.

Режим Managed доступен на Amazon EKS с хранилищем S3 в период закрытой предварительной версии. Команда сопровождения аккаунта ClickHouse включает его при регистрации вашей среды. init отклоняет kube-контекст, который не указывает на кластер EKS.

Каждому сервису нужны три принадлежащих вам облачных ресурса: бакет данных, бакет для резервных копий и роль IAM, которую принимают поды ClickHouse для доступа к ним. Вы создаёте их с помощью собственных учётных данных до создания сервиса и удаляете после того, как сервис удалён. Исполнитель не хранит учётных данных для ваших бакетов или IAM и никогда не удаляет данные. Единственные его облачные вызовы направляются в Amazon ECR и STS. Он выполняет вход в реестр, когда синхронизация платформы или создание сервиса загружает чарт, и проверяет образы под ролью pull с доступом только для чтения во время обновления платформы. Вызовов к S3 или IAM он не выполняет. Для каждого сервиса он создаёт Kubernetes Service типа LoadBalancer, который контроллер балансировщика нагрузки вашего кластера реализует как внутренний NLB в вашем аккаунте.

На ВМ исполнитель работает как юнит systemd clicklink-executor рядом с двумя другими. В Kubernetes это Deployment с одной репликой в пространстве имён коннектора. Он отдаёт данные о состоянии и метрики на порту 8086, а свой локальный API — на 127.0.0.1:9999.

​

Включение режима Managed

Режим Managed выбирается при enroll: передайте --managed команде clicklink clctl init либо ответьте на промпт в терминале. На ВМ init берёт кластер из kubeconfig этого хоста (--cluster-name, если в нём указано несколько EKS cluster) и выдаёт исполнителю cluster-wide доступ inline. В Kubernetes передайте --egress-cidrs с CIDR вашей конечной точки коннектора, чтобы chart подготовил свой NetworkPolicy с политикой default-deny во включенном состоянии.

Сама установка не меняется. Полный порядок действий описан в разделе онбординг, а флаги — в CLI reference.

​

Создание сервиса

Создание сервисов через конечную точку коннектора включается отдельно для каждого окружения; перед началом уточните это у команды сопровождения аккаунта ClickHouse.

Создание сервиса выполняется двумя командами. prepare создаёт всё на вашей стороне; instances create отправляет запрос на создание в ClickHouse Cloud через конечную точку вашего коннектора. ClickHouse Cloud формирует определение сервиса и передаёт запрос на создание исполнителю по его исходящему каналу. Исполнитель применяет его к вашему кластеру и сообщает о результате.

Учётные данные AWS нужны только команде prepare: она создаёт S3 бакеты и роль IAM. Команде instances create нужны конфигурация и учётные данные коннектора, а к локальному API исполнителя она обращается только при использовании --wait. На ВМ запускайте обе команды от имени root на хосте коннектора. В Kubernetes запускайте обе команды с рабочей станции, у которой есть kube-контекст управляемого кластера:

• Команде prepare требуется копия конфигурации коннектора (--config), kubectl port-forward к локальному API исполнителя и --output-dir с правом записи. Она сверяет Service name с исполнителем и не запускается, если не может до него дотянуться.
• Если на этом хосте нет указанных в конфигурации файлов учётных данных, instances create читает их из Secret’ов clicklink-hmac и clicklink-mtls и сообщает о каждом таком чтении. Добавьте --connector-namespace, если пространство имен коннектора отличается от clicklink. Такое резервное поведение предусмотрено только для instances create.

1. Подготовьте сервис

   Kubernetes

   CONNECTOR_NAMESPACE='clicklink'   # пространство имен коннектора, выбранное при инициализации
   kubectl -n "${CONNECTOR_NAMESPACE}" get configmap clicklink-connector-executor \
     -o jsonpath='{.data.config\.yaml}' > clicklink-config.yaml
   kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
   clicklink clctl executor prepare --config clicklink-config.yaml --output-dir ./clicklink-access
   

   Сохраните выходной каталог: в нем лежат body запроса на создание и запись с именем, которые читают instances create и любая повторная попытка.

   Linux VM

   sudo clicklink clctl executor prepare --config /etc/clicklink/config.yaml
   

   Команда выполняет четыре шага по порядку и останавливается на первой ошибке:

   1. Имя. Подбирает имя сервиса либо проверяет то, которое вы передали в --instance <name>. Сгенерированное имя записывается в <output-dir>/_prepare/<eks-cluster-name>.name и подхватывается следующим запуском, поэтому повторная попытка переиспользует бакеты и роль первого запуска. Флаг --new-name выбирает другое имя. Команда отклонит имя, которое исполнитель все еще удерживает, а также имя, в пространстве имен которого уже есть ClickHouse cluster.
   2. Хранилище. Создает бакеты для данных и резервных копий, а также роль IAM CH-S3-<name>-<region>-00-Role. Имена бакетов по умолчанию — <cluster>-clickhouse-data-<rand> и <cluster>-clickhouse-backup-<rand>; флаги --data-bucket и --backup-bucket переопределяют их. С --role-arn команда проверяет предоставленную вами роль и ничего не записывает в IAM.
   3. Grant и применение. На ВМ формирует bundle доступа исполнителя для пространства имен сервиса (ns-<name>), применяет его RBAC и регистрирует сервис в реестре исполнителя. В Kubernetes этот шаг пропускается: исполнитель работает от имени ServiceAccount своего пода и сам регистрирует сервис, когда поступает запрос на создание.
   4. Итоги. Генерирует пароль пользователя default и записывает body запроса на создание в <output-dir>/_prepare/<name>.create.json (режим 0600; в нем содержатся только хеши пароля). Выводит следующую команду в строке Next:.

   prepare выводит пароль пользователя default один раз, в stderr. Ни body запроса на создание, ни --output json его не содержат, а ClickHouse Cloud получает только его хеши. Сохраните пароль, прежде чем продолжать. Повторный запуск, обнаруживший body запроса на создание, оставляет уже записанные хеши и сообщает об этом.

   Передавайте --context <name>, если в вашем kubeconfig несколько контекстов; контекст должен указывать на EKS cluster, заданный в executor.cluster в конфигурации. --dry-run выполняет все шаги, ничего не создавая и не записывая. Шаг хеширования использует SHA-1, который Go отклоняет при GODEBUG=fips140=only; запускайте prepare на хосте без этой настройки.

2. Создайте сервис

   Kubernetes

   clicklink clctl instances create \
     --from-prepare ./clicklink-access/_prepare/<name>.create.json \
     --config clicklink-config.yaml \
     --wait
   

   Не закрывайте проброс порта, открытый на шаге prepare: именно через него --wait опрашивает исполнитель.

   Linux VM

   sudo clicklink clctl instances create \
     --from-prepare /etc/clicklink/access/executor/_prepare/<name>.create.json \
     --config /etc/clicklink/config.yaml \
     --wait
   

   Команда отправляет подготовленный body на конечную точку вашего connector, используя собственные credentials этого connector. Она выводит created <spoken-name> (state provisioning) и подсказку watch:. <spoken-name> — это имя, назначенное ClickHouse Cloud (например, amberaws-kq-42), а не подготовленное вами имя сервиса. В подсказке watch: и во всех командах clctl используется ваше имя сервиса.

   Повторный запуск с теми же входными данными безопасен. Ключ идемпотентности по умолчанию формируется на основе вашего окружения и имени сервиса, поэтому повторная отправка вернёт результат первого создания.

   --wait опрашивает локальный API исполнителя каждые 10 секунд, пока сервис не перейдёт в состояние running, но не дольше --wait-timeout (по умолчанию 30m). Команда сразу же завершается с ошибкой (той, что была записана), если исполнитель зафиксировал неудачное создание для этого имени либо сервис перешёл в состояние terminating, terminated или stale.

3. Проверить

   clicklink clctl instances get --name <name> --cluster <eks-cluster-name>
   

   Сервис готов, когда его status имеет значение running. Пользователю default назначается пароль, выведенный командой prepare. Значение --cluster также можно задать через переменную окружения CLCTL_CLUSTER.

​

Status

Исполнитель отвечает на запросы о status через свой локальный API, который слушает 127.0.0.1:9999 и не имеет собственной аутентификации. На ВМ выполняйте команды на хосте. В Kubernetes сначала настройте проброс порта и направляйте команды на него:

kubectl -n <connector-namespace> port-forward deployment/clicklink-connector-executor 9999:9999
clicklink clctl instances list --endpoint http://127.0.0.1:9999

clicklink clctl instances list выводит в формате JSON все сервисы, известные исполнителю. clicklink clctl instances get --name <name> --cluster <eks-cluster-name> выводит один сервис вместе с хранилищем, с которым он был создан. Исполнитель определяет status по ресурсу ClickHouseCluster сервиса (готовые реплики сервера против ожидаемых) и обновляет его каждые sync_interval (по умолчанию 30 секунд):

• provisioning: ни одна реплика сервера ещё не готова либо ресурс ClickHouseCluster ещё не создан
• running: готовы все ожидаемые реплики сервера
• degraded: готовы некоторые, но не все реплики сервера
• terminating: исполнитель удаляет сервис
• terminated: пространство имен сервиса удалено
• stale: сервис исчез из реестра исполнителя без операции удаления; --wait и teardown обрабатывают его так же, как terminated

Завершённый сервис остаётся в списке вместе со своим хранилищем до тех пор, пока teardown не удалит его облачные ресурсы.

Исполнитель фиксирует каждую команду, отправленную ему ClickHouse Cloud. clicklink clctl commands list выводит их с фильтрацией по --status (pending, running, completed, failed), --action (например, create_instance) или --cluster. clicklink clctl commands get <id> выводит одну команду с её стадией и результатом. У неуспешной команды поле result содержит ошибку: почему создание не завершилось успешно или какое обновление платформы ожидает вашего подтверждения.

​

Жизненный цикл сервиса

После создания сервиса ClickHouse Cloud управляет им через исполнитель. Он отправляет следующие команды:

• Масштабирование. ClickHouse Cloud задаёт фиксированное количество реплик, ограниченное настройкой ClickHouse Cloud (20 в конфигурации по умолчанию). Автомасштабирования нет.
• Остановка и запуск. При остановке серверы масштабируются до нуля, а Keeper сохраняется; при запуске количество реплик восстанавливается. Данные всё это время остаются в ваших бакетах.
• Перезапуск. Сервиса целиком, его Keeper или отдельного пода.
• Резервные копии. Резервное копирование запускает ClickHouse Cloud; копии попадают в ваш бакет для резервных копий, а при удалении резервной копии они удаляются оттуда.
• Обновления версии и изменения конфигурации. ClickHouse Cloud заново формирует определение сервиса с новой версией или настройкой. Оно поступает как команда create_instance, поэтому commands list --action create_instance показывает в том числе обновления. Исполнитель применяет его и ждёт, пока реплики снова не будут готовы.
• Удаление. Описано в разделе удаление сервиса.

Обновления версии и изменения конфигурации не требуют подтверждения со стороны клиента. ClickHouse Cloud применяет их к управляемому сервису так же, как масштабирование или перезапуск: повторно отправляет определение, а исполнитель приводит кластер в соответствие с ним.

Создание, масштабирование и запуск выполняются асинхронно. Исполнитель сообщает, что команда выполняется, сразу после применения определения и каждые 2 минуты отправляет отчёт о прогрессе. Об итоговом результате он сообщает, когда реплики сервера готовы. Если они не готовы в течение 2 часов, команда помечается как неуспешная; если реплики поднимутся позже, сервис возвращается в состояние running.

Подкоманды instances scale, instances patch и instances delete отправляют команды напрямую в локальный API исполнителя, минуя ClickHouse Cloud. Выполняйте их только по просьбе команды сопровождения аккаунта ClickHouse; в справочнике CLI описана каждая из них.

​

Support sessions для управляемого сервиса

Исполнитель подключает scraper к каждому создаваемому им сервису. Само средство диагностики он не разворачивает, поэтому support session не сможет запускать диагностику на управляемом сервисе, пока вы не сделаете это сами. Выполните provision один раз для каждого сервиса, указав пространство имен сервиса ns-<name>, — так же, как и для инстанса, зарегистрированного вами самостоятельно:

Kubernetes

printf '%s\n' "$CH_DEFAULT_PASSWORD" | clicklink clctl troubleshoot access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance <name> --instance-namespace ns-<name> \
  --server <kubernetes-api-server-url> --ch-admin-password-stdin \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace ns-<name>

$CH_DEFAULT_PASSWORD — это пароль пользователя default, который вывела команда prepare. Команда использует его для аутентификации, чтобы применить SQL-привилегии, и сама его не запрашивает. Затем добавьте пару Secret и ServiceAccount в troubleshooter.accessBundles и выполните helm upgrade, как показано в разделе добавление инстансов ClickHouse.

Linux VM

printf '%s\n' "$CH_DEFAULT_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <name> --instance-namespace ns-<name> \
  --server <kubernetes-api-server-url> --ch-admin-password-stdin

$CH_DEFAULT_PASSWORD — это пароль пользователя default, который вывела команда prepare.

Выдавайте привилегии пользователю ClickHouse через SQL, как показано выше. Пользователь, добавленный с помощью --ch-user-via cr, не сохранится: определение сервиса принадлежит ClickHouse Cloud и применяется повторно. При удалении сервиса исполнитель удаляет bundle средства диагностики на ВМ. В Kubernetes Secret и ServiceAccount из bundle сохраняются, пока вы не удалите их сами, — см. раздел удаление.

​

Удаление сервиса

Команды удаления на стороне клиента через конечную точку коннектора не предусмотрено: обратитесь к команде сопровождения аккаунта ClickHouse с просьбой удалить сервис. ClickHouse Cloud завершает его работу, а исполнитель удаляет рабочую нагрузку и её пространство имен (terminating, затем terminated). В AWS ничего не затрагивается: бакеты, их данные и роль IAM остаются на месте, пока вы не удалите их сами.

Как только сервис перейдёт в состояние terminated, удалите то, что создала команда prepare. Запустите teardown там же, где запускали prepare, и с теми же учётными данными AWS. В Kubernetes это означает ту же рабочую станцию, ту же копию конфигурации и тот же каталог вывода, а также открытый проброс порта до исполнителя:

Kubernetes

kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
clicklink clctl executor teardown --instance <name> --config clicklink-config.yaml --output-dir ./clicklink-access

Linux VM

sudo clicklink clctl executor teardown --instance <name>

Команда считывает запись исполнителя о сервисе: где находятся его данные и какая роль ему была назначена. Она удаляет роль IAM, созданную командой prepare, и заставляет исполнителя «забыть» сервис, тем самым освобождая имя. На ВМ она также удаляет относящиеся к сервису объекты RBAC уровня кластера, локальный bundle и запись в реестре.

По умолчанию данные и резервные копии сервиса сохраняются. У сохранённого бакета тег clicklink:deployed-name заменяется на clicklink:retained-from=<name>, поэтому повторно созданный сервис с тем же именем никогда его не унаследует, а в сводке указывается, где находятся данные. Чтобы удалить их, добавьте к той же команде --delete-data --delete-backups --yes.

--delete-data и --delete-backups очищают и удаляют указанные в них бакеты; восстановить их после этого невозможно. Прежде чем добавлять --yes, проверьте имена бакетов на шаге чтения записи.

Без --yes выполнение останавливается после шага чтения записи и выводит имена бакетов, которые были бы очищены. --dry-run считывает всё и ничего не записывает. Роль, переданная через --role-arn, или бакет, созданный не командой prepare, помечаются как сохраняемые и никогда не затрагиваются. Выполнение прерывается, если в пространстве имен сервиса всё ещё находится кластер ClickHouse. Сначала считывается вся информация и только потом происходит удаление, поэтому прерванный запуск ничего не меняет.

​

Когда connector офлайн

Работающие сервисы не зависят от исполнителя. ClickHouse Operator в вашем cluster поддерживает их работу, а отключившийся connector не прерывает то, что уже обслуживает запросы.

Пока ни один исполнитель не подключён, ClickHouse Cloud не может передать ему новую работу. Уже принятые команды создания, удаления или синхронизации платформы сохраняются и повторяются. Создание повторяется в течение 30 минут с момента последнего отчёта о прогрессе, удаление — в течение 2 часов, синхронизация платформы — до 10 попыток. После исчерпания этого лимита ваша конечная точка коннектора помечает команду как невыполненную. Все остальные команды жизненного цикла (scale, stop, start, restart, резервная копия, удаление резервной копии) отклоняются, а не ставятся в очередь. Команда создания или удаления, отправленная в тот момент, когда исполнитель не подключён, отклоняется точно так же; повторяются только уже принятые команды.

Команда, которую исполнитель уже принял, выполняется до конца; результат, о котором он не смог сообщить, отправляется при следующем соединении.

Для instances create требуется, чтобы ваша конечная точка коннектора была доступна с хоста, на котором она выполняется. Командам --wait, instances list, instances get и commands list нужен локальный API исполнителя, то есть сам исполнитель должен быть запущен. Срок действия токена одобрения платформы истекает по собственному таймеру, независимо от наличия связи; см. окно одобрения.