HAProxy Discovery

Este documento describe el uso y configuración del plugin de discovery para HAProxy.

Introducción

Este plugin de discovery de HAProxy para Pandora FMS está diseñado para automatizar la monitorización de tus balanceadores HAProxy, aprovechando la información detallada que proporciona el endpoint de estadísticas en formato CSV (/stats;csv). Al interactuar con dicho endpoint, el plugin puede recopilar métricas en tiempo real que son cruciales para entender el rendimiento y la salud de tu entorno HAProxy, incluyendo sesiones, bytes transferidos, errores, cola, comprobaciones de salud y mucho más. Por cada URL de HAProxy se creará un agente en Pandora FMS, con un módulo por cada métrica disponible.

Prerrequisitos

Parámetros

Modo simple

--urlsURLs del endpoint de estadísticas de HAProxy, separadas por comas. Cada URL generará un agente.
--usernombre del usuario si el endpoint de HAProxy requiere autenticación básica, opcional
--passwordcontraseña si el endpoint de HAProxy requiere autenticación básica, opcional
--sslpara verificar si la URL tiene certificado HTTPS o no, opcional
--prefixprefijo para los nombres de los módulos, opcional
--transfer_modemodo de transferencia de datos (native o tentacle), opcional
--tentacle_ipip del tentacle, opcional
--tentacle_portpuerto del tentacle, opcional
--intervalintervalo de monitorización en segundos, opcional
--allow_listexpresión regular para incluir únicamente los módulos cuyo nombre coincida, opcional
--deny_listexpresión regular para excluir módulos cuyo nombre coincida, opcional
--monitor_frontendsmonitorizar filas de tipo frontend (type=0), opcional
--monitor_backendsmonitorizar filas de tipo backend (type=1), opcional
--monitor_serversmonitorizar filas de tipo server (type=2), opcional

Modo avanzado

--confruta del archivo de configuración
--conf_targetsruta del archivo con las URLs de HAProxy (obligatorio al usar --conf)

Archivo de configuración (--conf)

username= nombre del usuario si el endpoint de HAProxy requiere autenticación básica, opcional
password= contraseña si el endpoint de HAProxy requiere autenticación básica, opcional
verify_ssl= para verificar si la URL tiene certificado HTTPS o no, opcional
prefix= prefijo para los nombres de los módulos, opcional
transfer_mode= modo de transferencia de datos (native o tentacle), opcional
tentacle_ip= ip del tentacle, opcional
tentacle_port= puerto del tentacle, opcional
agents_group= nombre del grupo de agentes al que se asignarán los agentes creados, opcional
agents_group_id= id del grupo de agentes al que se asignarán los agentes creados, opcional
interval= intervalo de monitorización en segundos, opcional
allow_list= expresión regular para incluir únicamente los módulos cuyo nombre coincida, opcional
deny_list= expresión regular para excluir módulos cuyo nombre coincida, opcional
monitor_frontends= monitorizar filas de tipo frontend (type=0), opcional
monitor_backends= monitorizar filas de tipo backend (type=1), opcional
monitor_servers= monitorizar filas de tipo server (type=2), opcional

Ejemplo

[CONF]
username=admin
password=12345
verify_ssl=true
prefix=haproxy_
transfer_mode=native
tentacle_ip=127.0.0.1
tentacle_port=41121
interval=300
allow_list=
deny_list=.*_wredis|.*_wretr
monitor_frontends=true
monitor_backends=true
monitor_servers=true

Archivo de targets (--conf_targets):

http://192.168.0.10:8404/stats
http://192.168.0.11:8404/stats

Configuración de HAProxy

Para que el plugin pueda obtener las estadísticas, HAProxy debe exponer el endpoint /stats;csv. La habilitación se realiza editando el fichero haproxy.cfg (por defecto en /etc/haproxy/haproxy.cfg).

Configuración mínima (sin autenticación, sin SSL)

Añade un frontend dedicado a las estadísticas:

frontend stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s

Con esta configuración el plugin consumirá la URL:

http://<IP_SERVIDOR>:8404/stats

El plugin normaliza automáticamente la URL añadiendo el sufijo ;csv y el parámetro norefresh cuando faltan, por lo que basta con indicar la URL base de stats.

Configuración con autenticación básica

Para proteger el endpoint con usuario y contraseña, define una userlist y aplica http-request auth en el frontend de stats:

frontend stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s

    acl auth_ok http_auth(stats_users)
    http-request auth realm stats if !auth_ok

userlist stats_users
    user admin password $6$rounds=5000$<HASH_SHA512>

Genera el hash de la contraseña con mkpasswd o openssl:

mkpasswd -m sha-256 mypassword
# o bien
openssl passwd -6 mypassword

