[SharedFS][SystemVM] 운영 중 Storage Service 런타임 코드 인플레이스 업그레이드 지원

[dhslove]

배경

현재 Storage Service System VM의 실행 코드는 System VM 템플릿에 포함되어 배포됩니다. 운영 중인 SharedFS 인스턴스에 개선된 ablestack-storagectl, 부팅 reconcile 및 모니터링 코드를 적용하려면 새 템플릿으로 System VM을 교체하는 절차가 필요하며, 이 과정은 서비스 중단과 운영 데이터 경로 변경 위험을 수반합니다.

관리 서버는 이미 StorageServiceHostCommand와 KVM 에이전트의 QGA guest-exec 경로를 통해 System VM 내부의 /usr/local/bin/ablestack-storagectl을 실행합니다. 또한 System VM은 NFS, SMB, iSCSI, NVMe-oF desired state를 영속화하고 부팅 reconcile 시 이를 재적용합니다. 이 구조를 확장하면 커널이나 OS 패키지를 바꾸지 않는 Storage Service 소유 런타임 코드를 운영 중 안전하게 갱신할 수 있습니다.

목표

• 운영 중인 Storage Service System VM을 중지·재생성하거나 템플릿으로 교체하지 않고, 호환 가능한 Storage Service 런타임 코드만 인플레이스 업그레이드합니다.
• 전송 파일의 무결성, 관리 서버·에이전트·System VM 간 호환성, 원자적 활성화와 자동 롤백을 보장합니다.
• serviceImpact=NONE 번들은 기존 NFS/SMB/iSCSI/NVMe-oF 세션과 데이터 경로를 유지한 상태에서 적용합니다.
• 커널·패키지 변경이 필요한 업데이트는 라이브 업그레이드 대상에서 제외하고 템플릿 유지보수 경로로 안내합니다.

현행 구조와 보완점

구분	AS-IS	TO-BE
명령 전달	관리 서버 → 호스트 에이전트 → QGA guest-exec → 기존 ablestack-storagectl 실행	전용 런타임 업그레이드 명령과 상태 조회 명령 추가
코드 배포	템플릿 빌드 시 실행 코드 포함	서명된 불변 런타임 번들을 별도로 등록·전송
파일 전송	일반화된 전송 계층 없음	QGA guest-file-open/write/close 기반 제한 크기 청크 전송
활성화	템플릿 교체	버전 디렉터리 설치 후 current 심볼릭 링크 원자적 전환
호환성	템플릿 생성 시점에만 검증	ABI, desired-state schema, 관리 서버·에이전트·템플릿 버전 사전 검증
실패 처리	작업별 오류 반환	이전 버전 자동 전환, 이전 코드로 reconcile, 트랜잭션 상태 보존
운영 가시성	템플릿 버전 중심	템플릿 버전과 런타임 번들 버전을 분리 표시

적용 범위

라이브 업그레이드 허용 대상

• ablestack-storagectl
• ablestack-storage-boot-reconcile
• ablestack-storage-monitor
• Storage Service 전용 helper/module 및 설정 렌더러
• Storage Service 소유 systemd unit/drop-in 중 프로토콜 데몬 재시작이 필요 없는 변경

템플릿 유지보수 대상으로 분리할 항목

• 커널, 커널 모듈 및 configfs 기능
• OS 패키지와 시스템 공유 라이브러리
• qemu-guest-agent, libvirt 및 호스트 에이전트 런타임
• 디스크 파티션·부팅 구조·기본 OS 변경
• 적용을 위해 프로토콜 데몬 또는 System VM 재부팅이 필수인 변경

런타임 번들 규격

서명된 압축 번들과 manifest를 릴리즈 산출물로 생성합니다.

manifest 필수 항목:

