Proxmox Monitor Agent - Integrando com o Home Assistant

home-assistant proxmox hacs monitoring

Proxmox Monitor Agent - Integrando com o Home Assistant

Este post e o terceiro de uma serie de quatro partes sobre o Proxmox Monitor Agent e a integracao com o Home Assistant.

Por que uma custom integration

Depois que o Proxmox Monitor Agent comecou a expor o snapshot JSON, eu poderia ter parado ali e criado alguns sensores REST manualmente no Home Assistant. Para um ou dois valores, isso ate resolveria. Um sensor para temperatura, outro para CPU, talvez um terceiro para status da coleta.

O problema e que esse tipo de solucao degrada rapido.

O snapshot nao tem apenas uma temperatura. Ele pode ter varias temperaturas, dependendo do hardware. Pode ter uma ou mais interfaces fisicas de rede. Pode ter filesystems, storages, VMs, LXCs e discos. Alguns itens aparecem e desaparecem conforme o host muda. Uma VM nova entra no Proxmox, um container e removido, uma interface muda, um sensor deixa de responder.

Fazer tudo isso com sensores REST e templates manuais significa espalhar logica pelo Home Assistant. Voce comeca copiando um value_template, depois ajusta outro, depois cria entidades com nomes diferentes, depois precisa lembrar qual sensor representa qual VM. Em pouco tempo, o monitoramento vira mais um pedaco de configuracao fragil.

Uma custom integration resolve esse problema de forma mais limpa. Ela conhece o contrato do PMA, valida o schema, cria unique IDs estaveis e organiza tudo como devices e entidades dentro do modelo nativo do Home Assistant.

Em vez de o usuario montar tudo na mao, ele adiciona a integracao, aponta para o endpoint do Proxmox e deixa o Home Assistant descobrir o resto.

Instalacao

A integracao pode ser instalada de duas formas.

O repositorio esta publico em:

https://github.com/mauricioj/proxmox-monitor-agent-home-assistant

A primeira forma, e a mais pratica para uso normal, e via HACS como custom repository.

No Home Assistant:

  1. Abra o HACS.
  2. Va em Integrations.
  3. Abra o menu de tres pontos.
  4. Clique em Custom repositories.
  5. Em Repository, informe:
https://github.com/mauricioj/proxmox-monitor-agent-home-assistant
  1. Em Category, selecione Integration.
  2. Clique em Add.
  3. Procure por Proxmox Monitor Agent no HACS.
  4. Instale a integracao.
  5. Reinicie o Home Assistant.

HACS com o repositorio custom adicionado

A segunda e copiar manualmente a pasta:

custom_components/proxmox_monitor_agent

para o diretorio custom_components da sua instalacao do Home Assistant.

Depois disso, o fluxo e o mesmo: reinicia o Home Assistant e adiciona a integracao pela interface, em dispositivos e servicos.

Depois do restart:

  1. Va em Settings.
  2. Abra Devices & services.
  3. Clique em Add integration.
  4. Procure por Proxmox Monitor Agent.
  5. Informe host, porta, path e intervalo de scan.

Essa parte e importante porque a integracao nao instala o agent no Proxmox. Ela tambem nao faz SSH no host, nao publica MQTT discovery e nao tenta gerenciar historico fora do Home Assistant. Ela assume que o Proxmox Monitor Agent ja esta rodando e expondo o endpoint HTTP.

Essa separacao deixa as responsabilidades claras:

  • O agent roda no Proxmox e publica /metrics.json.
  • A integracao roda no Home Assistant e consome esse JSON.
  • O Home Assistant cuida de historico, dashboards, alertas e automacoes.

Configuracao

Na configuracao, a integracao pede poucos campos:

  • Host.
  • Porta, por padrao 9782.
  • Path, por padrao /metrics.json.
  • Scan interval.

Config flow da integracao Proxmox Monitor Agent

Na pratica, se o agent estiver rodando em http://192.168.10.20:9782/metrics.json, voce informa:

Host: 192.168.10.20
Port: 9782
Path: /metrics.json

O scan interval define de quanto em quanto tempo o Home Assistant deve consultar o endpoint. Se o /health do agent estiver disponivel, ele tambem informa o intervalo de coleta configurado no host, o que ajuda a escolher um valor coerente.

Cada config entry representa um host Proxmox. Se voce tiver mais de um host, adiciona outra entrada. Isso evita misturar entidades de hosts diferentes e mantem os unique IDs previsiveis.

Durante o config flow, a integracao tenta buscar o snapshot e valida o schema. Ela espera:

schema.name == "pma.metrics"
schema.version == 1

Se nao conseguir conectar, o fluxo retorna erro de conexao. Se conectar, mas o schema nao for compativel, retorna erro de schema. Isso evita adicionar uma integracao apontando para um endpoint errado e so descobrir depois que nada funciona.

Como os dados viram devices

No Home Assistant, device e entity nao sao a mesma coisa. Entity e o sensor em si: temperatura, CPU, status, memoria. Device e o agrupamento fisico ou logico onde essas entidades vivem.

