Instalación del edge

ongrid-edge es un único binario Go estático más cuatro subprocesos de plugin. No hay compose, no hay DB, sin puerto entrante — una conexión TCP saliente al broker frontier, y una conexión HTTPS saliente por plugin al data plane.

La instalación canónica es curl-pipe desde el endpoint /install.sh del manager. El manager sirve el installer, el binario del agente, los binarios de plugin y el hook de upgrade desde el mismo path estático /edge/, así que lo único que el operador necesita es una ruta de red de vuelta al manager.

Prereqs

El host target necesita:

• Linux en amd64 o arm64. Los edges macOS funcionan pero pierden los plugins logs + hostmetrics (Grafana upstream / node_exporter no envían builds darwin); ver macOS edge dev.
• systemd para supervisión de servicio.
• TCP/40012 saliente al manager (control plane).
• TCP/443 saliente al manager (data plane — push de logs + trazas).
• curl y root (el installer re-execs vía sudo si es necesario).
• Sin piso específico de RAM/disco — el agente está bien por debajo de 50 MB RSS más lo que sea que usen los subprocesos de plugin.

Crea el edge en la UI

1. Inicia sesión en el manager.
2. Edges → New edge.
3. Nómbralo (p. ej. prod-web-01). Descripción opcional.
4. Pulsa Create.

La página de detalle ahora muestra:

• Access key (AK_...) — generada por el servidor, identifica el edge.
• Secret key (SK_...) — mostrada una vez. Si la pierdes, rotas.
• Install command — un one-liner curl ... | sudo bash -s -- con la access key, secret key, endpoint de túnel del edge y endpoint HTTP horneados.

Captura la secret key AHORA

La secret key se muestra una vez. Si la pierdes antes de instalar, borra y re-crea el edge — es más seguro que escarbar en backups de DB.

Comando de install

Copia el one-liner de la UI. Se ve como:

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

Semántica de los flags:

• --access-key / --secret-key — material de auth para el túnel geminio. El agente los presenta al marcar; frontier le pide al edgeauth del manager que verifique.
• --server-edge-addr — host:port para el control plane. Siempre 40012 salvo que lo hayas sobreescrito.
• --server-http-addr — host:port para el data plane y descarga de binarios. El mismo host:port que tu navegador usa para alcanzar la UI. Se permite host plano (default 443). El installer descarga su binario de https://<http-addr>/edge/ongrid-edge-<os>-<arch>.

Ejecútalo. El installer re-execs vía sudo si no estabas ya.

Qué se deja en disco

/usr/local/bin/
  └── ongrid-edge                       # the agent binary (mode 0755)

/usr/local/lib/ongrid-edge/
  ├── apply-pending-upgrade.sh          # ADR-024 ExecStartPre hook (mode 0755)
  ├── promtail                          # plugin: logs (Loki push)
  ├── otelcol-contrib                   # plugin: traces (OTLP push)
  ├── 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               # systemd unit

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

/var/log/ongrid-edge/                   # plugin stdout/stderr capture
                                        # (the agent itself logs to journal)

El installer también:

• Crea el usuario de sistema ongrid-edge (sin home, sin shell).
• Añade ongrid-edge a adm y systemd-journal para que el plugin de logs (promtail) pueda leer /var/log/* (root:adm 640) y el journal.
• systemctl daemon-reload && systemctl enable --now ongrid-edge.

Verifica

El installer espera hasta 20 segundos (override con ONGRID_INSTALL_WAIT=N) a que el agente loguee agent: registered with cloud al journal. Una instalación sana 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

Si STATUS=failed o pending, el installer vuelca las últimas 20 líneas del journal y te empuja hacia el fix más probable. Chequeos manuales:

# Service state
sudo systemctl status ongrid-edge

# Live journal
sudo journalctl -u ongrid-edge -f

# Test the data plane reachability
curl -kI https://203.0.113.10/

# Test the control plane reachability
nc -vz 203.0.113.10 40012

Las fallas más comunes, y qué significan:

Síntoma	Causa probable	Fix
unauthorized en el journal	typo en access/secret key o key stale	Rota el edge en la UI; re-ejecuta installer con las nuevas keys.
connection refused on :40012	broker frontier no expuesto / firewall	Revisa iptables / SG de la nube; verifica docker compose ps frontier en el manager.
Self-check: plugin binary MISSING	Instalación vieja antes del bundle de plugin, o curl desde un manager que nunca corrió install.sh	Re-ejecuta el comando de install — siempre re-fetchea los binarios de plugin.
Self-check: no puede leer el journal	ongrid-edge no está en el grupo systemd-journal	sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge.
Edge "online" pero Logs/Trazas vacíos	ONGRID_PUBLIC_URL en manager apunta a IP interna	Edita /opt/ongrid/.env en manager; reinicia compose.

Míralo en la UI

• Edges — punto verde junto al nombre de tu edge. La tarjeta muestra hostname, kernel, distro, RAM total, disco, versión del agente.
• Monitor — los paneles de CPU / memoria / disco / load se pueblan en unos ~30s.
• Logs — elige el edge, ve el tail de /var/log/* y journald.
• Topología — el nodo de host aparece.

Re-registro / rotación de keys

Si necesitas rotar la secret key (compromiso, key perdida, re-install del manager):

1. En la UI, Edges → <tu edge> → Rotate keys. Esto invalida el viejo secret y muestra uno nuevo.
2. Copia el nuevo comando de install. Es el mismo one-liner con las nuevas --access-key / --secret-key.
3. En el host del edge, re-ejecuta el comando de install. Va a:
   • Detener el ongrid-edge que corre limpiamente antes de sobreescribir el binario,
   • Re-fetchear el binario (para que un edge viejo recoja la versión del manager),
   • Re-fetchear los binarios de plugin,
   • Reescribir /etc/ongrid-edge/ongrid-edge.env con las nuevas keys (modo 0640, owner root:ongrid-edge),
   • systemctl restart ongrid-edge,
   • Re-ejecutar el self-check.

El mismo flujo es lo que usas para upgradear un edge a un nuevo manager. El re-registro es idempotente.

Desinstalar

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

Detiene + deshabilita el servicio, elimina el binario, la unit de systemd y el directorio env. Preserva /var/log/ongrid-edge para que puedas conservar los archivos de log del plugin para forense.

Detrás de un proxy corporativo / firewall

Los dos destinos salientes son:

• <manager-host>:40012 — túnel geminio, TCP plano (TLS-on-wire si el frontier del manager está configurado para ello; el build OSS es TCP plano detrás de geminio fronted por nginx).
• <manager-host>:443 — HTTPS para data plane de plugin + descarga de binarios + fetch de bundle de upgrade.

Si tu egreso va por un proxy http, setea HTTPS_PROXY en /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

Luego systemctl daemon-reload && systemctl restart ongrid-edge.

Qué sigue

• Checklist de primer arranque — una vez que un par de edges están reportando, el setup del lado del operador (alertas, canales, base de conocimiento).
• Upgrade — cómo se actualiza ongrid-edge por orden del operador (upgrade de un botón desde la UI).
• Plataformas / Linux edge — matriz de distros, distros que se sabe que funcionan, notas SELinux/AppArmor.