oto/agent-roadmap/archive/phase/edge-direct-oto-agent/milestones/edge-bootstrap-contract.md

Edge bootstrap 계약

목표

Jenkins node 연결식 UX를 Edge 중심 bootstrap 경험으로 재해석한다. Edge에서 OTO agent를 생성하고 대상 머신에서 실행할 bootstrap command를 발급하는 UX와 설치/등록 계약을 정의한다.

단계

Edge 직접 연결 기반 oto-agent

상태

완료

구현 잠금

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

범위

• Jenkins node를 연결하듯 Edge에서 OTO agent를 생성하고 대상 Linux 머신에서 실행할 bootstrap script를 발급하는 사용자 흐름을 정의한다.
• 대상 머신에는 OTO가 없다고 가정하고, bootstrap script가 OTO repo release asset URL에서 Linux용 OTO 바이너리를 다운로드해 실행 가능한 상태로 만든다.
• Edge는 bootstrap script에 다운로드 URL, agent 식별 값, Edge 연결 정보를 포함해 제공한다.
• 다운로드된 OTO는 ~/.oto/agent/config.yaml을 생성하거나 갱신하고, 백그라운드 등록/실행을 기본 방향으로 한다.
• Edge 등록 완료와 최초 heartbeat 도착을 online 판정 기준으로 둔다.
• HTTPS, checksum, signature, fingerprint 같은 보안 강화 항목은 MVP 구현 차단 조건이 아니라 후속 강화 범위로 분리한다.

필수 기능

• [edge-user-flow] Edge에서 agent 생성 후 bootstrap command를 발급하는 사용자 흐름이 정의되어 있다.
• [command-shape] bootstrap command 형식과 필수 인자가 정의되어 있다.
• [binary-select] Linux 대상 OTO repo release asset 다운로드와 arch 선택 규칙이 정의되어 있다.
• [config-path] agent 설정 생성 경로와 필수 설정 값이 정의되어 있다.
• [background-start] 다운로드 후 oto-agent를 백그라운드 등록/실행하는 기준이 정의되어 있다.
• [security-modes] 보안 강화 항목이 MVP 차단 조건과 후속 강화 범위로 분리되어 있다.

완료 기준

• Jenkins node 연결식 경험과 비교해 사용자가 Edge bootstrap 흐름을 이해할 수 있다.
• 사용자가 Edge에서 발급받은 script 하나로 OTO가 없는 Linux 대상 머신에서 OTO 다운로드와 실행을 시작할 수 있는 흐름이 설명된다.
• ~/.oto/agent/config.yaml 기준 설정 생성과 백그라운드 실행 기준이 설명된다.
• Edge 등록 완료와 최초 heartbeat 도착을 online으로 보는 상태 기준이 설명된다.
• 보안 강화 항목이 MVP 범위와 후속 강화 범위로 구분되어 구현을 막지 않는다.

범위 제외

• 실제 Edge 서버 API를 구현하지 않는다.
• 메시지 기반 run request 프로토콜을 구현하지 않는다.
• iop-node 연동을 추가하지 않는다.
• Linux 외 OS의 bootstrap script를 정의하지 않는다.
• checksum, signature, Edge fingerprint, credential rotation 같은 운영 보안 강화 구현을 포함하지 않는다.

작업 컨텍스트

