Set up docs MCPКоннектор поставляется в виде единого бинарного файла clicklink; команды запускаются через clicklink clctl. На этой странице описаны команды для установки и повседневной эксплуатации. Чтобы просмотреть полную справку, запустите любую команду с флагом --help. Флаги в поддеревьях troubleshoot и preflight также можно задавать через переменные окружения CLCTL_* (их имена указаны в справке для каждого флага) или в файле ~/.clicklink/clctl.yaml.
clicklink clctl init
Инициализирует коннектор с помощью токена регистрации, сохранённого пакета регистрации или подписанного сертификата, полученного по внешнему каналу. Один запуск подготавливает конфигурацию, настраивает доступ к ClickHouse, получает клиентский сертификат mTLS, выполняет развёртывание (Helm-чарт или модули systemd) и проверяет работоспособность. Повторный запуск безопасен: конфигурация и UUID кластера сохраняются, учётные данные атомарно перезаписываются, а существующий клиентский ключ используется повторно, если не указан --force. Полное описание процесса см. в разделе онбординг.
Точки входа
Требуется указать ровно одну из трёх точек входа; они взаимоисключающие.
| Флаг | Описание |
|---|---|
--enroll <url> |
Стандартный сценарий. Принимает конечную точку коннектора вашей организации (https://<subdomain>.<connector domain>), использует одноразовый токен регистрации (в терминале запрашивается без отображения вводимых символов, иначе считывается из первой строки stdin), записывает полученный пакет регистрации в handoff.yaml (режим 0600) и продолжает работу как --handoff handoff.yaml. Токен никогда не попадает в командную строку, на диск или в журналы. |
--handoff <path> |
Выполняет начальную настройку из сохранённого пакета регистрации. Повторные запуски и восстановление используют этот вариант после создания handoff.yaml. |
--signed-cert <path> |
Фаза 2 сценария для среды, изолированной от интернета: устанавливает клиентский certificate, подписанный вне канала связи, и завершает поэтапную установку. Параметр --chain <path> при необходимости заменяет вместе с ним цепочку CA. |
Общие флаги
| Флаг | Описание |
|---|---|
--target <shape> |
Вариант развертывания: systemd (по умолчанию; начальная настройка текущей ВМ) или helm (подготовка чарта clicklink-connector на рабочей станции с kubeconfig). |
--instance <spec> |
Экземпляр ClickHouse в виде разделенных запятыми пар key=value (name, host, port, secure, database, namespace, cluster); можно указывать несколько раз. Пропускает интерактивные запросы параметров экземпляра. |
--operators <emails> |
Разделенные запятыми адреса электронной почты операторов, которым разрешено открывать сеансы поддержки; включает шлюз сеансов и пропускает запрос. |
--no-gateway |
Отключает шлюз сеансов (без сеансов под управлением OIDC); пропускает запрос. На ВМ пользователь root хоста по-прежнему может управлять сеансами через локальный файл сеансов. |
--force |
Перезаписывает существующую конфигурацию или оверлей и повторно генерирует ключ клиента; также подтверждает замену еще действующего самоподписанного сертификата. UUID кластера сохраняется даже при использовании --force. |
--skip-provision |
Только подготовка: пропускает настройку доступа к ClickHouse для каждой роли (а для цели systemd — также включение и проверку юнита). Отдельно выполните clicklink clctl {scraper,troubleshoot} access provision. |
--ch-user-suffix <suffix> |
Необязательный суффикс для имен пользователей ClickHouse, создаваемых при подготовке (pcm_scraper становится pcm_scraper_<suffix>), чтобы второе развертывание коннектора могло совместно использовать экземпляр без конфликтов с пользователями первого. |
--ch-admin-password-stdin |
Считывает пароль администратора ClickHouse из stdin, когда он требуется для настройки SQL; при запуске из терминала вместо этого запрашивает пароль. |
Флаги подписания (только для фазы 1)
| Флаг | Описание |
|---|---|
--no-auto-sign |
Только для стадии: отключает автоматическое подписание CSR через конечную точку регистрации; предназначен для изолированных от интернета сред или сценариев подписания вне основного канала. |
--sign-endpoint <url> |
Переопределяет конечную точку подписания при регистрации (по умолчанию: формируется из конечной точки bundle добавлением DNS-метки enroll). Должен быть HTTPS URL. |
Флаги только для Kubernetes
Действуют только с --target helm.
| Флаг | Описание |
|---|---|
--target-namespace <ns> |
Пространство имен, в которое устанавливается чарт и создаются его Secrets (по умолчанию clicklink; запрашивается в терминале). |
--instance-namespace <ns> |
Пространство имен целевого экземпляра ClickHouse; используется для обнаружения нативного Service и в запросах, связанных с экземпляром. |
--storage-class <name> |
Класс хранилища для тома состояния troubleshooter (по умолчанию: класс хранилища кластера по умолчанию; запрашивается или обязателен, если в кластере такой класс не задан). |
--values <path> |
Путь к подготовленному наложению values (по умолчанию clicklink-values.yaml). |
--chart <ref> |
Чарт для развертывания: имя, разрешаемое через --chart-repo, или прямая ссылка oci://, URL либо локальная ссылка для зеркальных установок (по умолчанию clicklink-connector). |
--chart-repo <url> |
Репозиторий Helm, в котором разрешается имя чарта (по умолчанию https://releases.clicklink.clickhouse.com/charts); игнорируется для прямых ссылок в --chart. |
--chart-version <ver> |
Версия чарта для развертывания (по умолчанию: версия релиза этого бинарного файла). |
--ch-pod <ref> |
Под ClickHouse для этапов подготовки внутри пода; указывается именем или селектором меток k=v (по умолчанию: запущенный под, обслуживающий Service каждого экземпляра). |
--api-private-ca |
Конечная точка API использует сертификат, выданный CA пакета регистрации: вместо системных корневых сертификатов задается api.tls.caFile, указывающий на смонтированную цепочку CA. |
Флаги только для ВМ
Действуют только с --target systemd.
| Флаг | Описание |
|---|---|
--server <url> |
URL API-сервера Kubernetes, на который указывают пакеты доступа (по умолчанию: kubeconfig этого хоста; в противном случае будет предложено указать). |
--ca-data <base64> |
Base64 certificate-authority-data для --server (по умолчанию: kubeconfig этого хоста; в противном случае будет предложено указать). |
Конфликты флагов
--handoff,--enrollи--signed-certвзаимоисключающие; необходимо указать ровно один из них.- Флаги, предназначенные только для Kubernetes, не принимаются без
--target helm;--serverи--ca-dataне принимаются при--target helm(процесс Helm использует kubeconfig рабочей станции). --no-auto-signи--sign-endpointвзаимоисключающие; оба они, а также--api-private-ca, не принимаются вместе с--signed-cert.--operatorsи--no-gatewayвзаимоисключающие.- При
--skip-provisionне принимаются--ch-pod,--ch-user-suffix,--server,--ca-dataи--ch-admin-password-stdin(подготовка не выполняется).
clicklink clctl preflight
Запускает набор проверок коннектора, сгруппированных по категориям: config, files, network, clickhouse, systemd, access, disk, redaction. Каждая проверка возвращает один из статусов: pass, warn, fail или skip. Код выхода 0 означает, что все проверки успешно пройдены (предупреждения не блокируют выполнение); код выхода 2 означает, что одна или несколько проверок завершились ошибкой.
По умолчанию команда выполняется локально. При использовании --k8s-namespace она запускает бинарный файл в поде коннектора через kubectl exec, а отчет формирует локально (проверки systemd в подах всегда пропускаются). При использовании флагов удаленного канала вместо этого запускается установленный бинарный файл на удаленной ВМ.
| Флаг | Описание |
|---|---|
--config <path> |
Путь к файлу конфигурации коннектора; для удаленной цели — путь на соответствующем хосте. |
--output <fmt>, -o |
Формат вывода: text (по умолчанию) или json. |
--timeout <dur> |
Общий тайм-аут для всех проверок (по умолчанию 30s). |
--skip-systemd |
Пропускает проверки состояния модулей systemd (для хостов без systemd). |
--k8s-namespace <ns> |
Пространство имен чарта коннектора; запускает preflight внутри пода коннектора через kubectl exec. |
--k8s-component <name> |
Под коннектора, в котором выполняется запуск: scraper (по умолчанию) или troubleshooter. |
--k8s-pod <ref> |
Переопределение имени пода или селектора меток k=v (по умолчанию: метки компонента чарта). |
--k8s-container <name> |
Контейнер, в котором выполняется exec (по умолчанию: имя компонента). |
Флаги --k8s-* и флаги удаленного канала взаимоисключающие; выберите одну цель.
clicklink clctl troubleshoot session
Включает, отключает и проверяет сеанс поддержки — ограниченный по времени период, в течение которого troubleshooter принимает команды. Когда сеанс не активен, демон отклоняет все команды, даже если его WebSocket подключён. См. сеансы поддержки.
Команды работают в одном из двух режимов:
- Локальный файл (по умолчанию): считывают и записывают файл состояния сеанса на хосте, где запущен troubleshooter (по умолчанию
/var/lib/clicklink/session.json). - Шлюз: при использовании
--gateway-urlполучают токен OIDC ID и вместо этого обращаются к шлюзу сеансов troubleshooter с вашей рабочей станции.
Общие флаги
| Флаг | Описание |
|---|---|
--session-file <path> |
Путь к файлу состояния сеанса (по умолчанию /var/lib/clicklink/session.json). |
--config <path> |
Файл конфигурации коннектора; путь к файлу сеанса определяется по разделу troubleshooter. |
--gateway-url <url> |
Базовый URL шлюза сеанса. Если задан, команда получает Bearer-токен OIDC и обращается к шлюзу вместо локального файла состояния. Взаимоисключается с --session-file и --config. |
--gateway-audience <aud> |
Claim audience, с которым связан токен OIDC (по умолчанию clicklink-clctl, совпадает со значением шлюза по умолчанию). Указывайте его только при изменении audience шлюза. |
--gateway-issuer <url> |
Издатель OIDC, по которому шлюз выполняет проверку. Пустое значение выбирает путь Google; задайте его вместе с --oidc-client-id, чтобы запустить поток device-code для провайдера идентификации, отличного от Google. |
--oidc-client-id <id> |
ID публичного клиента OIDC для потока device-code, зарегистрированного в --gateway-issuer с включенным device grant. |
--token-file <path> |
Файл с заранее выпущенным ID-токеном OIDC, используемым как Bearer-токен и заменяющим другие способы получения токена. |
--gateway-ca <path> |
Набор CA для проверки сертификата шлюза (собственный сертификат). Если не задан, используется сертификат, закрепленный через gateway trust; самоподписанный шлюз без закрепленного сертификата отклоняется. |
включение сеанса
| Флаг | Описание |
|---|---|
--duration <dur> |
Время, в течение которого сеанс остаётся активным (по умолчанию 4h, максимум 24h). |
--reason <text> |
Необязательная текстовая причина, сохраняемая вместе с сеансом (до 256 символов). |
--user <name> |
Идентификатор оператора, сохраняемый в режиме локального файла; по умолчанию используется $SUDO_USER или $USER. В режиме шлюза источником истины служит адрес электронной почты, подтверждённый токеном. |
Включить сеанс не получится, если он уже активен: сначала отключите его или дождитесь истечения срока действия.
отключение сеанса
Немедленно деактивирует сеанс. Если активного сеанса нет, команда ничего не делает.
Статус сеанса
Показывает, активен ли сеанс, кто его включил и когда срок его действия истекает. --output (-o) задаёт формат вывода: table (по умолчанию) или json.
В Kubernetes подключитесь к шлюзу с помощью проброса порта:
kubectl -n <connector-namespace> port-forward \
statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
--gateway-url http://localhost:8443 \
--duration 1h --reason "support ticket 1234"clicklink clctl troubleshoot gateway trust
На ВМ шлюз сеанса использует самоподписанный TLS-сертификат. Эта команда сохраняет SHA-256-отпечаток сертификата в ~/.clicklink/clctl.yaml, чтобы команды session могли его проверять; если закреплённый отпечаток перестаёт совпадать, подключение блокируется. Доверие устанавливается одним из двух способов вне канала:
- С помощью флагов удалённого канала сертификат считывается непосредственно с ВМ по уже аутентифицированному каналу и закрепляется.
- Без канала передайте
--gateway-fingerprintсо значением SHA-256, записанным коннектором в журнал при создании сертификата; полученный сертификат закрепляется, только если он совпадает. Если не указывать этот флаг, отображается представленный отпечаток без закрепления.
| Флаг | Описание |
|---|---|
--gateway-url <url> |
Базовый URL шлюза, которому следует доверять (обязательно), например https://<vm-host>:8443. |
--gateway-fingerprint <sha256> |
Ожидаемый SHA-256-отпечаток из журнала коннектора, проверяемый перед закреплением. Двоеточия и регистр букв игнорируются. |
--remote-cert-file <path> |
Путь к сертификату шлюза на ВМ, считываемому через канал (по умолчанию /var/lib/clicklink/gateway/tls/server.crt). |
clicklink clctl troubleshoot gateway trust \
--gateway-url https://<vm-host>:8443 \
--gateway-fingerprint <sha256-from-connector-log>В Kubernetes закрепление не используется: предоставьте доступ к шлюзу через входной шлюз с сертификатом, выданным CA, или выполните проброс порта.
clicklink clctl troubleshoot audit tail
Выводит последние записи журнала аудита troubleshooter в формате JSON, по одной записи в строке для каждой команды, принятой или заблокированной демоном. Команда открывает журнал только для чтения и не изменяет его.
| Флаг | Описание |
|---|---|
--lines <n>, -n |
Количество выводимых последних записей (по умолчанию 50). |
--path <path> |
Путь к файлу журнала аудита (по умолчанию /var/log/clicklink/troubleshoot-audit.log). |
Образ среды выполнения коннектора не содержит оболочки, поэтому в Kubernetes эта команда является поддерживаемым средством чтения:
kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
/clicklink clctl troubleshoot audit tailНастройка доступа
clicklink clctl scraper access provision и clicklink clctl troubleshoot access provision создают пакет доступа для каждого экземпляра компонента, а с --force выполняют его ротацию: пользователя ClickHouse только для чтения и его привилегии, а также ServiceAccount Kubernetes, RBAC и токен, используемые компонентом. init выполняет это встроенно при установке; автономные команды используются для повторного запуска и ротации учетных данных.
| Флаг | Описание |
|---|---|
--instance <name> |
Имя экземпляра из конфигурации (обязательно). |
--server <url> |
URL API-сервера Kubernetes (обязательно). |
--ca-data <base64> |
CA‑сертификат кластера в формате Base64 для сгенерированного kubeconfig. |
--config <path> |
Файл конфигурации коннектора, из которого считывается экземпляр. |
--target <shape> |
systemd (по умолчанию: передать пакет на ВМ по удаленному каналу или сгенерировать локально с помощью --provider local) либо helm (создать Kubernetes Secret с пакетом для чарт). |
--target-namespace <ns> |
Пространство имен, в котором будет создан Secret с пакетом (обязательно с --target helm). |
--instance-namespace <ns> |
(--target helm) Пространство имен целевого экземпляра ClickHouse. |
--force |
Перезаписывает существующий пакет: используется при повторном запуске и ротации учетных данных. |
--secret-name <name> |
Переопределяет имя Secret с пакетом (по умолчанию clicklink-connector-<component>-access-<instance>). |
--output-dir <path> |
(--target helm или --provider local) Корневой каталог, в который будет помещен пакет. |
--ch-admin-user <name> |
Административный пользователь ClickHouse для применения привилегий (по умолчанию default). |
--ch-admin-password-stdin |
Считывает пароль администратора ClickHouse из stdin. |
--ch-user-suffix <suffix> |
Необязательный суффикс для подготовленного имени пользователя ClickHouse. |
--ch-user-via <mode> |
Способ подготовки пользователя ClickHouse: sql (по умолчанию; применяет сгенерированные привилегии от имени --ch-admin-user) или cr (записывает пользователя в custom resource экземпляра для экземпляров под управлением оператора без администратора, способного выполнять SQL). |
--apply-ch-grants |
(--target helm) Применяет сгенерированные привилегии внутри пода через kubectl exec, а не оставляет их для ручного применения. |
--ch-pod <ref>, --ch-pod-namespace <ns>, --ch-container <name> |
(--target helm с --apply-ch-grants или --ch-user-via cr) Выбирает под ClickHouse и контейнер для выполнения exec. |
--token-duration <dur> |
Срок действия токена ServiceAccount (по умолчанию 2160h, 90 дней; EKS ограничивает срок действия до 24 часов). |
--skip-restart |
Пропускает перезапуск компонента после подготовки доступа. |
--dry-run |
Выводит план и завершает работу; записи в Kubernetes, удаленные системы или ClickHouse не выполняются. |
Выполните ротацию учетных данных экземпляра для одного компонента:
clicklink clctl scraper access provision --target helm \
--target-namespace <connector-namespace> \
--instance <instance-name> --instance-namespace <clickhouse-namespace> \
--server <kubernetes-api-server-url> \
--apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
--forceФлаги каналов удалённого доступа
preflight, gateway trust и access provision принимают общий набор флагов для выбора способа подключения к целевой ВМ:
| Флаг | Описание |
|---|---|
--provider <name> |
Канал выполнения: ssh, aws (SSM) или gcp (IAP) для удалённых ВМ либо local при запуске на самой целевой ВМ. Если параметр не задан явно, он определяется по флагам соответствующего провайдера; local никогда не определяется автоматически. |
--ssh-host <host>, --ssh-user <user>, --ssh-port <port>, --ssh-identity-file <path> |
Сведения о подключении по SSH (--provider ssh); пользователь, порт и ключ по умолчанию берутся из вашей конфигурации SSH. |
--instance-id <id>, --region <region>, --profile <name> |
Экземпляр EC2, регион и профиль общей конфигурации для SSM (--provider aws). |
--project <id>, --zone <zone>, --instance-name <name> |
Проект, зона и экземпляр для туннелирования через IAP (--provider gcp). |