backup: add k8s VolumeSnapshot API (snapshot-controller v8.5.0) as Velero prereq; fix democratic-csi restart loop

history/2026-04-20-snapshot-controller-velero-prep.md

@@ -0,0 +1,118 @@
+---
+title: snapshot-controller 도입 + democratic-csi 재시작 루프 해소 (Velero 선결)
+date: 2026-04-20
+tags: [history, k3s, csi, snapshot, velero, democratic-csi]
+---
+
+## 현상
+
+democratic-csi controller(`synology-iscsi-democratic-csi-controller`)가 14일 동안 26회 재시작. 이전 종료 로그:
+
+```
+failed to list *v1.VolumeSnapshotContent: the server could not find
+the requested resource (get volumesnapshotcontents.snapshot.storage.k8s.io)
+→ Unexpected EOF during watch stream
+→ failed to renew lease
+→ F stopped leading
+```
+
+## 근본원인
+
+- controller 파드의 `external-snapshotter` sidecar(v8.2.1)가 쿠버네티스 표준 `snapshot.storage.k8s.io` CRD를 watch 시도
+- 클러스터에 해당 CRD가 설치되어 있지 않음 (Longhorn 자체 `snapshots.longhorn.io`, k3s `etcdsnapshotfiles.k3s.cattle.io`만 존재)
+- 404 에러 루프 + API watch stream 끊길 때 leader lease 갱신 실패 → 전체 sidecar exit
+
+## 결정: 표준 API 도입 + sidecar 정리 병행 (옵션 A + B)
+
+단순 수정이면 sidecar 비활성화만으로 충분. 그러나 "k8s 표준 백업 도구(Velero) 도입" 계획이 잡혔으므로 표준 CRD 설치도 함께 진행.
+
+### 옵션 분석
+
+| 방안 | 변경 범위 | Velero 호환 | 채택 |
+|-----|----------|-----------|------|
+| A. snapshot-controller 설치 | 클러스터 전역 | ✅ | ✅ |
+| B. democratic-csi sidecar 비활성 | controller 1개 | - | ✅ |
+| 현상 유지 | - | ❌ | - |
+
+Synology iSCSI PVC = 0개 (StorageClass만 있고 실사용 워크로드 없음). 현재 Synology snapshot 기능 불필요 → B 병행해도 기능 손실 없음.
+
+## 조치
+
+### 1. snapshot CRDs 설치 (v8.5.0)
+
+```bash
+for f in snapshot.storage.k8s.io_volumesnapshotclasses.yaml \
+         snapshot.storage.k8s.io_volumesnapshotcontents.yaml \
+         snapshot.storage.k8s.io_volumesnapshots.yaml; do
+  kubectl apply -f \
+    "https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.5.0/client/config/crd/$f"
+done
+```
+
+### 2. snapshot-controller Deployment (kube-system)
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.5.0/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v8.5.0/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml
+```
+
+결과: `snapshot-controller` Deployment(replicas=2) 가동, 파드 2개 Running.
+
+### 3. Longhorn VolumeSnapshotClass
+
+```yaml
+apiVersion: snapshot.storage.k8s.io/v1
+kind: VolumeSnapshotClass
+metadata:
+  name: longhorn-snapshot
+  labels:
+    velero.io/csi-volumesnapshot-class: "true"
+driver: driver.longhorn.io
+deletionPolicy: Delete
+parameters:
+  type: snap
+```
+
+`velero.io/csi-volumesnapshot-class=true` 라벨로 Velero가 자동 인식. 현재는 `type: snap`(Longhorn 내부 스냅샷). Velero는 VolumeSnapshot 메타를 오브젝트 스토리지에 저장하고 데이터는 이 스냅샷으로 관리. 장기 보관용 `type: bak`(R2 영속) 클래스는 Velero 실사용 단계에서 재검토.
+
+### 4. democratic-csi external-snapshotter sidecar 제거
+
+democratic-csi helm chart가 로컬에 없어 repo 추가 후 upgrade:
+
+```bash
+helm repo add democratic-csi https://democratic-csi.github.io/charts/
+helm repo update
+helm upgrade synology-iscsi democratic-csi/democratic-csi \
+  -n democratic-csi --version 0.15.1 --reuse-values \
+  --set controller.externalSnapshotter.enabled=false
+```
+
+결과:
+- controller 파드 sidecar 6/6 → **5/5**
+- 새 파드 `synology-iscsi-democratic-csi-controller-ccb945d6b-94fph` Running
+- 재시작 0회
+
+## 검증
+
+| 확인 항목 | 결과 |
+|----------|------|
+| snapshot.storage.k8s.io CRDs | 3종 Established |
+| snapshot-controller Deployment | 2/2 Running (kube-system) |
+| VolumeSnapshotClass `longhorn-snapshot` | 생성, Velero 라벨 부여 |
+| democratic-csi controller sidecars | 5개 (external-snapshotter 빠짐) |
+| 재시작 루프 | 해소 |
+
+## 다음 단계 (Phase 2)
+
+Velero 설치:
+- Backup Storage Location: R2 (기존 `longhorn-backup` 재활용 또는 신설 `velero-backup`) — 결정 필요
+- Volume Snapshot Location: CSI → `longhorn-snapshot` VolumeSnapshotClass
+- 스코프: 네임스페이스 단위, 전체 k8s 리소스 + PV 스냅샷 동시 캡처
+- 기존 파이프라인 정합:
+  - Longhorn BackupTarget(R2 longhorn-backup) 유지 → 볼륨 단위 복구용
+  - Velero → 네임스페이스/앱 단위 전체 복구용
+  - 중복이지만 목적이 다름. 두 개 공존
+
+## 정본 링크
+
+- [[backup|infra/data/backup.md]] (K8s 표준 VolumeSnapshot API 섹션 추가)

infra/data/backup.md

@@ -1,9 +1,24 @@
 ---
 title: 백업 파이프라인
-updated: 2026-04-15
+updated: 2026-04-20
 tags: [infra, backup]
 ---
 
+## K8s 표준 VolumeSnapshot API
+
+snapshot-controller + `snapshot.storage.k8s.io/v1` CRDs 설치됨 (2026-04-20). 향후 Velero 같은 표준 백업 도구 도입의 전제 조건.
+
+| 항목 | 값 |
+|------|-----|
+| snapshot-controller | v8.5.0, Deployment (kube-system, replicas=2) |
+| CRDs | VolumeSnapshot, VolumeSnapshotContent, VolumeSnapshotClass |
+| VolumeSnapshotClass | `longhorn-snapshot` (driver=driver.longhorn.io, type=snap) |
+| Velero 기본 클래스 라벨 | `velero.io/csi-volumesnapshot-class=true` (longhorn-snapshot에 부여) |
+
+현재 `longhorn-snapshot` 클래스는 `type: snap`(Longhorn 내부 스냅샷, 빠름). Velero가 오브젝트 스토리지에 메타/매니페스트를 백업하고 데이터는 VolumeSnapshot으로 관리. 별도의 `type: bak` 클래스(R2 영속) 추가는 Velero 도입 시점에 재검토.
+
+배경: democratic-csi의 external-snapshotter sidecar가 이 CRD를 watch하려다 404/EOF로 주기 재시작했음. 이번 설치로 원인 해소 + Velero 선결 조건 동시 달성. 이력: [[2026-04-20-snapshot-controller-velero-prep|history]]
+
 ## Longhorn PVC 백업 (K3s)
 
 BackupTarget `default` → R2 버킷 `longhorn-backup` (시크릿 `longhorn-backup-r2`). RecurringJob 4종 (critical-snapshot 매시 UTC, critical-backup 6h UTC, standard-snapshot `0 18 * * *` UTC = KST 03:00, standard-backup `0 19 * * *` UTC = KST 04:00).