iop/apps/control-plane

control-plane — Control Plane

여러 Edge를 연결하고 제어하며, Edge 설정 변경 요청과 명령 전달을 담당할 Go 기반 운영 제어 서버다. Control Plane은 Edge 데이터의 원본 저장소가 아니라 연결된 Edge를 제어하기 쉽게 만드는 레이어다.

현재 상태: Scaffold

현재 Control Plane은 실행 가능한 최소 서버 스캐폴드 단계다. Node를 직접 등록하거나 직접 스케줄링하는 계층으로 확정하지 않는다. Control Plane은 Edge를 통해 시스템을 제어하고, Edge가 자신의 설정, 로컬 런타임 상태와 Node registry를 운영하는 방향을 따른다. Edge는 다른 Control Plane으로 연결 대상을 옮겨도 실질 데이터 migration을 요구하지 않아야 한다.

IOP의 프론트엔드는 Control Plane 내부 UI가 아니라 Flutter-first Client로 둔다. Client의 기준 구현은 apps/client의 Flutter 앱이고, web 배포는 apps/client/Dockerfile이 빌드한 Flutter Web 산출물을 compose web 서비스에서 nginx로 정적 서빙한다. Client-Control Plane 통신은 proto-socket WebSocket/WSS를 우선하고, Control Plane-Edge 통신은 edge-node에서 사용 중인 proto-socket 흐름을 IOP Wire Protocol 기준으로 확장한다. net/http는 health/readiness/bootstrap 같은 보조 endpoint 용도로만 둔다.

운영 경계

Control Plane은 상시 운영, multi-edge 연결/health 확인, fleet-wide 명령, 정책/감사 UX의 계획된 기본 운영면이다. Edge-local bootstrap, bundle-local config, env/config 진단, node 등록 command 발급, smoke, 단일 Edge 유지보수 fallback은 iop-edge CLI에 남긴다.

Control Plane-Edge wire protocol은 Edge가 소유한 operation을 원격 운영면으로 소비한다. Edge 상태 조회, node 및 후속 agent 등록 상태 조회, command 전달, event 수신, run/cancel/status, bootstrap 발급 상태처럼 CLI와 Control Plane에 모두 필요한 작업은 Edge 내부의 표면 중립 service/operation boundary로 수렴시키고, Control Plane에서 Edge-local registry, run dispatch, stream relay 구현을 복제하지 않는다. Control Plane이 보관할 수 있는 정보는 연결 view, 제어 요청/결과, audit에 필요한 최소 운영 기록으로 제한한다.

계약 원문은 Control Plane-Edge wire는 repo root의 agent-contract/inner/control-plane-edge-wire.md, Client-Control Plane wire는 agent-contract/inner/client-control-plane-wire.md를 기준으로 한다.

현재 실행 표면

• GET /healthz
• GET /readyz
• Client WS proto-socket wire endpoint: server.wire_listen (기본 0.0.0.0:19080, /client 경로). 브라우저/앱 Client 경계다.
• Edge TCP proto-socket wire endpoint: server.edge_wire_listen (기본 0.0.0.0:19081). Edge가 outbound로 연결하는 Control Plane-Edge native wire 경계이며 Client WS와 같은 listener를 공유하지 않는다.
• Control Plane DB 접속 설정 예약: database.url
• Control Plane Redis 접속 설정 예약: redis.url, redis.key_prefix

두 wire endpoint는 환경변수로 override한다. Client WS는 IOP_WIRE_LISTEN, Edge TCP는 IOP_EDGE_WIRE_LISTEN으로 listen 주소를 바꾼다. compose dev 환경은 host publish port를 IOP_CONTROL_PLANE_WIRE_PORT(기본 19080), IOP_CONTROL_PLANE_EDGE_WIRE_PORT(기본 19081)로 분리해 둔다.

로컬 직접 실행 테스트는 configs/control-plane.yaml의 database.url, redis.url, redis.key_prefix를 사용한다. tracked 기본 예시는 DB/Redis URL을 비워 두며, 실제 환경값은 IOP_DATABASE_URL, IOP_REDIS_URL, IOP_REDIS_KEY_PREFIX 환경변수로 주입한다. dev compose 환경은 Postgres 기본 DB명을 iop-control-plane-dev, Redis DB를 2와 iop:control-plane:dev: key prefix로 둔다.

계획된 기능

• Go 단일 바이너리 운영 제어 서버
• 여러 Edge 연결 관리
• Edge 상태 조회
• Edge 설정 변경 요청
• Edge 명령 전달
• Edge 이벤트 수신
• Policy/Config, Job/Worker, Audit, Metrics/Event API 제공