> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Онбординг
> Установите коннектор ClickHouse и настройте его в Kubernetes или на ВМ с Linux
export const Image = ({img, alt, size = "lg", background}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
return ;
};
На этой странице описан процесс от токена регистрации до работоспособного проверенного коннектора. Коннектор устанавливается на один из двух вариантов: кластер Kubernetes (Helm) или ВМ Linux (systemd). Регистрация по токену — стандартный процесс; если ваша среда не может напрямую обращаться к конечным точкам ClickHouse, см. раздел [установки в изолированной от интернета среде и с зеркалированием](#air-gapped-and-mirrored-installs).
## Предварительные требования
Для любой установки:
* **Конечная точка коннектора и токен регистрации**, предоставленные ClickHouse во время онбординга (см. шаг 1).
* **Исходящий доступ через порт 443** к `https://.` и `https://.enroll.`, а также к `releases.clicklink.clickhouse.com` и Amazon ECR Public во время установки. Если какой-либо из этих адресов недоступен, см. [установки в изолированной от интернета среде и с зеркалированием](#air-gapped-and-mirrored-installs).
* **Доступный нативный 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. Поэтому сам по себе он не запускает коннектор.
## Установка и регистрация
Во время онбординга ClickHouse предоставляет конечную точку коннектора и одноразовый токен для регистрации. Конечная точка имеет следующий вид:
```text theme={null}
https://.
```
Токен одноразовый и быстро истекает, поэтому выполните регистрацию вскоре после его получения. Обращайтесь с ним как с секретом: CLI считывает его из скрытого приглашения (или из первой строки stdin), но никогда не из аргументов командной строки, диска или журналов. Если срок действия токена истёк до того, как вы успели его использовать, обратитесь к представителю ClickHouse, работающему с вашим аккаунтом, чтобы получить новый.
Одна команда устанавливает проверенный бинарный файл `clicklink`: она определяет вашу платформу и архитектуру (macOS или Linux, amd64 или arm64), загружает текущий релиз, проверяет контрольную сумму SHA-256, а при установленном cosign — подпись релиза, и устанавливает бинарный файл в каталог из переменной `PATH`. Для установки в Kubernetes выполните её на любой рабочей станции с доступом к кластеру через kubeconfig:
```bash theme={null}
curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | bash
```
Для установки на ВМ запустите тот же скрипт на хосте с параметром `--host`. После проверки загруженного файла он также создаёт системного пользователя `clicklink`, каталоги `/etc/clicklink`, `/var/lib/clicklink` и `/var/log/clicklink`, а также юниты systemd и создаёт стандартный файл `/etc/clicklink/redaction-patterns.yaml` (если он уже существует, файл сохраняется), поэтому на следующем шаге можно сразу перейти к регистрации:
```bash theme={null}
curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host
```
Оба способа поддерживают параметр `--version vX.Y.Z` для фиксации версии, и повторный запуск любого из них безопасен: при установке на хост создаётся резервная копия предыдущего бинарного файла, а текущая конфигурация сохраняется. Чтобы проверить скрипт перед запуском или самостоятельно скачать и проверить архив tarball релиза, см. раздел [ручная загрузка и проверка](#manual-download-and-verification).
Регистрация выполняется одной командой. Она активирует токен, настраивает доступ к ClickHouse, получает подписанный клиентский сертификат, устанавливает коннектор и проверяет его работу от начала до конца.
На рабочей станции выполните:
```bash theme={null}
clicklink clctl init --enroll https://. --target helm
```
Вставьте токен регистрации в скрытом приглашении. Затем 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 и перехватит перенаправленный пароль:
```bash theme={null}
clicklink clctl init --handoff handoff.yaml --target helm \
--instance name=,host=,port=9440,secure=true,database=default,namespace= \
--operators ',' \
--storage-class \
--ch-admin-password-stdin < admin-password.txt
```
Повторите `--instance` для каждого экземпляра ClickHouse. Чтобы отключить сеансы поддержки, передайте `--no-gateway` вместо `--operators`; эти два флага взаимоисключающие.
Установка с `--host` на предыдущем шаге уже развернула бинарный файл, системного пользователя `clicklink`, каталоги и модули systemd. Выполните регистрацию от имени root:
```bash theme={null}
sudo clicklink clctl init --enroll https://.
```
Вставьте токен регистрации в скрытом приглашении. Команда активирует токен (сохраняя пакет регистрации как `handoff.yaml`), записывает `/etc/clicklink/config.yaml`, устанавливает учетные данные API и цепочку CA, генерирует закрытый ключ и CSR и передает клиентский сертификат на подпись ClickHouse, подготавливает пользователей ClickHouse только для чтения для обоих демонов, включает и запускает службы `clicklink-scraper` и `clicklink-troubleshooter`, ожидает, пока каждая из них сообщит о готовности, и завершает работу запуском полного набора предварительных проверок.
`init` проверяет установку, прежде чем сообщить об успехе. В Kubernetes он до пяти минут опрашивает конечную точку `/livez` каждого включённого компонента и, если включён шлюз сеансов поддержки, дополнительно проверяет, что шлюз отвечает на неаутентифицированные проверки кодом `401`. На ВМ он ожидает ответа от `/livez` каждого демона, а затем запускает полный набор предварительных проверок: конфигурации, файлов, конфликтов портов, доступности сети, подключения к ClickHouse, состояния юнита systemd, доступа к каждому компоненту, диска и шаблонов маскирования.
Чтобы вручную проверить это в Kubernetes:
```bash theme={null}
CONNECTOR_NAMESPACE='clicklink' # the connector namespace you chose at init
kubectl get pods -n "${CONNECTOR_NAMESPACE}"
```
Все поды коннектора должны быть в состоянии `Running` и готовы к работе.
Чтобы проверить это вручную на ВМ:
```bash theme={null}
sudo clicklink clctl preflight
```
Она завершается с кодом `0`, если все проверки успешно пройдены, и с кодом `2` при любой ошибке, выводя сведения о неудачных проверках.
Пакет регистрации `handoff.yaml` (записываемый в рабочий каталог с правами `0600`) позволяет выполнять повторные запуски и восстановление во время установки без второго токена. Он содержит API-секрет коннектора в открытом виде, поэтому после успешной проверки установки удалите его:
```bash theme={null}
rm handoff.yaml # workstation (Kubernetes installs)
sudo rm handoff.yaml # VM host (init ran as root, so the file is root-owned)
```
Работающий connector хранит собственную копию учетных данных, поэтому его работа никак не зависит от файла: обновления и изменения конфигурации не требуют этого файла, а если позднее вам снова понадобится `init`, запросите новый токен регистрации у команды ClickHouse, отвечающей за ваш аккаунт, и выполните `init --enroll --force`.
## Установки в изолированной от интернета среде и с зеркалированием
Два независимых компонента можно передавать по отдельному каналу — в зависимости от доступности ресурсов из вашей среды.
**Передача bundle.** Если вы не хотите активировать токен через интернет, ClickHouse может предоставить bundle для регистрации непосредственно во время онбординга; вместо `--enroll` выполните `clicklink clctl init --handoff `. `--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:
```bash theme={null}
CLICKLINK_VERSION="$(curl -fsSL https://releases.clicklink.clickhouse.com/latest-version.txt)"
# Or pin a specific release: CLICKLINK_VERSION='v0.9.0'
CLICKLINK_TARBALL="clicklink-${CLICKLINK_VERSION}-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/').tar.gz"
for suffix in '' .sha256 .sig .crt; do
curl -fsSLO "https://releases.clicklink.clickhouse.com/${CLICKLINK_TARBALL}${suffix}"
done
if command -v sha256sum >/dev/null; then
sha256sum -c "${CLICKLINK_TARBALL}.sha256"
else
shasum -a 256 -c "${CLICKLINK_TARBALL}.sha256"
fi
```
Перед распаковкой проверьте подпись с помощью cosign:
```bash theme={null}
cosign verify-blob \
--certificate "${CLICKLINK_TARBALL}.crt" \
--signature "${CLICKLINK_TARBALL}.sig" \
--certificate-identity-regexp "^https://github\.com/ClickHouse/data-plane-clicklink/\.github/workflows/release\.yaml@refs/tags/v" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"${CLICKLINK_TARBALL}"
```
На рабочей станции (при установке в Kubernetes) распакуйте tar-архив и установите бинарный файл:
```bash theme={null}
tar -xzf "${CLICKLINK_TARBALL}"
sudo install -m 0755 clicklink /usr/local/bin/clicklink
```
На ВМ распакуйте tar-архив и выполните `sudo ./install.sh` из распакованного каталога; рядом с артефактами релиза будет выполнена та же установка на хост, что и с параметром `--host`.
## Если что-то пошло не так
Повторно выполните ту же команду. `init` идемпотентна: повторные запуски приводят к тому же состоянию, сохраняют существующую конфигурацию и подготовленные файлы, а также пропускают уже завершённые этапы. Если сбой происходит в середине шага, CLI выводит точные команды восстановления для вашей ситуации, и их можно безопасно выполнять повторно.
Если регистрация отклонена, токен либо уже был использован (повторно запустите команду с `--handoff handoff.yaml`, который существует до завершающего этапа очистки), либо недействителен или истёк (обратитесь в команду сопровождения аккаунта ClickHouse за новым токеном). Если регистрация завершается ошибкой передачи данных, токен не был израсходован — повторно выполните ту же команду.
`--force` — это явный сброс, а не обычная повторная попытка: он перезаписывает сохранённую конфигурацию или наложение values, повторно генерирует ключ клиента и заменяет действующий сертификат клиента (`409` от конечной точки подписания означает, что такой сертификат уже существует). UUID кластера коннектора сохраняется даже при использовании `--force`, поэтому повторно инициализированный коннектор сохраняет свою идентичность. Используйте его при ротации учётных данных или замене сертификата; полное описание модели повторного запуска и восстановления см. в разделе [operations](/docs/ru/products/bring-your-own-cloud/connector/operations).