toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add Domain Agent concept and OTO bootstrap direction

Browse source 
- Add Domain Agent section to README (specialized build/deploy agent)
- Update architecture diagram with OTO Agent under Edge Group
- Add Edge bootstrap/enrollment surface for domain agents
- Document OTO agent bootstrap flow (Jenkins-like node connection UX)
- Add deploy-dev.md section for OTO Agent bootstrap direction
- Support HTTP local/insecure mode with token/pinning/verification
This commit is contained in:
toki 2026-05-21 08:49:17 +09:00
parent 0309543472
commit f285db2310
3 changed files with 80 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
README.md
View file

@ -22,8 +22,9 @@ IOP의 실행 대상은 크게 두 가지다.
- Docker
- Code workspace 작업
- NomadCode 계열 자동화 작업
- OTO 같은 build/deploy domain agent
IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다.
IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다. 다만 모든 실행자를 `iop-node` 하위 프로세스로 흡수하지는 않는다. OTO처럼 자체 도메인과 배포 단위를 가진 자동화 도구는 Edge에 직접 붙는 specialized domain agent로 다룰 수 있다.
## Core Concept
@ -60,10 +61,10 @@ Control Plane
├─ Edge Group A
│ ├─ Node 1
│ ├─ Node 2
│ └─ Node 3
│ └─ OTO Agent 1
└─ Edge Group B
├─ Node 4
└─ Node 5
├─ Node 3
└─ OTO Agent 2
```
Control Plane은 Node에 직접 연결하지 않는다. 전체 시스템 제어는 Edge를 통해 이뤄지고, Edge는 자신이 관리하는 Node와 로컬 런타임 상태의 원본을 가진다.
@ -105,7 +106,9 @@ Edge는 단순 API gateway가 아니라 백엔드 전용 실행 그룹 컨트롤
Edge의 핵심 역할은 다음과 같다.
- Node registry
- Domain agent registry
- Node configuration
- Agent bootstrap/enrollment
- Adapter/Profile configuration
- Runtime routing
- Edge service API surface
@ -128,6 +131,14 @@ Node는 모델 런타임, CLI Agent, 도구 실행을 담당한다. Node는 Cont
Node는 가능한 한 단순한 실행 단위로 유지한다. 정책, 전체 시스템 조정, 다중 Edge 운영 판단을 Node에 밀어 넣지 않고, 전달받은 실행을 안정적으로 수행하는 데 집중한다.
### Domain Agent
Domain agent는 특정 자동화 도메인을 자체 바이너리와 자체 실행 모델로 가진 Edge 연결 실행자다.
OTO는 build/deploy domain agent의 대표 후보로 둔다. `oto-agent`는 `iop-node`를 통해 터미널 실행되는 하위 프로세스가 아니라, Edge에서 생성된 agent 등록 정보와 bootstrap command를 사용해 설치되고 Edge에 직접 outbound 연결한다. Edge는 OTO agent를 별도 agent type으로 인식하고, build run, cancel, status, capability, artifact, log event를 메시지 기반으로 제어한다.
이 경계에서 `iop-node`는 generic execution agent이고, OTO는 specialized build/deploy agent다.
### Worker Structure
Edge, Node, Control Plane은 별도 `iop-worker` 앱으로 분리하지 않고, 각 Go 서비스 내부의 공통 Worker 모듈을 사용한다. 공통 처리 모델은 `Job Queue`, `Worker Pool`, `Job Status`, `Retry`, `Timeout`, `Cancel`이며, Worker가 담당하는 역할은 서비스별 책임에 맞춰 분리한다.
@ -208,7 +219,7 @@ NomadCode
|---|---|
| `apps/web` | IOP 전체 Web Portal을 위한 Next.js 스캐폴드 |
| `apps/node` | Edge에 연결되어 adapter execution을 수행하는 Node agent |
| `apps/edge` | Node registry, 설정 전달, routing, stream relay를 담당하는 Edge skeleton |
| `apps/edge` | Node/domain agent registry, 설정 전달, bootstrap, routing, stream relay를 담당하는 Edge skeleton |
| `apps/control-plane` | 여러 Edge를 연결하고 Portal과 통신할 Go 기반 운영 제어 서버 스캐폴드 |
| `apps/worker` | 현재 placeholder이며, Worker 구조는 우선 각 Go 서비스 내부 공통 모듈 방향으로 둔다 |
| `packages` | 설정, 인증, 정책, 작업, 관측성, 버전 등 공통 패키지 |
@ -226,6 +237,10 @@ Edge의 외부 입력 표면은 두 방식을 병행 지원한다.
두 입력 방식은 Edge의 inbound/input surface로 함께 관리하고, 내부 실행은 기존 `RunRequest`/`RunEvent` 흐름으로 수렴시킨다. IOP native protocol은 이 둘을 대체하는 외부 호환 API가 아니라, Control Plane/Portal/운영 CLI가 Edge/Node 운영 제어와 lifecycle event를 다루기 위한 wire protocol로 유지한다.
Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 bootstrap/enrollment 표면을 제공한다. 목표 UX는 Jenkins node 연결처럼 Edge에서 agent를 먼저 생성하고, Edge가 발급한 bootstrap command를 대상 머신에서 실행해 agent를 설치/등록하는 방식이다. OTO는 이 경로의 대표 build/deploy agent이며, `iop-node`에 종속되지 않고 Edge에 직접 연결한다.
폐쇄망과 개발망을 고려해 bootstrap HTTP endpoint는 HTTPS를 기본 권장하되 필수 전제로 두지 않는다. HTTP local/insecure 모드를 허용하는 대신 one-time bootstrap token, Edge fingerprint 또는 public key pinning, 바이너리 checksum/signature 검증, 등록 후 장기 credential 재발급을 계약에 포함한다.
### Phase 1. Edge-Node execution skeleton
- Edge-Node 소켓 연결
@ -240,6 +255,8 @@ Edge의 외부 입력 표면은 두 방식을 병행 지원한다.
- 모델 서빙 adapter 확장
- CLI Agent 실행 안정화
- Runtime / Automation 실행 흐름 공통화
- Edge agent registry를 generic node와 specialized domain agent를 함께 다룰 수 있는 모델로 확장
- Edge가 agent type별 bootstrap command를 발급하는 HTTP bootstrap 표면 설계
- Node local execution history와 Edge event aggregation 경계 정리
- IOP native execution protocol을 기존 protobuf `RunRequest`, `RunEvent`, `NodeCommandRequest`, `EdgeNodeEvent` 계열 계약 위에서 정식화
- native protocol에는 node 선택, `adapter + target`, logical session, background run, cancel/terminate-session, capabilities/status/session/transport command, node lifecycle event처럼 OpenAI-compatible API로 표현하기 어려운 기능을 둠
@ -254,6 +271,7 @@ Edge의 외부 입력 표면은 두 방식을 병행 지원한다.
- Edge 명령 전달
- 이벤트 수신
- Portal-Control Plane, Control Plane-Edge 통신은 IOP Wire Protocol(protobuf-socket)을 기준으로 확장하고, 브라우저 직접 TCP가 어려운 경우 server-side bridge를 둠
- Portal/Control Plane에서 Edge agent 생성과 bootstrap command 발급 상태를 조회/관리
- OpenAI-compatible HTTP API는 외부 모델 클라이언트 호환 표면으로 유지하되, 운영/제어/세션 기능의 기본 프로토콜로 확장하지 않음
- A2A HTTP API는 Core/외부 agent가 Edge 실행 그룹에 작업을 위임하는 표준 입력으로 유지하되, Control Plane의 Edge 운영 제어 프로토콜로 확장하지 않음
@ -263,6 +281,7 @@ Edge의 외부 입력 표면은 두 방식을 병행 지원한다.
- Edge별 runtime/automation 상태 표시
- Edge 단위 실행 이력과 상태 집계
- Edge 단위 작업 실행과 제어
- OTO 같은 domain agent의 build/deploy 상태, artifact, capability를 Edge 단위 운영 화면과 이벤트 집계에 포함
- multi-edge 운영 명령과 이벤트 집계는 IOP native protocol을 기준으로 설계하고, OpenAI-compatible 표면은 특정 Edge/adapter로 라우팅되는 inference 호환 경로로 제한
- A2A 표면은 특정 Edge/adapter로 위임되는 agent task 경로로 제한하고, multi-edge scheduling과 fleet-wide state ownership은 Control Plane/native protocol에서 결정

25
docs/architecture.md
View file

@ -14,8 +14,10 @@ Control Plane
│ ├─ Node 1
│ │ ├─ adapter: cli
│ │ └─ adapter: ollama
│ └─ Node 2
│ └─ adapter: vllm
│ ├─ Node 2
│ │ └─ adapter: vllm
│ └─ OTO Agent
│ └─ domain: build/deploy
└─ Edge Group B
└─ Node 3
└─ adapter: cli
@ -27,6 +29,8 @@ Edge는 여러 Node를 묶는 실행 그룹 컨트롤러다. Edge는 Node regist
Node는 실제 실행자다. Node는 Edge에 연결되어 adapter execution을 수행하고, RuntimeEvent를 Edge로 돌려준다. 연결 생명주기와 이후 제어/상태성 이벤트는 RunEvent와 분리된 EdgeNodeEvent envelope로 다룬다.
Edge는 Node만 관리하는 컨트롤러로 고정하지 않는다. OTO처럼 독립 바이너리와 독립 실행 도메인을 가진 도구는 specialized domain agent로 Edge에 직접 연결할 수 있다. 이 경우 OTO agent는 `iop-node`의 하위 실행물이 아니라 Edge가 별도 agent type으로 등록하고 제어하는 build/deploy 실행자다.
## 현재 Edge-Node 흐름
현재 검증 중인 기본 흐름은 다음과 같다.
@ -44,6 +48,13 @@ Node
└─ resolves adapter + target
└─ executes adapter
└─ emits RuntimeEvent / EdgeNodeEvent
OTO Agent
└─ installed by Edge bootstrap command
└─ registers as build/deploy domain agent
└─ receives run/cancel/status/capability messages
└─ executes YAML pipeline
└─ emits step/log/artifact/result events
```
현재 실행 이력은 Node의 local SQLite store에서 검증 중이다. Edge 단위 이력 집계와 로컬 실행 그룹 상태 소유권은 로드맵에 따라 정리한다.
@ -110,8 +121,10 @@ type Adapter interface {
- Edge-Node 내부 통신은 TCP + protobuf 기반 소켓 흐름을 우선한다.
- Node는 Edge에 연결한다.
- OTO 같은 domain agent도 Edge에 직접 outbound 연결한다.
- Control Plane은 향후 Edge와 소켓 기반 연결을 맺는다.
- Control Plane이 Node에 직접 연결하거나 매 요청마다 Node를 직접 스케줄링하는 구조는 목표가 아니다.
- OTO agent는 Control Plane이나 `iop-node`에 직접 종속되지 않고 Edge의 agent registry와 bootstrap/enrollment 계약을 따른다.
- Portal-Control Plane, Control Plane-Edge, Edge-Node의 장기 통신 기준은 IOP Wire Protocol(protobuf-socket)이다. 브라우저가 직접 TCP를 사용할 수 없는 구간은 Web Portal이 직접 wire client가 되기보다 Control Plane의 server-side bridge를 통해 연결한다.
- OpenAI-compatible HTTP API와 A2A JSON-RPC HTTP API는 Edge 외부 입력 표면으로 유지하며, Control Plane 운영 제어 프로토콜의 기본값으로 삼지 않는다.
@ -119,7 +132,9 @@ type Adapter interface {
Control Plane과 Web은 중앙 운영면으로 묶어 compose 기반 서비스로 배포한다. dev 필드 테스트 compose에는 Control Plane DB와 Redis 후보를 함께 포함해 이후 schema, audit, event, queue 작업을 같은 배포 단위 안에서 진행한다.
Edge와 Node는 Docker 이미지로 만들지 않고 호스트 단일 바이너리로 배포한다. Jenkins는 Edge/Node 바이너리만 빌드하고, 각 호스트는 배포된 바이너리의 `setup` 명령을 통해 systemd 실행 환경을 준비한다.
Edge와 Node는 Docker 이미지로 만들지 않고 호스트 단일 바이너리로 배포한다. Jenkins는 Edge/Node 바이너리만 빌드하고, 각 호스트는 배포된 바이너리의 `setup` 명령을 통해 systemd 실행 환경을 준비한다. OTO는 별도 프로젝트의 단일 바이너리 build/deploy agent로 두고, 장기적으로는 Edge가 OTO agent 생성과 bootstrap command 발급을 담당한다.
Edge bootstrap UX는 Jenkins node 연결 방식과 유사하게 둔다. Edge에서 agent를 먼저 만들고 one-time token이 포함된 bootstrap command를 발급하면, 대상 머신이 이 command를 실행해 agent 바이너리 설치, 설정 생성, service 등록, Edge 등록을 완료한다. 폐쇄망과 개발망을 고려해 HTTPS를 권장하되 강제하지 않고, HTTP local/insecure 모드는 one-time token, Edge fingerprint 또는 public key pinning, checksum/signature 검증을 함께 요구한다.
운영 CLI는 분기된 설치 방식을 만들지 않는다. 공식 경로는 `iop-edge setup`과 `iop-node setup` 하나로 고정하고, 검토나 CI 확인은 별도 `render` 명령이 아니라 `--dry-run` 옵션으로 흡수한다.
@ -137,6 +152,10 @@ edge host:
node host:
iop-node setup -> systemd unit + config/data directories [구현 완료]
systemd -> iop-node serve --config /etc/iop/node.yaml
oto build host:
edge bootstrap command -> oto binary + agent config/service
systemd -> oto agent --config /etc/oto/agent.yaml
```
`setup`은 idempotent해야 한다. 기존 설정 파일은 기본적으로 덮어쓰지 않고, 필요한 디렉터리와 unit만 생성/갱신하며, `--enable`, `--start`, `--restart`, `--dry-run` 같은 옵션으로 운영 차이를 표현한다. `status`, `logs`, `start`, `stop`, `restart` 같은 명령은 초기 CLI에 넣지 않고 `systemctl`과 `journalctl`을 기준 운영 도구로 둔다.

34
docs/deploy-dev.md
View file

@ -19,9 +19,14 @@ edge host
node host
iop-node binary
node.yaml
oto build host
oto binary
agent.yaml
```
Edge와 Node는 Docker 이미지로 만들지 않는다. Jenkins는 repo의 shell entrypoint를 호출해 Edge/Node 바이너리 산출물을 만든다.
OTO는 별도 프로젝트의 단일 바이너리 산출물로 두고, IOP Edge는 장기적으로 OTO agent를 설치/등록시키는 bootstrap provider 역할을 가진다.
## Edge/Node 바이너리 빌드
@ -111,6 +116,35 @@ repo root에서 수동으로 검증할 때는 기존 helper를 사용할 수 있
IOP_EDGE_ADDR=<edge-host>:9090 ./bin/node.sh
```
## OTO Agent Bootstrap 방향
OTO는 `iop-node`에 종속시키지 않고 Edge에 직접 붙는 build/deploy domain agent로 둔다. 목표 UX는 Jenkins node 연결처럼 Edge에서 먼저 OTO agent를 생성하고, Edge가 발급한 bootstrap command를 대상 빌드 머신에서 실행하는 방식이다.
예상 흐름은 다음과 같다.
```text
Edge UI/API
-> oto agent 생성
-> one-time bootstrap token과 install command 발급
oto build host
-> bootstrap command 실행
-> OS/arch에 맞는 oto binary 다운로드
-> checksum/signature 검증
-> agent.yaml 생성
-> systemd/launchd/Windows service 등록
-> Edge에 outbound 등록
```
폐쇄망과 개발망에서는 도메인 인증서 발급이 어려울 수 있으므로 HTTPS를 필수 전제로 두지 않는다. 대신 HTTP local/insecure 모드는 명시적으로 선택하게 하고, one-time token, Edge fingerprint 또는 public key pinning, 바이너리 checksum/signature 검증, 등록 후 장기 credential 재발급을 함께 요구한다.
예시 command 형태는 다음처럼 둔다.
```bash
curl -fsSL http://edge.local:8080/bootstrap/oto.sh \
| sh -s -- --edge http://edge.local:8080 --token <one-time-token> --pool build-linux
```
## Field Smoke
최소 확인 순서는 다음을 기준으로 한다.