Skip to main content
На этой странице описан процесс от токена регистрации до работоспособного проверенного коннектора. Коннектор устанавливается на один из двух вариантов: кластер Kubernetes (Helm) или ВМ Linux (systemd). Регистрация по токену — стандартный процесс; если ваша среда не может напрямую обращаться к конечным точкам ClickHouse, см. раздел установки в изолированной от интернета среде и с зеркалированием.

​
Предварительные требования

Для любой установки:
  • Конечная точка коннектора и токен регистрации, предоставленные ClickHouse во время онбординга (см. шаг 1).
  • Исходящий доступ через порт 443 к https://<subdomain>.<connector-domain> и https://<subdomain>.enroll.<connector-domain>, а также к releases.clicklink.clickhouse.com и Amazon ECR Public во время установки. Если какой-либо из этих адресов недоступен, см. установки в изолированной от интернета среде и с зеркалированием.
  • Доступный нативный listener ClickHouse из среды, где запускается коннектор: защищенный (9440) или незашифрованный (9000); в Kubernetes определяется автоматически.
  • Административный доступ к ClickHouse для подготовки: пользователь default без пароля, пароль (запрашиваемый интерактивно или передаваемый через --ch-admin-password-stdin) либо экземпляр, управляемый оператором. В последнем случае подготовка переключается на внедрение CR и пароль не требуется.
  • cosign во всех средах, где скачиваются артефакты релиза. Установщик всегда проверяет контрольную сумму SHA-256, а при установленном cosign также проверяет подпись; если задано CLICKLINK_REQUIRE_COSIGN=1, без cosign установка не продолжится.
Для установок в Kubernetes (Helm):
  • Любой совместимый кластер Kubernetes.
  • Kubeconfig, позволяющий создавать и просматривать пространство имен коннектора, применять Secrets, выполнять exec в подах ClickHouse (подготовка запускает clickhouse-client внутри пода), создавать ServiceAccounts, Roles и RoleBindings, а также устанавливать chart.
  • Класс хранилища по умолчанию либо класс, указанный через --storage-class; troubleshooter хранит состояние в PersistentVolumeClaim.
  • Доступ для загрузки образов: узлы кластера должны иметь возможность скачать публичный образ из ECR или размещенное вами зеркало.
Для установок на ВМ с Linux (systemd):
  • Любой Linux-хост с systemd на amd64 или arm64. Сборки Linux работают в режиме FIPS.
  • Права root для установщика и init.
  • Свободные порты 8080, 8082 и 8084 (проверка работоспособности), а также 9090, 9092 и 9094 (метрики); также 8443, если включен шлюз сеансов поддержки.
  • Административный доступ к API-серверу Kubernetes для подготовки: через kubeconfig на хосте, с помощью --server и --ca-data или интерактивно. Пакеты доступа привязаны к Kubernetes ServiceAccounts на обеих целевых системах.
--skip-provision — единственный способ обойти требование Kubernetes, и он предназначен только для этапа подготовки: пропускает создание пользователя ClickHouse, а на ВМ — включение и проверку unit. Поэтому сам по себе он не запускает коннектор.

​
Установка и регистрация

1

Получите адрес конечной точки коннектора и токен регистрации

Во время онбординга ClickHouse предоставляет конечную точку коннектора и одноразовый токен для регистрации. Конечная точка имеет следующий вид:
Токен одноразовый и быстро истекает, поэтому выполните регистрацию вскоре после его получения. Обращайтесь с ним как с секретом: CLI считывает его из скрытого приглашения (или из первой строки stdin), но никогда не из аргументов командной строки, диска или журналов. Если срок действия токена истёк до того, как вы успели его использовать, обратитесь к представителю ClickHouse, работающему с вашим аккаунтом, чтобы получить новый.
2

Установите и проверьте CLI

