Helm (v1.x)

Déploiement de ClickStack à l’aide du chart Helm inline-template v1.x

Obsolète — chart v1.x

Cette 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

1. ​

   Prérequis

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

   Installation de ClickStack

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

   helm install my-clickstack clickstack/clickstack
   
4. ​

   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.

5. ​

   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 production

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

6. ​

   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éfaut

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

7. ​

   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
   
8. ​

   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 API

   Pour 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ées

Pour 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 production

Pour 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.x

Si 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émentaires

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

​

Documentation connexe

​

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