Supervision de Kubernetes - ClickHouse Documentation

Ce guide vous permet de collecter les logs et les métriques de votre système Kubernetes, puis de les envoyer vers ClickStack pour les visualiser et les analyser. Pour les données de démonstration, nous pouvons également utiliser le fork ClickStack de l’OpenTelemetry demo officielle.

Prérequis

Pour suivre ce guide, vous devez disposer de :

D’un cluster Kubernetes (v1.20+ recommandée) avec au moins 32 Gio de RAM et 100 Go d’espace disque disponibles sur un nœud pour ClickHouse.
Helm v3+
De kubectl, configuré pour interagir avec votre cluster

Options de déploiement

Vous pouvez suivre ce guide en utilisant l’une des options de déploiement suivantes :

Open Source ClickStack : déployez ClickStack entièrement dans votre cluster Kubernetes, y compris :
- ClickHouse
- HyperDX
- MongoDB (utilisé pour l’état et la configuration des tableaux de bord)
Managed ClickStack, avec ClickHouse et la ClickStack UI (HyperDX) gérés dans ClickHouse Cloud. Vous n’avez ainsi pas besoin d’exécuter ClickHouse ou HyperDX dans votre cluster.

Pour simuler le trafic applicatif, vous pouvez, si vous le souhaitez, déployer le fork ClickStack de l’OpenTelemetry Demo Application. Cela génère des données de télémétrie, notamment des logs, des métriques et des traces. Si vous avez déjà des charges de travail en cours d’exécution dans votre cluster, vous pouvez ignorer cette étape et surveiller les pods, nœuds et conteneurs existants.

Installer cert-manager (facultatif)

Si votre installation nécessite des certificats TLS, installez cert-manager à l’aide de Helm :

# Add Cert manager repo 

helm repo add jetstack https://charts.jetstack.io 

helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set startupapicheck.timeout=5m --set installCRDs=true --set global.leaderElection.namespace=cert-manager

Déployer l’OpenTelemetry Demo (facultatif)

Cette étape est facultative et s’adresse aux cas où vous n’avez aucun pod existant à surveiller. Les utilisateurs qui ont déjà des services déployés dans leur environnement Kubernetes peuvent l’ignorer, mais cette démo inclut des microservices instrumentés qui génèrent des données de traces et de session replay, ce qui permet d’explorer toutes les fonctionnalités de ClickStack.La suite déploie le fork ClickStack de la stack applicative OpenTelemetry Demo dans un cluster Kubernetes, conçu pour les tests d’observabilité et la démonstration de l’instrumentation. Il inclut des microservices backend, des générateurs de charge, des pipelines de télémétrie, l’infrastructure de support (par ex. Kafka, Redis) ainsi que des intégrations SDK avec ClickStack.Tous les services sont déployés dans l’espace de noms otel-demo. Chaque déploiement inclut :

Une instrumentation automatique avec OTel et les SDKs ClickStack pour les traces, les métriques et les logs.
Tous les services envoient leur instrumentation à un collecteur OpenTelemetry my-hyperdx-hdx-oss-v2-otel-collector (non déployé)
Le transfert des tags de ressource afin de corréler les logs, les métriques et les traces via la variable d’environnement OTEL_RESOURCE_ATTRIBUTES.

## download demo Kubernetes manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# wget alternative
# wget https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
kubectl apply --namespace otel-demo -f opentelemetry-demo.yaml

Lors du déploiement de la démo, vérifiez que tous les pods ont bien été créés et sont à l’état Running :

kubectl get pods -n=otel-demo

NAME                                 READY   STATUS    RESTARTS   AGE
accounting-fd44f4996-fcl4k           1/1     Running   0          13m
ad-769f968468-qq8mw                  1/1     Running   0          13m
artillery-loadgen-7bc4bdf47d-5sb96   1/1     Running   0          13m
cart-5b4c98bd8-xm7m2                 1/1     Running   0          13m
checkout-784f69b785-cnlpp            1/1     Running   0          13m
currency-fd7775b9c-rf6cr             1/1     Running   0          13m
email-5c54598f99-2td8s               1/1     Running   0          13m
flagd-5466775df7-zjb4x               2/2     Running   0          13m
fraud-detection-5769fdf75f-cjvgh     1/1     Running   0          13m
frontend-6dcb696646-fmcdz            1/1     Running   0          13m
frontend-proxy-7b8f6cd957-s25qj      1/1     Running   0          13m
image-provider-5fdb455756-fs4xv      1/1     Running   0          13m
kafka-7b6666866d-xfzn6               1/1     Running   0          13m
load-generator-57cbb7dfc9-ncxcf      1/1     Running   0          13m
payment-6d96f9bcbd-j8tj6             1/1     Running   0          13m
product-catalog-7fb77f9c78-49bhj     1/1     Running   0          13m
quote-576c557cdf-qn6pr               1/1     Running   0          13m
recommendation-546cc68fdf-8x5mm      1/1     Running   0          13m
shipping-7fc69f7fd7-zxrx6            1/1     Running   0          13m
valkey-cart-5f7b667bb7-gl5v4         1/1     Running   0          13m