Одна команда устанавливает проверенный бинарный файл clicklink: она определяет вашу платформу и архитектуру (macOS или Linux, amd64 или arm64), загружает текущий релиз, проверяет контрольную сумму SHA-256, а при установленном cosign — подпись релиза, и устанавливает бинарный файл в каталог из переменной PATH. Для установки в Kubernetes выполните её на любой рабочей станции с доступом к кластеру через kubeconfig:
Для установки на ВМ запустите тот же скрипт на хосте с параметром --host. После проверки загруженного файла он также создаёт системного пользователя clicklink, каталоги /etc/clicklink, /var/lib/clicklink и /var/log/clicklink, а также юниты systemd и создаёт стандартный файл /etc/clicklink/redaction-patterns.yaml (если он уже существует, файл сохраняется), поэтому на следующем шаге можно сразу перейти к регистрации:
Оба способа поддерживают параметр --version vX.Y.Z для фиксации версии, и повторный запуск любого из них безопасен: при установке на хост создаётся резервная копия предыдущего бинарного файла, а текущая конфигурация сохраняется. Чтобы проверить скрипт перед запуском или самостоятельно скачать и проверить архив tarball релиза, см. раздел ручная загрузка и проверка.
3

Зарегистрируйте и установите коннектор

Регистрация выполняется одной командой. Она активирует токен, настраивает доступ к ClickHouse, получает подписанный клиентский сертификат, устанавливает коннектор и проверяет его работу от начала до конца.
На рабочей станции выполните:
Вставьте токен регистрации в скрытом приглашении. Затем CLI запросит:
  • пространство имен коннектора (по умолчанию clicklink)
  • пространство имен, в котором работают экземпляры ClickHouse
  • сведения о подключении к инстансу, заполненные на основе обнаруженного сервиса ClickHouse
  • класс хранилища, только если в кластере не задан класс по умолчанию
  • параметры сеансов поддержки и, если они включены, список разрешенных адресов электронной почты операторов
  • пароль администратора ClickHouse, только если он необходим для подготовки SQL
Один запуск выполняет весь процесс: активирует токен (сохраняя пакет регистрации как handoff.yaml в рабочем каталоге), создает файл наложения значений Helm clicklink-values.yaml, создает пространство имен, применяет Secrets clicklink-hmac и clicklink-mtls, подготавливает пользователей ClickHouse только для чтения для каждого инстанса (автоматически выбирая предоставление прав SQL или внедрение CR для инстансов, управляемых оператором), генерирует закрытый ключ и CSR и передает клиентский сертификат на подпись ClickHouse, устанавливает Helm-релиз clicklink-connector с помощью встроенного клиента Helm (бинарный файл helm не требуется) и проверяет работоспособность.Для запусков без участия пользователя передавайте ответы на запросы с помощью флагов. Используйте сохраненный пакет как точку входа, поскольку при запуске не из терминала --enroll считывает токен регистрации из первой строки stdin и перехватит перенаправленный пароль:
Повторите --instance для каждого экземпляра ClickHouse. Чтобы отключить сеансы поддержки, передайте --no-gateway вместо --operators; эти два флага взаимоисключающие.
4

Проверьте успешное выполнение

init проверяет установку, прежде чем сообщить об успехе. В Kubernetes он до пяти минут опрашивает конечную точку /livez каждого включённого компонента и, если включён шлюз сеансов поддержки, дополнительно проверяет, что шлюз отвечает на неаутентифицированные проверки кодом 401. На ВМ он ожидает ответа от /livez каждого демона, а затем запускает полный набор предварительных проверок: конфигурации, файлов, конфликтов портов, доступности сети, подключения к ClickHouse, состояния юнита systemd, доступа к каждому компоненту, диска и шаблонов маскирования.Чтобы вручную проверить это в Kubernetes:
Все поды коннектора должны быть в состоянии Running и готовы к работе.Чтобы проверить это вручную на ВМ:
Она завершается с кодом 0, если все проверки успешно пройдены, и с кодом 2 при любой ошибке, выводя сведения о неудачных проверках.
5

Очистка

