Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Monitorización de Kubernetes

Esta guía le permite recopilar logs y métricas de su sistema Kubernetes y enviarlos a ClickStack para su visualización y análisis. Para los datos de demostración, usamos opcionalmente el fork de ClickStack de la demo oficial de OpenTelemetry.

Requisitos previos

Para seguir esta guía, necesitas tener:

  • Un clúster de Kubernetes (se recomienda v1.20+) con al menos 32 GiB de RAM y 100 GB de espacio en disco disponibles en un nodo para ClickHouse.
  • Helm v3+
  • kubectl, configurado para interactuar con tu clúster

Opciones de implementación

Puedes seguir esta guía con cualquiera de las siguientes opciones de implementación:

  • Open Source ClickStack: implementa ClickStack por completo dentro de tu clúster de Kubernetes, lo que incluye:

    • ClickHouse
    • HyperDX
    • MongoDB (utilizado para el estado y la configuración del dashboard)
  • Managed ClickStack, con ClickHouse y la UI de ClickStack (HyperDX) gestionados en ClickHouse Cloud. Esto elimina la necesidad de ejecutar ClickHouse o HyperDX dentro de tu clúster.

Para simular tráfico de la aplicación, opcionalmente puedes implementar el fork de ClickStack de la OpenTelemetry Demo Application. Esto genera datos de telemetría, incluidos logs, métricas y trazas. Si ya tienes workloads en ejecución en tu clúster, puedes omitir este paso y supervisar los pods, nodos y contenedores existentes.

Instalar cert-manager (opcional)

Si su implementación requiere certificados TLS, instale cert-manager con 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

Despliega OpenTelemetry Demo (opcional)

Este paso es opcional y está pensado para cuando no tienes pods que supervisar. Aunque los usuarios que ya tienen servicios desplegados en su entorno de Kubernetes pueden omitirlo, esta demo sí incluye microservicios instrumentados que generan datos de trazas y session replay, lo que permite explorar todas las funcionalidades de ClickStack.

A continuación se despliega el fork de ClickStack de la pila de aplicaciones OpenTelemetry Demo en un clúster de Kubernetes, adaptado para pruebas de observabilidad y para mostrar la instrumentación. Incluye microservicios de backend, generadores de carga, pipelines de telemetría, infraestructura de soporte (p. ej., Kafka, Redis) e integraciones de SDK con ClickStack.

Todos los servicios se despliegan en el espacio de nombres otel-demo. Cada implementación incluye:

  • Instrumentación automática con OTel y ClickStack SDKS para trazas, métricas y logs.
  • Todos los servicios envían su instrumentación a un colector de OpenTelemetry my-hyperdx-hdx-oss-v2-otel-collector (no desplegado)
  • Reenvío de etiquetas de recurso para correlacionar logs, métricas y trazas mediante la variable de entorno 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

Tras desplegar la demo, confirme que todos los pods se hayan creado correctamente y estén en estado 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

Arquitectura de la demo

La demo se compone de microservicios escritos en distintos lenguajes de programación que se comunican entre sí mediante gRPC y HTTP, además de un generador de carga que usa Locust para simular tráfico de usuarios. El código fuente original de esta demo se ha modificado para usar la instrumentación de ClickStack.

Arquitectura

Crédito: https://opentelemetry.io/docs/demo/architecture/

Puedes encontrar más detalles sobre la demo en:

Añade el repositorio del gráfico de Helm de ClickStack

Para implementar ClickStack, usamos el gráfico de Helm oficial.

Para ello, debemos añadir el repositorio de Helm de HyperDX:

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

Implementar ClickStack

Con el gráfico de Helm instalado, puedes implementar ClickStack en tu clúster. Puedes ejecutar todos los componentes, incluidos ClickHouse y HyperDX, dentro de tu entorno de Kubernetes, o bien implementar solo el collector y usar Managed ClickStack para ClickHouse y la interfaz de HyperDX.


ClickStack Open Source (autogestionado)

El siguiente comando instala ClickStack en el espacio de nombres otel-demo. El gráfico de Helm implementa:

  • Una instancia de ClickHouse
  • HyperDX
  • La distribución de ClickStack del OTel collector
  • MongoDB para almacenar el estado de la aplicación HyperDX

Si no vas a implementar la demo de OTel, puedes modificar esto y seleccionar un espacio de nombres adecuado.

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

Si prefieres usar Managed ClickStack, puedes implementar ClickStack y deshabilitar el ClickHouse incluido.

