Справочник CLI

Коннектор поставляется в виде единого бинарного файла 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`).

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

clicklink clctl init

Точки входа

Общие флаги

Флаги подписания (только для фазы 1)

Флаги только для Kubernetes

Флаги только для ВМ

Конфликты флагов

clicklink clctl preflight

clicklink clctl troubleshoot session

Общие флаги

включение сеанса

отключение сеанса

Статус сеанса

clicklink clctl troubleshoot gateway trust

clicklink clctl troubleshoot audit tail

Настройка доступа

Флаги каналов удалённого доступа

​clicklink clctl init

​Точки входа

​Общие флаги

​Флаги подписания (только для фазы 1)

​Флаги только для Kubernetes

​Флаги только для ВМ

​Конфликты флагов

​clicklink clctl preflight

​clicklink clctl troubleshoot session

​Общие флаги

​включение сеанса

​отключение сеанса

​Статус сеанса

​clicklink clctl troubleshoot gateway trust

​clicklink clctl troubleshoot audit tail

​Настройка доступа

​Флаги каналов удалённого доступа

clicklink clctl init

Точки входа

Общие флаги

Флаги подписания (только для фазы 1)

Флаги только для Kubernetes

Флаги только для ВМ

Конфликты флагов

clicklink clctl preflight

clicklink clctl troubleshoot session

Общие флаги

включение сеанса

отключение сеанса

Статус сеанса

clicklink clctl troubleshoot gateway trust

clicklink clctl troubleshoot audit tail

Настройка доступа

Флаги каналов удалённого доступа