Конфигурация

На этой странице описаны изменения конфигурации, которые чаще всего вносят после установки коннектора ClickHouse. Сведения о каждом ключе, его значении по умолчанию и назначении см. в справочнике по конфигурации; сведения о флагах командной строки — в справочнике CLI.

Для каждой цели установки коннектора предусмотрен свой вариант конфигурирования.

CONNECTOR_NAMESPACE='clicklink'   # пространство имен коннектора, выбранное при init
CHART_VERSION="$(helm get metadata clicklink-connector -n "${CONNECTOR_NAMESPACE}" | awk '/^VERSION:/{print $2}')"
helm upgrade clicklink-connector clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version "${CHART_VERSION}" \
  --namespace "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

helm upgrade clicklink-connector <same-chart-reference> \
  --version "${CHART_VERSION}" \
  -n "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml

sudo systemctl restart clicklink-scraper clicklink-troubleshooter
sudo clicklink clctl preflight

Каждая запись в разделе instances задает конечную точку нативного протокола ClickHouse, из которой коннектор читает данные: host, port, database, secure, а в Kubernetes также namespace и cluster. Учетные данные никогда не хранятся в конфигурации: каждый компонент получает пользователя ClickHouse с правами только для чтения из пакета доступа, создаваемого при подготовке.

scraper:
  instances:
    analytics:
      host: "clickhouse-analytics.clickhouse.svc.cluster.local"
      port: 9440
      database: "default"
      secure: true
      namespace: "clickhouse"
      cluster: "default"

troubleshooter:
  instances:
    analytics:
      host: "clickhouse-analytics.clickhouse.svc.cluster.local"
      port: 9440
      database: "default"
      secure: true
      namespace: "clickhouse"
      cluster: "default"

networkPolicy:
  clickhouseNamespaces:
    - "clickhouse"

CONNECTOR_NAMESPACE='clicklink'   # пространство имен коннектора, выбранное при инициализации
clicklink clctl scraper access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance analytics --instance-namespace clickhouse \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace clickhouse
clicklink clctl troubleshoot access provision --target helm \
  --target-namespace "${CONNECTOR_NAMESPACE}" \
  --instance analytics --instance-namespace clickhouse \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace clickhouse

scraper:
  accessBundles:
    analytics:
      secretName: clicklink-connector-scraper-access-analytics
      serviceAccountName: pcm-scraper-analytics

troubleshooter:
  accessBundles:
    analytics:
      secretName: clicklink-connector-troubleshooter-access-analytics
      serviceAccountName: pcm-troubleshooter-analytics

instances:
  analytics:
    host: "10.0.12.34"
    port: 9440
    database: "default"
    secure: true
    cluster: "default"

sudo clicklink clctl scraper access provision --provider local \
  --instance analytics --server <kubernetes-api-server-url>
sudo clicklink clctl troubleshoot access provision --provider local \
  --instance analytics --server <kubernetes-api-server-url>

Доступ к сеансам, управляемым шлюзом, ограничен списком разрешённых адресов электронной почты операторов: каждый запрос к шлюзу сеансов должен содержать краткоживущий OIDC ID-токен с подтверждённым адресом электронной почты из этого списка. Если список разрешённых пуст, шлюз закрыт, и никто не сможет открыть через него сеанс. На виртуальной машине пользователь root на хосте также может управлять сеансами напрямую через локальный файл сеансов; список разрешённых действует только для доступа через шлюз. Полную модель доверия см. в разделе сеансы поддержки.

clctl:
  gateway:
    enabled: true
    allowedOperators:
      - "oncall@example.com"
      - "dba@example.com"

oncall@example.com
dba@example.com

В Kubernetes chart включает NetworkPolicy, которая по умолчанию запрещает весь трафик и содержит список разрешённых направлений для исходящего трафика (networkPolicy.enabled: true). Объекты NetworkPolicy действуют только если ваш CNI обеспечивает их применение; при использовании CNI с поддержкой политик connector вообще не имеет исходящего трафика, пока в allowEgressCIDRs не будут указаны CIDR-диапазоны, соответствующие конечной точке API connector.

networkPolicy:
  enabled: true
  # CIDRs behind your connector API endpoint. Required under an enforcing CNI.
  allowEgressCIDRs:
    - "203.0.113.0/24"
  # Ports opened to allowEgressCIDRs.
  allowEgressPorts:
    - 443
  # Namespaces of your ClickHouse Services, matched by the
  # kubernetes.io/metadata.name label. Empty allows no in-cluster
  # ClickHouse access.
  clickhouseNamespaces:
    - "clickhouse"
  # Kubernetes API server CIDRs. On managed Kubernetes the API server sits
  # outside the cluster network, so it cannot be matched with a selector.
  apiserverCIDRs:
    - "172.16.0.0/28"