• bundleVersion
• runtimeAbiVersion, desiredStateSchemaVersion
• 지원 관리 서버·호스트 에이전트·System VM 템플릿 버전 범위
• 파일별 경로, SHA-256, 소유자, 그룹, 모드
• 변경 구성요소 및 서비스 영향도(NONE, PROTOCOL_RESTART, VM_REBOOT)
• 롤백 가능 최소·최대 버전
• 번들 서명과 서명 키 식별자

번들 경로는 allowlist로 제한하고 임의 셸, 임의 절대 경로, 장치 파일과 심볼릭 링크를 허용하지 않습니다. 릴리즈 파이프라인은 동일한 런타임 버전을 System VM 템플릿과 독립 번들 양쪽에 포함해야 합니다.

System VM 설치 구조

/opt/ablestack/storage-runtime/
  releases/<bundle-version>/
  current -> releases/<bundle-version>
/var/lib/ablestack-storage/runtime-updates/<transaction-id>/
/var/lib/ablestack-storage/runtime-update-state.json

• /usr/local/bin/ablestack-storagectl 등의 고정 진입점은 current 아래 실행 파일을 호출하는 짧은 wrapper로 구성합니다.
• 실행 중인 파일을 덮어쓰지 않고 staging 검증 후 디렉터리 rename과 current 링크 교체를 원자적으로 수행합니다.
• 관리 서버의 인스턴스 단위 잠금과 System VM의 flock을 함께 사용합니다.
• 활성화 중에는 같은 인스턴스의 desired-state 변경 작업을 대기시키거나 명시적으로 거절합니다.

기존 템플릿으로 생성된 System VM에는 전용 updater가 없으므로, 호스트 에이전트에 버전 고정·해시 고정된 최소 bootstrap 설치 명령을 제공합니다. bootstrap 호환성이 확인되지 않은 VM에는 업그레이드를 시작하지 않습니다. 향후 템플릿에는 updater를 기본 포함합니다.

전송 및 실행 프로토콜

임의 명령 실행 API가 아닌 다음 전용 작업을 StorageServiceHostCommand 계열에 추가합니다.

1. runtime-upgrade-capabilities
2. runtime-upgrade-begin
3. runtime-upgrade-write-chunk
4. runtime-upgrade-finalize
5. runtime-upgrade-preflight
6. runtime-upgrade-activate
7. runtime-upgrade-status
8. runtime-upgrade-rollback

대용량 base64 인자를 한 번의 guest-exec에 넣지 않고 QGA의 guest-file-open, guest-file-write, guest-file-close를 이용해 제한된 크기의 청크로 staging 파일을 전송합니다. 전송 종료 후 고정 updater만 guest-exec으로 실행합니다.

참고: QEMU Guest Agent command reference

업그레이드 상태 모델

AVAILABLE → STAGING → PREFLIGHT_OK → ACTIVATING
          → RECONCILING → VERIFYING → COMPLETE

실패 시: ROLLING_BACK → ROLLED_BACK 또는 FAILED

관리 서버 DB와 System VM 트랜잭션 파일에 transaction ID, 현재·대상 버전, 단계, 시간, 오류, 롤백 결과를 기록합니다. 관리 서버 재시작이나 통신 단절 후에도 상태를 재조회할 수 있어야 합니다.

사전 점검

• System VM이 Running이고 QGA가 응답하는지 확인
• 대상 번들의 서명, 파일 해시, 크기, 경로 allowlist 확인
• 관리 서버·호스트 에이전트·템플릿·런타임 ABI 호환성 확인
• staging 및 releases 디렉터리 여유 공간 확인
• 필수 실행 파일과 커널 기능 확인
• shell/Python 문법과 systemd unit 문법 확인
• 현재 런타임 버전, desired state, 마운트, listener, 세션 및 모니터 상태 스냅샷 기록
• 동시 프로토콜·공유·ACL·볼륨 변경 작업이 없는지 확인

활성화, 검증 및 롤백

