Справочник по конфигурации

На этой странице перечислены все параметры конфигурации, которые может потребоваться изменить, а также их значения по умолчанию и назначение: сначала файл конфигурации VM, затем значения Helm-чарта. Практические инструкции см. в руководстве по настройке.

Файл конфигурации VM

На виртуальной машине Linux коннектор читает файл /etc/clicklink/config.yaml, который создаётся командой clicklink clctl init и сохраняется при повторных запусках, если не указан параметр --force. Для ключей, отсутствующих в файле, используются приведённые ниже скомпилированные значения по умолчанию. Учётные данные в этом файле никогда не хранятся.

Ключи верхнего уровня

Ключ	По умолчанию	Значение
`pcm_infra_uuid`	создаётся командой `init`	Уникальный идентификатор этого развертывания коннектора, передаваемый с каждым upstream-запросом. Сохраняется при повторных запусках, включая `--force`. Не изменяйте.
`cloud`	определяется командой `init`	Метка облачного провайдера для этого хоста. Обязательна: при пустом значении демоны не запускаются.
`region`	определяется командой `init`	Метка региона для этого хоста. Обязательна: при пустом значении демоны не запускаются.
`api`		Блок подключения к upstream API; см. api.
`instances`	`{}`	Сопоставление экземпляров ClickHouse по имени; см. instances.
`scraper`		Блок демона scraper; см. scraper.
`troubleshooter`		Блок демона средства устранения неполадок; см. troubleshooter.
`observability`		Общий блок логирования и портов; см. observability.

api

Ключ	По умолчанию	Значение
`api.endpoint`	из пакета регистрации	Конечная точка API коннектора вашей организации: `https://<subdomain>.<connector domain>`.
`api.access_key_file`	`/etc/clicklink/access-key` (записывается `init`)	Файл с ключом доступа HMAC (режим 0600).
`api.secret_key_file`	`/etc/clicklink/secret-key` (записывается `init`)	Файл с секретным ключом HMAC (режим 0600).
`api.tls.enabled`	`true`	Предъявлять клиентский сертификат mTLS при подключении к API.
`api.tls.cert_file`	`/etc/clicklink/tls/client.crt`	Конечный клиентский сертификат mTLS; автоматически обновляется при продлении.
`api.tls.key_file`	`/etc/clicklink/tls/client.key`	Закрытый ключ клиента mTLS.
`api.tls.ca_file`	`/etc/clicklink/tls/ca.crt`	Дополнительная цепочка CA, добавляемая к системным корневым сертификатам для проверки сервера; `init` устанавливает сюда цепочку из пакета регистрации.
`api.retry.max_retries`	`5`	Количество повторных попыток для каждого API-запроса.
`api.retry.initial_delay`	`1s`	Задержка перед первой повторной попыткой.
`api.retry.max_delay`	`30s`	Максимальная задержка.
`api.retry.jitter_factor`	`0.25`	Случайное отклонение, добавляемое к задержкам.

инстансы

Каждая запись в instances.<name> описывает один целевой экземпляр ClickHouse, доступный по собственному протоколу:

Ключ	По умолчанию	Значение
`host`		Имя хоста или IP-адрес слушателя собственного протокола ClickHouse.
`port`		Порт собственного протокола (обычно `9440` с TLS, `9000` без шифрования).
`database`		База данных, используемая по умолчанию в сеансах коннектора.
`secure`	`false`	Использовать TLS для собственного соединения.
`max_open_conns`	не задано	Максимальное количество открытых соединений с этим инстансом.
`max_idle_conns`	не задано	Максимальное количество бездействующих соединений в пуле с этим инстансом.
`namespace`		Пространство имен Kubernetes инстанса, используемое для ограничения области чтения Kubernetes средством устранения неполадок.
`cluster`	`default`	Имя кластера ClickHouse, используемое для распределённых запросов.

scraper

