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

В этом руководстве описаны параметры конфигурации для Helm-развертываний ClickStack. Базовую установку см. в основном руководстве по развертыванию с Helm.

Организация значений

В чарте v2.x значения сгруппированы по типам ресурсов Kubernetes в блоке hyperdx::

hyperdx:
  ports:          # Общие номера портов (Deployment, Service, ConfigMap, Ingress)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"

  config:         # → clickstack-config ConfigMap (несекретные переменные окружения)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (секретные переменные окружения)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # Спецификация K8s Deployment (образ, реплики, пробы и т.д.)
  service:        # Спецификация K8s Service (тип, аннотации)
  ingress:        # Спецификация K8s Ingress (хост, tls, аннотации)
  podDisruptionBudget:  # Спецификация K8s PDB
  tasks:          # Спецификации K8s CronJob

Все переменные окружения передаются через два ресурса с фиксированными именами, которые совместно используются развертыванием HyperDX и OTel collector через envFrom:

clickstack-config ConfigMap — заполняется из hyperdx.config
clickstack-secret Secret — заполняется из hyperdx.secrets

Отдельного ConfigMap для OTel collector больше нет. Обе рабочие нагрузки используют одни и те же источники.

Настройка API-ключа

После успешного развертывания ClickStack настройте API-ключ, чтобы включить сбор данных телеметрии:

Перейдите к своему экземпляру HyperDX через настроенный входной шлюз или конечную точку сервиса
Войдите в панель мониторинга HyperDX и перейдите в Team settings, чтобы создать или получить API-ключ
Обновите развертывание с помощью API-ключа, используя один из следующих методов:

Способ 1: Обновление с помощью helm upgrade и файла значений

Добавьте API-ключ в values.yaml:

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"

Затем обновите развертывание:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

Способ 2: обновление через Helm upgrade с флагом –set

helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"

Перезапустите поды, чтобы применить изменения

После обновления API-ключа перезапустите поды, чтобы они применили новую конфигурацию:

kubectl rollout restart deployment my-clickstack-clickstack-app

Управление секретами

Для работы с конфиденциальными данными, такими как ключи API или учетные данные базы данных, чарт v2.x предоставляет единый ресурс clickstack-secret, который заполняется из hyperdx.secrets.

Значения секретов по умолчанию

В чарте заданы значения по умолчанию для всех секретов. Переопределите их в values.yaml:

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-otel-password"
    CLICKHOUSE_APP_PASSWORD: "your-clickhouse-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"

Использование внешнего секрета

Для рабочих развертываний, где нужно хранить учетные данные отдельно от значений Helm, используйте внешний секрет Kubernetes:

# Создайте секрет
kubectl create secret generic my-clickstack-secrets \
  --from-literal=HYPERDX_API_KEY=my-secret-api-key \
  --from-literal=CLICKHOUSE_PASSWORD=my-ch-password \
  --from-literal=CLICKHOUSE_APP_PASSWORD=my-ch-app-password \
  --from-literal=MONGODB_PASSWORD=my-mongo-password

Затем укажите это в values:

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"

Настройка входного шлюза

Чтобы открыть доступ к интерфейсу и API HyperDX по доменному имени, включите входной шлюз в файле values.yaml.

Общие настройки входного шлюза

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Должен совпадать с хостом входного шлюза

  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"

Включение TLS (HTTPS)

Чтобы защитить развертывание с помощью HTTPS:

1. Создайте TLS-секрет с сертификатом и ключом:

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. Включите TLS в конфигурации входного шлюза:

hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

Пример конфигурации входного шлюза

Для справки: ниже показано, как выглядит сгенерированный ресурс входного шлюза:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

Распространенные проблемы с входным шлюзом

Настройка path и rewrite:

Для Next.js и других SPA всегда используйте путь с регулярным выражением и аннотацию rewrite, как показано выше
Не используйте просто path: / без rewrite, так как это нарушит раздачу статических ресурсов

Несоответствие frontendUrl и ingress.host:

Если они не совпадают, возможны проблемы с cookie, перенаправлениями и загрузкой ресурсов

Неправильная настройка TLS:

Убедитесь, что ваш TLS-секрет действителен и правильно указан во входном шлюзе
Браузеры могут блокировать небезопасный контент, если вы открываете приложение по HTTP при включенном TLS

Версия контроллера входного шлюза:

Некоторые возможности (например, пути с регулярными выражениями и rewrite) требуют новой версии nginx ingress controller
Проверьте версию с помощью:

kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

Входной шлюз для OTel collector

Если вам нужно открыть доступ к конечным точкам OTel collector (для трассировок, метрик и журналов) через входной шлюз, используйте конфигурацию additionalIngresses. Это полезно, если вы отправляете телеметрические данные из-за пределов кластера или используете для collector собственный домен.

hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls

Это создает отдельный ресурс входного шлюза для конечных точек OTEL collector
Вы можете использовать другой домен, настроить отдельные параметры TLS и применить пользовательские аннотации
Правило пути с регулярным выражением позволяет направлять все сигналы OTLP (трассировки, метрики, журналы) через одно правило

В качестве альтернативы вы можете использовать additionalManifests, чтобы определить полностью настраиваемые ресурсы входного шлюза, например AWS ALB Ingress.

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

OTEL Collector разворачивается с помощью официального Helm-чарта OpenTelemetry Collector как подчарт otel-collector:. Настройте его напрямую в разделе otel-collector: файла values:

otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule

Переменные окружения (конечная точка ClickHouse, URL-адрес OpAMP и т. д.) передаются через общие ресурсы ConfigMap clickstack-config и Secret clickstack-secret. Параметр extraEnvsFrom в дочернем чарте уже настроен на чтение из обоих.

См. OpenTelemetry Collector Helm chart, чтобы узнать обо всех доступных значениях дочернего чарта.

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

MongoDB управляется оператором MCK через пользовательский ресурс MongoDBCommunity. Раздел spec ресурса CR выводится без изменений из mongodb.spec:

mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi

Пароль MongoDB задаётся в hyperdx.secrets.MONGODB_PASSWORD. Все доступные поля CRD см. в документации MCK.

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

ClickHouse управляется через ClickHouse Operator с помощью пользовательских ресурсов ClickHouseCluster и KeeperCluster. Разделы spec обоих CR дословно берутся из values:

clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Учетные данные пользователя ClickHouse берутся из hyperdx.secrets (а не из clickhouse.config.users, как в версии v1.x). Полный список доступных полей CRD см. в руководстве по настройке ClickHouse Operator.

Устранение неполадок входного шлюза

Проверьте ресурс входного шлюза:

kubectl get ingress -A
kubectl describe ingress <ingress-name>

Проверьте журналы контроллера входного шлюза:

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

Проверьте URL-адреса тестовых ресурсов:

Используйте curl, чтобы убедиться, что статические ресурсы отдаются как JS, а не как HTML:

curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Должен вернуть Content-Type: application/javascript

Инструменты разработчика в браузере:

Проверьте вкладку Network на наличие ответов 404 или ресурсов, для которых вместо JS возвращается HTML
Ищите в консоли ошибки вроде Unexpected token < (это означает, что вместо JS был возвращён HTML)

Проверьте перезапись путей:

Убедитесь, что входной шлюз не удаляет части путей к ресурсам и не переписывает их неправильно

Очистите кэш браузера и CDN:

После внесения изменений очистите кэш браузера и кэш CDN/прокси, чтобы избежать загрузки устаревших ресурсов

Настройка значений

Вы можете настроить параметры с помощью флагов --set:

helm install my-clickstack clickstack/clickstack --set key=value

Либо создайте собственный values.yaml. Чтобы получить значения по умолчанию:

helm show values clickstack/clickstack > values.yaml

Примените собственные значения:

helm install my-clickstack clickstack/clickstack -f values.yaml

Следующие шаги

Варианты развертывания - Внешние системы и минимальные развертывания
Облачные развертывания - Конфигурации GKE, EKS и AKS
Руководство по обновлению - Миграция с v1.x на v2.x
Дополнительные манифесты - Пользовательские объекты Kubernetes
Основное руководство по Helm - Базовая установка
Конфигурация (v1.x) - Руководство по настройке v1.x