Установка edge

ongrid-edge — это единый статический Go-бинарь плюс четыре plugin subprocess'а. Нет compose, нет БД, нет входящего порта — одно исходящее TCP-соединение к frontier-брокеру и одно исходящее HTTPS-соединение на плагин к плоскости данных.

Каноническая установка — curl-pipe с эндпоинта manager /install.sh. Manager сервит installer, бинарь агента, plugin-бинари и upgrade hook из того же /edge/ static-пути, так что единственное, что нужно оператору, — это сетевой маршрут обратно к manager.

Prereqs

Целевому хосту нужно:

• Linux на amd64 или arm64. macOS edge'и работают, но теряют logs
  • hostmetrics плагины (upstream Grafana / node_exporter не отгружают darwin-build'ы); см. macOS edge dev.
• systemd для service supervision.
• исходящий TCP/40012 к manager (control plane).
• исходящий TCP/443 к manager (data plane — логи + трейсы push).
• curl и root (installer re-exec'ит через sudo при необходимости).
• Нет конкретного RAM/disk floor — агент сильно ниже 50 MB RSS плюс что бы ни использовали plugin subprocess'ы.

Создать edge в UI

1. Войти в manager.
2. Edges → New edge.
3. Назовите (например, prod-web-01). Опциональное описание.
4. Нажмите Create.

Detail-страница теперь показывает:

• Access key (AK_...) — server-generated, идентифицирует edge.
• Secret key (SK_...) — показан один раз. Потеряете — ротируете.
• Install command — curl ... | sudo bash -s -- однострочник с access key, secret key, edge tunnel-эндпоинтом и HTTP- эндпоинтом запечёнными.

Захватите secret key СЕЙЧАС

Secret key показывается один раз. Если потеряете до установки, удалите и пересоздайте edge — это безопаснее, чем копаться в DB- бэкапах.

Install command

Скопируйте однострочник из UI. Он выглядит как:

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

Семантика флагов:

• --access-key / --secret-key — auth material для geminio- туннеля. Агент презентует их при дозвоне; frontier просит edgeauth manager'а верифицировать.
• --server-edge-addr — host:port для control plane. Всегда 40012, если вы это не override'или.
• --server-http-addr — host:port для плоскости данных и download бинаря. Тот же host:port, который ваш браузер использует, чтобы дотянуться до UI. Plain host разрешён (по умолчанию 443). Installer скачивает свой бинарь с https://<http-addr>/edge/ongrid-edge-<os>-<arch>.

Запустите. Installer re-exec'ит через sudo, если вы ещё не.

Что приземляется на диске

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

Installer также:

• Создаёт системного пользователя ongrid-edge (без home, без shell).
• Добавляет ongrid-edge в adm и systemd-journal, чтобы logs- плагин (promtail) мог читать /var/log/* (root:adm 640) и journal.
• systemctl daemon-reload && systemctl enable --now ongrid-edge.

Верификация

Installer ждёт до 20 секунд (override через ONGRID_INSTALL_WAIT=N), пока агент не залогирует agent: registered with cloud в journal. Здоровая установка печатает:

[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

Если STATUS=failed или pending, installer дампит последние 20 строк journal'а и подсказывает вам наиболее вероятный фикс. Ручные проверки:

# 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

Самые частые отказы и что они значат:

Симптом	Вероятная причина	Фикс
unauthorized в journal	опечатка access/secret key или устаревший ключ	Ротируйте edge в UI; перезапустите installer с новыми ключами.
connection refused on :40012	frontier-брокер не выставлен / firewall	Проверьте iptables / cloud SG; верифицируйте docker compose ps frontier на manager.
Self-check: plugin binary MISSING	Старая установка до plugin-bundle, или curl с manager, который никогда не запускал install.sh	Перезапустите install command — он всегда re-fetches plugin-бинари.
Self-check: невозможно прочитать journal	ongrid-edge не в группе systemd-journal	sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge.
Edge "online", но Logs/Traces пусты	ONGRID_PUBLIC_URL на manager указывает на внутренний IP	Отредактируйте /opt/ongrid/.env на manager; перезапустите compose.

Увидеть в UI

• Edges — зелёная точка рядом с именем вашего edge. Карточка показывает hostname, ядро, дистрибутив, общую RAM, диск, версию агента.
• Monitor — CPU / memory / disk / load панели наполняются в пределах ~30с.
• Logs — выберите edge, увидите /var/log/* и journald tail.
• Topology — host-узел появляется.

Re-register / ротация ключей

Если вам нужно ротировать secret key (компрометация, потерянный ключ, manager re-install):

1. В UI, Edges → <your edge> → Rotate keys. Это инвалидирует старый secret и показывает новый.
2. Скопируйте новую install command. Это тот же однострочник с новыми --access-key / --secret-key.
3. На edge-хосте перезапустите install command. Он:
   • Чисто остановит работающий ongrid-edge до перезаписи бинаря,
   • Refetch'ит бинарь (так что старый edge подхватит manager'скую версию),
   • Refetch'ит plugin-бинари,
   • Перепишет /etc/ongrid-edge/ongrid-edge.env с новыми ключами (mode 0640, owner root:ongrid-edge),
   • systemctl restart ongrid-edge,
   • Перезапустит self-check.

Тот же flow — что вы используете для апгрейда edge до нового manager. Повторная регистрация идемпотентна.

Деинсталляция

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

Останавливает + отключает service, удаляет бинарь, systemd-unit и env-директорию. Сохраняет /var/log/ongrid-edge, так что вы можете оставить plugin-log-файлы для forensics.

За корпоративным прокси / firewall

Два исходящих назначения:

• <manager-host>:40012 — geminio-туннель, plain TCP (TLS-on-wire, если frontier manager'а сконфигурирован для этого; OSS-сборка — plain TCP за nginx-fronted geminio).
• <manager-host>:443 — HTTPS для plugin data plane + binary download + upgrade bundle fetch.

Если ваш egress идёт через http-прокси, поставьте HTTPS_PROXY в /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

Затем systemctl daemon-reload && systemctl restart ongrid-edge.

Что дальше

• Чек-лист первого запуска — как только пара edge'ей check'инятся, operator-side setup (алерты, каналы, база знаний).
• Апгрейд — как ongrid-edge обновляется по команде оператора (one-button-upgrade из UI).
• Платформы / Linux edge — distro- матрица, distros, известно работающие, SELinux/AppArmor заметки.