toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-ops/rules/project/domain/control-plane/rules.md
toki de78479670 refactor: organize contract files and update agent-ops structure 
- Move contract files to inner/outer directory structure
- Add create-contract and update-contract skills
- Update agent-ops rules and domain rules
- Update roadmap and SDD documentation
- Update README files across apps
2026-06-27 07:02:48 +09:00

7.2 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
control-plane 49872ae120 2026-06-03

control-plane

목적 / 책임

여러 Edge를 연결하고 운영 제어할 제어면 영역이다. Control Plane은 Edge를 제어하기 쉽게 만드는 attachable layer이며, Edge의 실질 설정과 상태 원본을 소유하지 않는다. 현재는 health/readiness와 Edge registry 조회 HTTP, 환경별 설정 로딩, Client proto-socket WebSocket, Edge proto-socket TCP 연결 baseline을 제공하며, Node 직접 연결이나 직접 스케줄링은 책임으로 삼지 않는다.

포함 경로

  • apps/control-plane/cmd/control-plane/ — control-plane CLI 진입점, 설정 로딩, HTTP health/readiness와 Edge registry 조회 endpoint, wire server lifecycle
  • apps/control-plane/internal/wire/ — Control Plane wire protocol 상수, Client WebSocket endpoint, Edge TCP server와 in-memory Edge registry
  • 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/client/ — Control Plane을 소비하는 Flutter client UI/UX 영역
  • apps/node/ — 실제 adapter execution과 runtime session의 소유자
  • apps/worker/ — 비동기 작업 처리 예정 영역
  • packages/go/ — 여러 앱이 공유하는 Go 공통 패키지
  • proto/ — 메시지 계약 원본과 생성물
  • configs/ — 앱별 설정 예시와 공통 설정 계약 확인 영역

주요 구성 요소

  • rootCmd() / serveCmd() — control-plane serve command와 기본 config path 구성
  • controlPlaneConfig — HTTP listen, Client wire listen, Edge wire listen, DB, Redis, logging 설정 구조
  • loadConfig() / applyEnvOverrides() — YAML 설정 로딩과 IOP_* 환경 변수 override
  • run() — health/readiness/Edge registry HTTP server, Client WS server, Edge TCP server lifecycle 조립
  • registerEdgeRegistryHandlers() — /edges, /edges/{edge_id}, /edges/{edge_id}/events JSON 조회 endpoint
  • wire.Protocol — Control Plane 통신 표준을 protobuf-socket으로 고정하는 상수
  • wire.Endpoint — reserved wire endpoint 설정 타입
  • wire.ClientServer — /client WebSocket proto-socket hello 요청을 처리하는 서버 구현
  • wire.EdgeServer — Edge outbound TCP proto-socket 연결을 수락하고 hello/status/event 흐름을 처리하는 서버 구현
  • wire.EdgeRegistry — Edge connection view와 최근 node lifecycle event relay를 보관하는 in-memory registry
  • wire.EdgeParserMap() — Control Plane-Edge wire message parser map
  • wire.EdgeServer.RequestStatus() — 연결된 Edge에 EdgeStatusRequest를 보내 Edge-owned node snapshot을 조회하는 helper

유지할 패턴

  • Control Plane은 Edge를 통해 시스템을 관찰/제어한다. Node를 직접 등록하거나 직접 스케줄링하는 active contract를 만들지 않는다.
  • Control Plane은 Edge의 설정, Node registry, runtime/automation 상태의 canonical store가 아니다. Control Plane이 소유할 수 있는 것은 연결 view, 제어 요청/결과, audit에 필요한 최소 운영 기록으로 제한한다.
  • Edge는 다른 Control Plane으로 연결 대상을 옮길 수 있어야 한다. Control Plane 교체나 이전이 Edge 실질 데이터 migration을 요구하는 구조를 만들지 않는다.
  • Control Plane은 상시 운영, multi-edge 관찰/명령, 정책/감사 UX의 기본 운영면으로 확장한다. Edge-local bootstrap, config, 진단, 단일 Edge 유지보수 fallback을 대체하거나 제거하는 전제로 설계하지 않는다.
  • Control Plane-Edge wire protocol은 Edge가 소유한 operation contract를 원격 운영면으로 소비하는 형태로 설계한다. Edge CLI와 같은 행위를 노출해야 하면 Edge 쪽 표면 중립 service/operation boundary로 수렴시킨다.
  • net/http는 health/readiness와 단순 조회성 status endpoint에 우선 사용하고, IOP 고유 양방향 운영 통신은 proto-socket 기반 wire protocol로 확장한다.
  • 브라우저/앱 경계는 WebSocket/WSS proto-socket을 사용할 수 있다. Edge-Node TCP transport 기준을 이 경계에 억지로 적용하지 않는다.
  • Control Plane-Edge native wire는 Edge가 outbound로 연결하는 TCP proto-socket 경계로 둔다. Client WebSocket listener와 Edge TCP listener를 혼동하지 않는다.
  • Control Plane-Edge wire 상세는 agent-contract/inner/control-plane-edge-wire.md, Client-Control Plane wire 상세는 agent-contract/inner/client-control-plane-wire.md를 기준으로 확인한다.
  • Edge registry는 현재 in-memory connection/control view이다. durable history, audit, 정책 저장소를 이 registry에 섞지 않는다.
  • Edge status 조회는 Edge가 보고한 EdgeStatusResponse를 관찰한다. Control Plane에서 Node address, token, transport internals, Edge 설정 원본을 직접 소유하지 않는다.
  • 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를 통해 상태 조회, 설정 변경 요청, 명령 전달, 이벤트 수신을 확장한다. Control Plane 없는 bootstrap/local/field/진단 fallback은 iop-edge command 표면에 남긴다.
  • client: Client는 Control Plane의 HTTP/WS 표면을 소비하는 UI/UX와 Dart wire wrapper를 소유한다. Control Plane은 server endpoint와 Edge connection/control view를 소유한다.
  • platform-common: protobuf 원본, 생성물, 공통 설정/관측성 helper는 platform-common 계약을 따른다.
  • testing: Control Plane command, wire endpoint, bootstrap/enrollment 사용자 흐름을 바꾸면 testing domain rule의 검증 기준을 따른다.

금지 사항

  • Control Plane에서 Node를 직접 연결하거나 직접 스케줄링하는 경로를 제품 기본 계약으로 만들지 않는다.
  • Edge 설정, Node registry, runtime/automation 상태의 원본 저장소를 Control Plane에 만들지 않는다.
  • Edge-local registry, run dispatch, stream relay 구현을 Control Plane으로 복제하지 않는다.
  • Edge가 보고하지 않은 Node address/token/scheduling 필드를 Control Plane status API에 만들지 않는다.
  • Control Plane 도입만을 이유로 Edge-local CLI bootstrap/config/진단 fallback을 제품 기본 계약에서 제외하거나 제거하지 않는다. 축소는 별도 roadmap 결정과 대체 fallback 기준이 있을 때만 다룬다.
  • gRPC를 Control Plane 기본 wire protocol로 도입하지 않는다.
  • 실제 DB/Redis credential이나 환경별 endpoint를 tracked docs/rules에 기록하지 않는다.