{ "meta": { "title": "Integraciones de Proxmox — Homepage, Home Assistant, Grafana, Prometheus | ProxMenux Monitor", "description": "Guías copia-pega para conectar ProxMenux Monitor con los paneles de tu homelab: Homepage, Home Assistant, Grafana vía Prometheus, Uptime Kuma. Cada guía con la configuración exacta que esperan los paneles, los endpoints de la API usados y el patrón de cabecera de auth.", "ogTitle": "Integraciones de Proxmox — Homepage, Home Assistant, Grafana, Prometheus", "ogDescription": "Conjunto de guías para conectar ProxMenux Monitor con Homepage, Home Assistant, Grafana, Prometheus y Uptime Kuma.", "twitterTitle": "Integraciones de Proxmox | ProxMenux Monitor", "twitterDescription": "Guías para Homepage, Home Assistant, Grafana, Prometheus y Uptime Kuma." }, "header": { "title": "Integraciones", "description": "Guías copia-pega para conectar ProxMenux Monitor en los paneles y herramientas que tu homelab ya usa — Homepage, Home Assistant, Grafana vía Prometheus, Uptime Kuma. Cada guía muestra la configuración exacta que espera la herramienta receptora, el endpoint del Monitor con el que habla y el patrón de cabecera de auth que lo une todo.", "section": "Monitor de ProxMenux" }, "intro": { "title": "Qué puedes construir desde esta página", "body": "Copia cada ejemplo en la herramienta correspondiente. Los endpoints están documentados en la Referencia de la API; esta página explica cómo utilizarlos en Homepage, Home Assistant y Grafana. Las capturas muestran el resultado de esas configuraciones." }, "auth": { "heading": "Autenticación: lo único que cada guía necesita", "intro": "La mayoría de los endpoints usados por estas integraciones están autenticados. Tienes dos formas de satisfacer ese requisito.", "optAtitle": "Opción A — API token (recomendado para integraciones)", "optAbody1": "Entra en Ajustes → Seguridad → Tokens API. Pulsa Generar token, ponle un nombre, como homepage, home-assistant o prometheus, y cópialo: se muestra una sola vez. Caduca al año por defecto y puede revocarse individualmente. Úsalo para los clientes externos al navegador.", "optAbody2": "A partir de ahí cada petición es simplemente:", "optBtitle": "Opción B — flujo de login (usuario + contraseña)", "optBbody": "Útil para scripts que se autentican como un usuario humano. El token devuelto es de corta duración; la mayoría de integraciones deberían preferir la Opción A.", "outro": "El campo TOTP solo hace falta con la autenticación en dos pasos activada. La rotación y revocación de tokens, la política de contraseñas y el registro de auditoría se explican en Acceso y autenticación.", "httpsTitle": "Usando HTTPS en lugar de HTTP", "httpsIntro": "Cada guía de abajo usa http:// en las URLs para mantener los ejemplos cortos. Si has activado TLS en el Monitor (Settings → Security → SSL/HTTPS), cambia http:// por https:// en cada URL — ese es el único cambio. Dos notas específicas para ciertas herramientas:", "httpsItems": [ "Certificados autofirmados. La integración rest: de Home Assistant verifica TLS por defecto. Si el Monitor está usando su propio cert autofirmado, añade verify_ssl: false a cada bloque REST (junto a scan_interval:), o importa la CA del Monitor al trust store de HA. Lo mismo para cualquier herramienta que rechace certs no confiables.", "Prometheus ya tiene scheme: https listo en la configuración de scrape de abajo; descomenta / déjalo como https si TLS está activado en el Monitor." ] }, "homepage": { "heading": "Homepage", "headingHref": "https://gethomepage.dev", "intro": "Homepage es un panel de aplicaciones totalmente estático y personalizable. ProxMenux Monitor se enchufa vía el widget customapi integrado — pega una entrada de servicio en services.yaml, reinicia Homepage y la tarjeta aparece con números en vivo.", "iconCalloutTitle": "El logo oficial de ProxMenux está en dashboardicons.com", "iconCalloutBody": "Las guías de abajo usan icon: proxmenux.png. Homepage resuelve automáticamente los nombres de archivo simples contra dashboardicons.com — una librería de iconos curada para paneles autoalojados. La entrada de ProxMenux vive en dashboardicons.com/icons/external/proxmenux y Homepage la descarga en el primer render. La misma búsqueda funciona para miles de otras herramientas (Telegram, Discord, Grafana, Tailscale, etc.) — basta con escribir icon: <name>.png en cualquier entrada de servicio.", "imageAlt": "Panel Homepage mostrando tres tarjetas de ProxMenux Monitor (EDGE, VOID, DREAM) con uptime, CPU, RAM y temperatura para cada host Proxmox", "imageCaption": "Tres instancias de ProxMenux Monitor renderizadas como tarjetas Homepage — uptime, CPU, RAM y temperatura de CPU leídas en vivo desde /api/system en cada host cada 10 s.", "basicTitle": "Widget básico — sin autenticación", "basicIntro": "Usa esto cuando ProxMenux Monitor esté en una red de confianza y aún no hayas activado la autenticación en el lado del Monitor. La entrada más simple posible en services.yaml:", "authedTitle": "Widget autenticado", "authedIntro": "Genera un API token en Settings → Security → API Tokens en el Monitor, cópialo y pégalo en la cabecera Authorization de abajo — reemplaza el token de ejemplo mostrado tras Bearer con el que acabas de copiar:", "authedOutro": "Reinicia Homepage y la tarjeta se enciende con valores en vivo. Reutiliza el mismo token en todos los widgets Homepage que apunten al mismo host de ProxMenux Monitor.", "multiTitle": "Setup multi-widget — sistema, almacenamiento, red", "multiIntro": "Para una vista más rica, renderiza tres tarjetas separadas respaldadas por distintos endpoints — una para métricas del sistema, una para almacenamiento, una para red. Usa el mismo token en cada tarjeta; es la misma instancia del Monitor.", "multiCalloutTitle": "Múltiples hosts Proxmox", "multiCalloutBody": "Repite el bloque para cada host y obtendrás las tarjetas de la captura. Cada entrada usa la URL http://<host>:8008 de su propia instancia. Genera y guarda un token por host: cada instalación tiene su clave de firma y no debes asumir que el token de otra funcione." }, "homeAssistant": { "heading": "Home Assistant", "headingHref": "https://www.home-assistant.io", "intro": "Estos ejemplos usan la integración rest de Home Assistant y no necesitan un componente HACS propio. Leen endpoints del Monitor descritos en la Referencia de la API y convierten sus respuestas en sensores y atributos para automatizaciones. La configuración ofrece unos 25 sensores de recursos, salud, VMs/CTs, almacenamiento, red y actualizaciones. Añádela a configuration.yaml y recarga o reinicia HA.", "imageAlt": "Panel Home Assistant mostrando entidades de ProxMenux Monitor — badge de estado de salud, gauges de CPU / RAM / Temp, contador de VMs, uso de almacenamiento y contador de errores activos", "imageCaption": "ProxMenux Monitor como integración de primera clase en Home Assistant — sensores construidos desde la guía YAML de abajo.", "step1Title": "1 · Guarda el API token", "step1Body": "Guarda el token en secrets.yaml para separarlo de la configuración principal. Incluye el prefijo Bearer y el token en un único valor para usarlo como cabecera. El archivo no está cifrado y también debe mantenerse privado. Su ubicación depende de la instalación; normalmente es /config/secrets.yaml en HA OS o Container.", "step2Title": "2 · Añade la configuración REST", "step2Body": "Seis bloques REST cubren toda la superficie — uno por área principal del Monitor. Cada bloque tiene un scan_interval sensato ajustado a cuán a menudo cambian los datos subyacentes (recursos del sistema cada 30 s, salud cada 60 s, inventarios que cambian despacio cada 5-10 min). Pega en configuration.yaml:", "step3Title": "3 · Añade sensores binarios y helpers de template", "step3Body": "Dos sensores binarios y un par de sensores template redondean la integración — hacen que las automatizaciones y las tarjetas condicionales de Lovelace queden mucho más limpias que encadenar Jinja en cada sitio.", "step4Title": "4 · Recarga y verifica", "step4Body": "Desde la UI de HA: Developer Tools → YAML → Check Configuration primero para validar la sintaxis, luego recarga All YAML configuration (o reinicia completo). Después de que vuelva, filtra Settings → Devices & Services → Entities por proxmenux — deberías ver las ~25 entidades llenándose dentro de un intervalo de scan.", "replaceTitle": "¿Reemplazando una versión anterior de esta guía?", "replaceBody": "Si usaste una versión anterior, el registro de entidades puede conservar IDs obsoletos y las tarjetas mostrar Entidad no encontrada. Quita los bloques anteriores rest: y template: de configuration.yaml y recarga. En Ajustes → Dispositivos y servicios → Entidades, filtra por proxmenux y elimina las entradas antiguas restauradas o no disponibles. Añade después el YAML actual y recarga para registrar las nuevas.", "step5Title": "5 · Panel Lovelace", "step5Body": "El YAML de abajo es una única tarjeta vertical-stack que combina todas las sub-tarjetas en un bloque — cabecera con logo, KPIs rápidos, detalle del sistema, VMs, almacenamiento, red y una tarjeta condicional de problemas de salud. Para usarla: abre tu panel, pulsa el lápiz (editar), pulsa Add card, baja al final y elige Manual, luego pega:", "viewTipTitle": "¿Lo quieres como vista completa de panel en lugar de una sola tarjeta?", "viewTipBody": "Abre el menú de 3 puntos del panel → Raw configuration editor y añade una vista nueva con esta cabecera (encima de la lista cards: del YAML de arriba):", "viewTipOutro": "Eso te da una pestaña/vista dedicada en tu panel con su propio icono y título, en vez de una tarjeta larga en una vista existente.", "altViewTitle": "Alternativa — una vista de panel dedicada", "altViewIntro": "Para crear una pestaña propia dentro de un panel existente, añade una vista con el YAML de abajo. Una vista es una pestaña del panel; no crea una entrada nueva en la barra lateral. Pasos:", "altViewSteps": [ "Abre el panel donde quieres la nueva pestaña.", "Pulsa el lápiz (editar panel) arriba a la derecha.", "Pulsa la pestaña + al final de las pestañas existentes para crear una vista nueva.", "En el diálogo que se abre, cambia a la pestaña Code editor (arriba a la derecha del diálogo — alterna entre editor visual y YAML).", "Pega el YAML de abajo.", "Guarda. La vista ProxMenux Monitor aparece como pestaña dentro del panel con sus tarjetas." ], "twoEditorsTitle": "Dos editores YAML en HA — elige el correcto", "twoEditorsIntro": "Home Assistant tiene dos editores YAML que parecen similares pero esperan formatos distintos:", "twoEditorsItems": [ "Editor de una sola vista (esta guía) — abierto desde la pestaña + o desde Edit view → Code editor. Espera el cuerpo de una vista directamente: title:, path:, cards: al top level, sin guion inicial.", "Editor Raw del panel entero — abierto desde el menú de 3 puntos del panel. Espera la lista views: entera, con cada vista como item de lista (- inicial)." ], "twoEditorsOutro": "Pegar YAML de cuerpo de vista en el editor de panel entero (o viceversa) te deja con una Vista sin nombre y cards: []. El YAML de abajo es para el editor de una sola vista — pega exactamente como se muestra.", "viewImageAlt": "Vista dedicada de Home Assistant renderizando ProxMenux Monitor — cabecera picture-entity, KPIs glance y tarjetas de entidad Sistema / VMs / Almacenamiento / Red distribuidas automáticamente por HA en múltiples columnas", "viewImageCaption": "La vista ProxMenux Monitor en pantalla ancha. La disposición Masonry distribuye las tarjetas automáticamente en columnas; el resultado depende del tipo de vista configurado.", "twoColTipTitle": "¿Quieres un layout fijo de dos columnas en lugar del auto layout?", "twoColTipBody": "Reemplaza cualquier par de tarjetas (p. ej. Sistema + VMs, o Almacenamiento + Red) con un único horizontal-stack envolviendo ambas, para que siempre se rendericen lado a lado independientemente del ancho de pantalla:", "twoColTipOutro": "En móvil la fila se mantiene comprimida; el auto layout de HA (sin horizontal-stack) refluye mejor a anchos estrechos.", "step6Title": "6 · Automatizaciones", "step6Body": "Tres automatizaciones que cubren los escenarios reactivos más comunes — reemplaza notify.mobile_app_<your_phone> por el servicio notify que uses:", "logoTitle": "Sobre el logo de ProxMenux", "logoBody": "La tarjeta picture-entity en la parte superior del YAML Lovelace descarga el logo oficial de ProxMenux desde dashboardicons.com — una librería de iconos gratuita curada para paneles autoalojados. La entrada de ProxMenux vive en dashboardicons.com/icons/external/proxmenux. Home Assistant descarga el SVG sobre HTTPS en el primer render y lo cachea.", "logoBrokenTitle": "Si la tarjeta del logo muestra una imagen rota", "logoBrokenIntro": "Algunas instalaciones de HA (redes con firewall, bloqueadores de contenido, hosts sin internet pública) no pueden alcanzar jsdelivr.net en el momento del render. El arreglo es una copia local:", "logoBrokenSteps": [ "Descarga el SVG desde cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/proxmenux.svg.", "Guárdalo en /config/www/icons/proxmenux.svg en tu host HA.", "En el YAML Lovelace, reemplaza la URL image: por /local/icons/proxmenux.svg. Guarda y recarga — la imagen se renderiza desde el archivo local, sin internet necesaria." ], "scanTipTitle": "Regla práctica para scan_interval", "scanTipBody": "Un punto de partida razonable es consultar /api/system cada 30 s. /api/health/full suele leer datos en caché válidos hasta seis minutos; consultarlo cada 60 s no evita esa caché. Prueba cinco minutos para /api/storage/summary y una hora para /api/proxmenux/update-status. Ajusta los intervalos a tu hardware y número de hosts." }, "grafana": { "heading": "Prometheus + Grafana", "promHref": "https://prometheus.io", "grafanaHref": "https://grafana.com", "intro": "ProxMenux Monitor expone GET /api/prometheus con formato de exposición de texto Prometheus 0.0.4. Necesita un token Bearer si la autenticación está activada. Configura Prometheus para recoger las métricas y Grafana para visualizar la base de datos de series temporales.", "imageAlt": "Panel Grafana renderizando métricas de ProxMenux Monitor — gauge de uso de CPU, timeseries de uso de memoria, contador de VMs en ejecución, throughput de red", "imageCaption": "Un panel Grafana básico construido desde el scrape Prometheus de ProxMenux — CPU, memoria, VMs en ejecución, throughput de red. El catálogo completo de métricas vive en la API Reference → Métricas Prometheus.", "step1Title": "1 · Añade el job de scrape a Prometheus", "step1Body": "Pasa el API token vía el bloque nativo authorization de Prometheus (más limpio que cabeceras personalizadas y funciona con secret stores):", "step1After": "Recarga Prometheus con kill -HUP <PID> (sustituye PID por su ID de proceso), systemctl reload prometheus si el servicio lo permite o docker compose restart prometheus para el contenedor. Revisa Status → Targets: el job proxmenux debería pasar a UP en un intervalo de recogida. Las métricas llevan node=\"<hostname>\" para distinguir los hosts.", "tokenTipTitle": "Guarda el token en un archivo separado", "tokenTipBody": "Para despliegues en producción evita poner el token inline. Prometheus soporta credentials_file: /etc/prometheus/secrets/proxmenux.token como alternativa — guarda el token en un archivo 0600 y deja que Prometheus lo lea.", "step2Title": "2 · Verifica el scrape con un par de queries", "step2Body": "Antes de configurar Grafana, confirma que Prometheus realmente tiene los datos. Abre la propia UI de Prometheus en http://<prometheus-host>:9090, pulsa Query y ejecuta cualquiera de estas — deberías obtener números en vivo de tu host Proxmox:", "headerQuery": "Consulta", "headerConfirms": "Qué confirma", "verifyRows": [ { "query": "up{job=\"proxmenux\"}", "confirms": "Devuelve 1 si Prometheus recoge datos del Monitor correctamente y 0 si falla. Es la comprobación inicial más rápida." }, { "query": "proxmox_cpu_usage", "confirms": "Porcentaje de uso de CPU actual del host Proxmox. Debería cambiar si refrescas la query con unos segundos de diferencia." }, { "query": "proxmox_vms_running", "confirms": "Número de máquinas invitadas en ejecución. Compáralo con la interfaz de Proxmox." }, { "query": "proxmox_uptime_seconds / 86400", "confirms": "Uptime del host en días. Debería coincidir con el valor que verías en uptime en la shell de Proxmox." } ], "calloutTitle": "El 401 que puedes ver al pulsar la URL del endpoint es normal", "calloutBody": "Con la autenticación activa, al pulsar el enlace en Status → Targets el navegador consulta /api/prometheus sin la cabecera Bearer de Prometheus. Puede responder '{'\"error\":\"Authentication required\"'}'. Comprueba el State: UP del destino para confirmar que Prometheus recoge los datos con su token.", "step3Title": "3 · Añade Prometheus como fuente de datos en Grafana", "step3Body": "En Grafana, abre Connections → Data sources → Add new → Prometheus. Indica la URL de Prometheus, por ejemplo http://prometheus.lan:9090, guarda y prueba. Si tu servidor Prometheus exige autenticación, configúrala aquí por separado. El token del Monitor pertenece al job de recogida de Prometheus.", "step4Title": "4 · Construye paneles con estas queries PromQL", "step4Body": "Un set inicial que mapea directamente a lo que los usuarios típicamente vigilan en un host Proxmox:", "headerPanel": "Idea de panel", "headerPromql": "Consulta PromQL", "panelRows": [ { "panel": "Gauge de uso de CPU por host", "promql": "proxmox_cpu_usage" }, { "panel": "Gauge de uso de memoria por host", "promql": "proxmox_memory_usage_percent" }, { "panel": "Memoria usada vs total (timeseries)", "promql": "proxmox_memory_used_bytes / 1024 / 1024 / 1024" }, { "panel": "VMs / CTs en ejecución por host", "promql": "proxmox_vms_running" }, { "panel": "Temperatura de CPU", "promql": "proxmox_cpu_temperature_celsius" }, { "panel": "Throughput de red RX (bytes/s)", "promql": "rate(proxmox_interface_bytes_received_total[5m])" }, { "panel": "Throughput de red TX (bytes/s)", "promql": "rate(proxmox_interface_bytes_sent_total[5m])" }, { "panel": "Promedio de carga (1m)", "promql": "proxmox_load_average{period=\"1m\"}" }, { "panel": "Porcentaje de espacio usado por punto de montaje", "promql": "proxmox_disk_usage_percent" }, { "panel": "Carga de batería de UPS", "promql": "proxmox_ups_battery_charge_percent" }, { "panel": "Temperatura de GPU por slot", "promql": "proxmox_gpu_temperature_celsius" } ], "outro": "Añade cada query como un panel Grafana, configura la visualización adecuada (Stat para gauges, Time series para tendencias) y agrupa paneles en filas por categoría. Usa la etiqueta node como variable de panel (Settings → Variables → New → Query → label_values(proxmox_cpu_usage, node)) para filtrar todos los paneles por host." }, "uptimeKuma": { "heading": "Uptime Kuma y otras herramientas de comprobación de estado", "href": "https://github.com/louislam/uptime-kuma", "intro": "Para comprobar una palabra clave, usa GET /api/system-info. Esta ruta no exige token y devuelve nombre del host, tiempo de actividad y salud como healthy, warning o critical. Es una comprobación pública, a diferencia de los endpoints detallados protegidos.", "kumaTitle": "Uptime Kuma — Monitor HTTP de palabras clave", "kumaSteps": [ "En Uptime Kuma, pulsa + Add New Monitor.", "Tipo de monitor: HTTP(s) - Palabras clave.", "Nombre descriptivo: ProxMenux Monitor — pve01.", "URL: http://pve01.lan:8008/api/system-info.", "Keyword: healthy (el valor de health.status cuando el host está OK).", "Intervalo de comprobación: 60 segundos es suficiente.", "Guarda. La ruta system-info no necesita una cabecera Bearer." ], "healthchecksTitle": "healthchecks.io / pings tipo cron", "healthchecksBody": "Un trabajo cron puede consultar /api/system-info y comprobar .health.status == \"healthy\". Solo si supera la prueba debe enviar un ping de éxito a la URL única de Healthchecks.io. Ese servicio recibe pings de los trabajos; no consulta el Monitor. Un HTTP 2xx por sí solo no demuestra buena salud del host.", "richTitle": "¿Quieres datos de salud más ricos?", "richBody": "Para el estado completo —diez categorías de salud, errores activos y descartados— usa GET /api/health/full. Devuelve los datos de la ventana del panel en una respuesta y necesita un token Bearer si la autenticación está activada." }, "workflows": { "heading": "n8n, Zapier y scripts propios", "intro": "Las herramientas de workflow y scripts pueden enviar notificaciones con un POST a /api/notifications/send, por ejemplo por un fallo de CI o un trabajo cron demasiado largo. Es un envío directo: omite la cola y la espera entre huellas de eventos. Conserva el formato por canal, la IA opcional y la entrega a los canales configurados. Controla los duplicados desde quien llama.", "n8nBody": "En n8n, usa un nodo HTTP Request con POST, la URL anterior y el mismo JSON que curl. Elige credenciales genéricas Header Auth: nombre Authorization y valor Bearer YOUR_API_TOKEN, sustituyendo el marcador. Conecta una programación, webhook u otro nodo para disparar la petición.", "severityBody": "La gravedad usa INFO, WARNING o CRITICAL en mayúsculas. El objeto data aporta contexto del evento y campos de plantilla. En este endpoint, la IA solo recibe el título y el mensaje; los campos de data no se envían al proveedor. Consulta Notificaciones → Catálogo de eventos." }, "pveWebhook": { "heading": "Webhook nativo de Proxmox VE (entrante)", "intro1": "El sistema de notificaciones llegó en PVE 8.1; los destinos webhook nativos requieren Proxmox VE 8.3 o posterior. Activar notificaciones en Ajustes intenta registrar el Monitor como destino. Los avisos que PVE enruta allí, como informes de backups o replicación, entran en su flujo de envío. El alta depende de que la configuración esté disponible y permita escritura.", "intro2": "La mecánica, la plantilla de body que PVE envía, las entradas escritas en /etc/pve/notifications.cfg y el comportamiento en clusters están documentados en Notifications → Integración del webhook de PVE." }, "whereNext": { "heading": "Por dónde seguir", "items": [ { "label": "Referencia de la API", "href": "/docs/monitor/api", "tail": " — cada endpoint con método, path y el catálogo completo de métricas Prometheus." }, { "label": "Notificaciones", "href": "/docs/monitor/notifications", "tail": " — fuentes de eventos, canales, la pipeline de despacho, la integración del webhook de PVE en detalle." }, { "label": "Asistente de IA", "href": "/docs/monitor/ai-assistant", "tail": " — reformulación opcional de las plantillas en lenguaje sencillo antes de enviarlas a Telegram, Discord, correo o Gotify." }, { "label": "Acceso y autenticación", "href": "/docs/monitor/access-auth", "tail": " — emitir y revocar los API tokens que consumen estas guías, log de auditoría, configuración TLS." } ] } }