Kubernetes

Integración de Kubernetes para ClickStack: la pila de observabilidad de ClickHouse

ClickStack usa el OTel collector de OpenTelemetry (OTel) para recopilar logs, métricas y eventos de Kubernetes de los clústeres de Kubernetes y reenviarlos a ClickStack. Admitimos el formato nativo de logs de OTel y no se requiere ninguna configuración adicional específica de proveedores.

Esta guía integra lo siguiente:

• Logs
• Métricas de infraestructura

Para enviar métricas de aplicación o APM/traces, también tendrás que añadir a tu aplicación la integración correspondiente para su lenguaje.

La siguiente guía asume que has desplegado un ClickStack OTel collector como gateway, protegido con una API key de ingesta.

​

Creación de los archivos de configuración del gráfico de Helm de OTel

Para recopilar logs y métricas tanto de cada nodo como del propio clúster, necesitaremos desplegar dos colectores de OpenTelemetry independientes. Uno se desplegará como un conjunto de daemon para recopilar logs y métricas de cada nodo, y el otro se desplegará como una Implementación para recopilar logs y métricas del propio clúster.

​

Crear un secret para la API key

Crea un nuevo secret de Kubernetes con la API key de ingesta de HyperDX. Los componentes instalados a continuación lo usarán para ingerir de forma segura en tu ClickStack OTel collector:

kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \

Además, cree un ConfigMap con la ubicación de su ClickStack OTel collector:

kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=<OTEL_COLLECTOR_ENDPOINT>
# p. ej. kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318

​

Crear la configuración del conjunto de daemon

El conjunto de daemon recopilará logs y métricas de cada nodo del clúster, pero no recopilará eventos de Kubernetes ni métricas de todo el clúster.

Descargue el manifiesto del conjunto de daemon:

curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml

ClickStack gestionado

k8s_daemonset.yaml

# daemonset.yaml
mode: daemonset

# Obligatorio para usar las métricas de utilización de CPU/memoria de kubeletstats
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get

presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configura el procesador de Kubernetes para añadir metadatos de Kubernetes.
  # Añade el procesador k8sattributes a todas las canalizaciones y agrega las reglas necesarias al Rol de clúster.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # Cuando está habilitado, el procesador extraerá todas las etiquetas de un pod asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la etiqueta será la clave.
    extractAllPodLabels: true
    # Cuando está habilitado, el procesador extraerá todas las anotaciones de un pod asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la anotación será la clave.
    extractAllPodAnnotations: true
  # Configura el collector para recopilar métricas de nodo, pod de Kubernetes y contenedor desde el servidor API de un agente kubelet.
  # Añade el receiver kubeletstats a la canalización de métricas y agrega las reglas necesarias al Rol de clúster.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
  kubeletMetrics:
    enabled: true

extraEnvs:
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  receivers:
    # Configura métricas adicionales de kubelet
    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

  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

ClickStack Open Source

k8s_daemonset.yaml

# daemonset.yaml
mode: daemonset

# Necesario para usar las métricas de utilización de CPU/memoria de kubeletstats
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get

presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configura el procesador de Kubernetes para añadir metadatos de Kubernetes.
  # Añade el procesador k8sattributes a todas las canalizaciones y agrega las reglas necesarias al Rol de clúster.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # Cuando está habilitado, el procesador extraerá todas las etiquetas de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la etiqueta será la clave.
    extractAllPodLabels: true
    # Cuando está habilitado, el procesador extraerá todas las anotaciones de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la anotación será la clave.
    extractAllPodAnnotations: true
  # Configura el collector para recopilar métricas de nodos, pods de Kubernetes y contenedores desde el servidor de API de un agente kubelet.
  # Añade el receiver kubeletstats a la canalización de métricas y agrega las reglas necesarias al Rol de clúster.
  # Más información: 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:
    # Configura métricas adicionales de kubelet
    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}"
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
      compression: gzip

  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

​

Crear la configuración de la implementación

Para recopilar eventos de Kubernetes y métricas de todo el clúster, necesitaremos desplegar un colector de OpenTelemetry independiente mediante una implementación.

Descargue el manifiesto de la implementación:

curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml

Managed ClickStack

k8s_deployment.yaml

# deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# Solo queremos uno de estos colectores; si hubiera más, produciríamos datos duplicados
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # Cuando está habilitado, el procesador extraerá todas las etiquetas de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la etiqueta será la clave.
    extractAllPodLabels: true
    # Cuando está habilitado, el procesador extraerá todas las anotaciones de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la anotación será la clave.
    extractAllPodAnnotations: true
  # Configura el colector para recopilar eventos de Kubernetes.
  # Añade el k8sobject receiver a la canalización de logs y recopila eventos de Kubernetes de forma predeterminada.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configura Kubernetes Cluster Receiver para recopilar métricas a nivel de clúster.
  # Añade el k8s_cluster receiver a la canalización de métricas y agrega las reglas necesarias a ClusterRole.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
  clusterMetrics:
    enabled: true

extraEnvs:
  - 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
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

ClickStack Open Source

k8s_deployment.yaml

# deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# Solo queremos uno de estos colectores; si hubiera más, produciríamos datos duplicados
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # Cuando está habilitado, el procesador extraerá todas las etiquetas de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la etiqueta será la clave.
    extractAllPodLabels: true
    # Cuando está habilitado, el procesador extraerá todas las anotaciones de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la anotación será la clave.
    extractAllPodAnnotations: true
  # Configura el colector para recopilar eventos de Kubernetes.
  # Añade el k8sobject receiver a la canalización de logs y recopila eventos de Kubernetes de forma predeterminada.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configura Kubernetes Cluster Receiver para recopilar métricas a nivel de clúster.
  # Añade el k8s_cluster receiver a la canalización de métricas y agrega las reglas necesarias a ClusterRole.
  # Más información: 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

​

Despliegue del colector de OpenTelemetry

Ahora puede desplegar el colector de OpenTelemetry en su clúster de Kubernetes mediante el gráfico de Helm de OpenTelemetry.

Agregue el repositorio de Helm de OpenTelemetry:

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts # Agregar repositorio de Helm de OTel

Instala el chart con la configuración anterior:

copy

helm install my-opentelemetry-collector-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yaml
helm install my-opentelemetry-collector-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yaml

Ahora deberían aparecer en HyperDX las métricas, los logs y los eventos de Kubernetes de tu clúster de Kubernetes.

​

Reenvío de etiquetas de recurso a los pods (Recomendado)

Para correlacionar logs, métricas y trazas de la aplicación con los metadatos de Kubernetes (p. ej., nombre del pod, espacio de nombres, etc.), conviene reenviar los metadatos de Kubernetes a tu aplicación mediante la variable de entorno OTEL_RESOURCE_ATTRIBUTES.

A continuación se muestra una implementación de ejemplo que reenvía los metadatos de Kubernetes a la aplicación mediante variables de entorno:

# my_app_deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
        # Combinado con el Kubernetes Attribute Processor, esto garantizará
        # que los logs y las métricas del pod se asocien con un nombre de servicio.
        service.name: <MY_APP_NAME>
    spec:
      containers:
        - name: app-container
          image: my-image
          env:
            # ... otras variables de entorno
            # Recopilar metadatos de K8s desde la downward API para reenviarlos a la aplicación
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: POD_UID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: DEPLOYMENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['deployment']
            # Reenviar los metadatos de K8s a la aplicación mediante OTEL_RESOURCE_ATTRIBUTES
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: k8s.pod.name=$(POD_NAME),k8s.pod.uid=$(POD_UID),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(NODE_NAME),k8s.deployment.name=$(DEPLOYMENT_NAME)