diff --git a/README.md b/README.md index 795f4df..a36a13e 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,8 @@ Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 폐쇄망과 개발망을 고려해 bootstrap HTTP endpoint는 HTTPS를 기본 권장하되 필수 전제로 두지 않는다. HTTP local/insecure 모드를 허용하는 대신 one-time bootstrap token, Edge fingerprint 또는 public key pinning, 바이너리 checksum/signature 검증, 등록 후 장기 credential 재발급을 계약에 포함한다. +Agent를 설치하기 어려운 대상은 별도 축으로 다룬다. Edge는 `agent-terminal` tunnel 또는 remote terminal bridge 표면을 제공하고, 대상에 도달 가능한 Node가 SSH/WinRM/serial/local shell 같은 terminal transport를 열어 stdin/stdout/stderr, resize, signal, session lifecycle을 Edge로 relay한다. 이 방식은 target device에 IOP agent를 심지 않는 운영 경로이지, 접근 경로 없이 완전 agentless 제어를 보장하는 모델은 아니다. + ### Phase 1. Edge-Node execution skeleton - Edge-Node 소켓 연결 @@ -257,9 +259,10 @@ Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 - Runtime / Automation 실행 흐름 공통화 - Edge agent registry를 generic node와 specialized domain agent를 함께 다룰 수 있는 모델로 확장 - Edge가 agent type별 bootstrap command를 발급하는 HTTP bootstrap 표면 설계 +- agent 설치가 어려운 target을 위해 CLI persistent terminal profile 기반 remote shell POC를 추가하고, Edge가 session broker, Node가 terminal transport 실행자 역할을 갖는 경계를 검증 - 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로 표현하기 어려운 기능을 둠 +- native protocol에는 node 선택, `adapter + target`, logical session, background run, cancel/terminate-session, capabilities/status/session/transport command, remote terminal session event, node lifecycle event처럼 OpenAI-compatible API로 표현하기 어려운 기능을 둠 - Edge input surface는 OpenAI-compatible 입력을 모델/채팅 호환 경로로, A2A 입력을 agent 작업 위임과 상태 공유 경로로 분리해 유지 ### Phase 3. Control Plane @@ -272,6 +275,7 @@ Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 - 이벤트 수신 - Portal-Control Plane, Control Plane-Edge 통신은 IOP Wire Protocol(protobuf-socket)을 기준으로 확장하고, 브라우저 직접 TCP가 어려운 경우 server-side bridge를 둠 - Portal/Control Plane에서 Edge agent 생성과 bootstrap command 발급 상태를 조회/관리 +- Portal/Control Plane에서 remote terminal bridge session 생성, 대상 선택, 권한 확인, audit 조회를 지원하되 Control Plane이 Node에 직접 붙지 않고 Edge를 통해 제어 - OpenAI-compatible HTTP API는 외부 모델 클라이언트 호환 표면으로 유지하되, 운영/제어/세션 기능의 기본 프로토콜로 확장하지 않음 - A2A HTTP API는 Core/외부 agent가 Edge 실행 그룹에 작업을 위임하는 표준 입력으로 유지하되, Control Plane의 Edge 운영 제어 프로토콜로 확장하지 않음 @@ -288,6 +292,7 @@ Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 ### Phase 5. Policy, History, Audit - 권한, 정책, 이력, 감사 기능 확장 +- remote terminal bridge는 target allowlist, credential 관리, command/session audit, timeout, 동시 실행 제한, 입력/출력 기록 정책을 필수 설계 항목으로 둠 - 상세 설계는 후속 작업에서 결정 ## Development Notes @@ -298,6 +303,7 @@ Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 - OpenAI API 호환 계층은 외부 호환을 위한 표면이며, 내부 실행 모델 전체를 대표하지 않는다. - A2A API 계층은 agent 간 작업 위임과 상태 공유를 위한 표면이며, 단순 모델 호출 호환은 OpenAI-compatible API를 사용한다. - IOP native protocol은 OpenAI-compatible API나 A2A API를 대체하는 것이 아니라, Edge/Node 운영 제어와 CLI/session/command/event 같은 IOP 고유 기능을 제공하는 병행 표면이다. +- Remote terminal bridge는 Edge/Node 운영 제어 기능으로 분류하며, OpenAI-compatible API가 아니라 IOP native protocol과 정책/audit 계층에서 다룬다. - 앱별 README에는 현재 수동 테스트나 구현 세부가 더 많이 남아 있을 수 있다. 루트 README는 전체 방향과 경계를 설명하는 문서로 유지한다. ## Non-Goals for Current Stage diff --git a/docs/architecture.md b/docs/architecture.md index fdd67bb..b603467 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -31,6 +31,8 @@ Node는 실제 실행자다. Node는 Edge에 연결되어 adapter execution을 Edge는 Node만 관리하는 컨트롤러로 고정하지 않는다. OTO처럼 독립 바이너리와 독립 실행 도메인을 가진 도구는 specialized domain agent로 Edge에 직접 연결할 수 있다. 이 경우 OTO agent는 `iop-node`의 하위 실행물이 아니라 Edge가 별도 agent type으로 등록하고 제어하는 build/deploy 실행자다. +Agent를 설치하기 어려운 대상은 remote terminal bridge로 다룬다. Edge는 terminal session broker가 되고, 대상에 도달 가능한 Node가 local shell, SSH, WinRM, serial 같은 transport를 열어 stdin/stdout/stderr, resize, signal, session lifecycle을 relay한다. 이 경로는 target device에 IOP agent를 설치하지 않는 운영 방식이지만, 네트워크나 credential 같은 접근 경로 없이 대상을 제어하는 완전 agentless 모델은 아니다. + ## 현재 Edge-Node 흐름 현재 검증 중인 기본 흐름은 다음과 같다. @@ -122,6 +124,7 @@ type Adapter interface { - Edge-Node 내부 통신은 TCP + protobuf 기반 소켓 흐름을 우선한다. - Node는 Edge에 연결한다. - OTO 같은 domain agent도 Edge에 직접 outbound 연결한다. +- Remote terminal bridge는 Control Plane이 Node에 직접 붙는 구조가 아니라, Control Plane/Portal/운영 CLI가 Edge에 terminal session을 요청하고 Edge가 적절한 Node terminal transport로 중계하는 구조로 둔다. - Control Plane은 향후 Edge와 소켓 기반 연결을 맺는다. - Control Plane이 Node에 직접 연결하거나 매 요청마다 Node를 직접 스케줄링하는 구조는 목표가 아니다. - OTO agent는 Control Plane이나 `iop-node`에 직접 종속되지 않고 Edge의 agent registry와 bootstrap/enrollment 계약을 따른다. @@ -136,6 +139,8 @@ Edge와 Node는 Docker 이미지로 만들지 않고 호스트 단일 바이너 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 검증을 함께 요구한다. +Remote terminal bridge UX는 bootstrap과 분리한다. 대상에 agent를 설치할 수 있으면 bootstrap/enrollment를 우선하고, 설치가 어렵거나 일회성 유지보수 대상이면 Edge가 사전에 허용된 Node terminal profile을 통해 대상 terminal을 연다. 이 기능은 target allowlist, credential 관리, timeout, 동시 실행 제한, session audit를 전제로 한다. + 운영 CLI는 분기된 설치 방식을 만들지 않는다. 공식 경로는 `iop-edge setup`과 `iop-node setup` 하나로 고정하고, 검토나 CI 확인은 별도 `render` 명령이 아니라 `--dry-run` 옵션으로 흡수한다. ```text diff --git a/docs/deploy-dev.md b/docs/deploy-dev.md index 7b7b817..331282f 100644 --- a/docs/deploy-dev.md +++ b/docs/deploy-dev.md @@ -27,6 +27,7 @@ oto build host Edge와 Node는 Docker 이미지로 만들지 않는다. Jenkins는 repo의 shell entrypoint를 호출해 Edge/Node 바이너리 산출물을 만든다. OTO는 별도 프로젝트의 단일 바이너리 산출물로 두고, IOP Edge는 장기적으로 OTO agent를 설치/등록시키는 bootstrap provider 역할을 가진다. +Agent 설치가 어렵거나 일회성 유지보수 대상인 host/device는 별도 배포 단위로 보지 않고, 대상에 접근 가능한 Node의 terminal profile을 통해 Edge가 remote terminal bridge session을 중계하는 방향으로 둔다. ## Edge/Node 바이너리 빌드 @@ -120,6 +121,8 @@ IOP_EDGE_ADDR=:9090 ./bin/node.sh OTO는 `iop-node`에 종속시키지 않고 Edge에 직접 붙는 build/deploy domain agent로 둔다. 목표 UX는 Jenkins node 연결처럼 Edge에서 먼저 OTO agent를 생성하고, Edge가 발급한 bootstrap command를 대상 빌드 머신에서 실행하는 방식이다. +Agent를 설치할 수 있는 대상은 bootstrap/enrollment를 우선한다. 설치가 어렵거나 임시 제어만 필요한 대상은 Edge가 remote terminal bridge session을 열고, 대상에 도달 가능한 Node가 SSH/WinRM/serial/local shell 같은 terminal transport를 실행해 relay한다. 이 경로는 target allowlist, credential 관리, timeout, session audit를 전제로 한다. + 예상 흐름은 다음과 같다. ```text