toki/oto
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oto/agent-roadmap/archive/phase/edge-direct-oto-agent/milestones/oto-agent-registration.md

7.1 KiB
Raw Blame History

Milestone: oto-agent 등록 흐름

위치

  • Roadmap: agent-roadmap/ROADMAP.md
  • Phase: agent-roadmap/archive/phase/edge-direct-oto-agent/PHASE.md

목표

설치된 oto-agent가 iop-node를 거치지 않고 Edge에 직접 outbound 연결하는 등록 흐름을 구현 가능한 단위로 정리한다.

상태

[폐기]

구현 잠금

  • 상태: 해제
  • 결정 필요: 없음

범위

  • Edge bootstrap script로 설치된 Linux oto-agent가 ~/.oto/agent/config.yaml을 읽고 Edge에 직접 outbound 등록하는 흐름을 정의한다.
  • bootstrap script가 전달한 agent 식별 값과 Edge 연결 정보를 사용해 등록을 시작하는 최소 흐름을 정의한다.
  • 백그라운드 등록/실행 후 Edge 등록 완료와 최초 heartbeat 도착까지의 상태 전이를 정의한다.
  • Edge identity 검증, checksum/signature, 장기 credential 세부 정책은 MVP 이후 보안 강화 항목으로 분리한다.

기능

Epic: [registration-contract] Edge 직접 등록 계약

bootstrap으로 설치된 Linux oto-agent가 설정 파일을 읽고 Edge에 직접 등록되는 상태 전이를 묶는다.

  • [token-flow] bootstrap agent 식별 값 또는 token의 전달과 최초 등록 사용 흐름이 정의되어 있다.
  • [edge-identity] Edge identity 검증을 MVP 최소 연결 기준과 후속 보안 강화 기준으로 분리해 정리되어 있다.
  • [binary-integrity] OTO repo release asset 다운로드 기준과 후속 checksum/signature 강화 기준이 분리되어 있다.
  • [service-runtime] 백그라운드 실행 상태와 agent 프로세스 재시작 기준이 정의되어 있으며, bootstrap script 실행 후 다운로드된 oto-agent가 ~/.oto/agent/config.yaml을 통해 Edge에 직접 연결하는 상태 전이가 구현 가능한 수준으로 분해되어 있다.
  • [registration-state] Edge 등록 성공/실패, 최초 heartbeat 기반 online 판정, 재시도 기준과 백그라운드 실행 실패/등록 실패/heartbeat 미도착 상태 구분이 정의되어 있다. 검증: Edge 등록 완료와 최초 heartbeat 도착을 online으로 보는 판정 기준, 실패 상태 구분, 재시도 기준이 구현 가능한 수준으로 설명된다.

완료 리뷰

  • 상태: 폐기
  • 요청일: 없음
  • 완료 근거: iop2oto online smoke와 workspace lock 해제 근거는 확인되었지만, 제품 기본 경로가 독립 OTO Server/Runner로 전환되어 iop Edge 직접 등록 Milestone은 완료 대상이 아니라 폐기한다.
  • 리뷰 필요:
    • 사용자가 완료 결과를 확인했다
    • archive 이동을 승인했다
  • 리뷰 코멘트: iop Edge 직접 연결 내용은 독립 Control Plane 분리 마이그레이션의 source map/evidence로만 보존한다.

범위 제외

  • generic node agent 기능을 포함하지 않는다.
  • 원격 파이프라인 실행 메시지 전체를 구현하지 않는다.
  • 운영용 인증서 관리 시스템을 구현하지 않는다.
  • MVP에서 checksum/signature, Edge fingerprint, credential rotation 강제 구현을 포함하지 않는다.