1. 검증된 release 디렉터리를 원자적으로 확정합니다.
2. current 링크를 대상 버전으로 전환합니다.
3. unit 변경이 있을 때만 systemctl daemon-reload를 실행합니다.
4. 기존 persisted desired state로 전체 Storage Service reconcile을 수행합니다.
5. 프로토콜별 설정과 런타임을 검증합니다.
   • NFS: Ganesha 프로세스, listener, export, backing mount
   • SMB: Samba/Winbind, share, AD 상태, listener
   • iSCSI: target/configfs, portal, LUN, ACL
   • NVMe-oF: subsystem/configfs, port, namespace, host ACL
   • 공통: 모니터 캐시, reconcile 상태, 기존 세션과 데이터 경로
6. serviceImpact=NONE이면 기존 세션 유지 여부를 필수 검증합니다.
7. 하나라도 실패하면 current를 이전 버전으로 원자 복구하고 이전 코드로 desired state를 다시 reconcile합니다.

PROTOCOL_RESTART 또는 VM_REBOOT 영향도의 번들은 라이브 모드에서 거절하고 유지보수 작업 또는 템플릿 업그레이드 대상으로 표시합니다.

백엔드·API·DB

백엔드

• 런타임 번들 registry와 서명 검증 서비스
• 인스턴스별 capability/preflight/upgrade/rollback orchestration
• 인스턴스 단위 분산 잠금과 desired-state 변경 상호 배제
• 에이전트 명령·응답에 단계, 버전, 진행률, 검증 결과 포함

API

• 번들 목록·상세·등록·비활성화
• 대상 인스턴스 capability/preflight
• 업그레이드 시작·상태·이력
• 명시적 롤백
• 관리자 전용 권한, 이벤트 및 감사 로그

DB

• 런타임 번들 메타데이터와 서명·호환성 정보
• 인스턴스의 현재·이전·목표 런타임 버전
• 업그레이드 트랜잭션 단계, 오류, 검증·롤백 결과
• 템플릿 버전과 런타임 버전을 독립 저장

비밀 정보와 번들 원문은 DB에 저장하지 않습니다.

UI

SharedFS 상세 화면에 다음 정보를 추가합니다.

• System VM 템플릿 버전
• 현재 Storage Service 런타임 버전과 파일 해시
• 사용 가능한 호환 번들 및 서비스 영향도
• 마지막 업그레이드·검증·롤백 결과

런타임 업그레이드 대화상자는 세로형 및 라이트/다크 모드로 구성하고 다음 단계를 표시합니다.

1. 대상 버전과 변경 구성요소 확인
2. 사전 점검 결과와 서비스 영향도 확인
3. 최종 경고 및 실행 확정
4. 전송·활성화·reconcile·검증 진행률
5. 완료 또는 자동 롤백 결과

QGA 미응답, 호환성 불일치, 동시 변경 작업, 공간 부족 또는 유지보수 영향도인 경우 실행 버튼을 비활성화하고 사유를 표시합니다.

보안 요구사항

• 고정된 공개키로 번들 서명 검증
• 파일별 SHA-256 및 manifest 전체 무결성 확인
• 경로·파일 유형·크기 allowlist와 압축 해제 크기 제한
• transaction ID, nonce 및 버전 단조 증가를 통한 replay/downgrade 방지
• 관리자 권한과 이중 확인 절차
• 업그레이드 전 과정의 감사 이벤트 기록
• 번들·로그·DB에 비밀번호, API 키 및 서비스 비밀을 포함하지 않음

테스트 게이트

• NFS/SMB/iSCSI/NVMe-oF가 동시에 활성화된 인스턴스에서 읽기·쓰기와 세션 유지 검증
• 프로토콜별 단독 인스턴스 검증
• 기존 템플릿 VM의 bootstrap 설치와 향후 템플릿 기본 updater 검증
• 잘못된 서명·해시·ABI·schema·경로·권한·용량 부족 거절 검증
• STAGING, ACTIVATING, RECONCILING 단계별 관리 서버·에이전트·System VM 장애 주입
• 업그레이드 중 동시 API 변경 차단 검증
• 성공 및 롤백 후 System VM 재부팅 복구 검증
• serviceImpact=NONE에서 기존 클라이언트 세션과 I/O 연속성 검증
• 이전 관리 서버·에이전트와 신규 번들의 호환성 거절 검증