Architecture de la démonstration

La démonstration se compose de microservices écrits dans différents langages de programmation, qui communiquent entre eux via gRPC et HTTP, ainsi que d’un générateur de charge utilisant Locust pour simuler le trafic des utilisateurs. Le code source original de cette démonstration a été modifié pour utiliser l’instrumentation ClickStack.Crédit : https://opentelemetry.io/docs/demo/architecture/Vous trouverez plus de détails sur cette démonstration dans :

Ajouter le dépôt du chart Helm ClickStack

Pour déployer ClickStack, nous utilisons le chart Helm officiel.Pour cela, il faut ajouter le dépôt Helm HyperDX :

helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo update

Déployer ClickStack

Une fois le chart Helm installé, vous pouvez déployer ClickStack sur votre cluster. Vous pouvez soit exécuter tous les composants, y compris ClickHouse et HyperDX, dans votre environnement Kubernetes, soit déployer uniquement le collector et vous appuyer sur Managed ClickStack pour ClickHouse et l’interface HyperDX.

ClickStack Open Source (autogéré)

La commande suivante installe ClickStack dans le namespace otel-demo. Le chart Helm déploie :

Une instance ClickHouse
HyperDX
La distribution ClickStack de l’OTel collector
MongoDB pour stocker l’état de l’application HyperDX

Vous devrez peut-être ajuster le storageClassName en fonction de la configuration de votre cluster Kubernetes.

Les utilisateurs qui ne déploient pas la démo OTel peuvent modifier ce paramètre en choisissant un namespace approprié.

helm install my-hyperdx hyperdx/hdx-oss-v2   --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demo

ClickStack en productionCe chart installe également ClickHouse et l’OTel collector. Pour un environnement de production, il est recommandé d’utiliser les opérateurs ClickHouse et OTel collector et/ou d’utiliser Managed ClickStack.Pour désactiver ClickHouse et l’OTel collector, définissez les valeurs suivantes :

helm install myrelease <chart-name-or-path> --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false

Managed ClickStack

Si vous préférez utiliser Managed ClickStack, vous pouvez déployer ClickStack et désactiver le ClickHouse inclus.

Le chart déploie actuellement toujours HyperDX et MongoDB. Bien que ces composants constituent un autre moyen d’accès, ils ne sont pas intégrés à l’authentification de ClickHouse Cloud. Dans ce modèle de déploiement, ces composants sont destinés aux administrateurs, car ils donnent accès à la clé d’ingestion sécurisée nécessaire pour ingérer des données via l’OTel collector déployé, mais ils ne doivent pas être exposés aux utilisateurs finaux.

# spécifier les identifiants ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # URL https complète
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

helm install my-hyperdx hyperdx/hdx-oss-v2  --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} --set clickhouse.config.users.otelUserName=${CLICKHOUSE_USER} --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD} --set global.storageClassName="standard-rwo" -n otel-demo

Pour vérifier l’état du déploiement, exécutez la commande suivante et assurez-vous que tous les composants sont à l’état Running. Notez que ClickHouse sera absent si vous utilisez Managed ClickStack :

kubectl get pods -l "app.kubernetes.io/name=hdx-oss-v2" -n otel-demo

NAME                                                    READY   STATUS    RESTARTS   AGE
my-hyperdx-hdx-oss-v2-app-78876d79bb-565tb              1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-clickhouse-57975fcd6-ggnz2        1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-mongodb-984845f96-czb6m           1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-otel-collector-64cf698f5c-8s7qj   1/1     Running   0          14m

Accéder à l’interface HyperDX

