;
};
В режиме 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 во включенном состоянии.
Сама установка не меняется. Полный порядок действий описан в разделе [онбординг](/ru/products/bring-your-own-cloud/connector/onboarding#install-and-enroll), а флаги — в [CLI reference](/ru/products/bring-your-own-cloud/connector/reference/cli#init).
Создание сервиса
Создание сервисов через конечную точку коннектора включается отдельно для каждого окружения; перед началом уточните это у команды сопровождения аккаунта 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`.
```bash theme={null}
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` и любая повторная попытка.
```bash theme={null}
sudo clicklink clctl executor prepare --config /etc/clicklink/config.yaml
```
Команда выполняет четыре шага по порядку и останавливается на первой ошибке:
1. **Имя.** Подбирает имя сервиса либо проверяет то, которое вы передали в `--instance `. Сгенерированное имя записывается в `/_prepare/.name` и подхватывается следующим запуском, поэтому повторная попытка переиспользует бакеты и роль первого запуска. Флаг `--new-name` выбирает другое имя. Команда отклонит имя, которое исполнитель все еще удерживает, а также имя, в пространстве имен которого уже есть ClickHouse cluster.
2. **Хранилище.** Создает бакеты для данных и резервных копий, а также роль IAM `CH-S3---00-Role`. Имена бакетов по умолчанию — `-clickhouse-data-` и `-clickhouse-backup-`; флаги `--data-bucket` и `--backup-bucket` переопределяют их. С `--role-arn` команда проверяет предоставленную вами роль и ничего не записывает в IAM.
3. **Grant и применение.** На ВМ формирует bundle доступа исполнителя для пространства имен сервиса (`ns-`), применяет его RBAC и регистрирует сервис в реестре исполнителя. В Kubernetes этот шаг пропускается: исполнитель работает от имени ServiceAccount своего пода и сам регистрирует сервис, когда поступает запрос на создание.
4. **Итоги.** Генерирует пароль пользователя `default` и записывает body запроса на создание в `/_prepare/.create.json` (режим `0600`; в нем содержатся только хеши пароля). Выводит следующую команду в строке `Next:`.
`prepare` выводит пароль пользователя `default` один раз, в stderr. Ни body запроса на создание, ни `--output json` его не содержат, а ClickHouse Cloud получает только его хеши. Сохраните пароль, прежде чем продолжать. Повторный запуск, обнаруживший body запроса на создание, оставляет уже записанные хеши и сообщает об этом.
Передавайте `--context `, если в вашем kubeconfig несколько контекстов; контекст должен указывать на EKS cluster, заданный в `executor.cluster` в конфигурации. `--dry-run` выполняет все шаги, ничего не создавая и не записывая. Шаг хеширования использует SHA-1, который Go отклоняет при `GODEBUG=fips140=only`; запускайте `prepare` на хосте без этой настройки.
```bash theme={null}
clicklink clctl instances create \
--from-prepare ./clicklink-access/_prepare/.create.json \
--config clicklink-config.yaml \
--wait
```
Не закрывайте проброс порта, открытый на шаге `prepare`: именно через него `--wait` опрашивает исполнитель.
```bash theme={null}
sudo clicklink clctl instances create \
--from-prepare /etc/clicklink/access/executor/_prepare/.create.json \
--config /etc/clicklink/config.yaml \
--wait
```
Команда отправляет подготовленный body на конечную точку вашего connector, используя собственные credentials этого connector. Она выводит `created (state provisioning)` и подсказку `watch:`. `` — это имя, назначенное ClickHouse Cloud (например, `amberaws-kq-42`), а не подготовленное вами имя сервиса. В подсказке `watch:` и во всех командах `clctl` используется ваше имя сервиса.
Повторный запуск с теми же входными данными безопасен. Ключ идемпотентности по умолчанию формируется на основе вашего окружения и имени сервиса, поэтому повторная отправка вернёт результат первого создания.
`--wait` опрашивает локальный API исполнителя каждые 10 секунд, пока сервис не перейдёт в состояние `running`, но не дольше `--wait-timeout` (по умолчанию `30m`). Команда сразу же завершается с ошибкой (той, что была записана), если исполнитель зафиксировал неудачное создание для этого имени либо сервис перешёл в состояние `terminating`, `terminated` или `stale`.
```bash theme={null}
clicklink clctl instances get --name --cluster
```
Сервис готов, когда его `status` имеет значение `running`. Пользователю `default` назначается пароль, выведенный командой `prepare`. Значение `--cluster` также можно задать через переменную окружения `CLCTL_CLUSTER`.
Status
Исполнитель отвечает на запросы о status через свой локальный API, который слушает `127.0.0.1:9999` и не имеет собственной аутентификации. На ВМ выполняйте команды на хосте. В Kubernetes сначала настройте проброс порта и направляйте команды на него:
```bash theme={null}
kubectl -n 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 --cluster ` выводит один сервис вместе с хранилищем, с которым он был создан. Исполнитель определяет status по ресурсу `ClickHouseCluster` сервиса (готовые реплики сервера против ожидаемых) и обновляет его каждые `sync_interval` (по умолчанию 30 секунд):
* `provisioning`: ни одна реплика сервера ещё не готова либо ресурс `ClickHouseCluster` ещё не создан
* `running`: готовы все ожидаемые реплики сервера
* `degraded`: готовы некоторые, но не все реплики сервера
* `terminating`: исполнитель удаляет сервис
* `terminated`: пространство имен сервиса удалено
* `stale`: сервис исчез из реестра исполнителя без операции удаления; `--wait` и `teardown` обрабатывают его так же, как `terminated`
Завершённый сервис остаётся в списке вместе со своим хранилищем до тех пор, пока [teardown](#delete-a-service) не удалит его облачные ресурсы.
Исполнитель фиксирует каждую команду, отправленную ему ClickHouse Cloud. `clicklink clctl commands list` выводит их с фильтрацией по `--status` (`pending`, `running`, `completed`, `failed`), `--action` (например, `create_instance`) или `--cluster`. `clicklink clctl commands get ` выводит одну команду с её стадией и результатом. У неуспешной команды поле `result` содержит ошибку: почему создание не завершилось успешно или какое [обновление платформы](/ru/products/bring-your-own-cloud/connector/platform-updates) ожидает вашего подтверждения.
Жизненный цикл сервиса
После создания сервиса ClickHouse Cloud управляет им через исполнитель. Он отправляет следующие команды:
* **Масштабирование.** ClickHouse Cloud задаёт фиксированное количество реплик, ограниченное настройкой ClickHouse Cloud (20 в конфигурации по умолчанию). Автомасштабирования нет.
* **Остановка и запуск.** При остановке серверы масштабируются до нуля, а Keeper сохраняется; при запуске количество реплик восстанавливается. Данные всё это время остаются в ваших бакетах.
* **Перезапуск.** Сервиса целиком, его Keeper или отдельного пода.
* **Резервные копии.** Резервное копирование запускает ClickHouse Cloud; копии попадают в ваш бакет для резервных копий, а при удалении резервной копии они удаляются оттуда.
* **Обновления версии и изменения конфигурации.** ClickHouse Cloud заново формирует определение сервиса с новой версией или настройкой. Оно поступает как команда `create_instance`, поэтому `commands list --action create_instance` показывает в том числе обновления. Исполнитель применяет его и ждёт, пока реплики снова не будут готовы.
* **Удаление.** Описано в разделе [удаление сервиса](#delete-a-service).
Обновления версии и изменения конфигурации не требуют подтверждения со стороны клиента. ClickHouse Cloud применяет их к управляемому сервису так же, как масштабирование или перезапуск: повторно отправляет определение, а исполнитель приводит кластер в соответствие с ним.
Создание, масштабирование и запуск выполняются асинхронно. Исполнитель сообщает, что команда выполняется, сразу после применения определения и каждые 2 минуты отправляет отчёт о прогрессе. Об итоговом результате он сообщает, когда реплики сервера готовы. Если они не готовы в течение 2 часов, команда помечается как неуспешная; если реплики поднимутся позже, сервис возвращается в состояние `running`.
Подкоманды `instances scale`, `instances patch` и `instances delete` отправляют команды напрямую в локальный API исполнителя, минуя ClickHouse Cloud. Выполняйте их только по просьбе команды сопровождения аккаунта ClickHouse; в [справочнике CLI](/ru/products/bring-your-own-cloud/connector/reference/cli#instances-scale) описана каждая из них.
Support sessions для управляемого сервиса
Исполнитель подключает scraper к каждому создаваемому им сервису. Само средство диагностики он не разворачивает, поэтому [support session](/ru/products/bring-your-own-cloud/connector/support-sessions) не сможет запускать диагностику на управляемом сервисе, пока вы не сделаете это сами. Выполните provision один раз для каждого сервиса, указав пространство имен сервиса `ns-`, — так же, как и для инстанса, зарегистрированного вами самостоятельно:
```bash theme={null}
printf '%s\n' "$CH_DEFAULT_PASSWORD" | clicklink clctl troubleshoot access provision --target helm \
--target-namespace "${CONNECTOR_NAMESPACE}" \
--instance --instance-namespace ns- \
--server --ch-admin-password-stdin \
--apply-ch-grants --ch-pod --ch-pod-namespace ns-
```
`$CH_DEFAULT_PASSWORD` — это пароль пользователя `default`, который вывела команда `prepare`. Команда использует его для аутентификации, чтобы применить SQL-привилегии, и сама его не запрашивает. Затем добавьте пару Secret и ServiceAccount в `troubleshooter.accessBundles` и выполните `helm upgrade`, как показано в разделе [добавление инстансов ClickHouse](/ru/products/bring-your-own-cloud/connector/configuration#clickhouse-instances).
```bash theme={null}
printf '%s\n' "$CH_DEFAULT_PASSWORD" | sudo clicklink clctl troubleshoot access provision --provider local \
--instance --instance-namespace ns- \
--server --ch-admin-password-stdin
```
`$CH_DEFAULT_PASSWORD` — это пароль пользователя `default`, который вывела команда `prepare`.
Выдавайте привилегии пользователю ClickHouse через SQL, как показано выше. Пользователь, добавленный с помощью `--ch-user-via cr`, не сохранится: определение сервиса принадлежит ClickHouse Cloud и применяется повторно. При удалении сервиса исполнитель удаляет bundle средства диагностики на ВМ. В Kubernetes Secret и ServiceAccount из bundle сохраняются, пока вы не удалите их сами, — см. раздел [удаление](/ru/products/bring-your-own-cloud/connector/operations#uninstall-kubernetes).
Удаление сервиса
Команды удаления на стороне клиента через конечную точку коннектора не предусмотрено: обратитесь к команде сопровождения аккаунта ClickHouse с просьбой удалить сервис. ClickHouse Cloud завершает его работу, а исполнитель удаляет рабочую нагрузку и её пространство имен (`terminating`, затем `terminated`). В AWS ничего не затрагивается: бакеты, их данные и роль IAM остаются на месте, пока вы не удалите их сами.
Как только сервис перейдёт в состояние `terminated`, удалите то, что создала команда `prepare`. Запустите `teardown` там же, где запускали `prepare`, и с теми же учётными данными AWS. В Kubernetes это означает ту же рабочую станцию, ту же копию конфигурации и тот же каталог вывода, а также открытый проброс порта до исполнителя:
```bash theme={null}
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
clicklink clctl executor teardown --instance --config clicklink-config.yaml --output-dir ./clicklink-access
```
```bash theme={null}
sudo clicklink clctl executor teardown --instance
```
Команда считывает запись исполнителя о сервисе: где находятся его данные и какая роль ему была назначена. Она удаляет роль IAM, созданную командой `prepare`, и заставляет исполнителя «забыть» сервис, тем самым освобождая имя. На ВМ она также удаляет относящиеся к сервису объекты RBAC уровня кластера, локальный bundle и запись в реестре.
По умолчанию данные и резервные копии сервиса сохраняются. У сохранённого бакета тег `clicklink:deployed-name` заменяется на `clicklink:retained-from=`, поэтому повторно созданный сервис с тем же именем никогда его не унаследует, а в сводке указывается, где находятся данные. Чтобы удалить их, добавьте к той же команде `--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 исполнителя, то есть сам исполнитель должен быть запущен. Срок действия токена одобрения платформы истекает по собственному таймеру, независимо от наличия связи; см. [окно одобрения](/ru/products/bring-your-own-cloud/connector/platform-updates#the-approval-window).