완료 조건

• 허용 대상 런타임 코드가 System VM 중지·재생성·템플릿 교체 없이 갱신됩니다.
• 관리 서버, API와 UI에서 실제 적용 버전과 파일 해시를 확인할 수 있습니다.
• serviceImpact=NONE 업그레이드 중 기존 프로토콜 세션과 I/O가 유지됩니다.
• 실패 시 이전 런타임으로 자동 롤백되고 기존 desired state가 정상 복구됩니다.
• 업그레이드 성공·롤백 후 재부팅해도 선택된 런타임과 서비스 설정이 복구됩니다.
• 라이브 적용 범위를 벗어난 변경은 시작 전에 거절되고 템플릿 유지보수 경로로 안내됩니다.
• 릴리즈 런타임 번들과 신규 System VM 템플릿의 런타임 버전이 일치합니다.

연관 이슈

• 상위 추적: [SharedFS][Epic] Europa 운영 안정성·데이터 보호 개선 추적 #898
• 구성 백업·마지막 정상 구성 복원: [SharedFS] 구성 백업 번들 내보내기·업로드 및 마지막 정상 구성 복원 지원 #909

[dhslove]

#911 상세 설계 게시

#911 구현을 위한 코드 수준 상세 설계와 실제 22.x 개발 환경 Preflight 결과를 문서로 게시했습니다.

• 설계 문서: Storage Service 런타임 인플레이스 업그레이드 상세 설계
• 작업 브랜치: sharedfs/issue-911-runtime-inplace-upgrade
• 문서 커밋: 2d9af5101afa1be8f06a0fb58a6deae1fc132999
• 현재 상태: 상세 설계 완료, 구현 전

Preflight 검증 요약

• 대상: 22.x Storage Service VM i-2-608-VM (10.10.22.3에서 실행)
• QGA guest-file-*를 사용한 48 KiB 청크 전송과 전체 SHA-256 검증 성공
• guest-file-seek 기반 명시적 offset 재전송 및 동일 청크 멱등 처리 검증 성공
• OpenSSL 3 Ed25519 detached signature 정상 검증 및 변조 manifest 거부 확인
• 버전 디렉터리와 current 링크의 원자적 전환 검증 성공
• 의도적으로 실패한 새 runtime self-test 이후 직전 정상 버전 자동 롤백 검증 성공
• 다중 프로토콜 리스너가 실행 중인 상태에서 활성 runtime, 서비스, 리스너 및 마운트가 변경되지 않음을 확인

문서에는 runtime bundle/manifest 계약, QGA 전송 명령, SystemVM updater, 상태 머신, 자동 롤백, DB/API/UI 변경 대상, 보안, 릴리즈 파이프라인, 테스트 게이트와 #892/#897/#909 연계 경계를 포함했습니다.

[dhslove]

템플릿 세대 교체 유지보수 경로 분리

#911의 서명 runtime bundle 적용 범위를 벗어나는 커널, OS 패키지, 공용 라이브러리 및 SystemVM bootstrap 변경은 #920에서 추적합니다.

• [SharedFS][SystemVM] 운영 중 Storage Service 런타임 코드 인플레이스 업그레이드 지원 #911: 실행 중인 Storage Service 소유 runtime 코드의 인플레이스 전환
• [SharedFS][SystemVM] 운영 서비스의 SystemVM 템플릿 교체 업그레이드 및 설정 자동 복구 지원 #920: 동일 VM/NIC/IP와 데이터 볼륨을 유지한 SystemVM ROOT·템플릿 세대 교체, 설정/identity 자동 복구 및 previous ROOT 롤백

연계 이슈: #920