En el plugin se deberá facilitar ese mismo username y password mediante --user / --password (o los campos username / password del archivo de configuración).

Configuración con SSL/TLS

Para servir las estadísticas sobre HTTPS añade ssl crt al bind:

frontend stats
    bind *:8404 ssl crt /etc/haproxy/certs/stats.pem
    stats enable
    stats uri /stats
    stats refresh 10s

Genera un certificado autofirmado de pruebas con:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/haproxy/certs/stats.key \
  -out /etc/haproxy/certs/stats.crt \
  -subj "/CN=localhost"
cat /etc/haproxy/certs/stats.crt /etc/haproxy/certs/stats.key > /etc/haproxy/certs/stats.pem

En el plugin se indicará la URL con esquema https:// y el parámetro --ssl (o verify_ssl) según se quiera validar el certificado:

Configuración completa (SSL + autenticación)

global
    maxconn 4096

defaults
    mode http
    timeout connect 5s
    timeout client 30s
    timeout server 30s

frontend stats
    bind *:8404 ssl crt /etc/haproxy/certs/stats.pem
    stats enable
    stats uri /stats
    stats refresh 10s
    stats admin if TRUE

    acl auth_ok http_auth(stats_users)
    http-request auth realm stats if !auth_ok

userlist stats_users
    user admin password $6$rounds=5000$<HASH_SHA512>

frontend myapp
    bind *:80
    default_backend servers

backend servers
    server s1 127.0.0.1:8080 check

Tras modificar haproxy.cfg recarga el servicio para aplicar los cambios:

sudo systemctl reload haproxy

Verificación

Para comprobar que el endpoint responde correctamente, puedes hacer una petición manual al CSV de estadísticas:

curl -u admin:mypassword http://192.168.0.10:8404/stats;csv

