iop/agent-spec/control/control-plane-operations.md

spec_doc_type	spec_id	status	source_evidence
spec	control/control-plane-operations	부분	type path notes contract agent-contract/inner/control-plane-edge-wire.md Control Plane-Edge proto-socket TCP 계약 type path notes contract agent-contract/inner/client-control-plane-wire.md Client-Control Plane proto-socket WebSocket 계약 type path notes code apps/control-plane/internal/wire/edge_server.go Control Plane Edge TCP server, hello, status request, command dispatch type path notes code apps/edge/internal/controlplane/connector.go Edge mTLS connector, hello projection apply, lease acquisition, status response, command event relay type path notes code apps/control-plane/cmd/control-plane/credential_http_handlers.go Principal-authenticated credential HTTPS slot/route lifecycle type path notes code apps/control-plane/internal/credentiallease/service.go Durable binding re-read, secret open, signed recipient-sealed lease issuance type path notes code apps/control-plane/cmd/control-plane/http_edge_handlers.go Control Plane HTTP edge registry/status/events/commands view type path notes code apps/client/lib/control_plane_status_repository.dart Flutter client HTTP status repository type path notes code apps/client/lib/iop_wire/client_wire_client.dart Flutter proto-socket Client hello baseline type path notes test apps/control-plane/internal/wire/edge_server_test.go Control Plane-Edge wire 검증 type path notes test apps/control-plane/cmd/control-plane/edge_registry_handler_test.go provider 일반·long counter의 typed view와 HTTP JSON mapping 검증 type path notes test apps/edge/internal/service/status_provider_test.go configured offline Node/provider snapshot과 reconnect capacity 복구 검증

스펙: Control Plane 운영 기능

목적

Control Plane과 Client가 Edge 운영 상태를 어떻게 관찰하고 명령을 전달하는지 설명한다.

기능 목록

기능	설명
Control Plane server	HTTP health/readiness endpoint, Client proto-socket WebSocket endpoint, Edge proto-socket TCP endpoint를 함께 시작한다.
Client hello wire	/client WebSocket proto-socket에서 ClientHelloRequest/ClientHelloResponse baseline을 제공한다.
Edge outbound enrollment	Edge가 Control Plane TCP wire로 outbound 연결하고 EdgeHelloRequest를 보낸다. edge_id가 비어 있으면 거부된다.
credential HTTPS	Dedicated server-authenticated HTTPS exposes principal-authenticated slot and route lifecycle; provider plaintext is accepted only for create/rotate and is sealed before persistence.
host-local principal bootstrap	Initial principal/token bootstrap remains an offline CLI operation and returns the raw token only once; no remote bootstrap route exists.
managed CP-Edge security	Credential mode requires CP-Edge mTLS and certificate workload identity agreement with edge_id.
principal projection sync	Accepted hello carries the current secret-free projection, and durable mutations push strictly newer generations to connected managed Edges.
credential lease issuance	Edge requests a lease on the same authenticated connection after exact route/provider selection; Control Plane re-reads current generation, route, and slot before issuing a short-lived signed envelope sealed to the selected Node.
Edge connection registry	Control Plane은 Edge connection을 in-memory로 관리하고 reconnect stale cleanup을 connection token으로 방지한다.
Edge status request	Control Plane이 connected Edge에 EdgeStatusRequest를 보내 node/provider snapshot을 받는다.
connectivity-aligned provider snapshot	configured Node는 disconnect/pending 상태에도 connected=false로 남고 provider identity는 offline/zero effective state로 유지되며 reconnect ready 뒤 capacity와 함께 복구된다.
Edge command dispatch	Control Plane이 EdgeCommandRequest를 connected Edge에 보내고 response와 lifecycle event를 bounded audit view에 기록한다.
Edge/Fleet HTTP view	/edges, /edges/{id}, /edges/{id}/status, /edges/{id}/events, /edges/{id}/operations, /edges/{id}/commands와 fleet status 계열을 제공한다.
Flutter status repository	Flutter Client가 HTTP repository로 Edge/fleet status, events, operations, command response를 가져온다.
Flutter proto-socket client	Flutter proto-socket client는 현재 hello baseline을 지원한다.
IOP console package	packages/flutter/iop_console은 embeddable console shell/panel contract를 제공한다.

범위

• 포함: Control Plane process endpoints, credential HTTPS and offline bootstrap, Edge mTLS enrollment, projection/lease flow, Edge registry, status request/response, command dispatch/event audit, Client hello wire, Flutter status repository.
• 제외: Control Plane이 Edge config/state canonical store가 되는 기능, Node 직접 연결/스케줄링, durable audit DB, 정책/권한 model, full UI 정의 동기화.

주요 흐름

