> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Supervision de Kubernetes
> Prise en main de ClickStack et de la supervision de Kubernetes
export const Image = ({img, alt, size}) => {
return
;
};
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](https://helm.sh/)** 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**](https://github.com/ClickHouse/opentelemetry-demo). 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](https://cert-manager.io/) à l’aide de Helm :
```shell theme={null}
# 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](/fr/clickstack/integration-examples/kubernetes#forwarding-resouce-tags-to-pods) afin de corréler les logs, les métriques et les traces via la variable d’environnement `OTEL_RESOURCE_ATTRIBUTES`.
```shell theme={null}
## 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` :
```shell theme={null}
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](/fr/clickstack/ingesting-data/sdks/index).
*Crédit : [https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
Vous trouverez plus de détails sur cette démonstration dans :
* [la documentation d’OpenTelemetry](https://opentelemetry.io/docs/demo/)
* [le fork maintenu par ClickStack](https://github.com/ClickHouse/opentelemetry-demo)
### Ajouter le dépôt du chart Helm ClickStack
Pour déployer ClickStack, nous utilisons le [chart Helm officiel](/fr/clickstack/deployment/helm).
Pour cela, il faut ajouter le dépôt Helm HyperDX :
```shell theme={null}
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.
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é.
```shell theme={null}
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demo
```
**ClickStack en production**
Ce 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 :
```shell theme={null}
helm install myrelease --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false
```
Si vous préférez utiliser Managed ClickStack, vous pouvez déployer ClickStack et [désactiver le ClickHouse inclus](/fr/clickstack/deployment/helm#using-clickhouse-cloud).
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](#retrieve-ingestion-api-key) 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.
```shell theme={null}
# spécifier les identifiants ClickHouse Cloud
export CLICKHOUSE_URL= # URL https complète
export CLICKHOUSE_USER=
export 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 :
```shell theme={null}
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.
```shell theme={null}
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](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`](http://localhost:8080/team) 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 :
```shell theme={null}
# create secret with the ingestion API key
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_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.
```shell theme={null}
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 :
```shell theme={null}
# 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 :
```shell theme={null}
# 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
```
```yaml theme={null}
# 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 :
```shell theme={null}
# 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
```
```yaml theme={null}
# 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.
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.
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](http://localhost:8080).
```shell theme={null}
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 production**
En production, nous recommandons d'utiliser un Ingress avec TLS si vous n'utilisez pas Managed ClickStack. Par exemple :
```shell theme={null}
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](http://localhost:8080/kubernetes).
Chacun des onglets — Pods, Nodes et Namespaces — doit contenir des données.