La salida debe ser un CSV cuyo primer registro es la cabecera con los nombres de las columnas (# pxname,svname,qcur,qmax,...) y las siguientes filas contienen los datos de cada frontend, backend y server.

Ejecución manual

El formato de la ejecución del plugin es el siguiente:

./pandora_haproxy --urls <urls del endpoint de HAProxy separadas por comas> --user <usuario> --password <contraseña> --ssl <true|false> --prefix <prefijo> --transfer_mode <native|tentacle> --tentacle_ip <ip del tentacle> --tentacle_port <puerto del tentacle> --interval <intervalo> --allow_list <regex> --deny_list <regex> --monitor_frontends <true|false> --monitor_backends <true|false> --monitor_servers <true|false> --conf <ruta al fichero de configuración> --conf_targets <ruta al fichero de URLs>

Ejemplos:

para ejecutar el modo simple

./pandora_haproxy --urls http://192.168.0.10:8404/stats,http://192.168.0.11:8404/stats --user admin --password 12345 --ssl false --transfer_mode native --tentacle_ip 127.0.0.1 --tentacle_port 41121

para ejecutar el modo avanzado

./pandora_haproxy --conf /etc/pandora/haproxy.conf --conf_targets /etc/pandora/haproxy_targets.conf

La ejecución devolverá una salida en formato JSON con información sobre la ejecución, y generará un fichero XML por cada agente monitorizado (en modo tentacle) que enviará al servidor de Pandora FMS por el método de transferencia indicado en la configuración. En modo native los datos se exponen en el campo monitoring_data del JSON de salida para que los consuma el servidor de Discovery.

Discovery

Este plugin puede integrarse con el Discovery de Pandora FMS.

Para ello se debe cargar el paquete ".disco" que puede descargar desde la librería de Pandora FMS:

https://pandorafms.com/library/

Una vez cargado, se podrán monitorizar las instancias de HAProxy creando tareas de Discovery desde la sección Management > Discovery > Application > HAProxy

Para cada tarea se solicitarán los siguientes datos mínimos en el paso HAProxy Basic:

En el paso HAProxy Advanced se podrán configurar opciones adicionales:

Las tareas completadas con éxito tendrán un resumen de ejecución con la siguiente información:

Agentes y módulos generados por el plugin

El plugin creará un agente por cada URL de HAProxy indicada. El nombre del agente se calcula aplicando un hash MD5 sobre el netloc de la URL, y el alias se corresponde con dicho netloc (por ejemplo, 192.168.0.10:8404). En cada agente se incluirán los módulos obtenidos al parsear el endpoint CSV de estadísticas de HAProxy.

El módulo status se crea siempre para cada fila, independientemente de los tokens de monitorización, con el fin de alertar ante estados DOWN/MAINT/STOP. El resto de campos numéricos se incluyen como módulos generic_data (enteros/decimal) o generic_data_string (cadenas), siguiendo el formato <pxname>_<svname>_<campo>.

Los principales campos disponibles en el CSV de HAProxy, y que dan lugar a módulos, son:

pxname: Nombre del proxy (frontend/backend/listener).
svname: Nombre del servicio (FRONTEND/BACKEND/server name).
qcur: Peticiones actualmente en cola.
qmax: Máximo de peticiones en cola.
scur: Sesiones actuales.
smax: Máximo de sesiones.
slim: Límite de sesiones configurado.
stot: Sesiones acumuladas.
bin: Bytes recibidos.
bout: Bytes enviados.
dreq: Peticiones denegadas (seguridad).
dresp: Respuestas denegadas (seguridad).
ereq: Errores de petición.
econ: Errores de conexión hacia el backend.
eresp: Errores de respuesta.
wretr: Reintentos de conexión.
wredis: Reenvíos a otro servidor.
status: Estado (UP/DOWN/MAINT/STOP/...) — siempre se monitoriza.
weight: Peso total / peso del servidor.
act: Servidores activos (backend) / servidor activo.
bck: Servidores de backup (backend) / servidor de backup.
chkfail: Chequeos de salud fallidos.
chkdown: Transiciones UP->DOWN.
lastchg: Segundos desde la última transición UP<->DOWN.
downtime: Tiempo total de caída (segundos).
qlimit: Maxqueue configurado para el servidor.
pid: Process ID.
iid: ID único del proxy.
sid: ID del servidor (único dentro del proxy).
throttle: Porcentaje de throttle actual.
lbtot: Veces que el servidor fue seleccionado.
tracked: ID del proxy/servidor si el tracking está habilitado.
type: Tipo (0=frontend, 1=backend, 2=server, 3=socket).
rate: Sesiones por segundo (último segundo).
rate_lim: Límite configurado de nuevas sesiones/s.
rate_max: Máximo de sesiones por segundo.
check_status: Estado del último health check.
check_code: Código del check (capa 5-7).
check_duration: Tiempo en ms del último health check.
hrsp_1xx: Respuestas HTTP con código 1xx.
hrsp_2xx: Respuestas HTTP con código 2xx.
hrsp_3xx: Respuestas HTTP con código 3xx.
hrsp_4xx: Respuestas HTTP con código 4xx.
hrsp_5xx: Respuestas HTTP con código 5xx.
hrsp_other: Respuestas HTTP con otros códigos.
hanafail: Detalle de checks de salud fallidos.
req_rate: Peticiones HTTP por segundo.
req_rate_max: Máximo de peticiones HTTP por segundo.
req_tot: Total de peticiones HTTP recibidas.
cli_abrt: Transferencias abortadas por el cliente.
srv_abrt: Transferencias abortadas por el servidor.
comp_in: Bytes de respuesta HTTP alimentados al compresor.
comp_out: Bytes de respuesta HTTP emitidos por el compresor.
comp_byp: Bytes que pasaron por alto al compresor HTTP.
comp_rsp: Respuestas HTTP que fueron comprimidas.
lastsess: Segundos desde la última sesión asignada.
last_chk: Contenido/error del último health check.
last_agt: Contenido/error del último agent check.
qtime: Tiempo medio de cola (ms) sobre las últimas 1024 peticiones.
ctime: Tiempo medio de conexión (ms) sobre las últimas 1024 peticiones.
rtime: Tiempo medio de respuesta (ms) sobre las últimas 1024 peticiones.
ttime: Tiempo medio total de sesión (ms) sobre las últimas 1024 peticiones.
agent_status: Estado del último agent check.
agent_code: Código numérico reportado por el agent.
agent_duration: Tiempo en ms del último agent check.
check_desc: Descripción legible de check_status.
agent_desc: Descripción legible de agent_status.
check_rise: Parámetro rise del servidor para los checks.
check_fall: Parámetro fall del servidor para los checks.
check_health: Valor del health check del servidor.
agent_rise: Parámetro rise del agent.
agent_fall: Parámetro fall del agent.
agent_health: Parámetro health del agent.
addr: Dirección:puerto o socket unix.
cookie: Valor de cookie del servidor o nombre de cookie del backend.
mode: Modo del proxy (tcp, http, health, unknown).
algo: Algoritmo de balanceo.
conn_rate: Conexiones durante el último segundo transcurrido.
conn_rate_max: Mayor conn_rate conocido.
conn_tot: Número acumulado de conexiones.
intercepted: Peticiones interceptadas acumuladas.
dcon: Peticiones denegadas por reglas tcp-request connection.
dses: Peticiones denegadas por reglas tcp-request session.

El módulo status se traduce a un valor numérico según el siguiente mapeo: 5=UP, 4=OPEN, 3=NOLB, 2=MAINT, 1=STOP/STOPPING, 0=DOWN, lo que permite configurar alertas en base a umbrales de warning (2-4) y critical (0-2).