obsidian/history/2026-04-20-velero-install.md

title, date, tags

title	date	tags
Velero 도입 (K8s 표준 백업 도구)	2026-04-20	history velero backup k3s csi

배경

Longhorn BackupTarget은 볼륨 단위 복구에 강하지만 네임스페이스 · 앱 단위 전체 복원(k8s 리소스 정의 + PV 데이터 동시 캡처)을 지원하지 않음. 표준 도구 필요성 논의 후 Velero 도입 결정. 선결 조건 snapshot-controller + VolumeSnapshot CRDs는 2026-04-20-snapshot-controller-velero-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 저장소 · 네임스페이스

helm repo add vmware-tanzu https://vmware-tanzu.github.io/helm-charts
helm repo update vmware-tanzu

kubectl create namespace velero

2. R2 credentials 시크릿

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

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

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. 정기 스케줄

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 (Velero 섹션)
• 2026-04-20-snapshot-controller-velero-prep