• 기존 packaging 자료와 설치 스크립트(assets/package/**, assets/script/**)를 먼저 확인한다.
• 표준선(선택): Linux MVP는 사용자 홈 기반 설치를 우선하고, 설정 파일은 ~/.oto/agent/config.yaml을 사용한다.
• 표준선(선택): Edge는 OTO repo release asset URL을 bootstrap script에 포함해 제공하며, 나중에 필요하면 같은 계약을 유지한 채 artifact 서버나 Edge download URL 뒤로 옮길 수 있다.
• 표준선(선택): 백그라운드 실행은 사용자 권한으로 가능한 등록 방식을 우선하고, 등록 실패 시 사용자가 실행 상태를 확인할 수 있는 fallback을 둔다.
• 표준선(선택): 보안은 최소 agent 식별 값과 Edge 연결 정보 전달을 먼저 두고, checksum/signature/fingerprint/credential rotation은 후속 강화로 둔다.
• MVP 계약 기준(확정): Edge는 agent 생성 후 Linux 대상에서 바로 실행할 one-line bootstrap command를 발급한다.
  • 표준 command 형식:

    curl -fsSL "${OTO_BOOTSTRAP_URL}" | bash -s -- \
      --edge-url "${EDGE_URL}" \
      --agent-id "${AGENT_ID}" \
      --enrollment-token "${ENROLLMENT_TOKEN}" \
      --release-base-url "${OTO_RELEASE_BASE_URL}" \
      --agent-alias "${AGENT_ALIAS}"
    

  • 필수 인자: --edge-url, --agent-id, --enrollment-token, --release-base-url.
  • 선택 인자: --agent-alias, --install-dir, --config-path, --workspace-root, --log-dir, --no-background.
  • 기본 경로: --install-dir=$HOME/.oto/bin, --config-path=$HOME/.oto/agent/config.yaml, --workspace-root=$HOME/.oto/workspace, --log-dir=$HOME/.oto/agent/log.
• MVP 계약 기준(확정): Linux arch 선택은 대상 머신에서 uname -m으로 수행한다.
  • x86_64, amd64는 oto-linux-x64.tar.gz release asset을 사용한다.
  • aarch64, arm64는 oto-linux-arm64.tar.gz release asset을 사용한다.
  • 그 외 arch는 다운로드 전에 실패하고, 지원되지 않는 arch 값을 출력한다.
  • release asset archive에는 실행 파일 oto가 포함되어 있어야 한다.
• MVP 계약 기준(확정): bootstrap script는 ~/.oto/agent/config.yaml을 생성하거나 갱신한다.
  • 필수 설정 값: agent.id, agent.alias, agent.enrollment_token, edge.url, runtime.install_dir, runtime.workspace_root, runtime.log_dir.
  • 설정 파일과 상위 디렉터리는 사용자 홈 기준으로 만들고, 설정 파일 권한은 가능하면 600으로 제한한다.
• MVP 계약 기준(확정): background 실행은 사용자 권한의 best-effort 방식으로 시작한다.
  • 기본 실행은 oto agent run --config "$config_path"를 background로 시작하고, stdout/stderr는 log_dir 아래 로그 파일로 보낸다.
  • 시작한 프로세스 pid는 ~/.oto/agent/oto-agent.pid에 기록한다.
  • --no-background가 있으면 foreground 실행 command만 출력하거나 그대로 실행해 디버깅 가능하게 둔다.
  • background 시작 실패는 등록 실패와 구분해 사용자에게 로그 경로와 재실행 command를 출력한다.
• MVP 계약 기준(확정): 보안 강화는 MVP 차단 조건과 후속 강화로 분리한다.
  • MVP 차단 조건: bootstrap URL과 release base URL은 HTTPS를 기본으로 요구하고, enrollment token은 command 출력 이후 재출력하지 않는다.
  • MVP best-effort: 설정 파일 권한 제한, 임시 다운로드 파일 정리, token이 포함된 shell trace 비활성화.
  • 후속 강화: checksum/signature 검증, Edge fingerprint pinning, 단기 enrollment token 만료/회전, systemd user service 설치.
• framework, cli 도메인 rule이 관련될 수 있다.
• 선행 OTO Milestone: OTO-iop proto-socket 통신 기반
• 선행 iop Milestone: ../iop/agent-roadmap/milestones/agent-bootstrap-oto-enrollment.md
• 책임 경계: iop는 Edge의 agent 생성, bootstrap script 발급 표면, registry, credential 원천을 소유한다.
• 책임 경계: OTO는 release asset, Linux 설치 산출물, 설정 파일 생성, 백그라운드 실행 시작 기준을 소유한다.
• 재개 기준: 사용자 결정으로 Jenkins node식 Linux bootstrap 흐름을 기준선으로 확정했으므로 OTO 계약 정리를 진행할 수 있다.
• 구현 근거: 실제 Linux bootstrap script는 assets/script/shell/oto_agent_bootstrap.sh, 검증은 test/oto_agent_bootstrap_script_test.dart에 있다.