Installation edge

ongrid-edge est un binaire Go statique unique plus quatre sous-processus de plugin. Il n'y a pas de compose, pas de DB, pas de port entrant — une connexion TCP sortante vers le broker frontier, et une connexion HTTPS sortante par plugin vers le plan de données.

L'install canonique est un curl-pipe depuis l'endpoint /install.sh du manager. Le manager sert l'installer, le binaire agent, les binaires de plugin et le hook d'upgrade depuis le même path statique /edge/, donc la seule chose dont l'opérateur a besoin est une route réseau de retour vers le manager.

Prérequis

L'host cible a besoin :

• Linux sur amd64 ou arm64. Les edges macOS fonctionnent mais perdent les plugins logs + hostmetrics (les builds Grafana / node_exporter upstream ne livrent pas de builds darwin) ; voir edge macOS dev.
• systemd pour la supervision de service.
• TCP/40012 sortant vers le manager (plan de contrôle).
• TCP/443 sortant vers le manager (plan de données — push logs + traces).
• curl et root (l'installer se ré-exec via sudo si besoin).
• Pas de plancher RAM/disque spécifique — l'agent est bien sous 50 Mo RSS plus ce que les sous-processus de plugin utilisent.

Créer l'edge dans l'UI

1. Connectez-vous au manager.
2. Edges → New edge.
3. Nommez-le (par ex. prod-web-01). Description optionnelle.
4. Pressez Create.

La page de détail montre maintenant :

• Access key (AK_...) — généré côté serveur, identifie l'edge.
• Secret key (SK_...) — affiché une fois. Perdez-la et vous rotatez.
• Install command — une one-liner curl ... | sudo bash -s -- avec l'access key, la secret key, l'endpoint tunnel edge et l'endpoint HTTP cuits dedans.

Capturez la clé secrète MAINTENANT

La clé secrète est affichée une fois. Si vous la perdez avant d'installer, supprimez et re-créez l'edge — c'est plus sûr que de fouiller dans les backups DB.

Commande d'install

Copiez la one-liner depuis l'UI. Elle ressemble à :

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

La sémantique des flags :

• --access-key / --secret-key — matériel d'auth pour le tunnel geminio. L'agent les présente au dial ; frontier demande à l'edgeauth du manager de vérifier.
• --server-edge-addr — host:port pour le plan de contrôle. Toujours 40012 sauf si vous l'avez surchargé.
• --server-http-addr — host:port pour le plan de données et le téléchargement de binaire. Le même host:port que votre navigateur utilise pour atteindre l'UI. host simple est autorisé (défaut 443). L'installer télécharge son binaire depuis https://<http-addr>/edge/ongrid-edge-<os>-<arch>.

Exécutez-la. L'installer se ré-exec via sudo si vous ne l'avez pas déjà fait.

Ce qui est déposé sur disque

/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)

L'installer aussi :

• Crée l'utilisateur système ongrid-edge (pas de home, pas de shell).
• Ajoute ongrid-edge à adm et systemd-journal pour que le plugin logs (promtail) puisse lire /var/log/* (root:adm 640) et le journal.
• systemctl daemon-reload && systemctl enable --now ongrid-edge.

Vérifier

L'installer attend jusqu'à 20 secondes (surcharge avec ONGRID_INSTALL_WAIT=N) que l'agent logge agent: registered with cloud dans le journal. Une install saine affiche :

[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 ou pending, l'installer dump les 20 dernières lignes de journal et vous oriente vers le fix le plus probable. Vérifications manuelles :

# 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

Les échecs les plus courants, et ce qu'ils signifient :

Symptôme	Cause probable	Fix
unauthorized dans le journal	typo de clé access/secret ou clé stale	Rotatez l'edge dans l'UI ; re-exécutez l'installer avec les nouvelles clés.
connection refused on :40012	broker frontier non exposé / firewall	Vérifiez iptables / SG cloud ; vérifiez docker compose ps frontier sur le manager.
Self-check : plugin binary MISSING	Vieille install avant le bundle de plugins, ou curl depuis un manager qui n'a jamais exécuté install.sh	Re-exécutez la commande d'install — elle re-fetch toujours les binaires de plugin.
Self-check : impossible de lire le journal	ongrid-edge pas dans le groupe systemd-journal	sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge.
Edge « online » mais Logs/Traces vides	ONGRID_PUBLIC_URL sur le manager pointe sur une IP interne	Éditez /opt/ongrid/.env sur le manager ; redémarrez compose.

Voir dans l'UI

• Edges — point vert à côté du nom de votre edge. La carte montre hostname, kernel, distro, RAM totale, disque, version d'agent.
• Monitor — panels CPU / mémoire / disque / load se peuplent en ~30s.
• Logs — choisissez l'edge, voyez /var/log/* et le tail journald.
• Topology — nœud host apparaît.

Ré-enregistrer / rotater les clés

Si vous devez rotater la clé secrète (compromission, clé perdue, ré-install du manager) :

1. Dans l'UI, Edges → <votre edge> → Rotate keys. Cela invalide l'ancien secret et en montre un nouveau.
2. Copiez la nouvelle commande d'install. C'est la même one-liner avec les nouvelles --access-key / --secret-key.
3. Sur l'host edge, re-exécutez la commande d'install. Elle va :
   • Arrêter proprement le ongrid-edge en cours avant d'écraser le binaire,
   • Re-fetch le binaire (pour qu'un vieil edge prenne la version du manager),
   • Re-fetch les binaires de plugin,
   • Réécrire /etc/ongrid-edge/ongrid-edge.env avec les nouvelles clés (mode 0640, owner root:ongrid-edge),
   • systemctl restart ongrid-edge,
   • Re-exécuter le self-check.

Le même flux est ce que vous utilisez pour upgrader un edge vers un nouveau manager. Le ré-enregistrement est idempotent.

Désinstaller

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

Arrête + désactive le service, supprime le binaire, l'unit systemd et le répertoire env. Préserve /var/log/ongrid-edge pour que vous puissiez garder les fichiers de log de plugin pour le forensics.

Derrière un proxy / firewall corporate

Les deux destinations sortantes sont :

• <manager-host>:40012 — tunnel geminio, TCP brut (TLS-on-wire si le frontier du manager est configuré pour ; le build OSS est en TCP brut derrière un geminio fronté par nginx).
• <manager-host>:443 — HTTPS pour le plan de données plugin + téléchargement de binaire + fetch de bundle d'upgrade.

Si votre egress passe par un proxy http, posez HTTPS_PROXY dans /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

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

Et après

• Check-list de premier démarrage — une fois qu'un couple d'edges check in, le setup côté opérateur (alertes, canaux, base de connaissances).
• Upgrade — comment ongrid-edge se met à jour sur commande de l'opérateur (upgrade en un bouton depuis l'UI).
• Plateformes / Edge Linux — matrice de distros, distros connues pour fonctionner, notes SELinux/AppArmor.