Edge-Installation

ongrid-edge ist ein einzelnes statisches Go-Binary plus vier Plugin-Subprozesse. Es gibt kein Compose, keine DB, keinen eingehenden Port — eine ausgehende TCP-Verbindung zum Frontier-Broker und eine ausgehende HTTPS-Verbindung pro Plugin zur Datenebene.

Die kanonische Installation ist curl-pipe vom /install.sh-Endpunkt des Managers. Der Manager bedient den Installer, das Agent-Binary, die Plugin-Binaries und den Upgrade-Hook aus demselben /edge/-statischen Pfad, sodass das Einzige, was der Operator braucht, eine Netzwerkroute zurück zum Manager ist.

Voraussetzungen

Der Ziel-Host braucht:

Linux auf amd64 oder arm64. macOS-Edges funktionieren, verlieren aber die Logs- + Hostmetrics-Plugins (Upstream Grafana / node_exporter liefern keine Darwin-Builds aus); siehe macOS-Edge-Dev.
systemd für Service-Supervision.
Ausgehendes TCP/40012 zum Manager (Steuerungsebene).
Ausgehendes TCP/443 zum Manager (Datenebene — Logs + Traces Push).
curl und root (der Installer re-exect via sudo, falls nötig).
Kein spezifischer RAM/Disk-Floor — der Agent ist gut unter 50 MB RSS plus was auch immer die Plugin-Subprozesse verwenden.

Die Edge in der UI erstellen

Beim Manager anmelden.
Edges → New edge.
Benennen Sie sie (z. B. prod-web-01). Optionale Beschreibung.
Create klicken.

Die Detailseite zeigt jetzt:

Access Key (AK_...) — serverseitig generiert, identifiziert die Edge.
Secret Key (SK_...) — einmal angezeigt. Verlieren Sie ihn und Sie rotieren.
Install command — ein curl ... | sudo bash -s -- Einzeiler mit Access Key, Secret Key, Edge-Tunnel-Endpunkt und HTTP-Endpunkt eingebrannt.

Erfassen Sie den Secret Key JETZT

Der Secret Key wird einmal angezeigt. Wenn Sie ihn vor dem Installieren verlieren, löschen und erstellen Sie die Edge neu — das ist sicherer als sich durch DB-Backups zu graben.

Installationsbefehl

Kopieren Sie den Einzeiler aus der UI. Er sieht so aus:

bash

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

Die Flag-Semantik:

--access-key / --secret-key — Auth-Material für den geminio-Tunnel. Der Agent präsentiert diese beim Wählen; Frontier bittet die edgeauth des Managers, zu verifizieren.
--server-edge-addr — host:port für die Steuerungsebene. Immer 40012, es sei denn, Sie haben es überschrieben.
--server-http-addr — host:port für die Datenebene und den Binary-Download. Derselbe host:port, den Ihr Browser verwendet, um die UI zu erreichen. Reines host ist erlaubt (Default 443). Der Installer lädt sein Binary von https://<http-addr>/edge/ongrid-edge-<os>-<arch> herunter.

Ausführen. Der Installer re-exect via sudo, wenn Sie es nicht bereits taten.

Was auf der Disk landet

text

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

Der Installer:

