iop/agent-ops/rules/project/domain/control-plane/rules.md

domain	last_rule_review_commit	last_rule_updated_at
control-plane	6e1c201d0b	2026-05-28

control-plane

목적 / 책임

여러 Edge를 관찰하고 운영 제어할 중앙 제어면 영역이다. 현재는 health/readiness HTTP, 환경별 설정 로딩, proto-socket WebSocket hello baseline을 제공하며, Node 직접 연결이나 직접 스케줄링은 책임으로 삼지 않는다.

포함 경로

• apps/control-plane/cmd/control-plane/ — control-plane CLI 진입점, 설정 로딩, HTTP health/readiness 서버, wire server lifecycle
• apps/control-plane/internal/wire/ — Control Plane wire protocol 상수와 WebSocket proto-socket endpoint
• apps/control-plane/README.md — Control Plane 현재 상태와 계획된 운영 책임 설명
• apps/control-plane/Dockerfile — Control Plane 배포용 이미지 빌드 표면

제외 경로

• apps/edge/ — Edge-local Node registry, routing, input surface, stream relay의 소유자
• apps/node/ — 실제 adapter execution과 runtime session의 소유자
• apps/worker/ — 비동기 작업 처리 예정 영역
• packages/ — 여러 앱이 공유하는 공통 패키지
• proto/ — 메시지 계약 원본과 생성물
• configs/ — 앱별 설정 예시와 공통 설정 계약 확인 영역

주요 구성 요소

• rootCmd() / serveCmd() — control-plane serve command와 기본 config path 구성
• controlPlaneConfig — HTTP listen, wire listen, DB, Redis, logging 설정 구조
• loadConfig() / applyEnvOverrides() — YAML 설정 로딩과 IOP_* 환경 변수 override
• run() — health/readiness HTTP server와 WebSocket wire server lifecycle 조립
• wire.Protocol — Control Plane 통신 표준을 protobuf-socket으로 고정하는 상수
• wire.Endpoint — reserved wire endpoint 설정 타입
• wire WebSocket server — proto-socket hello 요청을 처리하는 서버 구현

유지할 패턴

• Control Plane은 Edge를 통해 시스템을 관찰/제어한다. Node를 직접 등록하거나 직접 스케줄링하는 active contract를 만들지 않는다.
• net/http는 health/readiness/bootstrap 같은 보조 endpoint에 우선 사용하고, IOP 고유 운영 통신은 proto-socket 기반 wire protocol로 확장한다.
• 브라우저/앱 경계는 WebSocket/WSS proto-socket을 사용할 수 있다. Edge-Node TCP transport 기준을 이 경계에 억지로 적용하지 않는다.
• ScheduleRequest/ScheduleResponse는 legacy placeholder로만 취급하고, 새 orchestration 계약은 Edge-owned runtime state를 우회하지 않도록 다시 설계한다.
• Control Plane 설정에 실제 환경값, credential, private endpoint를 tracked 문서에 쓰지 않는다. 환경별 값은 private rule 라우팅을 따른다.
• proto 계약을 바꾸면 proto/iop/*.proto를 먼저 수정하고 Go 생성물을 명령으로 갱신한다.

다른 도메인과의 경계

• edge: Edge는 로컬 실행 그룹 상태와 Node registry를 소유한다. Control Plane은 Edge를 통해 상태 조회, 설정 변경, 명령 전달, 이벤트 수신을 확장한다.
• platform-common: protobuf 원본, 생성물, 공통 설정/관측성 helper는 platform-common 계약을 따른다.
• testing: Control Plane command, wire endpoint, bootstrap/enrollment 사용자 흐름을 바꾸면 testing domain rule의 검증 기준을 따른다.

금지 사항

• Control Plane에서 Node를 직접 연결하거나 직접 스케줄링하는 경로를 제품 기본 계약으로 만들지 않는다.
• Edge-local registry, run dispatch, stream relay 구현을 Control Plane으로 복제하지 않는다.
• gRPC를 Control Plane 기본 wire protocol로 도입하지 않는다.
• 실제 DB/Redis credential이나 환경별 endpoint를 tracked docs/rules에 기록하지 않는다.