Configuration de Helm

Version 2.x du chartCette page décrit le chart Helm v2.x basé sur des sous-charts. Si vous utilisez encore le chart v1.x à modèles intégrés, consultez Configuration de Helm (v1.x). Pour les étapes de migration, consultez le guide de mise à niveau.

Ce guide présente les options de configuration des déploiements Helm de ClickStack. Pour l’installation de base, consultez le guide principal de déploiement Helm.

Organisation des values

Le chart v2.x organise les values par type de ressource Kubernetes dans le bloc hyperdx: :

hyperdx:
  ports:          # Shared port numbers (Deployment, Service, ConfigMap, Ingress)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"

  config:         # → clickstack-config ConfigMap (non-sensitive env vars)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (sensitive env vars)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # K8s Deployment spec (image, replicas, probes, etc.)
  service:        # K8s Service spec (type, annotations)
  ingress:        # K8s Ingress spec (host, tls, annotations)
  podDisruptionBudget:  # K8s PDB spec
  tasks:          # K8s CronJob specs

Toutes les variables d’environnement transitent par deux ressources aux noms fixes, partagées par le déploiement HyperDX et l’OTel collector via envFrom :

clickstack-config ConfigMap — renseignée à partir de hyperdx.config
clickstack-secret Secret — renseigné à partir de hyperdx.secrets

Il n’y a plus de ConfigMap distincte spécifique à OTel. Les deux charges de travail lisent à partir des mêmes sources.

Configuration de la clé API

Une fois ClickStack déployé avec succès, configurez la clé API pour activer la collecte des données de télémétrie :

Accédez à votre instance HyperDX via la ressource d’ingress configurée ou le point de terminaison du service
Connectez-vous au tableau de bord HyperDX, puis accédez à Paramètres de l’équipe pour générer ou récupérer votre clé API
Mettez à jour votre déploiement avec la clé API à l’aide de l’une des méthodes suivantes :

Méthode 1 : Mettre à jour avec Helm upgrade à l’aide du fichier values

Ajoutez la clé API à votre values.yaml :

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"

Ensuite, mettez à jour votre déploiement :

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

Méthode 2 : mise à jour via Helm upgrade avec l’option `--set`

helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"

Redémarrer les pods pour appliquer les modifications

Après avoir mis à jour la clé API, redémarrez les pods pour qu’ils prennent en compte la nouvelle configuration :

kubectl rollout restart deployment my-clickstack-clickstack-app

Le chart crée automatiquement un secret Kubernetes (clickstack-secret) avec vos valeurs de configuration. Aucune configuration supplémentaire du secret n’est nécessaire, sauf si vous souhaitez utiliser un secret externe.

Gestion des secrets

Pour gérer des données sensibles telles que des clés API ou des identifiants de base de données, le chart v2.x fournit une ressource clickstack-secret centralisée, alimentée à partir de hyperdx.secrets.

values par défaut des secrets

Le chart fournit des values par défaut pour tous les secrets. Remplacez-les dans votre values.yaml :

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

Utiliser un secret externe

Pour les déploiements en production où vous souhaitez conserver les identifiants séparés des values Helm, utilisez un secret Kubernetes externe :

# Create your secret
kubectl create secret generic my-clickstack-secrets \
  --from-literal=HYPERDX_API_KEY=my-secret-api-key \
  --from-literal=CLICKHOUSE_PASSWORD=my-ch-password \
  --from-literal=CLICKHOUSE_APP_PASSWORD=my-ch-app-password \
  --from-literal=MONGODB_PASSWORD=my-mongo-password

Référencez-le ensuite dans vos values :

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"

Configuration de l’ingress

Pour exposer l’UI HyperDX et l’API via un nom de domaine, activez l’ingress dans votre fichier values.yaml.

Configuration générale de l’ingress

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Must match ingress host

  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"

