Сеансы поддержки

Сеансы Support позволяют предоставить ClickHouse временный доступ для диагностики через коннектор ClickHouse. На этой странице рассказывается, что такое сеанс, как его включать и отключать, что могут делать операторы ClickHouse во время активного сеанса и как проверить все выполненные действия.

Что такое сеанс поддержки

Сеанс поддержки — это ограниченный по времени период, в течение которого troubleshooter принимает команды от инженеров поддержки ClickHouse. Когда сеанс не активен, troubleshooter отклоняет все команды, даже при наличии исходящего WebSocket-подключения. Другого пути выполнения нет: без сеанса ничего не запускается, и ClickHouse не может открыть его за вас. Плоскость управления ClickHouse никогда не подключается к вашей среде: она получает только то, что troubleshooter отправляет по исходящему каналу, причём этот канал передаёт команды лишь тогда, когда это разрешает состояние вашего сеанса.

Схема доверия для сеанса поддержки коннектора ClickHouse

Управлять сеансами можно двумя способами:

Шлюз сеансов — аутентифицированный API, встроенный в troubleshooter, с конечными точками enable, disable и status. Для каждого вызова шлюза требуется кратковременный OIDC ID-токен, адрес электронной почты в котором входит в ваш список разрешённых операторов.
Локальный файл сеанса в установках на ВМ с Linux, который записывается непосредственно на хосте с правами root.

Способ подключения к шлюзу зависит от целевой среды. Шлюз ВМ использует самоподписанный TLS-сертификат, отпечаток которого каждый оператор закрепляет вручную. Шлюз Kubernetes локально прослушивает HTTP на поде; доступ к нему осуществляется через kubectl port-forward (туннель использует TLS API server) или через Входной шлюз, который терминирует TLS с сертификатом, выданным CA.

Параметры сеанса, включая список разрешённых операторов, выбираются при выполнении clicklink clctl init.

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

Шлюз прослушивает порт 8443 на поде troubleshooter. Если у вас есть доступ к кластеру, подключитесь к нему через проброс порта; туннель использует TLS API-сервера Kubernetes:

CONNECTOR_NAMESPACE='clicklink'   # пространство имен коннектора, выбранное при инициализации
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward statefulset/clicklink-connector-troubleshooter 8443:8443

Затем в другом терминале включите сеанс:

clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 4h \
  --reason "<ticket reference>"

Таким же образом проверьте его состояние или завершите сеанс:

clicklink clctl troubleshoot session status --gateway-url http://localhost:8443
clicklink clctl troubleshoot session disable --gateway-url http://localhost:8443

OIDC-идентификатор вызывающей стороны должен быть в списке разрешенных операторов; неаутентифицированные или не включенные в список вызывающие стороны получают код 401 или 403, а попытка записывается в журнал. Если вы не хотите требовать учетные данные кластера, chart может предоставить доступ к шлюзу через опциональный входной шлюз, который терминирует TLS с сертификатом, выданным CA; см. configuration.

При наличии root-доступа к хосту управляйте сеансом напрямую. Состояние сохраняется в /var/lib/clicklink/session.json; демон и CLI атомарно читают и записывают этот файл:

sudo clicklink clctl troubleshoot session enable --duration 4h --reason "<ticket reference>"
sudo clicklink clctl troubleshoot session status
sudo clicklink clctl troubleshoot session disable

Шлюз также доступен на ВМ для вызывающих сторон без root-доступа. Он использует самоподписанный TLS, поэтому каждый пользователь сеанса один раз закрепляет отпечаток сертификата шлюза:

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-fingerprint>

Закрепленный отпечаток хранится в ~/.clicklink/clctl.yaml, а подключение завершается ошибкой, если предъявленный сертификат ему не соответствует.

Истечение срока действия сеанса

Сеансы завершаются автоматически. По умолчанию длительность составляет 4 часа; с помощью session enable --duration можно задать значение до 24 часов. По истечении срока действия сеанса или сразу после выполнения session disable troubleshooter перестаёт принимать команды. Отключение сеанса позволяет немедленно отозвать доступ: перезапуск и координация с ClickHouse не требуются.

Список разрешённых операторов

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

Kubernetes: задайте clctl.gateway.allowedOperators в файле наложения values. Список преобразуется в ConfigMap, который шлюз перечитывает каждые 30 секунд, поэтому изменение values и выполнение helm upgrade обновляют список разрешённых без перезапуска пода.
Linux ВМ: список разрешённых хранится в /etc/clicklink/allowed-operators.txt; файл записывается командой clicklink clctl init на основе указанных вами адресов электронной почты операторов.

Что операторы могут делать во время сеанса