Ключ	По умолчанию	Значение
`scraper.enabled`	`false` (`init` устанавливает `true`)	Запускает демон scraper.
`scraper.labels.platform`		Метка, добавляемая к каждой отправляемой метрике. Обязательна при включенном scraper.
`scraper.labels.env`		Метка окружения, например `production`. Обязательна.
`scraper.labels.region`		Метка региона. Обязательна.
`scraper.scrape.interval`	`2m`	Частота сбора данных с каждого инстанса.
`scraper.scrape.timeout`	`30s`	Тайм-аут запроса при одном сборе данных.
`scraper.scrape.tables`	см. ниже	Системные таблицы, из которых собираются данные для каждого инстанса. По умолчанию: `metric_log`, `asynchronous_metric_log`, `tables`, `warnings`, `server_settings`; `query_log` намеренно исключена, чтобы исходный текст SQL по умолчанию не покидал ваш периметр.
`scraper.buffer.path`	`/var/lib/clicklink/buffer`	Дисковый буфер для доставки как минимум один раз, пока конечная точка API недоступна.
`scraper.buffer.retention`	`168h`	Максимальный срок хранения буферизованных данных.
`scraper.buffer.max_size_mb`	`1024`	Максимальный размер буфера в МБ.
`scraper.sender.bandwidth_limit_mb`	`1.0`	Ограничение скорости загрузки в МБ/с.
`scraper.observability.health_port`	`8082`	Порт конечной точки проверки работоспособности scraper.
`scraper.observability.metrics_port`	`9092`	Порт метрик scraper.
`scraper.access_directory`	`/etc/clicklink/access/scraper`	Корневой каталог пакетов доступа scraper для каждого инстанса.

средство устранения неполадок

Ключ	По умолчанию	Значение
`troubleshooter.enabled`	`false` (`init` записывает `true`)	Запускать демон устранения неполадок.
`troubleshooter.poll_interval`	`5s`	Интервал опроса состояния сеанса.
`troubleshooter.command_timeout`	`60s`	Тайм-аут выполнения отдельной команды.
`troubleshooter.session_timeout`	`4h`	Стандартная продолжительность сеанса поддержки.
`troubleshooter.session_file_path`	`/var/lib/clicklink/session.json`	Файл состояния сеанса, общий для команд `clicklink clctl troubleshoot session`.
`troubleshooter.access_directory`	`/etc/clicklink/access/troubleshooter`	Корневой каталог пакетов доступа к экземплярам для средства устранения неполадок.
`troubleshooter.allowed_tables`	см. список разрешённых таблиц по умолчанию	Системные таблицы, из которых средство устранения неполадок может выполнять `SELECT`.
`troubleshooter.max_open_conns`	`5`	Ограничение числа открытых подключений к ClickHouse.
`troubleshooter.max_idle_conns`	`5`	Ограничение числа бездействующих подключений в пуле.
`troubleshooter.redaction.workers`	`4`	Воркеры для параллельного маскирования.
`troubleshooter.redaction.patterns_file`	`/etc/clicklink/redaction-patterns.yaml`	Редактируемые клиентом шаблоны маскирования; демон не запускается, если файл существует, но содержит недопустимые данные.
`troubleshooter.redaction.metrics_per_pattern`	`false`	Публиковать метрику-счётчик совпадений для каждого шаблона.
`troubleshooter.redaction.metrics_per_pattern_cap`	`50`	Ограничение числа уникальных имён шаблонов в метрике для каждого шаблона.
`troubleshooter.audit_log.path`	`/var/log/clicklink/troubleshoot-audit.log`	Журнал аудита в формате NDJSON, в который добавляются записи о каждой принятой или заблокированной команде.
`troubleshooter.audit_log.max_size_mb`	`128`	Ротировать активный файл журнала при превышении этого размера.
`troubleshooter.audit_log.max_files`	`5`	Количество сохраняемых ротированных файлов.
`troubleshooter.audit_log.max_age`	`168h`	Ротированные файлы старше этого срока удаляются.
`troubleshooter.gateway.enabled`	`false`	Запускать шлюз сеансов (сеансы поддержки через OIDC).
`troubleshooter.gateway.listen_addr`	`":8443"` (записывается `init`)	Адрес, на котором шлюз принимает подключения.
`troubleshooter.gateway.audience`	`clicklink-clctl` (записывается `init`)	Значение claim `audience`, обязательное для токенов операторов.
`troubleshooter.gateway.required_hosted_domain`	`""`	Необязательная проверка claim размещённого домена; токены из-за пределов домена отклоняются до проверки списка разрешений.
`troubleshooter.gateway.allowed_operators_file`	`/etc/clicklink/allowed-operators.txt` (записывается `init`)	Список разрешённых адресов электронной почты операторов, по одному в строке. Пустой список означает, что доступ закрыт.
`troubleshooter.gateway.rate_limit_per_minute`	`0` (отключено)	Ограничение частоты запросов для каждого оператора.
`troubleshooter.gateway.handler_timeout`	не задано	Тайм-аут обработки запроса на стороне сервера.
`troubleshooter.gateway.jwks_uri`	`""`	Конечная точка JWKS для провайдера идентификации, отличного от Google; при пустом значении используется Google.
`troubleshooter.gateway.issuer`	`""`	Значение claim `issuer`, которое необходимо закрепить при заданном `jwks_uri`.
`troubleshooter.gateway.tls.enabled`	`false` (`init` записывает `true` на VM при включённых сеансах поддержки)	Обслуживать шлюз по TLS с самоподписанным сертификатом, который демон выпускает при отсутствии сертификата; операторы закрепляют его отпечаток.
`troubleshooter.gateway.tls.cert_file`	`/var/lib/clicklink/gateway/tls/server.crt`	Сертификат шлюза.
`troubleshooter.gateway.tls.key_file`	`/var/lib/clicklink/gateway/tls/server.key`	Ключ шлюза.
`troubleshooter.gateway.tls.self_signed_dns_names`	`[]` (`init` предварительно заполняет хост)	SAN самоподписанного сертификата, который демон выпускает при его отсутствии; записи, распознаваемые как IP-адреса, становятся IP SAN.

