Passer au contenu principal
Ce guide explique comment migrer du chart Helm ClickStack inline-template (v1.x) vers l’architecture basée sur des sous-charts (v2.x). Il s’agit d’un changement incompatible qui remplace des ressources Kubernetes créées manuellement par des ressources personnalisées gérées par un opérateur pour MongoDB et ClickHouse, et s’appuie sur le chart Helm officiel de l’OpenTelemetry Collector.
Changement incompatibleLe chart v2.x n’est pas rétrocompatible avec la v1.x. Une mise à niveau sur place avec helm upgrade n’est pas prise en charge. Nous recommandons d’effectuer une nouvelle installation en parallèle du déploiement existant et de migrer les données, plutôt que de tenter une mise à niveau sur place.

​
Prérequis

  • Sauvegardez vos données avant la mise à niveau (MongoDB, PVC ClickHouse)
  • Vérifiez les surcharges actuelles de votre fichier values.yaml — la plupart des clés ont été déplacées ou renommées

​
Installation en deux phases

Le chart v2.x s’installe en deux phases. Les opérateurs (qui enregistrent les CRD) doivent être installés avant le chart principal (qui crée les CR) : 
# Phase 1: Install operators and CRDs
helm install clickstack-operators clickstack/clickstack-operators

# Phase 2: Install ClickStack
helm install my-clickstack clickstack/clickstack
Désinstallez dans l’ordre inverse : 
helm uninstall my-clickstack
helm uninstall clickstack-operators

​
Persistance des données

Les PersistentVolumeClaims créés par les opérateurs MongoDB et ClickHouse ne sont pas supprimés par helm uninstall. C’est intentionnel, afin d’éviter toute perte accidentelle de données. Pour supprimer les PVC après la désinstallation, consultez :

​
Classe de stockage

global.storageClassName et global.keepPVC ont été supprimés. La classe de stockage est désormais configurée directement dans la spécification CR de chaque opérateur : 
mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - spec:
              storageClassName: "fast-ssd"

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

​
Ce qui a changé

ComposantAvant (v1.x)Après (v2.x)
MongoDBDeployment inline + Service + PVCMongoDB Kubernetes Operator (MCK) gérant une CR MongoDBCommunity
ClickHouseDeployment inline + Service + ConfigMaps + PVCClickHouse Operator gérant les CR ClickHouseCluster et KeeperCluster
OTel collectorDeployment inline + Service (bloc otel.*)Chart Helm officiel d’OpenTelemetry Collector (sous-chart otel-collector:)
Valeurs HyperDXClés à plat sous hyperdx.*, avec tasks: et appUrl au niveau supérieurRéorganisées par type de ressource K8s sous hyperdx.* (voir ci-dessous)
hdx-oss-v2Ancien chart obsolèteEntièrement supprimé

​
Réorganisation des values HyperDX

Le bloc hyperdx: est désormais structuré par type de ressource Kubernetes : 
hyperdx:
  ports:          # Shared port numbers (Deployment, Service, ConfigMap, Ingress)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"   # Replaces the removed appUrl

  config:         # → clickstack-config ConfigMap (non-sensitive env vars)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (sensitive env vars)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # K8s Deployment spec (image, replicas, probes, etc.)
  service:        # K8s Service spec (type, annotations)
  ingress:        # K8s Ingress spec (host, tls, annotations)
  podDisruptionBudget:  # K8s PDB spec
  tasks:          # K8s CronJob specs (previously top-level tasks:)

​
Changements clés

Avant (v1.x)Après (v2.x)
appUrlSupprimé. Utilisez hyperdx.frontendUrl (valeur par défaut : http://localhost:3000)
tasks.* (niveau racine)hyperdx.tasks.*
mongodb.passwordhyperdx.secrets.MONGODB_PASSWORD
clickhouse.config.users.appUserPasswordhyperdx.secrets.CLICKHOUSE_APP_PASSWORD
clickhouse.config.users.otelUserPasswordhyperdx.secrets.CLICKHOUSE_PASSWORD
substitutions d’environnement otel.*hyperdx.config.* (non sensibles) et hyperdx.secrets.* (sensibles)

​
ConfigMap et Secret unifiés

Toutes les variables d’environnement sont désormais transmises via deux ressources aux noms fixes, partagées par le déploiement HyperDX et l’OTel collector via envFrom :
  • clickstack-config ConfigMap — renseignée à partir de hyperdx.config
  • clickstack-secret Secret — renseigné à partir de hyperdx.secrets
Il n’existe plus de ConfigMap distincte spécifique à OTel. Les deux charges de travail utilisent les mêmes sources.

​
Migration de MongoDB

​
Valeurs supprimées

Les valeurs mongodb.* suivantes n’existent plus : 
# REMOVED — do not use
mongodb:
  image: "..."
  port: 27017
  strategy: ...
  nodeSelector: {}
  tolerations: []
  livenessProbe: ...
  readinessProbe: ...
  persistence:
    enabled: true
    dataSize: 10Gi

​
Nouvelles valeurs

MongoDB est désormais géré par l’opérateur MCK via une ressource personnalisée MongoDBCommunity. La spécification de la ressource personnalisée est générée telle quelle à partir de 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
Le mot de passe MongoDB est défini dans hyperdx.secrets.MONGODB_PASSWORD (et non dans mongodb.password). Il est automatiquement référencé par le Secret du mot de passe et le modèle mongoUri. Pour ajouter de la persistance, ajoutez un bloc statefulSet dans mongodb.spec : 
mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi
Le sous-chart de l’opérateur MCK se configure sous mongodb-operator: (et non mongodb-kubernetes:). Consultez la documentation MCK pour obtenir la liste complète des champs de CRD disponibles.

​
Migration vers ClickHouse

​
Valeurs supprimées

Les valeurs clickhouse.* suivantes n’existent plus : 
# REMOVED — do not use
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: "..."

​
Nouvelles valeurs

ClickHouse est désormais géré par le ClickHouse Operator via les ressources personnalisées ClickHouseCluster et KeeperCluster. Les sections spec de ces deux ressources sont générées telles quelles à partir des 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
      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
Les identifiants utilisateur de ClickHouse proviennent désormais de hyperdx.secrets (et non de clickhouse.config.users). La spécification du cluster y fait référence à l’aide d’expressions de template. Le sous-chart ClickHouse Operator se configure sous clickhouse-operator:. Les webhooks et cert-manager sont désactivés par défaut. Consultez le guide de configuration de l’opérateur pour voir tous les champs de CRD disponibles.

​
Migration de l’OTEL Collector

​
Valeurs supprimées

Le bloc otel: a été entièrement supprimé : 
# REMOVED — do not use
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: ...

​
Nouvelles valeurs

L’OTel collector est désormais déployé via le chart Helm officiel OpenTelemetry Collector en tant que sous-chart otel-collector:. Il n’existe pas de chart parent otel: faisant office de wrapper — configurez directement le sous-chart. Les variables d’environnement (endpoint ClickHouse, URL OpAMP, etc.) sont partagées via la ConfigMap unifiée clickstack-config et le Secret clickstack-secret. Le extraEnvsFrom du sous-chart est préconfiguré : 
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
Pour définir les ressources (anciennement otel.resources) : 
otel-collector:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
Pour définir les répliques (précédemment otel.replicas) : 
otel-collector:
  replicaCount: 3
Pour définir nodeSelector/tolerations (anciennement otel.nodeSelector/otel.tolerations) : 
otel-collector:
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule
Consultez le chart Helm de l’OpenTelemetry Collector pour connaître l’ensemble des valeurs disponibles du sous-chart.

​
Valeurs inchangées

Les sections suivantes ne sont pas concernées par cette migration :
  • global.* (imageRegistry, imagePullSecrets)

​
Nouvelle installation ou mise à niveau sur place

Pour une nouvelle installation, aucune étape particulière n’est nécessaire. Les valeurs par défaut fonctionnent immédiatement. Pour une mise à niveau sur place d’une release existante, gardez à l’esprit que :
  1. Les opérateurs (MCK, ClickHouse Operator) seront installés sous forme de nouveaux déploiements dans votre espace de noms
  2. Le Deployment MongoDB existant et le Deployment ClickHouse existant seront supprimés par Helm (ils ne figurent plus dans les templates du chart)
  3. Les opérateurs créeront de nouveaux StatefulSets pour gérer MongoDB et ClickHouse
  4. Les PVC de l’ancien chart ne sont pas réutilisés automatiquement par les StatefulSets gérés par les opérateurs
Nous recommandons d’effectuer une nouvelle installation en parallèle du déploiement existant et de migrer les données, plutôt que de procéder à une mise à niveau sur place.

​
Étapes suivantes

Dernière modification le 25 juin 2026