Linux (edge)

edge 에이전트 (ongrid-edge) 는 Ongrid 가 관측하려는 모든 호스트에서 실행됩니다. Linux 에서는 단일 curl-pipe 명령으로 systemd 서비스로 설치됩니다. 에이전트는 단일 정적 Go 바이너리에 네 개의 플러그인 바이너리 (promtail, node_exporter, process-exporter, otelcol-contrib) 를 더한 형태입니다.

아키텍처

GOOS	GOARCH	상태
linux	amd64	일급
linux	arm64	일급

설치 스크립트는 uname -m 을 읽어 매칭되는 바이너리를 고르며, 이는 매니저의 /edge/ 정적 경로에서 내려받습니다:

text

x86_64 / amd64  → amd64
aarch64 / arm64 → arm64
anything else   → error: "unsupported arch"

지원 배포판

서버와 같은 집합에서 테스트합니다. 실제로는 systemd 245+ (StateDirectory= 가 동작) 와 glibc 2.31+ 이면 에이전트가 잘 돕니다.

배포판	테스트 버전
Ubuntu	20.04 LTS, 22.04 LTS, 24.04 LTS
Debian	11 (bullseye), 12 (bookworm)
RHEL	8, 9
Rocky Linux	8, 9
AlmaLinux	8, 9
Amazon Linux	2023

배포판이 여전히 sysvinit, OpenRC, runit 을 쓴다면 아래 "non-systemd" 절을 참고하세요.

설치 스크립트가 떨어뜨리는 것

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 는 디스크에 다음을 배치합니다:

경로	용도
`/usr/local/bin/ongrid-edge`	에이전트 바이너리
`/usr/local/lib/ongrid-edge/promtail`	로그 플러그인
`/usr/local/lib/ongrid-edge/otelcol-contrib`	트레이스 플러그인
`/usr/local/lib/ongrid-edge/node_exporter`	호스트 메트릭 플러그인
`/usr/local/lib/ongrid-edge/process_exporter`	프로세스 메트릭 플러그인
`/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh`	ADR-024 staged-bundle swap 훅
`/etc/ongrid-edge/ongrid-edge.env`	access/secret 키, cloud addr (mode 640, root:ongrid-edge)
`/etc/systemd/system/ongrid-edge.service`	systemd 유닛
`/var/lib/ongrid-edge/`	StateDirectory: pending-upgrade 스테이징, dedupe 상태
`/var/log/ongrid-edge/`	로컬 로그 디렉터리 (mode 750, `ongrid-edge` 소유)

