Integración con Prometheus y Grafana

Desplegar vergeos-exporter para recopilar métricas de vSAN, clúster y nodo en formato Prometheus, configurar paneles de Grafana e integrarlo con AlertManager para una supervisión proactiva.

Por qué importan las métricas externas

El panel de VergeOS proporciona salud y analíticas en tiempo real, pero las estrategias de monitoreo empresarial suelen requerir un almacén centralizado de series temporales que pueda agregar métricas entre múltiples sistemas, conservar datos más allá de la ventana de 45 días en la interfaz y activar reglas de alertas sofisticadas. La vergeos-exporter salva esta brecha al exponer métricas de VergeOS en formato Prometheus, el estándar de facto para el monitoreo nativo de la nube.

Con el exportador en ejecución, obtienes análisis de tendencias a largo plazo, correlación entre sistemas e integración con canalizaciones de alertas existentes, todo sin modificar el propio sistema VergeOS.

El vergeos-exporter

La vergeos-exporter es una herramienta de código abierto mantenida por Verge en el repositorio de GitHub verge-io/vergeos-exporter Repositorio de GitHub. Se conecta a la API REST de VergeOS, recopila métricas de la infraestructura y las expone en un extremo HTTP que Prometheus raspa a un intervalo configurable.

Métricas expuestas

El exportador recopila tres categorías de métricas:

Métricas de nivel vSAN

Capacidad, uso y asignación por nivel. Conteos de transacciones y reparaciones. Supervisión del estado de las unidades (online, offline, reparando, inicializando, verificando, sin redundancia, sin espacio). Temperatura y datos de estado de las unidades. Operaciones de lectura/escritura e IOPS.

Métricas del clúster

Cantidad de nodos por clúster. Utilización de RAM, CPU y disco. Estado de sincronización y salud.

Métricas de nodo

Uso de CPU y memoria por nodo. Rendimiento y latencia de la red. Estado de los servicios por nodo.

Una referencia completa de métricas está disponible en el metrics.md archivo del repositorio del exportador.

Arquitectura: extracción basada en pull

El vergeos-exporter sigue el modelo pull estándar de Prometheus. Prometheus inicia la conexión raspando el /metrics extremo del exportador en un intervalo configurado (normalmente 15–60 segundos). Este enfoque significa:

• No se requieren reglas de firewall entrantes
• en el propio sistema VergeOS Cualquier host con acceso de red a la API de VergeOS
• Múltiples instancias de Prometheus pueden raspar el mismo exportador para HA
• El exportador es compatible con AlertManager -- las reglas de alerta de Prometheus funcionan de forma nativa con las métricas expuestas

Configuración de la cuenta de servicio

Antes de desplegar el exportador, crea una cuenta de servicio dedicada en VergeOS con privilegios mínimos.

Paso a paso: crear la cuenta de servicio del exportador

1. Vaya a Sistema → Usuarios en la interfaz de VergeOS
2. Haga clic en Nuevo para crear un nuevo usuario
3. Rellena el formulario Nuevo usuario :

   • Nombre de usuario: prometheus-exporter (o un nombre descriptivo similar)
   • Tipo: API
   • Contraseña: un valor fuerte, generado aleatoriamente
   • Autenticación de dos factores: deja sin marcar -- el exportador se autentica mediante nombre de usuario y contraseña de la API
4. Haga clic en Enviar para guardar

Los nuevos usuarios Normal/API obtienen list/read en todo de forma predeterminada, que es exactamente lo que necesita el exportador. Para restringir más el alcance, limita las concesiones en Sistema → Permisos después de crear el usuario.

Mejor práctica de seguridad

Nunca uses una cuenta de administrador para el exportador. La cuenta de servicio solo necesita acceso de listado y lectura para consultar métricas, así que deja los valores predeterminados o restríngelos en Sistema → Permisos -- y compensa la credencial máquina a máquina usando una contraseña fuerte, generada aleatoriamente, y restringiendo el acceso de red al host del exportador.

Opciones de implementación

El vergeos-exporter admite múltiples modelos de despliegue. Elige el que mejor se adapte a tu infraestructura de monitoreo.

Opción 1: binario independiente

