toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-contract/inner/control-plane-edge-wire.md

3.3 KiB
Raw Blame History

Control Plane-Edge Wire Contract

계약 메타

  • id: iop.control-plane-edge-wire
  • boundary: inner
  • status: active-mvp
  • 원본 경로:
    • proto/iop/control.proto
    • apps/control-plane/internal/wire/wire.go
    • apps/control-plane/internal/wire/edge.go
    • apps/control-plane/internal/wire/edge_server.go
    • apps/edge/internal/controlplane/connector.go
  • human docs: apps/control-plane/README.md

읽는 조건

  • Control Plane-Edge TCP proto-socket endpoint를 바꿀 때
  • EdgeHello*, EdgeStatus*, EdgeCommand*, EdgeNodeSnapshot, EdgeNodeEvent를 바꿀 때
  • Edge status/command/event relay가 Edge-owned node registry나 runtime state를 어떻게 노출하는지 검토할 때

범위

이 계약은 Edge가 Control Plane으로 outbound 연결하는 내부 운영 wire다. Control Plane은 Edge 연결 view와 제어 요청/결과를 관리하고, Edge는 자신의 Node registry와 runtime 상태를 소유한 채 snapshot과 event를 보고한다.

주요 흐름

  • hello: Edge가 EdgeHelloRequest를 보내고 Control Plane이 EdgeHelloResponse로 enrollment를 승인 또는 거부한다.
  • status: Control Plane이 EdgeStatusRequest를 보내고 Edge가 EdgeStatusResponse로 Edge-owned snapshot을 반환한다.
  • command: Control Plane이 EdgeCommandRequest를 보내고 Edge가 EdgeCommandResponse와 EdgeCommandEvent로 처리 결과와 phase를 보고한다.
  • lifecycle event: Edge는 EdgeNodeEvent로 node/edge lifecycle event를 relay한다.

필드 의미

  • EdgeHelloRequest.edge_id: Control Plane connection registry의 Edge identity다. 비어 있으면 hello는 거부된다.
  • EdgeStatusResponse.nodes: Edge가 소유한 node snapshot view다.
  • EdgeNodeSnapshot.config: Node에 내려간 config payload의 관찰용 요약이다.
  • EdgeNodeSnapshot.provider_snapshots: runtime ProviderSnapshot wire name을 재사용한 Node resource/provider snapshot이다. category가 CLI/API/local inference resource kind를 구분하며, Node address, token, transport internals는 싣지 않는다.
  • EdgeCommandRequest.operation: Edge-owned operation 이름이다. Node 직접 scheduling 명령으로 사용하지 않는다.
  • EdgeCommandRequest.target_selector: Edge 내부 operation이 해석할 대상 selector다. Node address나 token을 외부화하지 않는다.
  • metadata: 필요한 Edge identity 또는 운영 보조 정보만 담는다. secret과 private endpoint 원문은 tracked 계약에 쓰지 않는다.

금지 사항

  • Control Plane에서 Node를 직접 연결하거나 직접 스케줄링하는 계약을 만들지 않는다.
  • ScheduleRequest/ScheduleResponse legacy tombstone을 활성 계약으로 되살리지 않는다.
  • Edge가 보고하지 않은 Node address, token, transport internals를 status/command 응답에 넣지 않는다.
  • Control Plane을 Edge 설정, Node registry, runtime/automation 상태의 원본 저장소로 만들지 않는다.
  • gRPC를 기본 Control Plane-Edge wire로 도입하지 않는다.

변경 시 확인할 코드/테스트

  • proto/iop/control.proto
  • apps/control-plane/internal/wire/edge_server_test.go
  • apps/control-plane/internal/wire/edge_test.go
  • apps/edge/internal/controlplane/connector_test.go
  • apps/edge/internal/controlplane/heartbeat_test.go
  • proto 변경 시 make proto