Erstellt den ongrid-edge-Systembenutzer (kein Home, keine Shell).
Fügt ongrid-edge zu adm und systemd-journal hinzu, sodass das Logs-Plugin (promtail) /var/log/* (root:adm 640) und das Journal lesen kann.
systemctl daemon-reload && systemctl enable --now ongrid-edge.

Verifizieren

Der Installer wartet bis zu 20 Sekunden (überschreiben mit ONGRID_INSTALL_WAIT=N), bis der Agent agent: registered with cloud in das Journal loggt. Eine gesunde Installation druckt:

text

[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

Wenn STATUS=failed oder pending, dumpt der Installer die letzten 20 Journal-Zeilen und fordert Sie zum wahrscheinlichsten Fix auf. Manuelle Checks:

bash

# 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

Die häufigsten Fehler und was sie bedeuten:

Symptom	Wahrscheinliche Ursache	Fix
`unauthorized` im Journal	Access/Secret-Key-Tippfehler oder veralteter Schlüssel	Edge in UI rotieren; Installer mit neuen Schlüsseln neu ausführen.
`connection refused on :40012`	Frontier-Broker nicht exponiert / Firewall	`iptables` / Cloud-SG prüfen; `docker compose ps frontier` auf Manager verifizieren.
Self-Check: `plugin binary MISSING`	Alte Installation vor Plugin-Bundle, oder curl von einem Manager, der nie `install.sh` ausgeführt hat	Installationsbefehl neu ausführen — er holt Plugin-Binaries immer neu.
Self-Check: kann Journal nicht lesen	`ongrid-edge` nicht in `systemd-journal`-Gruppe	`sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge`.
Edge „online" aber Logs/Traces leer	`ONGRID_PUBLIC_URL` auf Manager zeigt auf interne IP	`/opt/ongrid/.env` auf Manager editieren; Compose neu starten.

In der UI sehen

Edges — grüner Punkt neben Ihrem Edge-Namen. Karte zeigt Hostnamen, Kernel, Distro, gesamtes RAM, Disk, Agent-Version.
Monitor — CPU- / Memory- / Disk- / Last-Panels füllen sich innerhalb ~30s.
Logs — Edge wählen, /var/log/* und journald-Tail sehen.
Topology — Host-Knoten erscheint.

Neuregistrieren / Schlüssel rotieren

Wenn Sie den Secret Key rotieren müssen (Kompromittierung, verlorener Schlüssel, Manager-Neuinstallation):

In der UI: Edges → <Ihre Edge> → Rotate keys. Dies invalidiert den alten Secret und zeigt einen neuen.
Den neuen Installationsbefehl kopieren. Es ist der gleiche Einzeiler mit dem neuen --access-key / --secret-key.
Auf dem Edge-Host den Installationsbefehl neu ausführen. Er wird:
- Den laufenden ongrid-edge sauber stoppen, bevor das Binary überschrieben wird,
- Das Binary neu holen (sodass eine alte Edge die Manager-Version übernimmt),
- Die Plugin-Binaries neu holen,
- /etc/ongrid-edge/ongrid-edge.env mit den neuen Schlüsseln neu schreiben (Mode 0640, Eigentümer root:ongrid-edge),
- systemctl restart ongrid-edge,
- Den Self-Check neu ausführen.

Der gleiche Fluss ist, was Sie verwenden, um eine Edge auf einen neuen Manager zu upgraden. Neuregistrierung ist idempotent.

Deinstallation

bash

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

Stoppt + deaktiviert den Service, entfernt das Binary, die systemd-Unit und das env-Verzeichnis. Bewahrt /var/log/ongrid-edge, sodass Sie die Plugin-Log-Dateien für Forensik behalten können.

Hinter einem Corporate-Proxy / Firewall

Die beiden ausgehenden Ziele sind:

<manager-host>:40012 — geminio-Tunnel, einfaches TCP (TLS-on-Wire, wenn der Frontier des Managers dafür konfiguriert ist; der OSS-Build ist einfaches TCP hinter nginx-frontened geminio).
<manager-host>:443 — HTTPS für Plugin-Datenebene + Binary-Download + Upgrade-Bundle-Fetch.

Wenn Ihr Egress durch einen http-Proxy geht, setzen Sie HTTPS_PROXY in /etc/systemd/system/ongrid-edge.service.d/proxy.conf:

ini

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

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

Was als Nächstes

Erstinbetriebnahme-Checkliste — sobald ein paar Edges sich melden, das operator-seitige Setup (Alarme, Kanäle, Wissensbasis).
Upgrade — wie ongrid-edge sich selbst auf Operator-Befehl aktualisiert (One-Button-Upgrade aus der UI).
Plattformen / Linux-Edge — Distro-Matrix, Distros, die bekannt sind zu funktionieren, SELinux/AppArmor-Notizen.

Edge-Installation ​

Voraussetzungen ​

Die Edge in der UI erstellen ​

Installationsbefehl ​

Was auf der Disk landet ​

Verifizieren ​

In der UI sehen ​

Neuregistrieren / Schlüssel rotieren ​

Deinstallation ​

Hinter einem Corporate-Proxy / Firewall ​

Was als Nächstes ​

Edge-Installation

Voraussetzungen

Die Edge in der UI erstellen

Installationsbefehl

Was auf der Disk landet

Verifizieren

In der UI sehen

Neuregistrieren / Schlüssel rotieren

Deinstallation

Hinter einem Corporate-Proxy / Firewall

Was als Nächstes