Helm

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

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.

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"

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

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

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

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

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