Helm - ClickHouse Documentation

Chart version 2.xCette 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

Prérequis

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

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

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

Installer ClickStack

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

helm install my-clickstack clickstack/clickstack

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.

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 productionPour 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.

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éfautVous pouvez remplacer la connexion par défaut à l’instance ClickHouse intégrée. Pour en savoir plus, consultez “Using ClickHouse Cloud”.

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

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 APIPour 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éesPour 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 productionPour 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.xSi 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émentairesPour 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.

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

​Convient pour

​Étapes de déploiement

​Utiliser ClickHouse Cloud

​Remarques pour la production

​Configuration des tâches

​Mise à jour du chart

​Désinstaller ClickStack

​Dépannage

​Vérifier les logs

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

​Vérification du déploiement

​Choix du schéma : Map vs JSON

​Documentation associée

​Guides de déploiement

​Documentation v1.x

​Ressources supplémentaires

Convient pour

Étapes de déploiement

Utiliser ClickHouse Cloud

Remarques pour la production

Configuration des tâches

Mise à jour du chart

Désinstaller ClickStack

Dépannage

Vérifier les logs

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

Vérification du déploiement

Choix du schéma : Map vs JSON

Documentation associée

Guides de déploiement

Documentation v1.x

Ressources supplémentaires