{ "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": "ProxMenux Monitor" }, "intro": { "title": "Qué puedes construir desde esta página", "body": "Cada guía de abajo está lista para copiar a tu herramienta elegida. Los endpoints de la API usados aquí están documentados en la API Reference — esta página es el compañero \"cómo usarlos realmente en Homepage / Home Assistant / Grafana\". Las capturas muestran la salida real que verás una vez la guía esté en su sitio." }, "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": "Abre el panel y ve a Settings → Security → API Tokens. Pulsa Generate token, dale un nombre (p. ej. homepage, home-assistant, prometheus), y copia el token — se muestra una vez. De larga duración (un año de expiración por defecto), revocable individualmente, y lo que deberías usar para cualquier cliente no-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 es requerido cuando el 2FA está activado en la cuenta. La rotación de tokens, la revocación, la política de contraseñas y el log de auditoría viven en Access & Authentication.", "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: <nombre>.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 de entrada por host para obtener el layout multi-tarjeta de la captura de arriba — cada entrada apunta a la URL http://<host>:8008 de su propia instancia de ProxMenux Monitor. El token puede ser distinto por host (una entrada secret por host) o compartido, según cómo los generes." }, "homeAssistant": { "heading": "Home Assistant", "headingHref": "https://www.home-assistant.io", "intro": "No hay una integración HACS nativa para ProxMenux Monitor (todavía) — pero no la necesitas. La integración rest integrada en Home Assistant puede consumir cada endpoint documentado en la API Reference y convertir las respuestas en sensores, atributos y triggers. El build de referencia completo de abajo expone ~25 sensores cubriendo recursos del sistema, el Monitor de salud, VMs / CTs, almacenamiento, red, latencia al gateway y estado de actualización de ProxMenux — pega el YAML en configuration.yaml, reinicia y tienes una capa completa de observabilidad de Proxmox dentro de 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": "Mete el token en el secrets.yaml de Home Assistant para que nunca se filtre en un volcado de config. El prefijo bearer entero va en una línea — eso permite al YAML referenciarlo directamente como valor de cabecera. El nombre y ubicación del archivo depende de tu instalación de HA (típicamente /config/secrets.yaml para HA OS / 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 probaste una versión previa de estos bloques YAML, el registro de entidades de Home Assistant puede haber cacheado los IDs de entidad viejos y entidades obsoletas seguirán apareciendo (con warnings Entidad no encontrada en tus tarjetas Lovelace). Estado limpio en dos pasos: borra los bloques rest: y template: previos de configuration.yaml, recarga, y luego bajo Settings → Devices & Services → Entities filtra por proxmenux y quita cualquier entrada marcada como \"Restored\" o mostrada como indisponible. Luego pega el YAML actual y recarga de nuevo — las entidades nuevas se registran limpiamente.", "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": "Si prefieres tener una página dedicada completa (su propia pestaña en la barra lateral del panel) en vez de una tarjeta dentro de una vista existente, Home Assistant te deja crear una vista nueva directamente con YAML. 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 nueva pestaña ProxMenux Monitor aparece en la barra lateral con todas las tarjetas renderizadas." ], "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 dedicada ProxMenux Monitor como la renderiza Home Assistant en una pantalla ancha — el layout por defecto de HA divide las tarjetas en múltiples columnas automáticamente.", "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_<tu_movil> 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": "/api/system es barato de llamar — 30 s está bien. /api/health/full usa una caché interna de 6 min, así que hacer polling más a menudo de ~60 s no te aporta nada. /api/storage/summary cambia despacio — cada 5 min sobra. /api/proxmenux/update-status solo importa una vez por hora. Ajusta a tu presupuesto de hardware si tienes muchos sensores en muchos hosts." }, "grafana": { "heading": "Prometheus + Grafana", "promHref": "https://prometheus.io", "grafanaHref": "https://grafana.com", "intro": "ProxMenux Monitor expone un endpoint de scrape formato Prometheus en GET /api/prometheus (autenticado) devolviendo texto OpenMetrics. Cabléalo a Prometheus, luego construye un panel Grafana encima — los mismos datos que muestra la UI del panel, en el formato que tu TSDB espera.", "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 (kill -HUP o systemctl reload prometheus, o docker compose restart prometheus si lo corres como contenedor) y comprueba Status → Targets — el job proxmenux debería ponerse verde dentro de un intervalo de scrape. Cada métrica lleva una etiqueta node=\"<hostname>\" para que puedas distinguir hosts en las queries.", "tokenTipTitle": "Token vía archivo o env, no inline", "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://<host-prometheus>:9090, pulsa Query y ejecuta cualquiera de estas — deberías obtener números en vivo de tu host Proxmox:", "headerQuery": "Query", "headerConfirms": "Qué confirma", "verifyRows": [ { "query": "up{job=\"proxmenux\"}", "confirms": "Devuelve 1 si Prometheus está haciendo scrape del Monitor con éxito, 0 si no. La comprobación de cordura 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 guests en ejecución. Compara con lo que ves en la UI 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": "En la página Status → Targets, pulsar el enlace del endpoint (/api/prometheus) hace que tu navegador lo descargue directamente — sin la cabecera bearer que Prometheus usa para sus propios scrapes. Así que verás '{'\"error\":\"Authentication required\"'}'. Eso confirma que la API está correctamente protegida; el propio Prometheus se autentica correctamente porque tiene el token de la configuración de scrape. Confía en el verde State: UP, no en el click-through.", "step3Title": "3 · Añade Prometheus como fuente de datos en Grafana", "step3Body": "En Grafana: Connections → Data sources → Add new → Prometheus. Configura la URL a tu instancia de Prometheus (p. ej. http://prometheus.lan:9090), guarda y prueba. No se necesita auth extra en esta capa — Prometheus ya se ha autenticado a ProxMenux.", "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": "Query 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": "Load average (1m)", "promql": "proxmox_load_average{period=\"1m\"}" }, { "panel": "% espacio en disco usado por mountpoint", "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 otros status checkers", "href": "https://github.com/louislam/uptime-kuma", "intro": "Para probes externos, usa GET /api/system-info — es el único endpoint que funciona sin token, devolviendo un payload JSON pequeño con hostname, uptime y el estado global de salud (mapeado a healthy / warning / critical). Eso es exactamente lo que necesita un monitor basado en keyword.", "kumaTitle": "Uptime Kuma — HTTP keyword monitor", "kumaSteps": [ "En Uptime Kuma, pulsa + Add New Monitor.", "Monitor Type: HTTP(s) - Keyword.", "Friendly Name: ProxMenux Monitor — pve01.", "URL: http://pve01.lan:8008/api/system-info.", "Keyword: healthy (el valor de health.status cuando el host está OK).", "Heartbeat Interval: 60 segundos basta.", "Guarda. Sin cabeceras necesarias — el endpoint es público." ], "healthchecksTitle": "healthchecks.io / pings tipo cron", "healthchecksBody": "Mismo endpoint, misma forma — apunta tu ping tipo cron a /api/system-info y comprueba .health.status == \"healthy\". La mayoría de estos servicios aceptan un estado HTTP 2xx como señal de \"up\" también, en cuyo caso incluso un curl sin parsing basta.", "richTitle": "¿Quieres datos de salud más ricos?", "richBody": "Para el estado completo (las diez categorías del Monitor de salud + errores activos + lista dismissed), usa GET /api/health/full en su lugar — ese requiere un API token pero te da todo lo que el modal del panel renderiza en una sola respuesta." }, "workflows": { "heading": "n8n, Zapier y scripts propios", "intro": "Para herramientas de workflow y scripts ad-hoc que necesitan levantar notificaciones a través del Monitor (un fallo de CI, un sensor de smart-home, un cron job que tardó demasiado), la guía es un POST a /api/notifications/send. El evento fluye por la misma pipeline de despacho que cualquier cosa emitida internamente — dedup, cooldown, reescritura con IA opcional, fan-out a los canales configurados.", "n8nBody": "En n8n, el equivalente es un nodo HTTP Request con método POST, la URL de arriba, una cabecera Authorization configurada a Bearer '{''{'$credentials.proxmenux.token'}''}' (usando credentials de n8n) y un body JSON coincidiendo con el payload de curl. Cabléa cualquier nodo precedente como el trigger (cron, webhook, condición).", "severityBody": "Los valores de severidad son INFO, WARNING o CRITICAL (en mayúsculas). El payload data es JSON libre — el reescritor de IA, cuando está activado, sacará cualquier cosa útil de ahí para el cuerpo renderizado. La semántica completa de tipos de evento vive en Notifications → Catálogo de eventos." }, "pveWebhook": { "heading": "Webhook nativo de Proxmox VE (entrante)", "intro1": "Proxmox VE 8.1+ tiene su propio sistema de notificaciones. ProxMenux Monitor se registra como destino webhook para que todo lo que PVE emite por sí mismo (fencing HA, replicación, vzdump desde la GUI, renovación de certificado) aterrice en la misma pipeline de despacho que los propios eventos del Monitor. Esto ocurre automáticamente cuando pulsas Enable Notifications en la pestaña Settings — sin trabajo de integración requerido por parte del usuario.", "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": "API Reference", "href": "/docs/monitor/api", "tail": " — cada endpoint con método, path y el catálogo completo de métricas Prometheus." }, { "label": "Notifications", "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": " — el reescritor opcional que convierte cuerpos templated en lenguaje natural antes de llegar a Telegram / Discord / email / Gotify." }, { "label": "Access & Authentication", "href": "/docs/monitor/access-auth", "tail": " — emitir y revocar los API tokens que consumen estas guías, log de auditoría, configuración TLS." } ] } }