обсервабилити

Ключ	По умолчанию	Описание
`observability.enabled`	`true`	Включает конечные точки проверки работоспособности и метрик.
`observability.log_level`	`info`	Уровень журналирования.
`observability.health_port`	`8080`	Базовый общий порт для проверки работоспособности.
`observability.metrics_port`	`9090`	Базовый общий порт метрик.

Блоки observability для отдельных компонентов переопределяют эту базовую конфигурацию: scraper использует 8082/9092, средство устранения неполадок — 8084/9094, а шлюз при включении прослушивает порт 8443.

Список разрешённых таблиц по умолчанию

Набор allowed_tables для средства устранения неполадок по умолчанию, совпадающий со значением по умолчанию troubleshooter.allowedTables в Helm-чарте:

system.build_options    system.clusters       system.columns
system.databases        system.tables         system.parts
system.parts_columns    system.parts_summary  system.detached_parts
system.processes        system.merges         system.mutations
system.replicas         system.replication_queue
system.metrics          system.events         system.asynchronous_metrics
system.disks            system.storage_policies
system.settings         system.settings_profiles
system.settings_profile_elements
system.functions        system.formats        system.table_engines
system.users            system.roles          system.grants

Значения Helm-чарта

В Kubernetes коннектор настраивается с помощью значений Helm-чарта clicklink-connector. Команда clicklink clctl init создаёт оверлей clicklink-values.yaml со всеми заполненными ниже значениями и сохраняет его при повторных запусках, если не указан параметр --force. В таблицах приведены значения Helm-чарта по умолчанию; стандартные параметры рабочих нагрузок (resources, nodeSelector, tolerations, affinity, serviceAccount.annotations, env, imagePullSecrets) доступны для каждого компонента, имеют пустые значения по умолчанию и не повторяются в каждой таблице.

кластер

