Configurar Zabbix 7.4 para monitorizar Kubernetes / OpenShift mediante la API Server (sin Helm)

Introducción

En este artículo voy a explicar cómo configurar correctamente la monitorización de un clúster Kubernetes/OpenShift desde Zabbix 7.4.13, utilizando los templates oficiales de Zabbix y sin desplegar la solución mediante Helm.

Durante la instalación me encontré con varios problemas que no aparecen claramente documentados y que provocan errores bastante confusos, como:

• Cannot perform request: Failed to connect to localhost:6443
• cannot apply Prometheus pattern
• Connection timed out
• 401 Unauthorized
• 403 Forbidden

Después de realizar numerosas pruebas, conseguimos identificar cuál era realmente el problema y la configuración correcta.

Este artículo pretende servir como guía para cualquier administrador que quiera integrar Zabbix con OpenShift de forma sencilla.

Arquitectura utilizada para desplegar Zabbix 7.4 en GKE – Google Cloud

La instalación utilizada es la siguiente:

• Zabbix Server 7.4.13
• OpenShift 4.x
• Zabbix desplegado dentro del propio clúster como Deployment
• Sin Helm
• Templates oficiales de Zabbix

El primer objetivo fue monitorizar únicamente el API Server utilizando el template oficial:

Template: Kubernetes API server by HTTP

Una vez funcionando correctamente, posteriormente podrán añadirse el resto de templates.

Crear un ServiceAccount para Zabbix

Lo primero es crear un ServiceAccount que utilizará Zabbix para autenticarse contra la API de Kubernetes.

Ejemplo:

oc create sa monitoritgt -n <namespace>

Posteriormente se asignan los permisos necesarios.

En nuestro caso utilizamos un ServiceAccount con permisos suficientes para consultar la API.

Obtener el token del ServiceAccount

Obtenemos el token mediante:

oc create token monitoritgt -n <namespace>

Este token será el valor de la macro:

{$KUBE.API.TOKEN}

Importante:

El valor de la macro debe contener únicamente el JWT.

Incorrecto:

Bearer eyJhbGc...

Correcto:

eyJhbGc...

El propio template ya añade automáticamente la cabecera:

Authorization: Bearer {$KUBE.API.TOKEN}

Como crear un nuevo host en Zabbix 7.4

Desde la interfaz gráfica vamos a Data Collection > Host > Añadir nuevo

Creamos un nuevo host.

Asociamos únicamente el template:

Kubernetes API server by HTTP

No añadir todavía otras templates, de esta forma es mucho más sencillo localizar cualquier problema.

Configurar las macros del host para comunicar zabbix directamente con kubernetes

Configurar las siguientes macros:

URL del API Server

{$KUBE.API.SERVER.URL}

Valor:

https://kubernetes.default.svc/metrics

Este punto es muy importante. inicialmente configuramos:

https://kubernetes.default.svc

Lo que provocaba errores de preprocesado, el template espera directamente el endpoint Prometheus, no la raíz de la API.

Token

{$KUBE.API.TOKEN}

Valor:

<JWT del ServiceAccount>

Sin el prefijo Bearer.

Pruebas de conectividad realizadas

Antes de continuar con la configuración verificamos toda la conectividad desde el propio contenedor del Zabbix Server.

Es importante realizar estas pruebas desde el contenedor donde se ejecuta el proceso zabbix_server.

Comprobar resolución DNS

getent hosts kubernetes.default.svc

Resultado esperado:

172.30.0.1 kubernetes.default.svc.cluster.local

Observación:

En imágenes basadas en BusyBox es habitual que:

nslookup kubernetes.default.svc

devuelva:

NXDOMAIN

Sin que ello signifique ningún problema.

Comprobar conectividad con la API

wget -S --spider --no-check-certificate https://kubernetes.default.svc

Resultado esperado:

HTTP/1.1 403 Forbidden

Este resultado es correcto.

Significa que:

• existe conectividad
• TLS funciona
• el API Server responde

