Files
platform-core/docs/design/2026-11-12-state-disk-separation-design.md
T
DongHyeonka ec9a118d15 docs(design): plan the separation of state data from the root SSD
All SSD Local PVs share the root filesystem with the OS, container
images and build caches; review A12 and risk 2. Owner decision 3 asks
for a plan only.

Compare four options (shrink the Windows SSD, a new SSD, the HDD, do
nothing), recommend a new SSD and otherwise the Windows SSD, and give
the migration: mount the new filesystem at the same /srv/k3s/ssd path
so no PV changes, two rsync passes around a short stop, rollback. Note
the scripts whose root-SSD findmnt checks must change in the same PR.

Risk: documentation only; status 제안.

Verification: the PV sizes and paths come from the 2026-11-11 cluster
inventory; the findmnt checks were found with git grep.
2026-11-12 01:38:58 +09:00

5.0 KiB

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 제안
  • 작성일: 2026-11-12
  • 요약: 상태 데이터 Local PV(/srv/k3s/ssd)를 OS·이미지·빌드 캐시와 같은 SSD 파티션에서 떼어 내는 안과 이전 절차를 정리했다. 결정과 실행은 소유자 몫이다.
  • 현재 정본: 없음 — 아직 결정 전이다. 지금 배치는 docs/reviews/2026-11-11-k3s-maturity-review.md A12.

상태 데이터 디스크 분리

문제

/srv/k3s/ssd/*의 Local PV 8개(platform-postgres 20Gi, Gitea 50Gi, Prometheus 20Gi, Loki·Tempo 5Gi, Grafana·Alloy·pgAdmin·Alertmanager)가 루트 SSD sdc1(232GB, 파티션 하나)에 OS, containerd 이미지, Docker(빌드 캐시·runner), 에이전트 게이트 산출물과 같이 있다.

  • 11-09처럼 빌드 캐시가 디스크를 채우면 Postgres가 WAL을 못 써 멈춘다. PV capacity는 아무것도 막지 않는다 (파드 안 df가 루트 전체 228G를 보여 준다).
  • SSD 하나가 죽으면 상태와 OS를 함께 잃는다. 백업(CNPG, 호스트 백업)은 HDD에 있지만 되살리는 데 몇 시간이 걸린다.

안

안 내용 좋은 점 나쁜 점
A sda(1TB SSD, 지금 Windows NTFS 930G) 끝을 줄여 ext4 파티션을 만들고 /srv/k3s/ssd를 옮긴다 새 하드웨어 없음, SSD 속도 유지, 빌드가 상태를 못 채운다 Windows 파티션 축소(Windows에서 해야 함, 데이터 위험), 이중 부팅 디스크에 리눅스 데이터
B 새 SSD(예: 500GB)를 달아 /srv/k3s/ssd로 쓴다 가장 깨끗하다. 디스크 장애도 분리된다 구매·장착, 포트 여유 확인
C HDD sdb에 둔다 지금 바로 가능 Postgres·Prometheus가 HDD 지연을 받는다. AIStor와 같은 디스크라 장애 분리가 안 된다
D 그대로 두고 W1의 디스크 상한·경보로만 막는다 일이 없다 단일 SSD 장애 위험은 그대로

권하는 안: B, 안 되면 A. C는 성능 때문에, D는 위험이 남아서 버린다. 어느 안이든 W1의 디스크 경보·상한은 그대로 둔다.

이전 절차 (A·B 공통)

PV 객체의 local.path는 바꾸지 않는다. 새 파일시스템을 같은 경로 /srv/k3s/ssd에 mount하면 쿠버네티스 쪽 변경이 없다.

새 파일시스템 준비 → 임시 경로에 mount → 서비스별로 멈추고 rsync → 한 번에 경로 교체 → 다시 시작 → 확인
  1. 준비: 새 파티션을 ext4로 만들고 /mnt/new-ssd에 mount. 용량은 지금 PV 합(약 110Gi)의 두 배 이상.
  2. 백업: k3s-restart-window.md의 「창 전에」대로 호스트 백업과 CNPG 백업을 한 번씩 돌린다.
  3. 1차 복사(서비스 켠 채): sudo rsync -aHAX --numeric-ids /srv/k3s/ssd/ /mnt/new-ssd/.
  4. 창을 잡고 쓰는 쪽을 멈춘다: Gitea·Keycloak·tech-log를 0으로, CNPG kubectl cnpg hibernate on platform-postgres(또는 cnpg.io/hibernation: "on" annotation), 관측 StatefulSet을 0으로.
  5. 2차 복사: 3과 같은 명령에 --delete. 멈춘 상태라 빠르다.
  6. 교체: /srv/k3s/ssd를 /srv/k3s/ssd.old로 옮기고 새 파일시스템을 /srv/k3s/ssd에 mount(fstab UUID, noatime). 소유자·권한(/srv/k3s/ssd root 0750, 하위 폴더 소유자)이 같은지 stat으로 본다.
  7. 다시 시작: 4의 역순. after-reboot-checks.md 4~7.
  8. 하루 지켜본 뒤 /srv/k3s/ssd.old를 지운다(지우기는 소유자가 한다).

예상 중단: 2차 복사 몇 분 + 재시작 몇 분. Postgres 20Gi·Gitea 370MB 기준 30분 안쪽.

같이 고쳐야 하는 스크립트

PV 폴더를 준비·검사하는 스크립트가 「경로가 루트 SSD 파일시스템에 있고 그 아래 다른 mount가 없다」를 검사한다. /srv/k3s/ssd에 새 파일시스템을 mount하면 이 검사가 실패한다. 이전 PR에서 같이 고친다.

  • scripts/bootstrap/prepare-ssd-local-paths.sh, scripts/bootstrap/prepare-observability-local-paths.sh
  • scripts/bootstrap/apply-admin-services.sh(pgAdmin 경로: 「/srv가 root SSD 파일시스템 경계가 아닙니다」, 「아래에 다른 mount가 있습니다」)
  • 같은 findmnt 검사를 쓰는 다른 스크립트(git grep -l findmnt -- scripts): apply-aistor.sh, k3s 로컬 recovery 묶음 등은 경로가 다르지만 같이 확인한다.

되돌리기

6 이후에 문제가 나면 4처럼 멈추고 새 mount를 내린 뒤 /srv/k3s/ssd.old를 원래 이름으로 돌린다.

반증할 수 있는 가정

  • 「같은 경로에 mount하면 쿠버네티스 변경이 없다」: 틀렸다면 파드가 local PV의 노드 affinity나 경로 검사로 뜨지 않는다. 2차 복사 전에 Grafana(잃어도 되는 PV) 하나로 먼저 시험한다.
  • 「빌드 캐시가 상태를 못 채운다」: 틀렸다면 /srv/k3s/ssd가 다시 루트와 같은 장치로 보인다(findmnt -T /srv/k3s/ssd).