> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitorización de Kubernetes
> Primeros pasos con ClickStack y la monitorización de Kubernetes
export const Image = ({img, alt, size}) => {
return
;
};
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](https://helm.sh/)** 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**](https://github.com/ClickHouse/opentelemetry-demo). 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](https://cert-manager.io/) con Helm:
```shell theme={null}
# Agregar repositorio de Cert Manager
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](/es/clickstack/integration-examples/kubernetes#forwarding-resouce-tags-to-pods) para correlacionar logs, métricas y trazas mediante la variable de entorno `OTEL_RESOURCE_ATTRIBUTES`.
```shell theme={null}
## descargar el archivo de manifiesto de Kubernetes del demo
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# alternativa con wget
# 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`:
```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
```
### 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](/es/clickstack/ingesting-data/sdks).
*Crédito: [https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
Puedes encontrar más detalles sobre la demo en:
* [Documentación de OpenTelemetry](https://opentelemetry.io/docs/demo/)
* [fork mantenido por ClickStack](https://github.com/ClickHouse/opentelemetry-demo)
### Añade el repositorio del gráfico de Helm de ClickStack
Para implementar ClickStack, usamos el [gráfico de Helm oficial](/es/clickstack/deployment/helm).
Para ello, debemos añadir el repositorio de Helm de HyperDX:
```shell theme={null}
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.
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
Puede que necesites ajustar `storageClassName` según la configuración de tu clúster de Kubernetes.
Si no vas a implementar la demo de OTel, puedes modificar esto y seleccionar un espacio de nombres adecuado.
```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 producción**
Este gráfico también instala ClickHouse y el OTel collector. Para producción, se recomienda usar los operadores de ClickHouse y del OTel collector, y/o usar Managed ClickStack.
Para deshabilitar ClickHouse y el OTel collector, establece los siguientes valores:
```shell theme={null}
helm install myrelease --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false
```
Si prefieres usar Managed ClickStack, puedes implementar ClickStack y [deshabilitar el ClickHouse incluido](/es/clickstack/deployment/helm#using-clickhouse-cloud).
Actualmente, el gráfico siempre implementa tanto HyperDX como MongoDB. Aunque estos componentes ofrecen una vía de acceso alternativa, no están integrados con la autenticación de ClickHouse Cloud. En este modelo de implementación, estos componentes están pensados para administradores, ya que [proporcionan acceso a la clave segura de ingestión](#retrieve-ingestion-api-key) necesaria para ingestar a través del OTel collector implementado, pero no deberían exponerse a los usuarios finales.
```shell theme={null}
# especifica las credenciales de ClickHouse Cloud
export CLICKHOUSE_URL= # URL https completa
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
```
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:
```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
```
### Acceder a la UI de HyperDX
Incluso si usas Managed ClickStack, la instancia local de HyperDX desplegada en el clúster de Kubernetes sigue siendo necesaria. Proporciona una clave de ingestión gestionada por el servidor OpAMP incluido con HyperDX, lo que protege la ingestión a través del OTel collector desplegado, una capacidad que actualmente no está disponible en Managed ClickStack.
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.
```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
```
Acceda a [http://localhost:8080](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.
### 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`](http://localhost:8080/team) 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.
### 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:
```shell theme={null}
# crear el secret con la API key de ingesta
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY= \
-n otel-demo
# crear un ConfigMap que apunte al ClickStack OTel collector desplegado anteriormente
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.
```shell theme={null}
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.
### 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:
```shell theme={null}
# Agregar el repositorio Helm de OTel
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:
```shell theme={null}
# descargar el archivo de manifiesto
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# instalar el gráfico de Helm
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
# Solo queremos uno de estos collectors; con más, se generarían datos duplicados
replicaCount: 1
presets:
kubernetesAttributes:
enabled: true
# Cuando está habilitado, el procesador extraerá todas las labels de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
# El nombre exacto de la label será la clave.
extractAllPodLabels: true
# Cuando está habilitado, el procesador extraerá todas las annotations de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
# El nombre exacto de la annotation será la clave.
extractAllPodAnnotations: true
# Configura el collector 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 el 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 e incorpora las reglas necesarias a ClusteRole.
# 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
```
A continuación, despliega el collector como un conjunto de daemon para métricas y logs a nivel de nodo y pod:
```shell theme={null}
# descargar el archivo de manifiesto
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# instalar el gráfico de Helm
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
# 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 agregar metadatos de Kubernetes.
# Agrega el procesador k8sattributes a todas las canalizaciones y añade 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 del 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 del pod asociado y las añadirá como atributos de recurso.
# El nombre exacto de la anotación será la clave.
extractAllPodAnnotations: true
# Configura el recopilador para obtener métricas de nodo, pod y contenedor desde el servidor de API en un agente kubelet.
# Agrega el receiver kubeletstats a la canalización de métricas y añade 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 del agente 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
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.
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.
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](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 producción**
En producción, recomendamos usar un Ingreso con TLS si no estás usando Managed ClickStack. Por ejemplo:
```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
```
Para explorar los datos de Kubernetes, ve al dashboard predefinido específico en `/kubernetes`, por ejemplo [http://localhost:8080/kubernetes](http://localhost:8080/kubernetes).
Cada una de las pestañas, Pods, Nodos y Espacios de nombres, debería mostrar datos.