Пока сеанс активен, инженеры поддержки ClickHouse могут выполнять следующие действия:

SQL-запросы только для чтения к вашим кластерам от имени пользователя pcm_troubleshooter, доступного только к явно указанному списку разрешенных таблиц. По умолчанию этот список включает таблицы ClickHouse system, такие как system.parts, system.merges, system.replicas, system.metrics и system.settings; доступ к system.query_log и system.text_log безусловно запрещен, поэтому история запросов никогда не покидает систему. В список по умолчанию также входит system.processes, столбец query которой показывает текст запросов, выполняющихся в данный момент; удалите ее из списка разрешенных таблиц сеанса (troubleshooter.allowedTables в оверлее Helm, troubleshooter.allowed_tables в конфигурационном файле VM), если текст выполняемых запросов не должен быть виден во время сеанса. У пользователя есть только привилегии SELECT для отдельных таблиц — без прав на запись, DDL или административных привилегий.
Доступ к данным Kubernetes только для чтения для каждого подготовленного развертывания (пакеты доступа привязаны к Kubernetes ServiceAccount в обеих целях установки): get, list и watch для подов, логов подов, сервисов, configmaps, events, PersistentVolumeClaims, deployments, statefulsets и replicasets в предоставленных пространствах имен. Без подготовленного пакета troubleshooter полностью отказывается выполнять команды типа kubectl.

RBAC troubleshooter не содержит разрешений exec, delete или patch, поэтому операторы не могут открыть оболочку в ваших подах или изменить что-либо через коннектор. Полный список привилегий и RBAC приведен в справочнике модели привилегий.

Журнал аудита

Каждый вызов шлюза и каждая команда, выполненная в ходе сеанса, добавляются в /var/log/clicklink/troubleshoot-audit.log как отдельный объект JSON в каждой строке (NDJSON). Поле submitted_by фиксирует идентификационные данные, связанные с каждой записью, и их значение зависит от происхождения записи: вызовы шлюза содержат адрес электронной почты, подтверждённый проверенным токеном, и никогда не используют значение, предоставленное клиентом; изменения сеанса, выполненные локально на ВМ, фиксируют пользователя хоста, вызвавшего команду; а команды, выполненные в ходе сеанса, фиксируют идентификационные данные организации, передаваемые по аутентифицированному каналу команд. Запись шлюза о включении сеанса выглядит так:

{
  "timestamp": "2026-06-22T22:30:00.123456789Z",
  "command_id": "11111111-2222-4333-8444-555555555555",
  "submitted_by": "operator@clickhouse.com",
  "command_type": "clctl.session.enable",
  "command_text": "ticket #1234",
  "instance_id": "",
  "status": "ok",
  "duration_ms": 42,
  "output_lines": 0,
  "remote_addr": "10.20.30.40"
}

Для записей жизненного цикла сеанса используются типы команд clctl.session.enable, clctl.session.disable и clctl.session.status; значение --reason команды enable сохраняется как command_text. Команды, выполняемые во время сеанса, записываются по той же схеме. status отличает успешные вызовы от попыток с результатами unauthorized, forbidden и rate_limited, поэтому отклонённые обращения также попадают в журнал.

На ВМ прочитайте файл напрямую с помощью clicklink clctl troubleshoot audit tail. В Kubernetes журнал находится внутри пода troubleshooter, а образ контейнера не содержит оболочки, поэтому через kubectl exec вызовите встроенный модуль чтения бинарного файла:

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" exec statefulset/clicklink-connector-troubleshooter -- \
  /clicklink clctl troubleshoot audit tail

Журнал аудита — это обычный файл в вашей среде; отправляйте его в свою SIEM, как и любой другой журнал хоста или контейнера.

Маскирование

Всё, что возвращает troubleshooter, маскируется перед тем, как покинуть вашу среду. Встроенные шаблоны охватывают IPv4- и IPv6-адреса, Bearer-токены, ключи доступа AWS, адреса электронной почты, JWT, закрытые SSH-ключи и учетные данные в строках подключения. Их можно расширить или переопределить в /etc/clicklink/redaction-patterns.yaml; запись с тем же именем, что и встроенный шаблон, заменяет его. Демон не запускается при недопустимом файле шаблонов, а clicklink clctl preflight проверяет этот файл, поэтому некорректная конфигурация маскирования вызывает явную ошибку, а не молча пропускает данные.

Архитектура: все подключения, устанавливаемые коннектором, и потоки данных в рамках сеансов.
Конфигурация: настройки шлюза, списка разрешённых адресов и маскирования данных.
FAQ: кратко об отзыве доступа, аудите и исходящем трафике данных.