backup: install Velero v1.18 (chart 12.0.0) + daily-full schedule to R2 velero-backup

2026-04-20 10:12:21 +09:00
parent a2884a60d8
commit 5d0632cb68
2 changed files with 201 additions and 8 deletions
--- a/history/2026-04-20-velero-install.md
+++ b/history/2026-04-20-velero-install.md
@@ -0,0 +1,159 @@
+---
+title: Velero 도입 (K8s 표준 백업 도구)
+date: 2026-04-20
+tags: [history, velero, backup, k3s, csi]
+---
+
+## 배경
+
+Longhorn BackupTarget은 볼륨 단위 복구에 강하지만 네임스페이스 · 앱 단위 전체 복원(k8s 리소스 정의 + PV 데이터 동시 캡처)을 지원하지 않음. 표준 도구 필요성 논의 후 Velero 도입 결정. 선결 조건 snapshot-controller + VolumeSnapshot CRDs는 [[2026-04-20-snapshot-controller-velero-prep|prep]]에서 완료됨.
+
+## 결정 사항
+
+| 항목 | 값 | 근거 |
+|------|-----|------|
+| 백업 대상 스토리지 | R2 신설 버킷 `velero-backup` | 기존 `longhorn-backup`과 역할 혼동 방지. 버킷 IAM 정책 분리 여지 |
+| 리전 | ENAM (R2 기본 자동 배정) | APAC 지정 API 옵션 없음. 배치 백업이라 레이턴시 영향 미미 |
+| Credentials | 기존 R2 키 재사용 | Vault `secret/cloud/cloudflare/r2` · 현재 R2 계정 단일 |
+| Volume snapshot | CSI (`longhorn-snapshot` VolumeSnapshotClass, type=snap) | Longhorn 네이티브 스냅샷 사용. 속도 빠름 |
+| 스케줄 | 일 1회 UTC 16:00 (KST 01:00) | Longhorn 6h critical-backup과 겹치지 않음 |
+| TTL | 720h (30일) | 월 단위 보관. 장기 보관은 별도 수동 백업 또는 TTL 연장 |
+| 스코프 | 전체 네임스페이스 + cluster-scoped, 단 인프라 NS 제외 | 초기 도입은 포괄적으로. 추후 좁히는 게 쉬움 |
+
+## 설치
+
+### 1. Helm 저장소 · 네임스페이스
+
+```bash
+helm repo add vmware-tanzu https://vmware-tanzu.github.io/helm-charts
+helm repo update vmware-tanzu
+
+kubectl create namespace velero
+```
+
+### 2. R2 credentials 시크릿
+
+```bash
+printf '[default]\naws_access_key_id=<KEY>\naws_secret_access_key=<SECRET>\n' \
+  | kubectl -n velero create secret generic velero-cloud-credentials \
+      --from-file=cloud=/dev/stdin
+```
+
+키는 Vault `secret/cloud/cloudflare/r2`에 보관.
+
+### 3. values.yaml
+
+```yaml
+initContainers:
+  - name: velero-plugin-for-aws
+    image: velero/velero-plugin-for-aws:v1.14.0
+    imagePullPolicy: IfNotPresent
+    volumeMounts:
+      - mountPath: /target
+        name: plugins
+
+credentials:
+  useSecret: true
+  existingSecret: velero-cloud-credentials
+
+configuration:
+  features: EnableCSI
+  defaultBackupTTL: 720h
+  defaultVolumesToFsBackup: false
+
+  backupStorageLocation:
+    - name: default
+      provider: aws
+      bucket: velero-backup
+      default: true
+      config:
+        region: us-east-1              # R2 무시하지만 필수 필드
+        s3ForcePathStyle: "true"
+        s3Url: https://d8e5997eb4040f8b489f09095c0f623c.r2.cloudflarestorage.com
+        checksumAlgorithm: ""          # R2 호환성 (AWS SDK checksum 비활성)
+
+  volumeSnapshotLocation:
+    - name: default
+      provider: csi
+
+snapshotsEnabled: true
+deployNodeAgent: false                  # restic 파일 단위 백업은 현재 불필요
+
+resources:
+  requests:
+    cpu: 100m
+    memory: 256Mi
+  limits:
+    memory: 512Mi
+```
+
+```bash
+helm install velero vmware-tanzu/velero -n velero --version 12.0.0 \
+  -f /tmp/velero-values.yaml
+```
+
+### 4. 검증 (테스트 백업)
+
+`outline` 네임스페이스(Longhorn 5Gi PVC 포함)로 테스트:
+
+```
+Phase:  Completed
+CSI Snapshots:
+  outline/outline-data:
+    Snapshot Content Name: snapcontent-297415e0-...
+    CSI Driver:            driver.longhorn.io
+    Snapshot Size (bytes): 5368709120
+    Result:                succeeded
+```
+
+### 5. 정기 스케줄
+
+```yaml
+apiVersion: velero.io/v1
+kind: Schedule
+metadata:
+  name: daily-full
+  namespace: velero
+spec:
+  schedule: "0 16 * * *"
+  template:
+    ttl: 720h
+    includedNamespaces: ["*"]
+    excludedNamespaces:
+      - kube-system
+      - kube-public
+      - kube-node-lease
+      - velero
+      - longhorn-system
+      - democratic-csi
+      - metallb-system
+      - cert-manager
+      - monitoring
+      - logging
+      - external-secrets
+      - nfs-provisioner
+      - rabbitmq-system
+    snapshotVolumes: true
+    storageLocation: default
+    volumeSnapshotLocations: [default]
+    defaultVolumesToFsBackup: false
+```
+
+## 주의/함정
+
+- `config.checksumAlgorithm: ""` 없으면 R2에서 AWS SDK의 integrity check로 업로드 실패 가능. Velero 공식 issue에서 권장됨.
+- `region: us-east-1`은 R2가 무시하지만 SDK 검증 때문에 필수.
+- VolumeSnapshot/VolumeSnapshotContent CRD는 스냅샷 완료 후 Velero가 즉시 GC. `kubectl get volumesnapshot -A`에 남지 않는 건 정상.
+- velero CLI 설치는 로컬 Mac에서 `brew install velero`. 서버 작업에는 kubectl + Backup CRD로도 가능.
+
+## 다음 과제
+
+- R2 `velero-backup` 버킷 전용 Scoped Token 발급 (현재는 전 버킷 공통 키 재사용) — 보안 강화
+- 복원 리허설: 월 1회 임의 네임스페이스를 다른 클러스터 또는 격리된 네임스페이스로 restore 테스트
+- Longhorn `type: bak` VolumeSnapshotClass 추가 검토 (R2 영속 저장 필요 시)
+- Velero 알림 통합: backup 실패 시 Discord 또는 email (velero webhook/plugin)
+
+## 정본 링크
+
+- [[backup|infra/data/backup.md]] (Velero 섹션)
+- [[2026-04-20-snapshot-controller-velero-prep|prep history]]
--- a/infra/data/backup.md
+++ b/infra/data/backup.md
@@ -4,20 +4,54 @@ updated: 2026-04-20
 tags: [infra, backup]
 ---

