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 d7324fe184 feat: client integration and control-plane phase updates 
- Update control-plane and edge domain rules
- Update roadmap phase and current status
- Archive client-integration-clone-adoption and nexo-notification-message-smoke-alignment milestones
- Update control-plane-client milestone
- Add client assets, lib/src, integrations tests
- Add google-services.json for client android
- Update client pubspec, build configs, and platform manifests
2026-05-30 18:02:06 +09:00

4.6 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
control-plane 7b9345bc1a 2026-05-30

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를 만들지 않는다.
  • 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/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를 통해 상태 조회, 설정 변경, 명령 전달, 이벤트 수신을 확장한다. Control Plane 없는 bootstrap/local/field/진단 fallback은 iop-edge command 표면에 남긴다.
  • 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으로 복제하지 않는다.
  • Control Plane 도입만을 이유로 Edge-local CLI bootstrap/config/진단 fallback을 제품 기본 계약에서 제외하거나 제거하지 않는다. 축소는 별도 roadmap 결정과 대체 fallback 기준이 있을 때만 다룬다.
  • gRPC를 Control Plane 기본 wire protocol로 도입하지 않는다.
  • 실제 DB/Redis credential이나 환경별 endpoint를 tracked docs/rules에 기록하지 않는다.