Note importante concernant la configurationhyperdx.frontendUrl doit correspondre à l’hôte configuré pour l’ingress et inclure le protocole (par exemple, https://hyperdx.yourdomain.com). Cela garantit le bon fonctionnement de tous les liens, cookies et redirections générés.

Activer le TLS (HTTPS)

Pour sécuriser votre déploiement avec HTTPS : 1. Créez un secret TLS avec votre certificat et votre clé privée :

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. Activez TLS dans la configuration de votre Ingress :

hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

Exemple de configuration d’ingress

À titre indicatif, voici à quoi ressemble la ressource d’ingress générée :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

Pièges courants liés à l’Ingress

Configuration du chemin et de la réécriture :

Pour Next.js et les autres SPA, utilisez toujours un chemin avec expression régulière et une annotation de réécriture, comme indiqué ci-dessus
N’utilisez pas seulement path: / sans réécriture, car cela empêchera le chargement correct des ressources statiques

frontendUrl et ingress.host incohérents :

S’ils ne correspondent pas, vous pouvez rencontrer des problèmes avec les cookies, les redirections et le chargement des ressources

Mauvaise configuration de TLS :

Assurez-vous que votre secret TLS est valide et correctement référencé dans l’Ingress
Les navigateurs peuvent bloquer le contenu non sécurisé si vous accédez à l’application en HTTP alors que TLS est activé

Version du contrôleur Ingress :

Certaines fonctionnalités (comme les chemins avec expression régulière et les réécritures) nécessitent des versions récentes du contrôleur NGINX Ingress
Vérifiez votre version avec :

kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

Ingress du OTel collector

Si vous devez exposer les points de terminaison de votre OTel collector (pour les traces, les métriques et les logs) via un ingress, utilisez la configuration additionalIngresses. Cela permet d’envoyer des données de télémétrie depuis l’extérieur du cluster ou d’utiliser un domaine personnalisé pour le collector.

hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls

Cela crée une ressource Ingress distincte pour les points de terminaison de l’OTel collector
Vous pouvez utiliser un autre domaine, configurer des paramètres TLS spécifiques et appliquer des annotations personnalisées
La règle de chemin avec expression régulière vous permet d’acheminer tous les signaux OTLP (traces, métriques, logs) via une seule règle

Si vous n’avez pas besoin d’exposer l’OTel collector vers l’extérieur, vous pouvez ignorer cette configuration. Pour la plupart des utilisateurs, la configuration Ingress générale est suffisante.

Vous pouvez également utiliser additionalManifests pour définir des ressources Ingress entièrement personnalisées, comme un Ingress AWS ALB.

Configuration de l’OTEL collector

L’OTEL Collector est déployé via le chart Helm officiel de l’OpenTelemetry Collector, en tant que sous-chart otel-collector:. Configurez-le directement sous otel-collector: dans vos values :

otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule

Les variables d’environnement (endpoint ClickHouse, URL OpAMP, etc.) sont partagées via la ConfigMap unifiée clickstack-config et le Secret clickstack-secret. Le extraEnvsFrom du sous-chart est déjà configuré pour lire depuis les deux. Consultez le chart Helm OpenTelemetry Collector pour connaître toutes les valeurs de sous-chart disponibles.

Configuration de MongoDB

MongoDB est géré par l’opérateur MCK au moyen d’une ressource personnalisée MongoDBCommunity. La spécification de la ressource personnalisée est reproduite telle quelle à partir de mongodb.spec :

mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi

Le mot de passe MongoDB est défini dans hyperdx.secrets.MONGODB_PASSWORD. Consultez la documentation MCK pour obtenir la liste complète des champs de CRD disponibles.

Configuration de ClickHouse

ClickHouse est géré par le ClickHouse Operator via les ressources personnalisées ClickHouseCluster et KeeperCluster. Les sections spec de ces deux ressources sont générées telles quelles à partir des values :

clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Les identifiants utilisateur de ClickHouse sont récupérés depuis hyperdx.secrets (et non depuis clickhouse.config.users comme en v1.x). Consultez le guide de configuration du ClickHouse Operator pour voir tous les champs de CRD disponibles.

Résolution des problèmes liés à l’ingress

Vérifiez la ressource d’ingress :

kubectl get ingress -A
kubectl describe ingress <ingress-name>

Consultez les journaux du contrôleur ingress :

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

Tester les URL des ressources : Utilisez curl pour vérifier que les ressources statiques sont renvoyées en JavaScript, et non en HTML :

curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Should return Content-Type: application/javascript

Outils de développement du navigateur :

Vérifiez l’onglet Réseau pour repérer les erreurs 404 ou les ressources qui renvoient du HTML au lieu de JS
Recherchez des erreurs comme Unexpected token < dans la console (cela indique que du HTML est renvoyé à la place de JS)

Vérifiez les réécritures de chemin :

Assurez-vous que l’ingress ne supprime pas les chemins des ressources et ne les réécrit pas incorrectement

Videz le cache du navigateur et du CDN :

Après les modifications, videz le cache de votre navigateur ainsi que tout cache CDN/proxy afin d’éviter des ressources obsolètes

Personnaliser les values

Vous pouvez personnaliser les paramètres à l’aide des options --set :

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

Vous pouvez également créer un values.yaml personnalisé. Pour récupérer les values par défaut :

helm show values clickstack/clickstack > values.yaml

Appliquez vos values de configuration personnalisées :

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

Étapes suivantes

Options de déploiement - Systèmes externes et déploiements minimaux
Déploiements Cloud - Configurations GKE, EKS et AKS
Guide de mise à niveau - Migration de la v1.x vers la v2.x
Manifestes supplémentaires - Objets Kubernetes personnalisés
Guide principal Helm - Installation de base
Configuration (v1.x) - Guide de configuration de la v1.x

Fonctionnalités

Guides

Organisation des values

Configuration de la clé API

Méthode 1 : Mettre à jour avec Helm upgrade à l’aide du fichier values

Méthode 2 : mise à jour via Helm upgrade avec l’option `--set`

Redémarrer les pods pour appliquer les modifications

Gestion des secrets

values par défaut des secrets

Utiliser un secret externe

Configuration de l’ingress

Configuration générale de l’ingress

Activer le TLS (HTTPS)

Exemple de configuration d’ingress

Pièges courants liés à l’Ingress

Ingress du OTel collector

Configuration de l’OTEL collector

Configuration de MongoDB

Configuration de ClickHouse

Résolution des problèmes liés à l’ingress

Personnaliser les values

Étapes suivantes

​Organisation des values

​Configuration de la clé API

​Méthode 1 : Mettre à jour avec Helm upgrade à l’aide du fichier values

​Méthode 2 : mise à jour via Helm upgrade avec l’option --set

​Redémarrer les pods pour appliquer les modifications

​Gestion des secrets

​values par défaut des secrets

​Utiliser un secret externe

​Configuration de l’ingress

​Configuration générale de l’ingress

​Activer le TLS (HTTPS)

​Exemple de configuration d’ingress

​Pièges courants liés à l’Ingress

​Ingress du OTel collector

​Configuration de l’OTEL collector

​Configuration de MongoDB

​Configuration de ClickHouse

​Résolution des problèmes liés à l’ingress

​Personnaliser les values

​Étapes suivantes

Organisation des values

Configuration de la clé API

Méthode 1 : Mettre à jour avec Helm upgrade à l’aide du fichier values

Méthode 2 : mise à jour via Helm upgrade avec l’option `--set`

Redémarrer les pods pour appliquer les modifications

Gestion des secrets

values par défaut des secrets

Utiliser un secret externe

Configuration de l’ingress

Configuration générale de l’ingress

Activer le TLS (HTTPS)

Exemple de configuration d’ingress

Pièges courants liés à l’Ingress

Ingress du OTel collector

Configuration de l’OTEL collector

Configuration de MongoDB

Configuration de ClickHouse

Résolution des problèmes liés à l’ingress

Personnaliser les values

Étapes suivantes