Helm (v1.x)

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

• Preuves de concept
• Production

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

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.

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

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

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

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 :

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

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.

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

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

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

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.

• 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

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

• 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