oto/agent-roadmap/phase/edge-direct-oto-agent/milestones/oto-agent-registration.md

Milestone: oto-agent 등록 흐름

위치

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

목표

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

상태

[진행중]

구현 잠금

• 상태: 잠금
• 결정 필요:
  • iop에서 OTO에 대한 Edge 직접 통신 경로가 확보되었는지 확인한다.

범위

• 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으로 보는 판정 기준, 실패 상태 구분, 재시도 기준이 구현 가능한 수준으로 설명된다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: registration-state와 online/실패/heartbeat 기준이 남아 있어 완료 후보가 아니다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 없음

범위 제외

• 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 판정과 재시도 정책은 agent 메시지/heartbeat 흐름과 맞물려 별도 정리가 필요하다.
• 선행 OTO Milestone: OTO-iop proto-socket 통신 기반
• 선행 iop Milestone: agent bootstrap OTO enrollment
• 외부 의존 잠금: iop에서 OTO에 대한 Edge 직접 통신 경로가 확보되면 이 Milestone은 잠금 해제 후보가 된다. 런타임 판별은 프로젝트 상위 .agent-roadmap-sync/locks.yaml에서 관리한다.
• 책임 경계: iop는 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 판정과 재시도 정책을 agent 메시지/heartbeat 흐름과 맞춰 정리한다.