Два правила требуют особого внимания:

• apiserverCIDRs: если параметр пуст, чарт не создаёт правило исходящего трафика для API-сервера. В этом случае первый запрос демонов к токену Kubernetes завершается сетевой ошибкой — это означает, что параметр необходимо задать. В управляемом Kubernetes используйте CIDR конечной точки API-сервера кластера.
• clctl.gateway.jwksEgressCIDRs: если включён шлюз сеансов, средство устранения неполадок получает JWKS вашего провайдера идентификации для проверки токенов операторов. При политике запрета по умолчанию пустой параметр блокирует все проверки токенов:

clctl:
  gateway:
    jwksEgressCIDRs:
      - "199.36.153.8/30"

Пример — диапазон private.googleapis.com, охватывающий провайдер идентификации Google, доступный через Private Google Access; для любого другого провайдера идентификации укажите его диапазон (или CIDR прокси исходящего трафика перед ним).

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

Вывод Troubleshooter маскируется, прежде чем покинуть ваш периметр. Встроенные шаблоны охватывают ipv4, ipv6, bearer-token, aws-access-key, email, jwt, ssh-private-key и connection-string-credentials. Вы можете добавить собственные шаблоны в YAML-файл: они применяются первыми в порядке, указанном в файле, затем применяются встроенные шаблоны. Запись, использующая name встроенного шаблона, заменяет его.

Для каждого шаблона задаются name (обязательный, уникальный), regex (обязательный, синтаксис Go RE2), replace (по умолчанию [REDACTED], поддерживает ссылки на захваченные группы $1) и case_insensitive (по умолчанию false):

version: 1
patterns:
  - name: internal-hostname
    regex: '\b[a-z0-9-]+\.corp\.example\.com\b'
    replace: '[REDACTED:internal-host]'

  # Reusing a built-in name replaces the built-in pattern.
  - name: ipv4
    regex: '\b(?:\d{1,3}\.){3}\d{1,3}\b'
    replace: '[REDACTED:ip]'

На виртуальной машине файл находится по пути /etc/clicklink/redaction-patterns.yaml; установщик создаёт закомментированный файл по умолчанию и сохраняет вашу версию при обновлениях. В Kubernetes поместите YAML в ConfigMap с ключом redaction-patterns.yaml и задайте его имя в troubleshooter.redaction.patternsConfigMap; чарт монтирует его по тому же пути.

В опубликованном чарт для image.repository заранее указан публичный мультиархитектурный образ connector, подписанный cosign, поэтому для обычной установки не нужно задавать значения image. Чтобы просмотреть опубликованные значения по умолчанию:

CLICKLINK_VERSION="$(curl -fsSL https://releases.clicklink.clickhouse.com/latest-version.txt)"
helm show values clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version "${CLICKLINK_VERSION#v}"

Чтобы использовать собственный registry для Pull, переопределите repository в наложении:

image:
  repository: "registry.example.com/mirrors/clicklink"

Чтобы установить сам чарт из частного зеркала, init принимает --chart как имя чарт из --chart-repo либо как прямую ссылку oci://, URL, локальный архив или каталог. По умолчанию --chart-version соответствует версии самого CLI, поэтому бинарный файл и чарт обновляются вместе:

clicklink clctl init --handoff handoff.yaml --target helm \
  --chart oci://registry.example.com/charts/clicklink-connector

Если конечная точка API вашего коннектора находится за private CA в пределах вашего периметра, передайте --api-private-ca в init: он задаст api.tls.caFile: /etc/clicklink/secrets/mtls/ca.crt, и конечная точка будет проверяться по цепочке CA из вашего пакета регистрации, а не по системным корневым сертификатам. На виртуальной машине эквивалентом является api.tls.ca_file в /etc/clicklink/config.yaml; init устанавливает цепочку сертификатов из пакета в /etc/clicklink/tls/ca.crt и добавляет её в системное хранилище корневых сертификатов для проверки. Инструкции по регистрации и подписанию сертификатов в полностью изолированной от интернета среде см. в разделе онбординг.

persistence:
  enabled: true
  storageClass: "gp3"
  size: 5Gi

scraper:
  buffer:
    path: /var/lib/clicklink/buffer
    retention: 168h
    max_size_mb: 1024