# especifica las credenciales de ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # URL https completa
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

Para verificar el estado de la implementación, ejecuta el siguiente comando y confirma que todos los componentes estén en estado Running. Ten en cuenta que ClickHouse no aparecerá si estás usando 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

Acceder a la UI de HyperDX

Por seguridad, el servicio usa ClusterIP y no se expone externamente de forma predeterminada.

Para acceder a la UI de HyperDX, redirige el puerto 3000 al puerto 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

Acceda a http://localhost:8080 para abrir la UI de HyperDX.

Cree un usuario e indique un nombre de usuario y una contraseña que cumplan los requisitos de complejidad.

UI de HyperDX

Obtener la API key de ingesta

La ingestión en el OTel collector desplegado por el ClickStack collector está protegida con una API key de ingesta.

Ve a Configuración del equipo y copia la API key de ingesta de la sección API Keys. Esta API key garantiza una ingestión de datos segura a través del OpenTelemetry collector.

Copiar API key

Crear un Secret de Kubernetes para la API key

Cree un nuevo Secret de Kubernetes con la API key de ingesta y un ConfigMap que contenga la ubicación del OTel collector desplegado con el gráfico de Helm de ClickStack. Los componentes posteriores lo usarán para permitir la ingesta en el collector desplegado con el gráfico de Helm de 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

Reinicie los pods de OpenTelemetry Demo Application para que apliquen la API key de ingesta.

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

Las trazas y los logs de los servicios de demostración deberían empezar a llegar a HyperDX.

Datos de Kubernetes en HyperDX

Añade el repositorio de Helm de OpenTelemetry

Para recopilar métricas de Kubernetes, implementaremos un OTel collector estándar y lo configuraremos para enviar datos de forma segura a nuestro ClickStack collector mediante la API key de ingesta anterior.

Para ello, debemos instalar el repositorio de Helm de OpenTelemetry:

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

Desplegar los componentes del collector de Kubernetes

Para recopilar logs y métricas tanto del clúster en sí como de cada nodo, es necesario implementar dos OpenTelemetry collectors independientes, cada uno con su propio manifiesto. Los dos manifiestos proporcionados — k8s_deployment.yaml y k8s_daemonset.yaml — trabajan en conjunto para recopilar datos de telemetría exhaustivos de su clúster de Kubernetes.

  • k8s_deployment.yaml implementa una sola instancia de OpenTelemetry Collector responsable de recopilar eventos y metadatos de todo el clúster. Recopila eventos de Kubernetes, métricas del clúster y enriquece los datos de telemetría con etiquetas y anotaciones de los pods de Kubernetes. Este collector se ejecuta como una implementación independiente con una sola réplica para evitar la duplicación de datos.

  • k8s_daemonset.yaml despliega un colector basado en conjunto de daemon que se ejecuta en cada nodo de su clúster. Recopila métricas a nivel de nodo y de pod de Kubernetes, así como logs de contenedores, mediante componentes como kubeletstats, hostmetrics y procesadores Kubernetes Attribute Processor. Estos colectores enriquecen los logs con metadatos y los envían a HyperDX mediante el exportador OTLP.

En conjunto, estos manifiestos habilitan la observabilidad de pila completa en todo el clúster, desde la infraestructura hasta la telemetría a nivel de aplicación, y envían los datos enriquecidos a ClickStack para su análisis centralizado.

Primero, instale el colector como una implementación:

# 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

A continuación, despliega el collector como un conjunto de daemon para métricas y logs a nivel de nodo y pod:

# 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

Explora los datos de Kubernetes en HyperDX

Ve a tu UI de HyperDX, ya sea usando tu instancia desplegada en Kubernetes o a través de Managed ClickStack.

Managed ClickStack

Si usas Managed ClickStack, simplemente inicia sesión en tu servicio de ClickHouse Cloud y selecciona "ClickStack" en el menú de la izquierda. La autenticación será automática y no necesitarás crear un usuario.

Las fuentes de datos para logs, métricas y trazas se crearán previamente para ti.

ClickStack Open Source

Para acceder a HyperDX desplegado localmente, puedes usar el reenvío de puertos con el siguiente comando y acceder a HyperDX en 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

Para explorar los datos de Kubernetes, ve al dashboard predefinido específico en /kubernetes, por ejemplo http://localhost:8080/kubernetes.

Cada una de las pestañas, Pods, Nodos y Espacios de nombres, debería mostrar datos.

ClickHouse en Kubernetes
Navigation