sequenceDiagram
  participant Client
  participant CP as Control Plane
  participant Edge

  Edge->>CP: EdgeHelloRequest
  CP->>CP: verify mTLS identity, build projection
  CP-->>Edge: accepted hello + PrincipalProjection
  CP->>Edge: PrincipalProjectionApplyRequest after mutation
  Edge-->>CP: applied generation
  Edge->>CP: AcquireLeaseRequest(exact binding, Node recipient)
  CP-->>Edge: signed recipient-sealed lease or rejection
  Client->>CP: HTTP edge/fleet status
  CP->>Edge: EdgeStatusRequest
  Edge-->>CP: EdgeStatusResponse
  CP-->>Client: status view
  Client->>CP: command request
  CP->>Edge: EdgeCommandRequest
  Edge-->>CP: command response/event
  CP-->>Client: command result

계약

• iop.control-plane-edge-wire: agent-contract/inner/control-plane-edge-wire.md
• iop.client-control-plane-wire: agent-contract/inner/client-control-plane-wire.md
• proto 원문: proto/iop/control.proto

설정/데이터/이벤트

• Control Plane config는 configs/control-plane.yaml과 apps/control-plane/cmd/control-plane/main.go config loader를 기준으로 한다.
• Client WS listen은 IOP_WIRE_LISTEN, Edge TCP listen은 IOP_EDGE_WIRE_LISTEN으로 override할 수 있다.
• Edge connector 설정은 configs/edge.yaml의 control_plane 섹션이다.
• Managed Control Plane startup requires the credential HTTPS certificate/key, CP-Edge mTLS certificate/key/CA, durable database, external at-rest encryption keyring, lease issuer key id/private key, and bounded lease TTL/cache. Key and credential contents are mounted files, not tracked YAML values.
• The projection contains active token hashes and safe route/slot/profile/model/revision facts only. Lease acquisition re-reads durable generation, route, and slot state, so revoke/disable/rotation and stale revisions fail closed even if a request observed an older snapshot.
• Slot/route mutation success includes projection synchronization. Operator lifecycle is bootstrap, create slot, bind route, rotate by expected revision, disable/enable when reversible suspension is needed, and revoke when permanent invalidation is required.
• Edge registry recent node events와 command audit는 bounded in-memory buffer다. durable audit store가 아니다.
• EdgeNodeSnapshot.connected는 current dispatch-ready ownership과 같고 accepted/pending connection은 false다. configured offline provider는 status=unavailable, health=offline, capacity/in-flight/queued/long-context 관련 수치를 0으로 보고한다.
• online provider의 in-flight는 Edge provider lease state, queued 값은 Edge queue의 candidate pressure다. current owner의 ready/disconnect 전이 뒤에만 관측 event가 relay되고 stale/rejected close는 live snapshot/event를 바꾸지 않는다.
• Client build-time endpoint는 IOP_CONTROL_PLANE_HTTP_URL, IOP_CONTROL_PLANE_WIRE_URL Dart define으로 주입된다.

검증

• go test ./apps/control-plane/internal/wire
• go test ./apps/control-plane/cmd/control-plane
• go test ./apps/edge/internal/controlplane
• make test-control-plane-edge-wire
• go test ./apps/control-plane/internal/credentialstore ./apps/control-plane/internal/credentialops ./apps/control-plane/internal/credentiallease
• go test ./apps/control-plane/cmd/control-plane -run 'Credential|SecureDelivery'
• make client-test - Flutter 환경과 dependency가 준비되어 있을 때 실행한다.

한계와 주의사항

• Credential slot/route state and projection generation are durable in the configured SQL store; the general fleet command/event audit remains an in-memory bounded view rather than a durable audit ledger.
• Client-Control Plane proto-socket wire는 hello baseline이고, 운영 상태 조회는 현재 HTTP repository가 담당한다.
• Edge/command/event registry는 in-memory bounded view다. audit, 권한, durable history는 별도 설계가 필요하다.
• Control Plane status/command 응답에 Node address, token, transport internals를 넣지 않는다.
• Control Plane이 Node를 직접 연결하거나 스케줄링하는 구조를 만들지 않는다.
• Raw principal tokens, provider plaintext, ciphertext, private keys, lease ids, and target URLs must not appear in logs, metrics, status/event payloads, or task evidence.

변경 기록

• 2026-07-07: 현재 Control Plane/Client 코드와 wire 계약 기준으로 bootstrap spec 작성.
• 2026-07-07: 기능 목록 중심으로 축소하고 주요 흐름을 Mermaid sequence diagram으로 정리.
• 2026-07-22: dispatch-ready connectivity와 configured offline provider snapshot, reconnect capacity 복구, current-owner event 의미를 현재 Edge status 구현과 계약 기준으로 동기화.
• 2026-08-02: Synchronized credential HTTPS, host-local bootstrap, CP-Edge mTLS identity, active projection refresh, authenticated lease issuance, and durable slot/route lifecycle with current source.