Hay binarios precompilados disponibles para Linux, Windows y macOS (amd64 y arm64) en la página de GitHub Releases .

# Descargar y extraer (ejemplo Linux amd64)
wget https://github.com/verge-io/vergeos-exporter/releases/latest/download/vergeos-exporter-linux-amd64.tar.gz
tar xzf vergeos-exporter-linux-amd64.tar.gz

# Ejecutar con las banderas requeridas
./vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'

El exportador escucha en el puerto 9888 de forma predeterminada. Sobrescribe con la -web.listen-address si es necesario.

Opción 2: servicio systemd de Linux

Para implementaciones Linux de producción, ejecuta el exportador como un servicio systemd administrado:

# /etc/systemd/system/vergeos-exporter.service
[Unit]
Description=Exportador de Prometheus de VergeOS
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vergeos_exporter
ExecStart=/usr/local/bin/vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

# Crear el usuario del servicio, habilitar y arrancar
sudo useradd -r -s /usr/sbin/nologin vergeos_exporter
sudo systemctl daemon-reload
sudo systemctl enable --now vergeos-exporter

Opción 3: servicio de Windows (NSSM)

En hosts de monitoreo Windows, usa NSSM (Non-Sucking Service Manager) para ejecutar el exportador como un servicio de Windows:

1. Descarga NSSM y coloca nssm.exe en una ubicación permanente (por ejemplo, C:\Program Files\nssm\)
2. Registra el servicio:

nssm install vergeos-exporter "C:\monitoring\vergeos-exporter.exe"
nssm set vergeos-exporter AppParameters "-verge.url https://your-vergeos-host -verge.username prometheus-exporter -verge.password YourStrongPassword"
nssm set vergeos-exporter Start SERVICE_AUTO_START
nssm start vergeos-exporter

Opción 4: Docker Compose

El repositorio incluye un ejemplo de Docker Compose listo para usar en examples/docker-compose/ que agrupa el exportador, Prometheus y Grafana en una sola pila, ideal para evaluaciones rápidas o entornos de laboratorio.

# Estructura simplificada de docker-compose.yml
services:
  vergeos-exporter:
    image: vergeos-exporter:latest
    ports:
      - "9888:9888"
    environment:
      - VERGE_URL=https://your-vergeos-host
      - VERGE_USERNAME=prometheus-exporter
      - VERGE_PASSWORD=YourStrongPassword

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"

El ejemplo de Docker Compose recupera automáticamente el binario correcto específico para tu arquitectura.

Configuración de Prometheus

Añade el exportador como un destino de scraping en tu prometheus.yml:

scrape_configs:
  - job_name: "vergeos"
    scrape_interval: 30s
    scrape_timeout: 30s
    static_configs:
      - targets: ["exporter-host:9888"]
        labels:
          environment: "producción"
          cluster: "site-a"

Para monitorear múltiples entornos VergeOS, despliega un exportador por entorno y añade cada uno como un destino separado (o usa relabeling de Prometheus para descubrimiento dinámico).

Panel de Grafana

El vergeos-exporter incluye un panel de Grafana preconfigurado (examples/grafana-dashboard.json) que cubre métricas de vSAN, clúster y nodo desde el primer momento.

Los paneles del dashboard incluyen

Categoría	Paneles
Rendimiento de vSAN	Indicadores de capacidad y uso por nivel, gráficos de IOPS, rendimiento de lectura/escritura
Salud del clúster	Cantidad de nodos, estado de sincronización, utilización agregada de CPU y RAM
Detalles del nodo	CPU, memoria, rendimiento de red y temperatura por nodo
Salud del almacenamiento	Estados de las unidades, estado de reparación, contadores de errores

Importar el panel

1. Abre Grafana y ve a Paneles → Importar
2. Haga clic en Subir archivo JSON y selecciona el grafana-dashboard.json del repositorio del exportador
3. Selecciona tu fuente de datos de Prometheus en el menú desplegable
4. Haga clic en Importar

El panel funciona inmediatamente una vez que Prometheus está recibiendo métricas del exportador.

Verificación

Después del despliegue, verifica que el exportador esté recopilando métricas:

# Probar directamente el extremo de métricas
curl -s http://localhost:9888/metrics | head -20

# La salida esperada incluye líneas como:
# HELP vergeos_vsan_tier_capacity_bytes Capacidad total por nivel vSAN
# TYPE vergeos_vsan_tier_capacity_bytes gauge
# vergeos_vsan_tier_capacity_bytes{tier="1"} 1.234567e+12

Si el extremo devuelve métricas, Prometheus las raspará automáticamente en su siguiente intervalo. Consulta la página de Destinos de Prometheus (http://prometheus:9090/targets) para confirmar que el vergeos trabajo muestra un estado UP.

Lista de verificación de solución de problemas

Síntoma	Compruebe
No se devolvieron métricas	Verifica que la URL, el nombre de usuario y la contraseña de VergeOS sean correctos
Conexión rechazada	Confirma que el proceso del exportador está en ejecución y escuchando en 9888
Error de autenticación	Confirma que la cuenta de servicio es Type = API con Autenticación de dos factores sin marcar
Métricas parciales	Verifica que la cuenta de servicio tenga list y read permisos
Destino de Prometheus CAÍDO	Comprueba la conectividad de red entre Prometheus y el host del exportador
Tiempo de espera de scraping	Aumenta -scrape.timeout (30 s por defecto) para entornos grandes

Integración con AlertManager

Como el exportador expone métricas estándar de Prometheus, puedes escribir reglas de alerta que se activen cuando se superen los umbrales:

# Ejemplo de reglas de alerta para métricas de Verge
groups:
  - name: vergeos_alerts
    rules:
      - alert: VSANTierNearCapacity
        expr: vergeos_vsan_tier_usage_bytes / vergeos_vsan_tier_capacity_bytes > 0.85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "El nivel vSAN {{ $labels.tier }} supera el 85% de capacidad"

      - alert: DriveOffline
        expr: vergeos_vsan_drive_state{state="offline"} > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "La unidad {{ $labels.drive }} está offline en el nodo {{ $labels.node }}"

AlertManager puede enrutar estas alertas a email, Slack, PagerDuty, OpsGenie o cualquier extremo webhook, integrando el monitoreo de VergeOS en tu flujo de trabajo existente de gestión de incidentes.

Alternativa: integración directa de API con Zabbix

Si tu organización usa Zabbix en lugar de Prometheus, puedes consultar directamente la API REST de VergeOS usando elementos HTTP Agent de Zabbix:

1. Crea un token de API mediante Sistema → Documentación de la API (Swagger UI)
2. Usa elementos HTTP Agent de Zabbix para consultar extremos como /api/v4/vms, /api/v4/nodes, /api/v4/vnets
3. Autentícate haciendo POST a /api/sys/tokens y pasando el token de sesión en el x-yottabyte-token encabezado

El exportador de Prometheus sigue siendo el enfoque recomendado para la mayoría de los entornos debido a su conjunto de métricas más rico y su panel ya preparado.

¿Vienes de VMware o Nutanix?

VergeOS expone métricas de la plataforma a través de la vergeos-exporter, que presenta datos de vSAN, clúster y nodo en formato estándar de Prometheus. Prometheus realiza scraping pull del exportador en el puerto 9888 y Grafana renderiza el panel incluido, de modo que las métricas de VergeOS fluyen hacia la misma pila Prometheus + Grafana que muchos equipos ya ejecutan junto con sus plataformas existentes.

Puntos clave

• La vergeos-exporter expone métricas de vSAN, clúster y nodo en el puerto 9888 en formato estándar de Prometheus
• Crea una cuenta de servicio dedicada de tipo API -- list/read en todo es el valor predeterminado para los nuevos usuarios Normal/API
• Despliega como binario independiente, servicio systemd, servicio de Windows (NSSM) o pila Docker Compose
• El panel de Grafana incluido proporciona visibilidad inmediata sobre la salud del almacenamiento, el clúster y los nodos
• Prometheus AlertManager la integración permite alertas proactivas sobre capacidad, estado de las unidades y umbrales de rendimiento
• El exportador usa extracción basada en pull -- no se necesitan cambios de firewall entrantes en el sistema VergeOS