Même lorsque vous utilisez Managed ClickStack, l’instance locale d’HyperDX déployée dans le cluster Kubernetes reste nécessaire. Elle fournit une clé d’ingestion gérée par le serveur OpAMP inclus avec HyperDX et permet une ingestion sécurisée via l’OTel collector déployé — une fonctionnalité qui n’est pas encore disponible dans Managed ClickStack.

Pour des raisons de sécurité, le service utilise ClusterIP et n’est pas exposé à l’extérieur par défaut.Pour accéder à l’interface HyperDX, effectuez une redirection de port de 3000 vers le port local 8080.

kubectl port-forward \
 pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}' -n otel-demo) \
  8080:3000 \
 -n otel-demo

Rendez-vous sur http://localhost:8080 pour accéder à HyperDX UI.Créez un utilisateur en indiquant un nom d’utilisateur et un mot de passe conformes aux exigences de complexité.

Récupérer la clé API d’ingestion

L’ingestion vers l’OTel collector déployé par le ClickStack collector est sécurisée par une clé d’ingestion.Accédez à Team Settings et copiez l’Ingestion API Key depuis la section API Keys. Cette clé API garantit la sécurité de l’ingestion des données via l’OpenTelemetry collector.

Créer un secret Kubernetes pour l’API key

Créez un nouveau secret Kubernetes avec l’API key d’ingestion, ainsi qu’une ConfigMap contenant l’adresse de l’OTel collector déployé avec le chart Helm ClickStack. Les composants suivants l’utiliseront pour autoriser l’ingestion vers le collector déployé avec le chart Helm ClickStack :

# create secret with the ingestion API key
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo

# create a ConfigMap pointing to the ClickStack OTel collector deployed above
kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318

Redémarrez les pods de l’OpenTelemetry Demo Application afin de prendre en compte la clé API d’ingestion.

kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demo

Les données de traces et de logs provenant des services de démonstration devraient désormais commencer à affluer vers HyperDX.

Ajouter le dépôt Helm OpenTelemetry

Pour collecter les métriques Kubernetes, nous allons déployer un OTel collector standard et le configurer pour envoyer les données de manière sécurisée à notre ClickStack collector à l’aide de la clé API d’ingestion ci-dessus.Cela nécessite d’installer le dépôt Helm OpenTelemetry :

# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts 

Déployer les composants du collector Kubernetes

Pour collecter les logs et les métriques du cluster lui-même et de chaque nœud, nous devrons déployer deux collecteurs OpenTelemetry distincts, chacun avec son propre manifeste. Les deux manifestes fournis — k8s_deployment.yaml et k8s_daemonset.yaml — fonctionnent conjointement pour collecter des données de télémétrie complètes depuis votre cluster Kubernetes.

k8s_deployment.yaml déploie une instance unique d’OpenTelemetry Collector chargée de collecter les événements et les métadonnées à l’échelle du cluster. Elle recueille les événements Kubernetes, les métriques du cluster et enrichit les données de télémétrie avec les labels et annotations des pods. Ce collecteur s’exécute comme un déploiement autonome avec une seule réplique pour éviter les doublons de données.
k8s_daemonset.yaml déploie un collecteur basé sur un DaemonSet qui s’exécute sur chaque nœud de votre cluster. Il collecte les métriques des nœuds et des pods, ainsi que les logs des conteneurs, à l’aide de composants comme kubeletstats, hostmetrics et les Kubernetes attribute processors. Ces collecteurs enrichissent les logs avec des métadonnées et les envoient à HyperDX via l’exporteur OTLP.

Ensemble, ces manifests permettent une observabilité full-stack à l’échelle du cluster, de l’infrastructure jusqu’à la télémétrie applicative, et transmettent les données enrichies à ClickStack pour une analyse centralisée.Commencez par installer le collecteur en tant que déploiement :

# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# install the helm chart
helm install --namespace otel-demo k8s-otel-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yaml

k8s_deployment.yaml

# k8s_deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# We only want one of these collectors - any more and we'd produce duplicate data
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
    # The label's exact name will be the key.
    extractAllPodLabels: true
    # When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
    # The annotation's exact name will be the key.
    extractAllPodAnnotations: true
  # Configures the collector to collect Kubernetes events.
  # Adds the k8sobject receiver to the logs pipeline and collects Kubernetes events by default.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configures the Kubernetes Cluster Receiver to collect cluster-level metrics.
  # Adds the k8s_cluster receiver to the metrics pipeline and adds the necessary rules to ClusteRole.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
  clusterMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT
 
config:
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