Пакет регистрации handoff.yaml (записываемый в рабочий каталог с правами 0600) позволяет выполнять повторные запуски и восстановление во время установки без второго токена. Он содержит API-секрет коннектора в открытом виде, поэтому после успешной проверки установки удалите его:
Работающий connector хранит собственную копию учетных данных, поэтому его работа никак не зависит от файла: обновления и изменения конфигурации не требуют этого файла, а если позднее вам снова понадобится init, запросите новый токен регистрации у команды ClickHouse, отвечающей за ваш аккаунт, и выполните init --enroll --force.

​
Установки в изолированной от интернета среде и с зеркалированием

Два независимых компонента можно передавать по отдельному каналу — в зависимости от доступности ресурсов из вашей среды. Передача bundle. Если вы не хотите активировать токен через интернет, ClickHouse может предоставить bundle для регистрации непосредственно во время онбординга; вместо --enroll выполните clicklink clctl init --handoff <bundle-file>. --handoff заменяет только активацию токена: подписание сертификата по-прежнему выполняется через конечную точку регистрации, поэтому используйте этот параметр отдельно, если эта конечная точка доступна там, где вы запускаете init. Подписание сертификата по отдельному каналу. Если конечная точка регистрации недоступна там, где вы запускаете init, добавьте --no-auto-sign: init подготовит всё необходимое и создаст clicklink.csr. Отправьте CSR в ClickHouse через команду сопровождения аккаунта ClickHouse, затем завершите установку, указав полученные сертификат и цепочку: sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt на ВМ либо полной командой завершения, которую выведет подготовленный запуск в Kubernetes (включая --target helm). Передаётся только CSR; закрытый ключ никогда не покидает вашу среду. В Kubernetes параметр --chart принимает имя chart, разрешаемое через --chart-repo, ссылку oci://, прямой URL, локальный архив или каталог, а значение --chart-version по умолчанию соответствует версии самого CLI, чтобы бинарный файл и chart поставлялись вместе. Чтобы использовать образы из собственного registry, скопируйте container image в зеркало и задайте image.repository в наложении values. Если на пути исходящего трафика connector получает сертификат от закрытого CA, передайте --api-private-ca, чтобы конечная точка API проверялась по цепочке CA из bundle для регистрации, а не по системному хранилищу доверенных сертификатов. Установщик также может работать через зеркало: разместите артефакты релиза и install.sh в собственном зеркале и укажите его с помощью CLICKLINK_MIRROR_URL.

​
Ручная загрузка и проверка

Если вы не хотите передавать установщик через конвейер, скачайте и проверьте релиз самостоятельно. Этот блок определит вашу платформу и архитектуру; запускайте его без изменений на macOS или Linux, с архитектурой amd64 или arm64:
Перед распаковкой проверьте подпись с помощью cosign:
На рабочей станции (при установке в Kubernetes) распакуйте tar-архив и установите бинарный файл:
На ВМ распакуйте tar-архив и выполните sudo ./install.sh из распакованного каталога; рядом с артефактами релиза будет выполнена та же установка на хост, что и с параметром --host.

​
Если что-то пошло не так

Повторно выполните ту же команду. init идемпотентна: повторные запуски приводят к тому же состоянию, сохраняют существующую конфигурацию и подготовленные файлы, а также пропускают уже завершённые этапы. Если сбой происходит в середине шага, CLI выводит точные команды восстановления для вашей ситуации, и их можно безопасно выполнять повторно. Если регистрация отклонена, токен либо уже был использован (повторно запустите команду с --handoff handoff.yaml, который существует до завершающего этапа очистки), либо недействителен или истёк (обратитесь в команду сопровождения аккаунта ClickHouse за новым токеном). Если регистрация завершается ошибкой передачи данных, токен не был израсходован — повторно выполните ту же команду. --force — это явный сброс, а не обычная повторная попытка: он перезаписывает сохранённую конфигурацию или наложение values, повторно генерирует ключ клиента и заменяет действующий сертификат клиента (409 от конечной точки подписания означает, что такой сертификат уже существует). UUID кластера коннектора сохраняется даже при использовании --force, поэтому повторно инициализированный коннектор сохраняет свою идентичность. Используйте его при ротации учётных данных или замене сертификата; полное описание модели повторного запуска и восстановления см. в разделе operations.
Последнее изменение 26 августа 2026 г.