Ключ	По умолчанию	Описание
`cluster.pcmInfraUuid`	`""` (заполняется `init`)	Уникальный идентификатор этого развертывания коннектора. Обязателен, если включен хотя бы один компонент; сохраняется при повторных запусках.
`cluster.region`	`""` (заполняется `init`)	Метка региона. Обязательно.
`cluster.cloud`	`""` (заполняется `init`)	Метка облачного провайдера. Обязательно.

image

Ключ	По умолчанию	Значение
`image.repository`	задано в опубликованном Helm-чарте	Репозиторий образа коннектора. Опубликованный Helm-чарт указывает на образ из публичного registry (мультиархитектурный, подписанный cosign); изменяйте его только при необходимости переопределения, например для mirror внутри периметра. Опубликованное значение можно посмотреть с помощью `helm show values`.
`image.tag`	`""` (соответствует `appVersion` Helm-чарта; `init` фиксирует версию CLI)	Тег образа.
`image.pullPolicy`	`IfNotPresent`	Политика загрузки образа Kubernetes.

api

Ключ	По умолчанию	Значение
`api.endpoint`	`""` (заполняется командой `init`)	Конечная точка API коннектора вашей организации, общая для обоих компонентов.
`api.tls.enabled`	`true`	Предъявлять клиентский сертификат mTLS при подключении к API.
`api.tls.caFile`	`""` (системные корневые сертификаты)	CA‑сертификат, добавляемый к системенным корневым сертификатам для проверки сервера. Укажите `/etc/clicklink/secrets/mtls/ca.crt` (или повторно запустите `init` с `--api-private-ca`), если конечная точка использует сертификат, подписанный частным CA.

secrets

Helm-чарт использует заранее созданные Secrets; init создаёт их перед установкой.

Ключ	По умолчанию	Значение
`secrets.mtlsSecretName`	`clicklink-mtls`	Secret типа `kubernetes.io/tls`, содержащий клиентский ключ mTLS, сертификат и цепочку CA.
`secrets.hmacSecretName`	`clicklink-hmac`	Непрозрачный Secret, содержащий `access-key` и `secret-key` для подписи запросов.
`secrets.mtlsWriteback`	`true`	Позволяет демонам записывать автоматически обновлённый конечный сертификат mTLS обратно в Secret mTLS. Предоставляет ServiceAccounts компонента привилегию `update` для этого единственного Secret с точным именем; без неё обновлённые сертификаты будет негде надёжно хранить.

scraper

Ключ	По умолчанию	Описание
`scraper.enabled`	`false` (`init` записывает `true`)	Развернуть scraper.
`scraper.replicaCount`	`1`	Реплики scraper.
`scraper.logLevel`	`info`	Уровень журналирования.
`scraper.ports.health`	`8082`	Порт конечной точки проверки работоспособности.
`scraper.ports.metrics`	`9092`	Порт метрик.
`scraper.instances`	`{}`	Map экземпляров ClickHouse с той же структурой, что и поля instances для VM.
`scraper.labels.platform`, `scraper.labels.env`, `scraper.labels.region`	`""`	Метки, добавляемые к каждой отправляемой метрике. При включенном scraper требуются все три; в противном случае Helm-чарт выдаёт ошибку при рендеринге.
`scraper.config`	`{}`	Передача ключей конфигурации `scraper`, не описанных выше (интервал scrape, буфер, отправитель и т. д.; та же схема, что и у блока scraper для VM).
`scraper.bufferSizeLimit`	`2Gi`	Максимальный размер временного volume scraper; scraper не хранит постоянное состояние на диске.
`scraper.rbac.extraSecretNames`	`[]`	Дополнительные имена Secret, для которых ServiceAccount scraper может выполнять `get`; допускаются только точные имена.
`scraper.accessBundles`	`{}`	Пакеты доступа для каждого экземпляра с ключом в виде имени экземпляра; каждый содержит `secretName` и `serviceAccountName`. Монтируются в `/etc/clicklink/access/scraper/<instance>/`; создаются командой `clicklink clctl scraper access provision --target helm`.

