---
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 섹션 추가)