-## K8s 표준 VolumeSnapshot API
+## Velero (K8s 표준 백업 도구)

-snapshot-controller + `snapshot.storage.k8s.io/v1` CRDs 설치됨 (2026-04-20). 향후 Velero 같은 표준 백업 도구 도입의 전제 조건.
+네임스페이스 · 앱 단위 전체 복원을 위한 표준 백업 도구. Longhorn BackupTarget(볼륨 단위)과 공존 — 목적이 다름.
+
+| 항목 | 값 |
+|------|-----|
+| Namespace | velero |
+| Chart | vmware-tanzu/velero `12.0.0` (app `v1.18.0`) |
+| Plugin | `velero/velero-plugin-for-aws:v1.14.0` (initContainer) |
+| Features | `EnableCSI` |
+| BackupStorageLocation | `default` → R2 버킷 `velero-backup` (ENAM), endpoint `d8e5997eb4040f8b489f09095c0f623c.r2.cloudflarestorage.com` |
+| VolumeSnapshotLocation | `default` (provider=csi) |
+| VolumeSnapshotClass | `longhorn-snapshot` (driver.longhorn.io, type=snap) |
+| Credentials 시크릿 | `velero-cloud-credentials` (namespace: velero). Vault `secret/cloud/cloudflare/r2` 재사용 (기존 `longhorn-backup-r2`와 동일 키) |
+| 클라이언트 | `brew install velero` (macOS) |
+
+### 백업 스케줄 `daily-full`
+
+| 항목 | 값 |
+|------|-----|
+| Cron | `0 16 * * *` UTC (KST 01:00) |
+| TTL | 720h (30일) |
+| 스코프 | 전체 네임스페이스 (`*`) + cluster-scoped |
+| 제외 네임스페이스 | kube-system, kube-public, kube-node-lease, velero, longhorn-system, democratic-csi, metallb-system, cert-manager, monitoring, logging, external-secrets, nfs-provisioner, rabbitmq-system |
+| 볼륨 | CSI 스냅샷 (Longhorn 네이티브 스냅샷으로 생성) |
+
+기존 Longhorn BackupTarget은 유지 (볼륨 단위 장애 복구용). Velero는 네임스페이스 단위 전체 복구용.
+
+### 운영 명령
+
+```bash
+velero backup get -n velero
+velero backup describe <name> -n velero --details
+velero backup logs <name> -n velero
+velero backup create adhoc-<name> --include-namespaces <ns> --snapshot-volumes -n velero --wait
+
+velero schedule get -n velero
+velero restore create --from-backup <name> -n velero
+```
+
+### snapshot-controller (선결 인프라)

 | 항목 | 값 |
 |------|-----|
 | 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에 부여) |
+| CRDs | snapshot.storage.k8s.io/v1 — VolumeSnapshot, VolumeSnapshotContent, VolumeSnapshotClass |

-현재 `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]]
+도입 이력: [[2026-04-20-snapshot-controller-velero-prep|prep]] · [[2026-04-20-velero-install|install]]

 ## Longhorn PVC 백업 (K3s)