средство устранения неполадок

Ключ	По умолчанию	Значение
`troubleshooter.enabled`	`false` (`init` записывает `true`)	Развертывает средство устранения неполадок (StatefulSet с одной репликой).
`troubleshooter.logLevel`	`info`	Уровень логирования.
`troubleshooter.ports.health`	`8084`	Порт конечной точки проверки работоспособности.
`troubleshooter.ports.metrics`	`9094`	Порт метрик.
`troubleshooter.instances`	`{}`	Сопоставление экземпляров ClickHouse той же структуры, что и `scraper.instances`.
`troubleshooter.sessionTimeout`	`4h`	Длительность сеанса поддержки по умолчанию.
`troubleshooter.allowedTables`	стандартный список разрешенных таблиц	Таблицы, для которых пользователь ClickHouse средства устранения неполадок может выполнять `SELECT`. Этот список следует проверить с точки зрения безопасности и при необходимости изменить в вашем overlay; валидатор команд в любом случае применяет жестко заданный список запрещенных таблиц (`query_log`, `text_log`) независимо от указанного здесь списка.
`troubleshooter.auditLog.path`	`/var/log/clicklink/troubleshoot-audit.log`	Путь к журналу аудита на томе состояния, чтобы он сохранялся при перепланировании пода.
`troubleshooter.auditLog.maxSizeMb`	`128`	Выполнять ротацию при превышении этого размера.
`troubleshooter.auditLog.maxFiles`	`5`	Количество сохраняемых файлов после ротации.
`troubleshooter.auditLog.maxAge`	`168h`	Файлы после ротации старше этого срока удаляются.
`troubleshooter.redaction.workers`	`4`	Воркеры для параллельного маскирования.
`troubleshooter.redaction.patternsConfigMap`	`""`	Имя ConfigMap, ключ `redaction-patterns.yaml` которого содержит пользовательские шаблоны; Helm-чарт монтирует его в `/etc/clicklink/redaction-patterns.yaml`. Если значение пустое, применяются только встроенные шаблоны.
`troubleshooter.redaction.metricsPerPattern`	`false`	Отправлять метрику-счетчик совпадений для каждого шаблона.
`troubleshooter.redaction.metricsPerPatternCap`	`50`	Ограничение количества уникальных имен шаблонов в метрике по шаблонам.
`troubleshooter.config`	`{}`	Сквозная передача для любого ключа конфигурации `troubleshooter`, не описанного выше (интервал опроса, тайм-аут команды, ограничения подключений и т. д.).
`troubleshooter.rbac.extraSecretNames`	`[]`	Дополнительные имена Secret, для которых ServiceAccount средства устранения неполадок может выполнять `get`; допускаются только точные имена.
`troubleshooter.accessBundles`	`{}`	Пакеты доступа для каждого экземпляра той же структуры, что и `scraper.accessBundles`, монтируемые в `/etc/clicklink/access/troubleshooter/<instance>/`.

сохранение данных

Ключ	По умолчанию	Значение
`persistence.enabled`	`true`	Хранить каталог состояния средства устранения неполадок в PersistentVolumeClaim, чтобы состояние сеанса и журнал аудита сохранялись после перезапусков.
`persistence.storageClass`	`""` (по умолчанию для кластера)	Класс хранилища для заявки; `init` задаёт его на основе `--storage-class` или обнаруженного значения по умолчанию.
`persistence.size`	`5Gi`	Размер заявки.
`persistence.accessModes`	`[ReadWriteOnce]`	Режимы доступа заявки.

clctl.gateway

Шлюз сеансов для сеансов поддержки.