작업 컨텍스트

  • 관련 경로: lib/oto/**, test/oto_agent_*, assets/script/shell/oto_agent_bootstrap.sh
  • 선행 Edge bootstrap 계약은 완료 상태로 아카이브되었으며, 일반 작업에서는 활성 Phase의 archive 링크와 아래 표준선을 기준으로 한다.
  • 선행 계약의 상세 문서는 과거 기록 확인이나 복원이 명시된 경우에만 읽는다.
  • 표준선(선택): Linux MVP는 OTO가 없는 대상 머신에서 bootstrap script로 release asset을 다운로드한 뒤 ~/.oto/agent/config.yaml을 생성하고 백그라운드로 실행한다.
  • 표준선(선택): online 판정은 Edge 등록 완료와 최초 heartbeat 도착을 모두 만족했을 때로 둔다.
  • 표준선(선택): bootstrap agent 식별 값 또는 token은 보안 완성보다 등록 대상 식별과 최초 연결 매칭을 위한 최소 계약으로 먼저 둔다.
  • 표준선(선택): 바이너리 무결성은 후속 강화 항목으로 두고, MVP에서는 release asset 다운로드 기준과 실패 처리만 먼저 정리한다.
  • 구현 근거: AgentConfig는 ~/.oto/agent/config.yaml 형태의 agent.id, agent.alias, agent.enrollment_token, edge.url, runtime 경로를 파싱한다.
  • 구현 근거: CommandAgent는 oto agent run --config <path>를 통해 설정 파일을 읽고 AgentRunner로 등록을 시작한다.
  • 구현 근거: EdgeRegistrationClient는 proto_socket으로 Edge endpoint에 연결해 enrollment token을 RegisterRequest로 전송하고 RegisterResponse를 accepted/rejected 결과로 변환한다.
  • 구현 근거: registration/config/CLI 검증은 test/oto_agent_config_test.dart, test/oto_agent_registration_test.dart, test/oto_agent_cli_test.dart, test/oto_iop_connection_smoke_test.dart에 있다.
  • MVP 재시작 기준: bootstrap으로 시작한 background 프로세스의 pid/log를 기준으로 사용자가 상태를 확인하고 oto agent run --config <path>를 재실행한다. 자동 재시작과 systemd user service는 후속 강화로 둔다.
  • 남은 작업: Edge 등록 완료 이후 최초 heartbeat 도착까지의 online 판정과 재시도 정책은 iop2oto의 online smoke PASS evidence와 맞춰 OTO registration-state에 정리한다.
  • 선행 OTO Milestone: OTO-iop proto-socket 통신 기반
  • 선행 iop2oto Milestone: OTO Agent Registry 구현 → OTO Bootstrap Command 발급 → OTO Registration Online Smoke → OTO Registration Unlock Handoff
  • iop2oto 잠금 해제 근거(2026-06-04): OTO Agent Registry 구현과 OTO Bootstrap Command 발급은 workspace lock에서 enable로 확인되었다. OTO Registration Online Smoke는 agent-task/archive/2026/06/m-oto-registration-online-smoke/03+01,02_smoke_evidence/complete.log 기준 make test-oto-registration-online-smoke PASS, registration accepted, node.online, reason=first_heartbeat evidence가 확인되었다.
  • 외부 의존 잠금: /config/workspace/.agent-roadmap-sync/locks.yaml의 oto:oto-agent-registration entry에서 모든 rely-on.status가 enable로 동기화되어 이 Milestone의 구현 잠금은 해제되었다.
  • 책임 경계: iop2oto는 Edge outbound enrollment를 받아들이는 registry/protocol/credential 기준을 정리한다.
  • 책임 경계: OTO는 설치된 oto-agent가 해당 기준을 소비해 설정을 만들고 Edge에 직접 outbound 연결하는 상태 전이를 정리한다.
  • 네트워크, 설치, packaging 관련 코드나 문서가 추가될 경우 관련 도메인 rule을 먼저 확인한다.
  • 구현 계획: agent-task/m-oto-agent-registration/ 하위 plan-code-review 루프로 진행한다.
  • 확인 필요: Edge 등록 완료 이후 최초 heartbeat 도착까지의 online 판정과 재시도 정책을 OTO registration-state에 반영한다.
  • 폐기 사유: OTO는 iop Edge에 직접 연결되는 domain agent가 아니라 services/core OTO Server와 apps/runner OTO runner 간 계약으로 재구성한다. 이 문서의 registration/heartbeat/bootstrap 근거는 agent-roadmap/phase/independent-control-plane/milestones/control-plane-separation-migration.md의 migration source로만 사용한다.