Instalação do edge

ongrid-edge é um único binário Go estático mais quatro subprocessos de plugin. Não há compose, sem DB, sem porta inbound — uma conexão TCP outbound para o broker frontier, e uma conexão HTTPS outbound por plugin para o data plane.

A instalação canônica é curl-pipe do endpoint /install.sh do manager. O manager serve o instalador, o binário do agent, os binários dos plugins, e o hook de upgrade do mesmo path estático /edge/, então a única coisa que o operador precisa é de uma rota de rede de volta ao manager.

Pré-requisitos

O host alvo precisa:

• Linux em amd64 ou arm64. Edges macOS funcionam mas perdem os plugins de logs + hostmetrics (upstream Grafana / node_exporter não distribuem builds darwin); veja dev de edge macOS.
• systemd para supervisão de serviço.
• TCP/40012 outbound ao manager (control plane).
• TCP/443 outbound ao manager (data plane — push de logs + traces).
• curl e root (o instalador re-executa via sudo se necessário).
• Sem floor específico de RAM/disco — o agent fica bem abaixo de 50 MB RSS mais o que os subprocessos de plugin usam.

Crie o edge na UI

1. Faça login no manager.
2. Edges → New edge.
3. Dê um nome (ex.: prod-web-01). Descrição opcional.
4. Pressione Create.

A página de detalhe agora mostra:

• Access key (AK_...) — gerada server-side, identifica o edge.
• Secret key (SK_...) — mostrada uma vez. Perdeu, rotacionou.
• Comando de install — um one-liner curl ... | sudo bash -s -- com a access key, secret key, endpoint de tunnel do edge, e endpoint HTTP embutidos.

Capture a secret key AGORA

A secret key é mostrada uma vez. Se você perder antes de instalar, delete e recrie o edge — é mais seguro que cavar nos backups do DB.

Comando de install

Copie o one-liner da UI. Parece com:

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=203.0.113.10:40012 \
    --server-http-addr=203.0.113.10:443

A semântica das flags:

• --access-key / --secret-key — material de auth para o tunnel geminio. O agent apresenta isso no dial; frontier pede ao edgeauth do manager para verificar.
• --server-edge-addr — host:port para o control plane. Sempre 40012 a menos que você tenha sobrescrito.
• --server-http-addr — host:port para o data plane e download de binário. Mesmo host:port que seu browser usa para alcançar a UI. host puro é permitido (default 443). O instalador baixa o binário de https://<http-addr>/edge/ongrid-edge-<os>-<arch>.

Rode. O instalador re-executa via sudo se você não já estava.

O que é colocado em disco

/usr/local/bin/
  └── ongrid-edge                       # o binário do agent (mode 0755)

/usr/local/lib/ongrid-edge/
  ├── apply-pending-upgrade.sh          # hook ExecStartPre do ADR-024 (mode 0755)
  ├── promtail                          # plugin: logs (push Loki)
  ├── otelcol-contrib                   # plugin: traces (push OTLP)
  ├── node_exporter                     # plugin: hostmetrics
  └── process_exporter                  # plugin: procmetrics

/etc/ongrid-edge/
  └── ongrid-edge.env                   # access/secret keys (mode 0640,
                                        # owner root:ongrid-edge)

/etc/systemd/system/
  └── ongrid-edge.service               # unit do systemd

/var/lib/ongrid-edge/                   # StateDirectory, criado no start
  └── .upgrade/                         # bundles staged, markers

/var/log/ongrid-edge/                   # captura de stdout/stderr dos plugins
                                        # (o próprio agent loga no journal)

O instalador também:

