Руководство по обновлению Helm

В этом руководстве описана миграция с Helm-чарта ClickStack с inline-template (v1.x) на архитектуру на основе субчартов (v2.x). Это несовместимое изменение, при котором вручную созданные ресурсы Kubernetes заменяются на пользовательские ресурсы MongoDB и ClickHouse, управляемые операторами, а также используется официальный Helm-чарт OpenTelemetry Collector.

Несовместимое изменениеЧарт v2.x не обратно совместим с v1.x. Обновление через helm upgrade на месте не поддерживается. Мы рекомендуем выполнить новую установку параллельно с существующим развертыванием и перенести данные, вместо того чтобы пытаться обновить систему на месте.

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

Перед обновлением создайте резервную копию данных (MongoDB, ClickHouse PVCs)
Проверьте текущие переопределения в values.yaml — большинство ключей перемещены или переименованы

Установка в два этапа

Чарт v2.x предполагает установку в два этапа. Операторы (которые регистрируют CRD) должны быть установлены до основного чарта (который создаёт CR):

# Фаза 1: Установка операторов и CRD
helm install clickstack-operators clickstack/clickstack-operators

# Фаза 2: Установка ClickStack
helm install my-clickstack clickstack/clickstack

Удаляйте в обратном порядке:

helm uninstall my-clickstack
helm uninstall clickstack-operators

Постоянное хранение данных

PersistentVolumeClaims, созданные операторами MongoDB и ClickHouse, не удаляются командой helm uninstall. Это сделано намеренно, чтобы предотвратить случайную потерю данных. Чтобы удалить PVC после деинсталляции, см.:

документацию по MongoDB Kubernetes Operator

Класс хранилища

global.storageClassName и global.keepPVC были удалены. Теперь класс хранилища настраивается непосредственно в спецификации CR каждого оператора:

mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - spec:
              storageClassName: "fast-ssd"

clickhouse:
  keeper:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"
  cluster:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"

Что изменилось

Компонент	До (v1.x)	После (v2.x)
MongoDB	Встроенные Развертывание + Service + PVC	MongoDB Kubernetes Operator (MCK), управляющий CR `MongoDBCommunity`
ClickHouse	Встроенные Развертывание + Service + ConfigMap + PVC	ClickHouse Operator, управляющий CR `ClickHouseCluster` и `KeeperCluster`
OTEL Collector	Встроенные Развертывание + Service (блок `otel.*`)	Официальный Helm-чарт OpenTelemetry Collector (субчарт `otel-collector:`)
Значения HyperDX	Плоские ключи в `hyperdx.*`, а также `tasks:` верхнего уровня и `appUrl`	Реорганизованы по типам ресурсов K8s в `hyperdx.*` (см. ниже)
hdx-oss-v2	Устаревший legacy-чарт	Полностью удалён

Реорганизация значений HyperDX

Блок hyperdx: теперь сгруппирован по типам ресурсов Kubernetes:

hyperdx:
  ports:          # Общие номера портов (Развертывание, Service, ConfigMap, Входной шлюз)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"   # Заменяет удалённый appUrl

  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 Развертывание (образ, реплики, пробы и т.д.)
  service:        # Спецификация K8s Service (тип, аннотации)
  ingress:        # Спецификация K8s Входной шлюз (хост, tls, аннотации)
  podDisruptionBudget:  # Спецификация K8s PDB
  tasks:          # Спецификации K8s CronJob (ранее tasks: на верхнем уровне)

Основные изменения

До (v1.x)	После (v2.x)
`appUrl`	Удалено. Используйте `hyperdx.frontendUrl` (по умолчанию — `http://localhost:3000`)
`tasks.*` (на верхнем уровне)	`hyperdx.tasks.*`
`mongodb.password`	`hyperdx.secrets.MONGODB_PASSWORD`
`clickhouse.config.users.appUserPassword`	`hyperdx.secrets.CLICKHOUSE_APP_PASSWORD`
`clickhouse.config.users.otelUserPassword`	`hyperdx.secrets.CLICKHOUSE_PASSWORD`
Переопределения env для `otel.*`	`hyperdx.config.` (несекретные данные) и `hyperdx.secrets.` (секретные данные)

Единые ConfigMap и Secret

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

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

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

Миграция MongoDB

Удалённые значения

Следующих значений mongodb.* больше нет:

# УДАЛЕНО — не использовать
mongodb:
  image: "..."
  port: 27017
  strategy: ...
  nodeSelector: {}
  tolerations: []
  livenessProbe: ...
  readinessProbe: ...
  persistence:
    enabled: true
    dataSize: 10Gi

Новые значения

Теперь MongoDB управляется оператором MCK через пользовательский ресурс MongoDBCommunity. Спецификация CR без изменений берётся из mongodb.spec:

mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    users:
      - name: hyperdx
        db: hyperdx
        passwordSecretRef:
          name: '{{ include "clickstack.mongodb.fullname" . }}-password'
        roles:
          - name: dbOwner
            db: hyperdx
          - name: clusterMonitor
            db: admin
        scramCredentialsSecretName: '{{ include "clickstack.mongodb.fullname" . }}-scram'
    additionalMongodConfig:
      storage.wiredTiger.engineConfig.journalCompressor: zlib

Пароль MongoDB задаётся в hyperdx.secrets.MONGODB_PASSWORD (а не в mongodb.password). На него автоматически ссылаются Secret с паролем и шаблон mongoUri. Чтобы добавить постоянное хранение данных, добавьте блок statefulSet в mongodb.spec:

mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi

Субчарт оператора MCK настраивается в разделе mongodb-operator: (а не mongodb-kubernetes:). Все доступные поля CRD см. в документации MCK.

Миграция в ClickHouse

Удалённые значения

Следующих значений clickhouse.* больше не существует:

# УДАЛЕНО — не использовать
clickhouse:
  image: "..."
  terminationGracePeriodSeconds: 90
  resources: {}
  livenessProbe: ...
  readinessProbe: ...
  startupProbe: ...
  nodeSelector: {}
  tolerations: []
  service:
    type: ClusterIP
    annotations: {}
  persistence:
    enabled: true
    dataSize: 10Gi
    logSize: 5Gi
  config:
    clusterCidrs: [...]
    users:
      appUserPassword: "..."
      otelUserPassword: "..."
      otelUserName: "..."

Новые значения

Теперь ClickHouse управляется через ClickHouse Operator с помощью пользовательских ресурсов ClickHouseCluster и KeeperCluster. Обе спецификации CR формируются напрямую из значений:

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
      keeperClusterRef:
        name: '{{ include "clickstack.clickhouse.keeper" . }}'
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
      settings:
        extraUsersConfig:
          users:
            app:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_APP_PASSWORD }}'
            otelcollector:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_PASSWORD }}'
        extraConfig:
          max_connections: 4096
          keep_alive_timeout: 64
          max_concurrent_queries: 100

Учетные данные пользователя ClickHouse теперь берутся из hyperdx.secrets, а не из clickhouse.config.users. В спецификации кластера они указываются через шаблонные выражения. Субчарт ClickHouse Operator настраивается в разделе clickhouse-operator:. Вебхуки и cert-manager по умолчанию отключены. Все доступные поля CRD см. в руководстве по настройке оператора.

Миграция OTel collector

Удалённые значения

Раздел otel: полностью удалён:

# УДАЛЕНО — не использовать
otel:
  enabled: true
  image: ...
  replicas: 1
  resources: {}
  clickhouseEndpoint: ...
  clickhouseUser: ...
  clickhousePassword: ...
  clickhouseDatabase: "default"
  opampServerUrl: ...
  port: 13133
  nativePort: 24225
  grpcPort: 4317
  httpPort: 4318
  healthPort: 8888
  env: []
  customConfig: ...

Новые значения

OTel collector теперь разворачивается через официальный Helm-чарт OpenTelemetry Collector как субчарт otel-collector:. Обёртки родительского чарта otel: больше нет — настраивайте субчарт напрямую. Переменные окружения (конечная точка ClickHouse, URL OpAMP и т. д.) используются совместно через единый ConfigMap clickstack-config и Secret clickstack-secret. Для сабчарта extraEnvsFrom уже преднастроен:

otel-collector:
  enabled: true
  mode: deployment
  image:
    repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
    tag: ""
  extraEnvsFrom:
    - configMapRef:
        name: clickstack-config
    - secretRef:
        name: clickstack-secret
  ports:
    otlp:
      enabled: true
      containerPort: 4317
      servicePort: 4317
    otlp-http:
      enabled: true
      containerPort: 4318
      servicePort: 4318

Чтобы указать ресурсы (ранее otel.resources):

otel-collector:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"

Чтобы настроить реплики (ранее otel.replicas):

otel-collector:
  replicaCount: 3

Чтобы настроить nodeSelector/tolerations (ранее otel.nodeSelector/otel.tolerations):

otel-collector:
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule

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

Неизменные значения

Следующие разделы не затрагивает эта миграция:

global.* (imageRegistry, imagePullSecrets)

Установка с нуля vs. обновление на месте

Для установки с нуля никаких специальных действий не требуется. Значения по умолчанию работают сразу. Для обновления на месте существующего релиза обратите внимание на следующее:

Операторы (MCK, ClickHouse Operator) будут установлены как новые развертывания в вашем пространстве имен
Существующие развертывания MongoDB и ClickHouse будут удалены Helm (их больше нет в шаблонах чарта)
Операторы создадут новые StatefulSet для управления MongoDB и ClickHouse
PVC из старого чарта не переиспользуются автоматически в StatefulSet, управляемых операторами

Мы рекомендуем выполнить установку с нуля рядом с существующим развертыванием и перенести данные, а не выполнять обновление на месте.

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

Основное руководство по Helm - Базовая установка для v2.x
Руководство по конфигурации - ключи API, секреты и входной шлюз
Дополнительные манифесты - Пользовательские объекты Kubernetes
Репозиторий Helm-чартов ClickStack - Исходный код чартов и справочник по значениям

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

​Установка в два этапа

​Постоянное хранение данных

​Класс хранилища

​Что изменилось

​Реорганизация значений HyperDX

​Основные изменения

​Единые ConfigMap и Secret

​Миграция MongoDB

​Удалённые значения

​Новые значения

​Миграция в ClickHouse

​Удалённые значения

​Новые значения

​Миграция OTel collector

​Удалённые значения

​Новые значения

​Неизменные значения

​Установка с нуля vs. обновление на месте

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

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

Установка в два этапа

Постоянное хранение данных

Класс хранилища

Что изменилось

Реорганизация значений HyperDX

Основные изменения

Единые ConfigMap и Secret

Миграция MongoDB

Удалённые значения

Новые значения

Миграция в ClickHouse

Удалённые значения

Новые значения

Миграция OTel collector

Удалённые значения

Новые значения

Неизменные значения

Установка с нуля vs. обновление на месте

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