macOS (edge, 개발 전용)

ongrid-edge 바이너리는 darwin/amd64 와 darwin/arm64 로 크로스 컴파일됩니다. Makefile 은 make build-edge-all 의 일부로 둘 다 빌드합니다:

text

build-edge-darwin-amd64   → bin/darwin-amd64/ongrid-edge
build-edge-darwin-arm64   → bin/darwin-arm64/ongrid-edge

이 바이너리들은 에이전트를 개발하는 엔지니어가 Linux VM 을 띄우지 않고 Mac 에서 반복 작업할 수 있도록 존재합니다. 지원되는 프로덕션 대상이 아닙니다.

macOS 에서 동작하는 것

에이전트 프로세스가 시작되어 셸에서 ONGRID_EDGE_* 환경 변수를 읽고, 매니저로 가는 geminio 터널을 엽니다.
라이프사이클 RPC 동작: 에이전트가 등록되고 하트비트를 보내며, 매니저가 시작한 도구 호출을 받습니다.
bash skill (cmdpolicy 게이팅) 이 호스트에 대해 실행됩니다: ls, ps, df, uname 등 큐레이션된 읽기 전용 집합이 광고대로 동작합니다.
내장 gopsutil 컬렉터가 host_info, get_host_load, get_host_processes 를 받쳐 줍니다. 실제 숫자를 반환합니다.
127.0.0.1:22 에 대한 WebSSH 가 동작합니다 (System Settings 에서 Remote Login 을 활성화했다고 가정).

macOS 에서 동작하지 않는 것

기능	이유
`promtail` 로그 플러그인	Grafana 가 릴리스 tarball 에 darwin promtail 바이너리를 게시하지 않습니다. `make fetch-promtail` 단계는 Linux 만 받습니다.
`node_exporter` 호스트 메트릭 플러그인	동일한 업스트림 공백 — node_exporter 는 Linux 전용 릴리스만 배포합니다.
`process-exporter` 프로세스 메트릭 플러그인	동일한 업스트림 공백.
`otelcol-contrib` 트레이스 플러그인	Linux 만 번들 — 릴리스 tarball 크기 관리 목적.
curl-pipe 설치 스크립트	`deploy/install/edge/install.sh` 가 명시적으로 `only linux is supported by this installer; got: darwin` 으로 에러를 냅니다.
systemd 식 supervision	macOS 는 launchd 를 씁니다. 릴리스에는 launchd plist 가 들어가지 않습니다.
`journald` 로그 소스	macOS 는 unified log (`os_log`) 를 씁니다 — promtail 바이너리가 있다 해도 로그 플러그인은 다른 reader 가 필요합니다.
ADR-024 staged-bundle 업그레이드 훅	훅은 `ExecStartPre=` 에 연결된 Linux 셸 스크립트입니다. 동등 경로가 없습니다.

실무에서 이것이 의미하는 바: Mac 에서 make build-edge-darwin-arm64 후 ./bin/darwin-arm64/ongrid-edge 를 실행하면, 매니저 UI 의 Edges 페이지에 노트북이 나타나고, 에이전트와 대화하여 ls, ps, df 를 실행시킬 수 있지만, 그 edge 에 대해 Logs 페이지, Monitor 페이지의 호스트 패널, Traces 페이지는 모두 비어 있을 것입니다.

Mac 에서 에이전트 실행

# 1. cross-compile (or just `go build`, since you're already on darwin)
make build-edge-darwin-arm64

# 2. point at your manager
export ONGRID_EDGE_CLOUD_ADDR=ongrid.example.com:40012
export ONGRID_EDGE_ACCESS_KEY=<from manager UI: Edges → New>
export ONGRID_EDGE_SECRET_KEY=<from manager UI; shown once>

# 3. run it in the foreground
./bin/darwin-arm64/ongrid-edge

에이전트는 stderr 로 로그를 씁니다. 아무도 /var/log/ongrid-edge/ 를 만들지 않으므로 그 디렉터리는 없습니다. 로그 파일이 필요하면 리다이렉트하세요: ./ongrid-edge 2>&1 | tee ~/ongrid-edge.log.

launchd? 아직

launchd plist 가 있다면 로그인 시 자동 시작과 자동 재시작을 얻을 수 있습니다. 우리가 아직 배포하지 않은 이유는:

네 개의 플러그인이 어차피 macOS 에서 돌지 않으므로, 거기서 supervise 되는 에이전트는 추론하기 어려운 기능 부분집합을 줍니다.
프로덕션에서 macOS 호스트는 극히 드뭅니다. 반쯤만 지원하는 플랫폼에 약속을 걸고 싶지 않습니다.

자체 개발용으로 하나 만들고 싶다면, 최소 예시를 둡니다. ~/Library/LaunchAgents/io.ongrid.edge.plist 로 저장하세요:

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>io.ongrid.edge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/ongrid-edge</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>ONGRID_EDGE_CLOUD_ADDR</key><string>ongrid.example.com:40012</string>
    <key>ONGRID_EDGE_ACCESS_KEY</key><string>...</string>
    <key>ONGRID_EDGE_SECRET_KEY</key><string>...</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/ongrid-edge.out.log</string>
  <key>StandardErrorPath</key><string>/tmp/ongrid-edge.err.log</string>
</dict>
</plist>

그리고 launchctl load ~/Library/LaunchAgents/io.ongrid.edge.plist.

코드 서명 / Gatekeeper

에이전트는 코드 서명되어 있지 않습니다. 처음 실행할 때 macOS 가 "개발자를 검증할 수 없어 열 수 없습니다" 로 거부합니다. 둘 중 하나로 해결합니다:

xattr -d com.apple.quarantine ./ongrid-edge 로 검역 플래그 제거, 또는
Finder 에서 우클릭 → Open 으로 한 번 열면 이후로는 선택을 기억합니다.

자기 Mac 에서 소스 빌드 (go build ./cmd/ongrid-edge) 하면 검역 플래그 자체가 붙지 않습니다.

프로덕션에서 macOS 를 써야 할까요?

아닙니다. Linux 박스를 쓰세요. 월 $5 짜리 Linux VM 에서 에이전트가 완벽히 동작하며, Mac mini 에서 돌리는 것은 홈랩용으로는 동작하지만 Ongrid 가 제공하는 가치의 80% 를 공급하는 네 개의 플러그인 (호스트 메트릭, 로그, 트레이스) 을 잃습니다.

개발 전용 경로는 개발 중에 에이전트를 dogfood 할 수 있도록 존재합니다. 배포 대상이 아닙니다.

macOS (edge, 개발 전용) ​

macOS 에서 동작하는 것 ​

macOS 에서 동작하지 않는 것 ​

Mac 에서 에이전트 실행 ​

launchd? 아직 ​

코드 서명 / Gatekeeper ​

프로덕션에서 macOS 를 써야 할까요? ​