Ensuite, déployez le collecteur en tant que DaemonSet pour les métriques et les journaux au niveau des nœuds et des pods :

# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# install the helm chart
helm install --namespace otel-demo k8s-otel-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yaml

k8s_daemonset.yaml

# k8s_daemonset.yaml
mode: daemonset

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
   
# Required to use the kubeletstats cpu/memory utilization metrics
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get
 
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configures the Kubernetes Processor to add Kubernetes metadata.
  # Adds the k8sattributes processor to all the pipelines and adds the necessary rules to ClusterRole.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
    # The label's exact name will be the key.
    extractAllPodLabels: true
    # When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
    # The annotation's exact name will be the key.
    extractAllPodAnnotations: true
  # Configures the collector to collect node, pod, and container metrics from the API server on a kubelet..
  # Adds the kubeletstats receiver to the metrics pipeline and adds the necessary rules to ClusterRole.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
  kubeletMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  receivers:
    # Configures additional kubelet metrics
    kubeletstats:
      collection_interval: 20s
      auth_type: 'serviceAccount'
      endpoint: '${env:K8S_NODE_NAME}:10250'
      insecure_skip_verify: true
      metrics:
        k8s.pod.cpu_limit_utilization:
          enabled: true
        k8s.pod.cpu_request_utilization:
          enabled: true
        k8s.pod.memory_limit_utilization:
          enabled: true
        k8s.pod.memory_request_utilization:
          enabled: true
        k8s.pod.uptime:
          enabled: true
        k8s.node.uptime:
          enabled: true
        k8s.container.cpu_limit_utilization:
          enabled: true
        k8s.container.cpu_request_utilization:
          enabled: true
        k8s.container.memory_limit_utilization:
          enabled: true
        k8s.container.memory_request_utilization:
          enabled: true
        container.uptime:
          enabled: true
 
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
 
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

Explorer les données Kubernetes dans HyperDX

Accédez à votre interface HyperDX, soit en utilisant votre instance déployée dans Kubernetes, soit via Managed ClickStack.

Managed ClickStack

Si vous utilisez Managed ClickStack, connectez-vous simplement à votre service ClickHouse Cloud et sélectionnez “ClickStack” dans le menu de gauche. Vous serez automatiquement authentifié et n’aurez pas besoin de créer d’utilisateur.Les sources de données pour les logs, les métriques et les traces seront créées à l’avance pour vous.

ClickStack Open Source

Pour accéder à l’instance HyperDX déployée localement, vous pouvez effectuer une redirection de port à l’aide de la commande suivante, puis accéder à HyperDX à l’adresse http://localhost:8080.

kubectl port-forward \
 pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}' -n otel-demo) \
  8080:3000 \
 -n otel-demo

ClickStack en productionEn production, nous recommandons d’utiliser un Ingress avec TLS si vous n’utilisez pas Managed ClickStack. Par exemple :

helm upgrade my-hyperdx hyperdx/hdx-oss-v2 \
--set hyperdx.ingress.enabled=true \
--set hyperdx.ingress.host=your-domain.com \
--set hyperdx.ingress.tls.enabled=true

Pour explorer les données Kubernetes, accédez au tableau de bord dédié disponible à l’adresse /kubernetes, par exemple http://localhost:8080/kubernetes.Chacun des onglets — Pods, Nodes et Namespaces — doit contenir des données.

​Prérequis

​Options de déploiement

​Installer cert-manager (facultatif)

​Déployer l’OpenTelemetry Demo (facultatif)

​Architecture de la démonstration

​Ajouter le dépôt du chart Helm ClickStack

​Déployer ClickStack

​Accéder à l’interface HyperDX

​Récupérer la clé API d’ingestion

​Créer un secret Kubernetes pour l’API key

​Ajouter le dépôt Helm OpenTelemetry

​Déployer les composants du collector Kubernetes

​Explorer les données Kubernetes dans HyperDX

Prérequis

Options de déploiement

Installer cert-manager (facultatif)

Déployer l’OpenTelemetry Demo (facultatif)

Architecture de la démonstration

Ajouter le dépôt du chart Helm ClickStack

Déployer ClickStack

Accéder à l’interface HyperDX

Récupérer la clé API d’ingestion

Créer un secret Kubernetes pour l’API key

Ajouter le dépôt Helm OpenTelemetry

Déployer les composants du collector Kubernetes

Explorer les données Kubernetes dans HyperDX