Verificar el token

TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)

wget -qO- \
--header="Authorization: Bearer $TOKEN" \
--no-check-certificate \
https://kubernetes.default.svc/version

Debe devolver un JSON con la versión del clúster.

Ejemplo:

{
  "major":"1",
  "minor":"31"
}

Verificar permisos sobre la API

wget -qO- \
--header="Authorization: Bearer $TOKEN" \
--no-check-certificate \
https://kubernetes.default.svc/api/v1/nodes

Debe devolver el listado completo de nodos.

Si esto funciona:

• el token es correcto
• el ServiceAccount tiene permisos
• el RBAC está correctamente configurado

Verificar el endpoint de métricas

wget -qO- \
--header="Authorization: Bearer $TOKEN" \
--no-check-certificate \
https://kubernetes.default.svc/metrics

Debe devolver texto en formato Prometheus.

Ejemplo:

# HELP aggregator_discovery_aggregation_count_total
# TYPE aggregator_discovery_aggregation_count_total counter

aggregator_discovery_aggregation_count_total 313

Si devuelve un JSON con:

{
  "paths":[

entonces se está consultando la raíz del API y no el endpoint correcto.

Error al conectar zabbix 7.4 con kubernetes

El error que más tiempo nos llevó localizar fue el siguiente:

Failed: cannot apply Prometheus pattern

El detalle mostraba algo parecido a:

{
  "paths":[
    "/api",
    "/apis",
...

Este error no estaba relacionado con:

• permisos
• ServiceAccount
• token
• SSL
• conectividad

El problema era mucho más simple.

El template esperaba recibir métricas Prometheus.

Sin embargo, estaba recibiendo la respuesta JSON de la raíz del API Server.

La solución consistió en configurar la macro:

{$KUBE.API.SERVER.URL}

con el valor:

https://kubernetes.default.svc/metrics

En lugar de:

https://kubernetes.default.svc

Comprobar que la configuración funciona

Una vez corregida la macro, los ítems comenzaron a recoger datos correctamente.

Por ejemplo:

• CPU
• Resident memory
• Virtual memory
• API server requests
• Authentication attempts
• Audit events
• TLS handshake errors
• Goroutines
• Go threads
• gRPC metrics

Esto confirma que Zabbix ya está leyendo correctamente las métricas Prometheus del API Server.

¿Y el template Kubernetes cluster state by HTTP?

Una vez validado el API Server, el siguiente paso consiste en añadir el template:

Kubernetes cluster state by HTTP

Este template descubre automáticamente:

• Nodes
• Pods
• Namespaces
• Deployments
• DaemonSets
• StatefulSets
• Jobs

En OpenShift algunos ítems relacionados con los kubelets pueden requerir ajustes adicionales, ya que el acceso directo a determinados endpoints puede estar restringido por la configuración del clúster.

Por este motivo es recomendable validar primero el template del API Server y únicamente después añadir el resto.

Conclusiones y comentarios tras la conexión de nuestro Zabbix 7.4 para obtener métricas del cluster de Kubernetes

Tras varias horas de pruebas, la conclusión principal fue que el problema nunca estuvo en Kubernetes ni en OpenShift.

La conectividad era correcta desde el principio.

El ServiceAccount también.

El token funcionaba correctamente.

El error estaba provocado por una configuración incorrecta de la macro utilizada por el template oficial.

Una vez apuntando directamente al endpoint /metrics, Zabbix comenzó a interpretar correctamente las métricas Prometheus y la monitorización empezó a funcionar sin necesidad de modificar el template oficial.

Si vas a desplegar Zabbix 7.4.13 sobre OpenShift sin Helm, mi recomendación es validar siempre primero la conectividad desde el propio contenedor del Zabbix Server y añadir los templates de forma progresiva. Este enfoque permite localizar rápidamente cualquier problema y evita invertir tiempo en depurar errores que, como en este caso, se reducen a una única macro mal configurada.