longhorn: snapshot-purge cron 워크어라운드 (v1.11.1 stuck snapshot)

infra/platform/longhorn.md

@@ -1,6 +1,6 @@
 ---
 title: Longhorn 분산 블록 스토리지
-updated: 2026-04-23
+updated: 2026-05-02
 tags: [infra, platform, longhorn, storage, k3s]
 ---
 
@@ -57,6 +57,51 @@ defaultSettings:
 - 복구 시 주의: `longhorn.io/fromBackup` annotation은 Longhorn v1.8+ CSI에서 무시됨 → Volume CR 직접 생성 후 `longhorn-static` SC PV 만드는 절차. 상세 [[../data/k3s-backup|k3s-backup]]
 - 주기 백업 라벨 키는 **대시 포함**: `recurring-job-group.longhorn.io/<group>=enabled` (과거 오타 이슈 [[../../history/2026-04-15-longhorn-backup-label-typo|history]])
 
+## Stuck snapshot 임시 cron (v1.11.1 워크어라운드)
+
+v1.11.1 instance-manager 재시작 후 일부 snapshot CR 이 `status.markRemoved=true && status.readyToUse=false && status.ownerID=""` 상태로 멈춘다. ownerId 가 비어 longhorn-manager 가 reconcile 못 하고, 수동 `kubectl delete` / finalizer patch 시 admission webhook 이 finalizer 를 즉시 재추가해 정리 불가.
+
+근본 fix 는 **v1.11.2 / v1.12 업그레이드**. 그때까지 임시로 snapshotPurge API 를 cron 으로 자동 호출해 engine 단의 chain cleanup 을 주기적으로 트리거.
+
+### 구성
+
+| 항목 | 값 |
+|---|---|
+| Helm chart | `gitea.inouter.com/kaffa/helm-charts` · `charts/longhorn-snapshot-purge` |
+| ArgoCD App | `argocd/longhorn-snapshot-purge` (auto-sync, prune, selfHeal) |
+| CronJob | `longhorn-system/longhorn-snapshot-purge` |
+| Schedule | `*/30 * * * *` |
+| ServiceAccount | `longhorn-snapshot-purge` (ns Role: `snapshots.longhorn.io` get/list) |
+| Image | `alpine/k8s:1.32.1` (kubectl + curl + jq 포함) |
+
+### 동작
+
+1. namespace 내 `snapshots.longhorn.io` 전수 list
+2. `status.markRemoved=true` 이면서 `status.readyToUse=false` 인 CR 추출 → `spec.volume` 중복 제거
+3. 각 volume 에 `POST http://longhorn-frontend.longhorn-system.svc/v1/volumes/{name}?action=snapshotPurge` 호출
+4. HTTP 200 / 비-200 별 카운트, 비-200 있으면 job exit 1
+
+### 한계 / 운영 주의
+
+- snapshotPurge 는 chain 의 redundant snapshot 만 정리. **stuck snapshot 이 그 볼륨의 유일 snapshot 이고 volume-head 의 직속 parent 라면 .img 파일이 정리되지 않는다** (engine snapshotList 에서 `removed=true` 만 마킹 유지).
+- 따라서 cron 은 디스크 재확보의 best-effort. CR 자체 cleanup 은 보장 안 됨 — 그건 v1.11.2 / v1.12 업그레이드로 해결.
+- 임시 cron 이라 **업그레이드 직후 ArgoCD App 삭제로 회수**할 것 (chart 디렉토리는 repo 에 보존하되 Application 만 prune).
+
+### 운영 명령
+
+```bash
+# 수동 트리거 (다음 30분 boundary 기다리지 않을 때)
+kubectl -n longhorn-system create job --from=cronjob/longhorn-snapshot-purge longhorn-snapshot-purge-manual-$(date +%s)
+
+# 마지막 실행 로그
+kubectl -n longhorn-system logs -l job-name --tail=50 --selector='batch.kubernetes.io/job-name'
+
+# stuck snapshot 현재 카운트
+kubectl get snapshots.longhorn.io -A -o json | jq '[.items[] | select(.status.markRemoved == true and .status.readyToUse == false)] | length'
+```
+
+상세 도입 기록: [[../../history/2026-05-02-longhorn-snapshot-purge-cron|history]]
+
 ## 업그레이드 절차 (표준)
 
 minor skip 금지 — 한 단계씩 순차. 각 단계 공통: