Helm

Déployer ClickStack avec Helm - La stack d’observabilité ClickHouse

Chart version 2.x

Cette page documente le chart Helm v2.x basé sur des sous-charts. Si vous utilisez encore le chart v1.x avec des templates inline, consultez le guide Helm v1.x. Pour les étapes de migration, consultez le guide de mise à niveau.

Le chart Helm de ClickStack est disponible ici et constitue la méthode recommandée pour les déploiements en production.

Le chart v2.x utilise une installation en deux phases. Les operators et les CRD sont d’abord installés via le chart clickstack-operators, puis le chart principal clickstack, qui crée des ressources personnalisées gérées par operator pour ClickHouse, MongoDB et l’OpenTelemetry Collector.

Par défaut, le chart Helm provisionne tous les composants principaux, notamment :

• ClickHouse — géré par le ClickHouse Operator via les ressources personnalisées ClickHouseCluster et KeeperCluster
• HyperDX — l’UI et l’API d’observabilité
• OpenTelemetry (OTel) collector — déployé via l’OpenTelemetry Collector Helm chart officiel en tant que sous-chart
• MongoDB — géré par le MongoDB Kubernetes Operator (MCK) via une ressource personnalisée MongoDBCommunity

Cependant, il peut facilement être personnalisé pour s’intégrer à un déploiement ClickHouse existant — par exemple, hébergé sur ClickHouse Cloud.

Le chart prend en charge les bonnes pratiques Kubernetes standard, notamment :

• Configuration spécifique à l’environnement via values.yaml
• Limites de ressources et mise à l’échelle au niveau des pods
• Configuration de TLS et d’Ingress
• Gestion des secrets et configuration de l’authentification
• Manifests supplémentaires pour déployer des objets Kubernetes arbitraires (NetworkPolicy, HPA, ALB Ingress, etc.) en complément du chart

​

Convient pour

• Les preuves de concept
• La production

​

Étapes de déploiement

1. ​

   Prérequis

   • Helm v3+
   • cluster Kubernetes (v1.20+ recommandé)
   • kubectl configuré pour interagir avec votre cluster
2. ​

   Ajouter le dépôt Helm de ClickStack

   Ajoutez le dépôt Helm de ClickStack :

   helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
   helm repo update
   
3. ​

   Installer les opérateurs

   Installez d’abord le chart de l’opérateur. Cela enregistre les CRD requises par le chart principal :

   helm install clickstack-operators clickstack/clickstack-operators
   

   Attendez que les pods de l’opérateur soient prêts avant de poursuivre :

   kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
   
4. ​

   Installer ClickStack

   Une fois les opérateurs démarrés, installez le chart principal :

   helm install my-clickstack clickstack/clickstack
   
5. ​

   Vérifier l’installation

   Vérifiez l’installation :

   kubectl get pods -l "app.kubernetes.io/name=clickstack"
   

   Lorsque tous les pods sont prêts, continuez.

6. ​

   Transfert de ports

   Le transfert de ports permet d’accéder à HyperDX et de le configurer. Pour un déploiement en production, il est préférable d’exposer le service via une ressource d’entrée ou un équilibreur de charge afin de garantir un accès réseau approprié, la terminaison TLS et la scalabilité. Le transfert de ports convient surtout au développement local ou à des tâches administratives ponctuelles, et non à des environnements pérennes ou à haute disponibilité.

   kubectl port-forward \
     pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
     8080:3000
   

   Configuration de l’ingress en production

   Pour les déploiements en production, configurez l’ingress avec TLS plutôt que d’utiliser le transfert de port. Consultez le guide de configuration de l’ingress pour obtenir des instructions détaillées.

7. ​

   Accéder à l’UI

   Rendez-vous sur http://localhost:8080 pour accéder à l’UI HyperDX.

   Créez un utilisateur en indiquant un nom d’utilisateur et un mot de passe conformes aux exigences.

   Lorsque vous cliquez sur Create, des sources de données sont créées pour l’instance ClickHouse déployée avec le chart Helm.

   Remplacer la connexion par défaut

   Vous pouvez remplacer la connexion par défaut à l’instance ClickHouse intégrée. Pour en savoir plus, consultez “Using ClickHouse Cloud”.

8. ​

   Personnaliser les valeurs (facultatif)

   Vous pouvez personnaliser ces valeurs à l’aide des options --set. Par exemple :

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

   Vous pouvez également modifier le values.yaml. Pour obtenir les valeurs par défaut :

   helm show values clickstack/clickstack > values.yaml
   

   Exemple de configuration :

   hyperdx:
     frontendUrl: "https://hyperdx.example.com"
   
     deployment:
       replicas: 2
       resources:
         limits:
           cpu: "2"
           memory: 4Gi
         requests:
           cpu: 500m
           memory: 1Gi
   
     ingress:
       enabled: true
       host: hyperdx.example.com
       tls:
         enabled: true
         tlsSecretName: "hyperdx-tls"
   

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

   Utilisation des secrets (facultatif)

   Le chart v2.x utilise un secret unifié (clickstack-secret), alimenté à partir de hyperdx.secrets dans vos values. Toutes les variables d’environnement sensibles — y compris les mots de passe ClickHouse, les mots de passe MongoDB et la clé API HyperDX — passent par ce secret unique.

   Pour remplacer les valeurs du secret :

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

   Pour la gestion externe des secrets (par exemple à l’aide d’un opérateur de secrets), vous pouvez faire référence à un secret Kubernetes existant :

   hyperdx:
     useExistingConfigSecret: true
     existingConfigSecret: "my-external-secret"
     existingConfigConnectionsKey: "connections.json"
     existingConfigSourcesKey: "sources.json"
   

   Gestion des clés API

   Pour des instructions détaillées sur la configuration des clés API, notamment les différentes méthodes de configuration et les procédures de redémarrage des pods, consultez le guide de configuration des clés API.

​

Utiliser ClickHouse Cloud

Si vous utilisez ClickHouse Cloud, désactivez l’instance ClickHouse intégrée et renseignez vos identifiants Cloud :

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

Créez le secret de connexion séparément :

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

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

Configurations externes avancées

Pour les déploiements en production avec une configuration via des secrets, des collectors OTel externes ou des configurations minimales, consultez le guide des options de déploiement.

​

Remarques pour la production

Par défaut, ce chart installe ClickHouse, MongoDB et l’OTel collector. Pour un environnement de production, il est recommandé de gérer ClickHouse et l’OTel collector séparément.

Pour désactiver ClickHouse et l’OTel collector :

clickhouse:
  enabled: false

otel-collector:
  enabled: false

Bonnes pratiques pour la production

Pour les déploiements en production, y compris la configuration de la haute disponibilité, la gestion des ressources, la configuration d’Ingress/TLS et les paramètres spécifiques au Cloud (GKE, EKS, AKS), consultez :

• Guide de configuration - Ingress, TLS et gestion des secrets
• Déploiements Cloud - paramètres spécifiques au Cloud et liste de contrôle pour la production

​

Configuration des tâches

Par défaut, une tâche est définie dans la configuration du chart sous forme de cronjob et se charge de vérifier si des alertes doivent se déclencher. Dans la version 2.x, la configuration des tâches a été déplacée sous hyperdx.tasks :

Paramètre	Description	Valeur par défaut
hyperdx.tasks.enabled	Active/désactive les tâches cron dans le cluster. Par défaut, l’image HyperDX exécute les tâches cron dans le processus principal. Définissez cette valeur sur true si vous préférez utiliser une tâche cron distincte dans le cluster.	false
hyperdx.tasks.checkAlerts.schedule	Planification cron de la tâche check-alerts	*/1 * * * *
hyperdx.tasks.checkAlerts.resources	Requêtes et limites de ressources pour la tâche check-alerts	Voir values.yaml

​

Mise à jour du chart

Pour passer à une version plus récente :

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

Pour vérifier les versions disponibles du chart :

helm search repo clickstack

Mise à niveau depuis la version 1.x

Si vous effectuez une mise à niveau depuis le chart inline-template v1.x, consultez le guide de mise à niveau pour connaître la procédure de migration. Il s’agit d’un changement incompatible : une commande helm upgrade sur place n’est pas prise en charge.

​

Désinstaller ClickStack

Désinstallez dans l’ordre inverse :

helm uninstall my-clickstack            # Remove app + CRs first
helm uninstall clickstack-operators     # Remove operators + CRDs

Remarque : 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, reportez-vous à :

• documentation de l’opérateur Kubernetes MongoDB

​

Dépannage

​

Vérifier les logs

kubectl logs -l app.kubernetes.io/name=clickstack

​

Débogage après l’échec d’une installation

helm install my-clickstack clickstack/clickstack --debug --dry-run

​

Vérification du déploiement

kubectl get pods -l app.kubernetes.io/name=clickstack

Ressources de dépannage supplémentaires

Pour les problèmes spécifiques à l’Ingress, les problèmes de TLS ou le dépannage des déploiements Cloud, consultez :

• Dépannage de l’Ingress - Distribution des ressources, réécritures de chemin, problèmes de navigateur
• Déploiements Cloud - Problèmes liés à GKE OpAMP et problèmes spécifiques au cloud

​

Choix du schéma : Map vs JSON

Par défaut, ClickStack stocke les attributs dans des colonnes Map(LowCardinality(String), String). Il s’agit du schéma recommandé pour les charges de travail d’observabilité. Associé à la sérialisation de map compartimentée et à des index textuels sur les clés et les valeurs de la map, il permet des recherches sélectives sans la surcharge d’ingestion par clé propre aux sous-colonnes JSON dynamiques.

Un schéma de type JSON est disponible en bêta pour évaluation sur des charges de travail avec un ensemble réduit et stable de clés d’attributs. Il n’est pas recommandé par défaut. Consultez Map vs JSON type pour la comparaison complète et les variables d’environnement requises pour activer la prise en charge de JSON.

​

Documentation associée

​

Guides de déploiement

• Options de déploiement - ClickHouse externe, OTel collector et déploiements minimaux
• Guide de configuration - Clés API, secrets et configuration de l’Ingress
• Déploiements Cloud - Configurations GKE, EKS et AKS, et bonnes pratiques pour la production
• Guide de mise à niveau - Migration de v1.x vers v2.x
• Manifestes supplémentaires - Déployer des objets Kubernetes personnalisés en plus du chart

​

Documentation v1.x

• Helm (v1.x) - guide de déploiement pour v1.x
• Configuration (v1.x) - configuration pour v1.x
• Options de déploiement (v1.x) - options de déploiement pour v1.x
• Déploiements Cloud (v1.x) - configurations Cloud pour v1.x

​

Ressources supplémentaires

• Guide de prise en main de ClickStack - Introduction à ClickStack
• Dépôt des charts Helm de ClickStack - Code source des charts et référence des valeurs
• Documentation Kubernetes - Référence de Kubernetes
• Documentation Helm - Référence de Helm