Ключ	По умолчанию	Значение
`clctl.gateway.enabled`	`false`	Запускать шлюз сеансов в средстве устранения неполадок.
`clctl.gateway.listenAddr`	`":8443"`	Адрес прослушивания, доступный только в поде.
`clctl.gateway.port`	`8443`	Порт контейнера, доступный через Service и входной шлюз средства устранения неполадок; соответствует порту `listenAddr`.
`clctl.gateway.audience`	`clicklink-clctl`	Утверждение audience, обязательное для токенов операторов. По умолчанию клиент сеансов использует то же значение, поэтому согласовывать их нужно только при изменении этого значения.
`clctl.gateway.requiredHostedDomain`	`""`	Необязательное утверждение hosted-domain, которое требуется шлюзу; токены не из вашего рабочего пространства отклоняются до проверки по списку разрешённых.
`clctl.gateway.allowedOperators`	`[]` (закрыт)	Список разрешённых адресов электронной почты операторов, отображаемый в ConfigMap; для ротации измените values и выполните `helm upgrade`.
`clctl.gateway.jwksUri`	`""`	Переопределение конечной точки JWKS для провайдеров идентификации, отличных от Google; при пустом значении используется конечная точка Google.
`clctl.gateway.issuer`	`""`	Утверждение issuer, значение которого необходимо закрепить. Требуется для любого фактического развертывания с заданным `jwksUri`.
`clctl.gateway.jwksEgressCIDRs`	`[]`	CIDR-диапазоны, к которым шлюзу необходим доступ для проверки JWKS при NetworkPolicy с запретом по умолчанию; пустое значение блокирует все проверки токенов.
`clctl.gateway.ingressFromSelector`	`{}`	Источник входящего трафика в NetworkPolicy для порта шлюза; пустое значение разрешает доступ из любого пода в пространстве имен Helm-чарта. При использовании входного шлюза укажите метку пространства имен его контроллера.
`clctl.gateway.rateLimit.requestsPerMinute`	`30`	Ограничение частоты запросов для каждого оператора.
`clctl.gateway.ingress.enabled`	`false`	Создать входной шлюз для шлюза. Если параметр отключен, операторы получают доступ к шлюзу через `kubectl port-forward`; контроллер входящего трафика и cert-manager не требуются.
`clctl.gateway.ingress.className`, `hosts`, `tls`, `annotations`	`""`, `[]`, `[]`, `{}`	Стандартные поля входного шлюза; `tls` ссылается на Secrets типа `kubernetes.io/tls`.

networkPolicy

Ключ	По умолчанию	Значение
`networkPolicy.enabled`	`true`	Создает NetworkPolicy с запретом всего трафика по умолчанию и списком разрешенных исходящих подключений. Для применения необходим CNI, поддерживающий принудительное применение политик.
`networkPolicy.allowEgressCIDRs`	`[]`	CIDR-диапазоны, в которых находится конечная точка API вашего коннектора. При CNI с принудительным применением политик у коннектора не будет исходящего трафика, пока это значение не задано.
`networkPolicy.allowEgressPorts`	`[443]`	Порты, открытые для `allowEgressCIDRs`; переопределите значение, если конечная точка использует нестандартный порт.
`networkPolicy.clickhouseNamespaces`	`[]`	Пространства имен сервисов ClickHouse, сопоставляемые по метке `kubernetes.io/metadata.name`. Пустое значение запрещает доступ к ClickHouse внутри кластера.
`networkPolicy.metricsScrapeSelector`	`{}`	Ограничивает входящий трафик для сбора метрик определенным пространством имен Prometheus по метке; пустое значение разрешает сбор метрик с любого пода в пространстве имен Helm-чарта.
`networkPolicy.kubeletProbeCIDRs`	`[]`	CIDR-диапазоны, из которых исходят проверки состояния Кубелета (IP-адреса узлов). Пустое значение разрешает входящий трафик для проверок из любого источника, что соответствует исключению для Кубелета в большинстве CNI; при строгой политике запрета по умолчанию укажите значение явно.
`networkPolicy.apiserverCIDRs`	`[]`	CIDR-диапазоны API-сервера Kubernetes. Пустое значение не создает правила исходящего трафика к API-серверу, и в управляемом Kubernetes демоны не смогут выполнить первый запрос токена, пока значение не будет задано.