Edge 설치

ongrid-edge 는 단일 정적 Go 바이너리에 4 개의 플러그인 서브 프로세스가 붙은 형태입니다. compose 도 DB 도 인바운드 포트도 없습니다 — frontier 브로커로의 아웃바운드 TCP 연결 하나, 플러그인당 데이터 플레인으로의 아웃바운드 HTTPS 연결 하나입니다.

표준 설치는 매니저의 /install.sh 엔드포인트에서 curl-pipe 입니다. 매니저는 같은 /edge/ 정적 경로에서 installer, 에이전트 바이너리, 플러그인 바이너리, 업그레이드 훅을 제공하므로 운영자에게 필요한 것은 매니저로의 네트워크 경로뿐입니다.

사전 요건

대상 호스트에 필요한 것:

• amd64 또는 arm64 의 Linux. macOS edge 도 동작하지만 logs + hostmetrics 플러그인을 잃습니다 (업스트림 Grafana / node_exporter 가 darwin 빌드를 제공하지 않음); macOS edge dev 참고.
• 서비스 감독용 systemd.
• 매니저로의 아웃바운드 TCP/40012 (컨트롤 플레인).
• 매니저로의 아웃바운드 TCP/443 (데이터 플레인 — 로그 + 트레이스 push).
• curl 과 root (필요 시 installer 가 sudo 로 재실행).
• 특정 RAM/디스크 하한 없음 — 에이전트는 50 MB RSS 미만에 플러그인 서브 프로세스 사용량이 추가됨.

UI 에서 edge 생성

1. 매니저에 로그인.
2. Edges → New edge.
3. 이름 지정 (예: prod-web-01). 설명은 선택.
4. Create 를 누름.

상세 페이지에 다음이 표시됩니다:

• Access key (AK_...) — 서버 생성, edge 식별자.
• Secret key (SK_...) — 단 한 번 표시. 잃으면 회전.
• Install command — access key, secret key, edge 터널 엔드포인트, HTTP 엔드포인트가 박힌 curl ... | sudo bash -s -- 한 줄.

secret key 즉시 캡처

secret key 는 한 번만 표시됩니다. 설치 전에 잃으면 edge 를 삭제하고 재생성하세요 — DB 백업을 뒤지는 것보다 안전합니다.

설치 명령

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 — geminio 터널 인증 자료. 에이전트가 다이얼 시 이를 제시; frontier 가 매니저의 edgeauth 에 검증 요청.
• --server-edge-addr — 컨트롤 플레인용 host:port. 오버라이드하지 않는 한 항상 40012.
• --server-http-addr — 데이터 플레인 및 바이너리 다운로드용host:port. 브라우저가 UI 에 도달하는 같은 host:port. plain host 허용 (기본 443). installer 는 https://<http-addr>/edge/ongrid-edge-<os>-<arch> 에서 바이너리를 다운로드.

실행합니다. sudo 가 아니면 installer 가 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 시스템 사용자 (홈 없음, 셸 없음) 생성.
• ongrid-edge 를 adm 과 systemd-journal 에 추가하여 logs 플러그인 (promtail) 이 /var/log/* (root:adm 640) 와 journal 을 읽을 수 있게 함.
• systemctl daemon-reload && systemctl enable --now ongrid-edge.

검증

installer 는 에이전트가 journal 에 agent: registered with cloud 를 기록하기를 최대 20 초 기다립니다 (ONGRID_INSTALL_WAIT=N 로 오버라이드). 정상 설치는 다음을 출력:

[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 라인을 덤프하고 가장 유력한 수정 방향을 안내합니다. 수동 점검:

# 서비스 상태
sudo systemctl status ongrid-edge

# 라이브 journal
sudo journalctl -u ongrid-edge -f

# 데이터 플레인 도달성 테스트
curl -kI https://203.0.113.10/

# 컨트롤 플레인 도달성 테스트
nc -vz 203.0.113.10 40012

가장 흔한 실패와 의미:

Symptom	Likely cause	Fix
journal 에 unauthorized	access/secret key 오타 또는 만료된 key	UI 에서 edge 회전; 새 키로 installer 재실행.
connection refused on :40012	frontier 브로커가 노출되지 않음 / 방화벽	iptables / cloud SG 점검; 매니저에서 docker compose ps frontier 확인.
Self-check: plugin binary MISSING	플러그인 번들 이전의 오래된 설치, 또는 install.sh 가 실행된 적 없는 매니저에서의 curl	설치 명령 재실행 — 플러그인 바이너리는 항상 재 fetch.
Self-check: cannot read journal	ongrid-edge 가 systemd-journal 그룹에 없음	sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge.
Edge 는 "online" 이지만 Logs/Traces 비어 있음	매니저의 ONGRID_PUBLIC_URL 이 내부 IP 를 가리킴	매니저의 /opt/ongrid/.env 편집; compose 재시작.

UI 에서 확인

• Edges — edge 이름 옆 녹색 점. 카드에 hostname, 커널, 배포판, 총 RAM, 디스크, 에이전트 버전 표시.
• Monitor — CPU / 메모리 / 디스크 / load 패널이 약 30 초 안에 채워짐.
• Logs — edge 선택, /var/log/* 와 journald tail 확인.
• Topology — 호스트 노드 표시.

재등록 / 키 회전

secret key 회전이 필요한 경우 (유출, 키 분실, 매니저 재설치):

1. UI 에서 Edges → <your edge> → Rotate keys. 이전 secret 을 무효화하고 새 secret 을 표시.
2. 새 설치 명령 복사. 새로운 --access-key / --secret-key 를 가진 같은 한 줄.
3. edge 호스트에서 설치 명령 재실행. 다음을 수행:
   • 바이너리 덮어쓰기 전에 실행 중인 ongrid-edge 를 정상 종료,
   • 바이너리 재 fetch (오래된 edge 가 매니저의 버전을 픽업),
   • 플러그인 바이너리 재 fetch,
   • /etc/ongrid-edge/ongrid-edge.env 를 새 키로 재작성 (mode 0640, 소유자 root:ongrid-edge),
   • systemctl restart ongrid-edge,
   • 자체 점검 재실행.

같은 흐름이 edge 를 새 매니저로 업그레이드 하는 데 쓰입니다. 재등록은 멱등입니다.

제거

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

서비스 중지 + 비활성화, 바이너리, systemd unit, env 디렉터리 제거. 포렌식을 위해 플러그인 로그 파일을 유지할 수 있도록 /var/log/ongrid-edge 는 보존합니다.

사내 프록시 / 방화벽 뒤

두 아웃바운드 목적지:

• <manager-host>:40012 — geminio 터널, plain TCP (매니저의 frontier 가 구성되어 있으면 wire 상 TLS; OSS 빌드는 nginx-fronted geminio 뒤의 plain TCP).
• <manager-host>:443 — 플러그인 데이터 플레인 + 바이너리 다운로드 + 업그레이드 번들 fetch 용 HTTPS.

egress 가 http 프록시를 거치면 /etc/systemd/system/ongrid-edge.service.d/proxy.conf 에 HTTPS_PROXY 를 설정합니다.

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

그런 다음 systemctl daemon-reload && systemctl restart ongrid-edge.

다음은

• 첫 부팅 체크리스트 — edge 가 몇 개 체크인하면 운영자측 설정 (알림, 채널, 지식 베이스).
• Upgrade — UI 의 원-버튼 업그레이드에서 ongrid-edge 가 자체 업데이트하는 방법.
• Platforms / Linux edge — 배포판 매트릭스, 동작 확인된 배포판, SELinux/AppArmor 노트.