diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index 51278ff..7fd7435 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -15,7 +15,7 @@ OTO는 YAML 기반 빌드/배포 파이프라인을 실행하는 Dart CLI에서 ### Edge 직접 연결 기반 `oto-agent` -- [Edge bootstrap 계약](milestones/edge-bootstrap-contract.md) - 상태: 보류; 목표: Jenkins node 연결식 UX를 Edge bootstrap 설치/등록 계약으로 정리한다. OTO-iop proto-socket 통신 기반과 iop의 Agent Bootstrap과 OTO 등록 기준 정리를 기다린다. +- [Edge bootstrap 계약](milestones/edge-bootstrap-contract.md) - 상태: 계획; 목표: Jenkins node 연결식 UX를 Linux 대상 OTO bootstrap script 설치/등록 계약으로 정리한다. - [`oto-agent` 등록 흐름](milestones/oto-agent-registration.md) - 상태: 계획; 목표: `oto-agent` 설치 후 Edge 직접 outbound 등록 흐름을 구현 가능한 단위로 정리한다. ### 메시지 기반 빌드 에이전트 diff --git a/agent-ops/roadmap/milestones/edge-bootstrap-contract.md b/agent-ops/roadmap/milestones/edge-bootstrap-contract.md index cee8bac..169126f 100644 --- a/agent-ops/roadmap/milestones/edge-bootstrap-contract.md +++ b/agent-ops/roadmap/milestones/edge-bootstrap-contract.md @@ -11,53 +11,57 @@ Edge 직접 연결 기반 `oto-agent` ## 상태 -보류 +계획 ## 구현 잠금 -- 상태: 잠금 -- 결정 필요: 아래 체크리스트 - - [ ] iop의 Agent Bootstrap과 OTO 등록에서 Edge bootstrap 사용자 흐름이 확정되었는가? - - [ ] iop가 발급하는 bootstrap command의 필수 입력, 출력, 만료, 재시도, 보안 모드 기준이 확정되었는가? - - [ ] Edge 서버 API, agent registry, credential schema 중 OTO가 참조할 계약 범위가 정해졌는가? +- 상태: 해제 +- 결정 필요: 없음 ## 범위 -- Jenkins node를 연결하듯 Edge에서 agent 생성과 bootstrap command 발급을 시작하는 사용자 흐름을 정의한다. -- Edge가 발급하는 bootstrap command의 입력, 출력, 만료, 재시도 정책을 정의한다. -- 대상 머신의 OS/arch에 맞는 OTO 바이너리 설치 경로를 정리한다. -- agent 설정 파일 생성 위치와 최소 설정 값을 정의한다. -- HTTPS 기본 권장, HTTP local/insecure 허용 범위, 폐쇄망 사용 조건을 구분한다. +- 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] OS/arch별 바이너리 선택 규칙이 정의되어 있다. +- [ ] [binary-select] Linux 대상 OTO repo release asset 다운로드와 arch 선택 규칙이 정의되어 있다. - [ ] [config-path] agent 설정 생성 경로와 필수 설정 값이 정의되어 있다. -- [ ] [security-modes] HTTPS, HTTP local, insecure 모드의 허용 조건이 문서화되어 있다. +- [ ] [background-start] 다운로드 후 `oto-agent`를 백그라운드 등록/실행하는 기준이 정의되어 있다. +- [ ] [security-modes] 보안 강화 항목이 MVP 차단 조건과 후속 강화 범위로 분리되어 있다. ## 완료 기준 - [ ] Jenkins node 연결식 경험과 비교해 사용자가 Edge bootstrap 흐름을 이해할 수 있다. -- [ ] 사용자가 Edge에서 발급받은 command 하나로 대상 머신에 OTO agent 설치를 시작할 수 있는 흐름이 설명된다. -- [ ] 보안 모드별 요구 사항과 위험이 구분되어 구현 전에 검토 가능하다. -- [ ] 폐쇄망 배포와 개발망 테스트가 같은 계약 안에서 설명된다. +- [ ] 사용자가 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/**`)를 먼저 확인한다. -- 표준선(선택): OTO 바이너리 선택과 설정 생성 경로는 기존 packaging/script 구조, platform 관례, framework/cli 도메인 rule을 우선 기준으로 삼고 예외만 결정 필요로 올린다. +- 표준선(선택): 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은 후속 강화로 둔다. - framework, cli 도메인 rule이 관련될 수 있다. - 선행 OTO Milestone: OTO-iop proto-socket 통신 기반 - 선행 iop Milestone: `../iop/agent-ops/roadmap/milestones/agent-bootstrap-oto-enrollment.md` -- 책임 경계: iop는 Edge의 agent 생성, bootstrap command 발급, registry, credential, 보안 검증 기준을 정리한다. -- 책임 경계: OTO는 iop가 정한 bootstrap 계약을 바탕으로 OTO 바이너리 선택, 설치 시작 command, agent 설정 파일 생성 기준을 정리한다. -- 보류 사유: Edge bootstrap 계약은 iop에서 선행 진행되어야 하므로 OTO 쪽 작업은 pending 상태로 둔다. -- 재개 기준: iop에서 Edge bootstrap 사용자 흐름, bootstrap command 요구사항, 보안 모드 기준이 먼저 정리된 뒤 OTO 쪽 계약 문서와 구현 범위를 확정한다. +- 책임 경계: iop는 Edge의 agent 생성, bootstrap script 발급 표면, registry, credential 원천을 소유한다. +- 책임 경계: OTO는 release asset, Linux 설치 산출물, 설정 파일 생성, 백그라운드 실행 시작 기준을 소유한다. +- 재개 기준: 사용자 결정으로 Jenkins node식 Linux bootstrap 흐름을 기준선으로 확정했으므로 OTO 계약 정리를 진행할 수 있다. diff --git a/agent-ops/roadmap/milestones/oto-agent-registration.md b/agent-ops/roadmap/milestones/oto-agent-registration.md index 85905e6..2577b71 100644 --- a/agent-ops/roadmap/milestones/oto-agent-registration.md +++ b/agent-ops/roadmap/milestones/oto-agent-registration.md @@ -14,42 +14,46 @@ Edge 직접 연결 기반 `oto-agent` ## 구현 잠금 -- 상태: 잠금 -- 결정 필요: 아래 체크리스트 - - [ ] Edge bootstrap 계약과 iop의 Agent Bootstrap과 OTO 등록 기준이 확정되었는가? - - [ ] bootstrap token과 Edge identity 검증 중 OTO가 확정할 책임 범위가 정해졌는가? - - [ ] credential schema 중 OTO가 참조하거나 생성할 범위가 정해졌는가? +- 상태: 해제 +- 결정 필요: 없음 ## 범위 -- one-time bootstrap token 검증 흐름을 정의한다. -- Edge fingerprint 또는 public key pinning 기준을 정리한다. -- 바이너리 checksum/signature 검증을 agent 등록 계약에 포함한다. -- 설치 후 agent가 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 이후 보안 강화 항목으로 분리한다. ## 필수 기능 -- [ ] [token-flow] bootstrap token의 생성, 전달, 사용, 만료 흐름이 정의되어 있다. -- [ ] [edge-identity] Edge identity 검증 방식 후보가 정리되어 있다. -- [ ] [binary-integrity] 바이너리 무결성 검증 기준이 정의되어 있다. -- [ ] [registration-state] agent 등록 성공/실패 상태와 재시도 기준이 정의되어 있다. +- [ ] [token-flow] bootstrap agent 식별 값 또는 token의 전달과 최초 등록 사용 흐름이 정의되어 있다. +- [ ] [edge-identity] Edge identity 검증을 MVP 최소 연결 기준과 후속 보안 강화 기준으로 분리해 정리되어 있다. +- [ ] [binary-integrity] OTO repo release asset 다운로드 기준과 후속 checksum/signature 강화 기준이 분리되어 있다. +- [ ] [service-runtime] 백그라운드 실행 상태와 agent 프로세스 재시작 기준이 정의되어 있다. +- [ ] [registration-state] Edge 등록 성공/실패, 최초 heartbeat 기반 online 판정, 재시도 기준이 정의되어 있다. ## 완료 기준 -- [ ] agent 등록 보안 계약이 TLS 강제 환경과 local/insecure 환경 모두에서 설명된다. -- [ ] 설치 완료 후 Edge 직접 연결까지의 상태 전이가 구현 가능한 수준으로 분해되어 있다. +- [ ] bootstrap script 실행 후 다운로드된 `oto-agent`가 `~/.oto/agent/config.yaml`을 통해 Edge에 직접 연결하는 상태 전이가 구현 가능한 수준으로 분해되어 있다. +- [ ] Edge 등록 완료와 최초 heartbeat 도착을 online으로 보는 판정 기준이 구현 가능한 수준으로 설명된다. +- [ ] 백그라운드 실행 실패, 등록 실패, heartbeat 미도착 상태가 구분된다. - [ ] `iop-node`를 경유하지 않는다는 제품 경계가 명확하다. +- [ ] 보안 강화 항목이 후속 작업으로 분리되어 MVP 등록 흐름을 막지 않는다. ## 범위 제외 - generic node agent 기능을 포함하지 않는다. - 원격 파이프라인 실행 메시지 전체를 구현하지 않는다. - 운영용 인증서 관리 시스템을 구현하지 않는다. +- MVP에서 checksum/signature, Edge fingerprint, credential rotation 강제 구현을 포함하지 않는다. ## 작업 컨텍스트 - Edge bootstrap 기반 `oto-agent` 작업 전에는 Edge bootstrap 계약을 먼저 확인한다. -- 표준선(선택): 바이너리 무결성은 checksum 검증을 기본선으로 두고 signature는 확장 후보로 둔다. 등록 성공/실패 상태와 재시도는 일반 agent 등록 상태 모델로 정리하며, service 등록 방식과 파일 경로는 platform 관례와 OTO packaging 구조를 우선 따른다. +- 표준선(선택): Linux MVP는 OTO가 없는 대상 머신에서 bootstrap script로 release asset을 다운로드한 뒤 `~/.oto/agent/config.yaml`을 생성하고 백그라운드로 실행한다. +- 표준선(선택): online 판정은 Edge 등록 완료와 최초 heartbeat 도착을 모두 만족했을 때로 둔다. +- 표준선(선택): bootstrap agent 식별 값 또는 token은 보안 완성보다 등록 대상 식별과 최초 연결 매칭을 위한 최소 계약으로 먼저 둔다. +- 표준선(선택): 바이너리 무결성은 후속 강화 항목으로 두고, MVP에서는 release asset 다운로드 기준과 실패 처리만 먼저 정리한다. - 선행 OTO Milestone: OTO-iop proto-socket 통신 기반 - 선행 iop Milestone: `../iop/agent-ops/roadmap/milestones/agent-bootstrap-oto-enrollment.md` - 책임 경계: iop는 Edge outbound enrollment를 받아들이는 registry/protocol/credential 기준을 정리한다.