시스템 사용자 ongrid-edge (셸 없음, 홈 없음) 가 생성되며 두 그룹에 추가됩니다: adm (그래야 promtail 이 mode 640 root:adm 인 /var/log/* 를 읽을 수 있습니다) 과 systemd-journal (그래야 journal 을 읽을 수 있습니다).

systemd 유닛

deploy/install/edge/install.sh 에서 그대로:

ini

[Unit]
Description=ongrid edge agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/ongrid-edge/ongrid-edge.env
ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge
Restart=always
RestartSec=5
User=ongrid-edge
Group=ongrid-edge
AmbientCapabilities=CAP_NET_ADMIN
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
StateDirectory=ongrid-edge
StateDirectoryMode=0755
ReadWritePaths=/var/log/ongrid-edge
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

알아둘 만한 핵심 사항:

ProtectSystem=strict 이 /usr, /boot, /etc 를 읽기 전용으로 만듭니다. 에이전트는 StateDirectory= (/var/lib/ongrid-edge) 와 ReadWritePaths= (/var/log/ongrid-edge) 바깥으로는 절대 쓰지 않습니다.
AmbientCapabilities=CAP_NET_ADMIN 은 몇몇 edge skill 이 읽기 전용 네트워크 점검 (ss -ntlp 같은 탐색, nft list ruleset 을 통한 점검, conntrack 읽기) 을 할 수 있게 해 줍니다. 에이전트 자체는 raw socket 을 열지 않습니다.
ExecStartPre=-+ ( - 는 실패 무시, + 는 root 로 실행) 가 ADR-024 staged-bundle swap 을 연결합니다. 이전 부팅에서 pending 업그레이드가 스테이징되어 있었다면 이 훅이 그것을 적용한 뒤 어느 쪽이든 exit 0 으로 끝냅니다.
StandardOutput=journal 은 promtail 과의 계약입니다 — 에이전트 자체 로그는 pid-1 의 stdout 이 아니라 journald 에서 읽을 수 있고, promtail 의 journal 소스가 이를 집어 갑니다.

로그 소스: journald, syslog 아님

Promtail 은 journald 를 스크레이프하도록 구성되어 있습니다 (비영속은 /run/log/journal, 영속은 /var/log/journal). /var/log/syslog 나 /var/log/messages 를 tail 하지 않습니다. 배포판이 rsyslog 를 쓰고 영속 journal 을 비활성화해 두었다면, 활성화하세요:

mkdir -p /var/log/journal
systemd-tmpfiles --create --prefix /var/log/journal
systemctl restart systemd-journald

영속 journal 없이도 로그 플러그인은 동작하지만, 히스토리는 RAM 안의 런타임 journal (/run/log/journal) 로 제한됩니다.

non-systemd Linux (sysvinit / OpenRC / runit)

curl-pipe 설치 스크립트는 systemctl 부재 시 hard-fail 합니다. 그래도 에이전트를 돌릴 수는 있습니다 — 바이너리를 /usr/local/bin/ongrid-edge 에 두고, 필수 환경 변수 세 개 (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) 를 export 한 뒤 바이너리를 exec 하는 자신만의 init 스크립트를 작성하면 됩니다. 잃는 것:

크래시 시 자동 재시작 (init 시스템이 제공하는 것으로 대체).
apply-pending-upgrade.sh 훅, 따라서 원격 whole-bundle 업그레이드 (ADR-024) 가 조용히 no-op.
플러그인 바이너리 (설치 스크립트가 함께 받는 것들, 위 참조).

이 네 플러그인 바이너리도 https://<manager>/edge/<name>-linux-<arch> 에서 접근 가능합니다. 원하는 디렉터리로 손으로 받아 두고 ONGRID_EDGE_PLUGIN_BIN_DIR 을 그쪽으로 가리키세요.

에이전트가 필요 없는 권한

런타임에 root 가 필요 없습니다 (에이전트는 ongrid-edge 사용자로 실행됩니다).
CAP_SYS_ADMIN, CAP_NET_RAW, CAP_SYS_PTRACE 가 필요 없습니다. 어떤 skill 이 이 중 하나를 요구하면 cmdpolicy 게이트가 거절합니다.
Docker 가 필요 없습니다. 플러그인 런타임은 컨테이너가 아니라 단순 subprocess supervisor 입니다.

에이전트가 여는 포트

포트	Bind	이유
9101	localhost	에이전트 자신의 `/metrics` 및 `/healthz`
9102	localhost	node_exporter (hostmetrics 플러그인 활성화 시)
9256	localhost	process-exporter (procmetrics 플러그인 활성화 시)

방화벽을 통과해야 하는 것은 매니저의 40012 포트로 가는 아웃바운드 터널 연결 하나뿐입니다. edge 호스트에 인바운드 포트를 열 필요는 없습니다.

제거

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

서비스를 중지하고, 바이너리, env 파일, systemd 유닛을 제거합니다. /var/log/ongrid-edge/ 는 의도적으로 남겨 둡니다 — 완전히 지우고 싶다면 손으로 purge 하세요.

Linux (edge) ​

아키텍처 ​

지원 배포판 ​

설치 스크립트가 떨어뜨리는 것 ​

systemd 유닛 ​

로그 소스: journald, syslog 아님 ​

non-systemd Linux (sysvinit / OpenRC / runit) ​

에이전트가 필요 없는 권한 ​

에이전트가 여는 포트 ​

제거 ​