A integracao cria um device principal para o host Proxmox. E ali que entram os sensores do host: CPU, memoria, uptime, status da coleta, temperaturas, storage e outros dados ligados diretamente ao servidor.

Device principal do host Proxmox no Home Assistant

Para VMs e LXCs, a integracao cria devices separados, vinculados ao host. Isso e mais organizado do que jogar todos os sensores no mesmo device. Uma VM pode ter status, CPU, memoria e uptime proprios. Um LXC tambem.

O identificador do host vem do snapshot. Para VMs, o padrao usa o VMID. Para LXCs, usa o CTID. Isso permite unique IDs deterministicas, em vez de depender de nomes visuais que podem mudar.

A ideia e que uma VM chamada home-assistant pode mudar de nome, mas o VMID continua sendo a identidade mais estavel dentro do Proxmox. O mesmo vale para containers.

Esse desenho tambem ajuda a evitar churn. Se o nome exibido muda, a entidade nao precisa virar outra entidade. Se o item some temporariamente, a entidade pode ficar indisponivel em vez de ser apagada e recriada.

Entidades criadas

Na primeira versao, o foco da integracao e cobrir o que realmente ajuda a monitorar o host no Home Assistant.

No device principal do host, entram sensores como:

  • Status da coleta.
  • Duracao da coleta.
  • Uso de CPU.
  • Load average de 1, 5 e 15 minutos.
  • Memoria usada.
  • Swap usado.
  • Uptime.
  • Temperaturas expostas pelo host.

Sensores de temperatura do host no Home Assistant

Para VMs e LXCs, a integracao cria sensores de:

  • Status.
  • Uso de CPU.
  • Memoria usada.
  • Uptime.

Entidades de uma VM ou LXC no Home Assistant

Para rede, ela cria entidades por interface fisica, como estado, RX bytes, TX bytes, erros e velocidade quando disponivel.

Para filesystems e storage, cria sensores de uso e disponibilidade. Isso permite criar alertas simples para storage enchendo, que e outro tipo de problema comum em homelab.

Um detalhe pratico: alguns valores de bytes sao convertidos para unidades mais humanas, como KiB, MiB, GiB ou TiB, para ficarem melhores na interface do Home Assistant.

Polling local e diagnosticos

A integracao usa DataUpdateCoordinator, que e o padrao do Home Assistant para coordenar polling de dados compartilhados entre varias entidades.

Isso evita que cada entidade faca sua propria requisicao HTTP. Em vez disso, a integracao consulta o endpoint uma vez por intervalo, guarda o snapshot mais recente no coordinator e as entidades leem seus valores dali.

O iot_class da integracao e local_polling. Isso descreve bem o modelo: o Home Assistant esta consultando um endpoint local, dentro da rede, em intervalos definidos. Nao depende de nuvem e nao precisa sair para internet.

A integracao tambem expoe diagnostics com um resumo do endpoint, schema, coleta e identidade do host. Isso ajuda quando algo nao aparece como esperado. Em vez de olhar apenas uma entidade indisponivel, voce consegue ver se o problema esta no endpoint, no schema, na coleta ou em algum modulo especifico do agent.

O status partial da coleta tambem e importante. Se uma ferramenta opcional falha, isso nao significa que o snapshot inteiro deve ser descartado. O agent pode retornar dados uteis mesmo com um modulo parcial. A integracao deve tratar isso como dado utilizavel com diagnostico, nao como falha total.

O que acontece quando algo desaparece

Ambientes Proxmox sao dinamicos. VMs podem ser criadas e removidas. Containers podem ser desligados. Discos podem aparecer e sumir. Sensores podem depender de modulo do kernel, BIOS, hardware ou permissao.

Se a integracao apagasse entidades automaticamente sempre que um item sumisse de um snapshot, o Home Assistant ficaria instavel. Historico seria quebrado, dashboards perderiam cards e automacoes poderiam ficar apontando para entidades recriadas.

Por isso a estrategia mais conservadora e manter as entidades registradas e marcar como indisponiveis quando o item nao aparece no snapshot atual.

Isso e especialmente importante para sensores dinamicos. Um disco USB pode sumir e voltar. Uma VM pode estar temporariamente ausente em um host. Uma leitura de sensor pode falhar em uma coleta e voltar na proxima.

Entidade indisponivel e uma informacao. Entidade apagada automaticamente e perda de contexto.

Proximo passo

Com a integracao instalada, o ponto cego do Proxmox vira entidades dentro do Home Assistant. Temperatura, status de coleta, CPU, memoria, storage, VMs e LXCs passam a existir no mesmo lugar onde eu ja tenho historico, dashboards e notificacoes.

Esse e o momento em que o projeto comeca a pagar a conta do incidente original. Agora da para criar alertas antes do host desligar. Da para saber se o agent parou de responder. Da para acompanhar VMs criticas.

No proximo post eu mostro exatamente essa parte: alertas no Home Assistant e os proximos passos para, no futuro, automatizar os exaustores do rack de forma mais segura.

Parte 4 - Alertas no Home Assistant e Proximos Passos