• Cria o user de sistema ongrid-edge (sem home, sem shell).
• Adiciona ongrid-edge a adm e systemd-journal para que o plugin de logs (promtail) possa ler /var/log/* (root:adm 640) e o journal.
• systemctl daemon-reload && systemctl enable --now ongrid-edge.

Verifique

O instalador espera até 20 segundos (override com ONGRID_INSTALL_WAIT=N) pelo agent logar agent: registered with cloud no journal. Uma instalação saudável imprime:

[INFO]  waiting for tunnel handshake (up to 20s)...

--- self-check ---
[OK]    plugin binary present: promtail
[OK]    plugin binary present: otelcol-contrib
[OK]    plugin binary present: node_exporter
[OK]    plugin binary present: process_exporter
[OK]    journald readable by ongrid-edge
[OK]    data-plane host 203.0.113.10:443 reachable (TCP)
[OK]    self-check passed

[OK]    installed:    ongrid-edge v0.7.159
[OK]    connected:    edge_id=42 via 203.0.113.10:40012
[OK]    tail logs:    journalctl -u ongrid-edge -f

Se STATUS=failed ou pending, o instalador dumpa as últimas 20 linhas do journal e te direciona para o fix mais provável. Checks manuais:

# Estado do serviço
sudo systemctl status ongrid-edge

# Journal ao vivo
sudo journalctl -u ongrid-edge -f

# Teste alcançabilidade do data plane
curl -kI https://203.0.113.10/

# Teste alcançabilidade do control plane
nc -vz 203.0.113.10 40012

As falhas mais comuns, e o que significam:

Sintoma	Causa provável	Fix
unauthorized no journal	typo em access/secret key ou chave stale	Rotacione o edge na UI; re-rode o instalador com chaves novas.
connection refused on :40012	broker frontier não exposto / firewall	Cheque iptables / SG da cloud; verifique docker compose ps frontier no manager.
Self-check: plugin binary MISSING	Instalação antiga antes do bundle de plugin, ou curl de um manager que nunca rodou install.sh	Re-rode o comando de install — ele sempre re-fetcha binários de plugin.
Self-check: não consegue ler o journal	ongrid-edge não está no grupo systemd-journal	sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge.
Edge "online" mas Logs/Traces vazios	ONGRID_PUBLIC_URL no manager aponta para IP interno	Edite /opt/ongrid/.env no manager; restart do compose.

Veja na UI

• Edges — ponto verde ao lado do nome do seu edge. Card mostra hostname, kernel, distro, RAM total, disco, versão do agent.
• Monitor — painéis de CPU / memória / disco / load populam em ~30s.
• Logs — escolha o edge, veja tail de /var/log/* e do journald.
• Topologia — nó de host aparece.

Re-registrar / rotacionar chaves

Se você precisa rotacionar a secret key (comprometimento, chave perdida, manager re-instalado):

1. Na UI, Edges → <seu edge> → Rotate keys. Isso invalida a antiga secret e mostra uma nova.
2. Copie o novo comando de install. É o mesmo one-liner com a nova --access-key / --secret-key.
3. No host do edge, re-rode o comando de install. Ele vai:
   • Parar o ongrid-edge rodando limpamente antes de sobrescrever o binário,
   • Re-fetchar o binário (para que um edge antigo pegue a versão do manager),
   • Re-fetchar os binários de plugin,
   • Reescrever /etc/ongrid-edge/ongrid-edge.env com as novas chaves (mode 0640, owner root:ongrid-edge),
   • systemctl restart ongrid-edge,
   • Re-rodar o self-check.

O mesmo fluxo é o que você usa para atualizar um edge a um novo manager. Re-registro é idempotente.

Desinstalar

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- --uninstall

Para + desabilita o serviço, remove o binário, a unit systemd, e o diretório de env. Preserva /var/log/ongrid-edge para que você possa manter os arquivos de log de plugin para forense.

Atrás de um proxy / firewall corporativo

Os dois destinos outbound são:

• <manager-host>:40012 — tunnel geminio, TCP puro (TLS-on-wire se o frontier do manager está configurado para isso; o build OSS é TCP puro atrás de geminio frontendado por nginx).
• <manager-host>:443 — HTTPS para data plane do plugin + download de binário + fetch de bundle de upgrade.

Se seu egress passa por um proxy http, defina HTTPS_PROXY em /etc/systemd/system/ongrid-edge.service.d/proxy.conf:

[Service]
Environment=HTTPS_PROXY=http://proxy.corp:3128
Environment=NO_PROXY=127.0.0.1,localhost

Então systemctl daemon-reload && systemctl restart ongrid-edge.

O que vem a seguir

• Checklist de primeiro boot — uma vez que alguns edges estão fazendo check-in, o setup do lado operador (alertas, canais, base de conhecimento).
• Upgrade — como o ongrid-edge se atualiza sob comando do operador (one-button-upgrade da UI).
• Plataformas / edge Linux — matriz de distros, distros conhecidas que funcionam, notas SELinux/AppArmor.