Helm (v1.x) - ClickHouse Documentation

Obsolète — chart v1.xCette page documente le chart Helm v1.x inline-template, qui est en mode maintenance et ne recevra plus de nouvelles fonctionnalités. Pour les nouveaux déploiements, utilisez le chart v2.x. Pour migrer un déploiement v1.x existant, 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. Par défaut, le chart Helm déploie tous les composants principaux, notamment :

ClickHouse
HyperDX
collecteur OpenTelemetry (OTel)
MongoDB (pour l’état persistant de l’application)

Il peut toutefois être facilement personnalisé pour s’intégrer à un déploiement ClickHouse existant, par exemple hébergé dans 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 de l’Ingress
Gestion des secrets et configuration de l’authentification

Convient pour

Preuves de concept
Production

Étapes de déploiement

Prérequis

Helm v3+
cluster Kubernetes (v1.20+ recommandé)
kubectl configuré pour communiquer 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

Installation de ClickStack

Pour installer le chart ClickStack avec les valeurs par défaut :

helm install my-clickstack clickstack/clickstack

Vérifier l’installation

Vérifiez l’installation :

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

Une fois que tous les pods sont prêts, poursuivez.

Redirection de ports

La redirection 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 un Ingress ou un répartiteur de charge afin de garantir un accès réseau approprié, la terminaison TLS et une bonne montée en charge. La redirection de ports convient surtout au développement local ou à des tâches administratives ponctuelles, et non à des environnements durables 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 d’Ingress en productionPour les déploiements en production, configurez l’Ingress avec TLS plutôt que d’utiliser la redirection de port. Consultez le guide de configuration de l’Ingress pour des instructions détaillées.

Accéder à l’interface

Rendez-vous sur http://localhost:8080 pour accéder à l’HyperDX UI.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 package Helm.

Remplacer la connexion par défautVous pouvez remplacer la connexion par défaut de l’instance ClickHouse intégrée. Pour plus de détails, consultez “Using ClickHouse Cloud”.

Personnaliser les valeurs (facultatif)

Vous pouvez personnaliser la configuration à l’aide des options --set. Par exemple :

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

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

helm show values clickstack/clickstack > values.yaml

Exemple de configuration :

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

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

Utilisation des secrets (facultatif)

Pour gérer des données sensibles telles que des clés API ou des identifiants de base de données, utilisez des secrets Kubernetes. Les charts Helm de HyperDX fournissent des fichiers de secrets par défaut que vous pouvez modifier et appliquer à votre cluster.

Utilisation de secrets préconfigurés

Le chart Helm inclut un modèle de secret par défaut situé dans charts/clickstack/templates/secrets.yaml. Ce fichier fournit une structure de base pour la gestion des secrets.Si vous devez appliquer manuellement un secret, modifiez et appliquez le modèle secrets.yaml fourni :

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

Appliquez le secret à votre cluster :

kubectl apply -f secrets.yaml

Créer un secret personnalisé

Si vous le souhaitez, vous pouvez créer manuellement un secret Kubernetes personnalisé :

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

Référencer un secret

Pour référencer un secret dans values.yaml :

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

Gestion des clés APIPour des instructions détaillées sur la configuration des clés API, y compris 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.

Utilisation de ClickHouse Cloud

Si vous utilisez ClickHouse Cloud, désactivez l’instance ClickHouse déployée par le chart Helm et renseignez les identifiants Cloud :

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# how to overwrite default connection
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

Vous pouvez également utiliser un fichier values.yaml :

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# or if installed...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

Configurations externes avancéesPour les déploiements en production avec une configuration via des secrets, des collecteurs OpenTelemetry (OTel) externes ou des configurations minimales, consultez le guide des options de déploiement.

Remarques pour la production

Par défaut, ce chart installe également ClickHouse et le collecteur OpenTelemetry (OTel). Toutefois, en production, il est recommandé de gérer ClickHouse et le collecteur OpenTelemetry (OTel) séparément. Pour désactiver ClickHouse et le collecteur OpenTelemetry (OTel), définissez les valeurs suivantes :

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

Bonnes pratiques en productionPour les déploiements en production, y compris la configuration de la haute disponibilité, la gestion des ressources, la configuration de l’Ingress/TLS et les configurations spécifiques au Cloud (GKE, EKS, AKS), consultez :

Guide de configuration - Gestion de l’Ingress, du TLS et 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, la configuration du chart inclut une tâche sous forme de cronjob, chargée de vérifier si des alertes doivent se déclencher. Voici ses options de configuration :

Paramètre	Description	Par défaut
`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. Passez cette valeur à true si vous préférez utiliser une tâche cron distincte dans le cluster.	`false`
`tasks.checkAlerts.schedule`	Planification cron de la tâche check-alerts	`/1 * * *`
`tasks.checkAlerts.resources`	Requêtes et limites de ressources pour la tâche check-alerts	Voir `values.yaml`

Mise à niveau 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

Passer à la version 2.xSi vous souhaitez migrer vers le chart v2.x basé sur des sous-charts, consultez le Guide de mise à niveau pour obtenir les instructions de migration. Il s’agit d’une modification incompatible : une commande helm upgrade sur place n’est pas prise en charge.

Désinstallation de ClickStack

Pour supprimer le déploiement :

helm uninstall my-clickstack

Cela supprimera toutes les ressources associées à la release, mais les données persistantes (le cas échéant) pourront subsister.

Dépannage

Vérification des logs

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

Débogage d’une installation en échec

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

Vérifier le déploiement

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

Ressources de dépannage supplémentairesPour les problèmes liés à l’Ingress, les problèmes de TLS ou le dépannage des déploiements Cloud, voir :

Dépannage d’Ingress - Chargement des ressources, réécritures de chemins, problèmes de navigateur
Déploiements Cloud - Problèmes 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 v1.x

Options de déploiement (v1.x) - ClickHouse externe, collecteur OpenTelemetry (OTel) et déploiement minimal
Guide de configuration (v1.x) - Clés API, secrets et configuration de l’ingress
Déploiements Cloud (v1.x) - Configurations GKE, EKS et AKS, et bonnes pratiques pour la production

Documentation v2.x

Helm (v2.x) - Guide de déploiement pour v2.x
Guide de mise à niveau - Migration de v1.x vers v2.x

Ressources supplémentaires

Guide de démarrage de ClickStack - Introduction à ClickStack
Dépôt des charts Helm de ClickStack - Code source du chart et référence des valeurs
Documentation Kubernetes - Référence Kubernetes
Documentation Helm - Référence Helm

​Convient pour

​Étapes de déploiement

​Utilisation de secrets préconfigurés

​Créer un secret personnalisé

​Référencer un secret

​Utilisation de ClickHouse Cloud

​Remarques pour la production

​Configuration des tâches

​Mise à niveau du chart

​Désinstallation de ClickStack

​Dépannage

​Vérification des logs

​Débogage d’une installation en échec

​Vérifier le déploiement

​Choix du schéma : Map vs JSON

​Documentation connexe

​Guides de déploiement v1.x

​Documentation v2.x

​Ressources supplémentaires

Convient pour

Étapes de déploiement

Utilisation de secrets préconfigurés

Créer un secret personnalisé

Référencer un secret

Utilisation de ClickHouse Cloud

Remarques pour la production

Configuration des tâches

Mise à niveau du chart

Désinstallation de ClickStack

Dépannage

Vérification des logs

Débogage d’une installation en échec

Vérifier le déploiement

Choix du schéma : Map vs JSON

Documentation connexe

Guides de déploiement v1.x

Documentation v2.x

Ressources supplémentaires