228 lines
8.4 KiB
Markdown
228 lines
8.4 KiB
Markdown
---
|
||
title: K3s 백업 파이프라인
|
||
updated: 2026-04-15 Longhorn 라벨 키 오타 수정 (recurring-job-group, 대시 포함). 자세히는 history/2026-04-15-longhorn-backup-label-typo.md 참조
|
||
tags: [infra, backup, k3s, r2, longhorn, synology]
|
||
---
|
||
|
||
## 아키텍처 (2026-04-14 이후)
|
||
|
||
두 레이어 병행:
|
||
|
||
```
|
||
앱 레벨: K3s Pod(dump/rsync) → NAS (/volume1/k3s-backup/) → R2(k3s-backup)
|
||
↓
|
||
Synology systemd timer
|
||
|
||
Longhorn: Longhorn Volume → Snapshot → Backup → R2(longhorn-backup)
|
||
↓
|
||
RecurringJob (cluster-native)
|
||
```
|
||
|
||
| 레이어 | 용도 | 정합성 | 복원 단위 |
|
||
|--------|------|--------|----------|
|
||
| 앱 레벨 (pg_dump, gitea dump, rsync) | 1순위 복구 경로 | application-consistent | 특정 테이블·파일 |
|
||
| Longhorn Volume backup | 2순위 안전망, 볼륨 통째 롤백 | crash-consistent (block-level) | 볼륨 전체 |
|
||
|
||
**DB는 반드시 앱 레벨 dump 병행.** Longhorn 백업 단독은 crash-consistent에 불과해 트랜잭션 중간 상태가 캡처될 수 있음.
|
||
|
||
## K3s → NAS (NFS)
|
||
|
||
### NFS PV/PVC
|
||
|
||
| 네임스페이스 | PVC 이름 | NFS 경로 | 비고 |
|
||
|-------------|----------|----------|------|
|
||
| gitea | gitea-backup-nfs | /volume1/k3s-backup/gitea | gitea dump |
|
||
|
||
- NFS 서버: 192.168.9.100 (Synology NAS)
|
||
- PV reclaim policy: Retain
|
||
|
||
### CronJob
|
||
|
||
| 네임스페이스 | CronJob | 스케줄 | 내용 |
|
||
|-------------|---------|--------|------|
|
||
| gitea | gitea-backup | 0 3 * * * (UTC) | gitea dump → NFS |
|
||
|
||
## NAS → R2 (Synology systemd timer)
|
||
|
||
### Synology 구성
|
||
|
||
- **rclone 설정**: `/volume1/docker/rclone/rclone.conf`
|
||
- **rclone 실행**: Docker 컨테이너 (`rclone/rclone:latest`)
|
||
- **systemd service**: `r2-backup.service`
|
||
- **systemd timer**: `r2-backup.timer` — 매일 05:00 KST (±5분 jitter)
|
||
|
||
### R2 버킷
|
||
|
||
- 버킷명: `k3s-backup`
|
||
- 엔드포인트: `https://d8e5997eb4040f8b489f09095c0f623c.r2.cloudflarestorage.com`
|
||
- 크레덴셜: [[vault]] `secret/cloud/cloudflare/r2`
|
||
|
||
### 관리 명령 (Synology SSH)
|
||
|
||
```bash
|
||
# 수동 sync
|
||
sudo systemctl start r2-backup.service
|
||
|
||
# 상태 확인
|
||
sudo systemctl status r2-backup.timer
|
||
sudo systemctl list-timers r2-backup.timer
|
||
|
||
# 로그
|
||
sudo journalctl -u r2-backup.service
|
||
|
||
# R2 내용 확인
|
||
sudo /usr/local/bin/docker run --rm \
|
||
-v /volume1/docker/rclone:/config:ro \
|
||
rclone/rclone:latest \
|
||
--config /config/rclone.conf \
|
||
ls r2:k3s-backup/
|
||
```
|
||
|
||
## 보존 정책
|
||
|
||
- NAS: 수동 관리 (디스크 여유에 따라)
|
||
- R2: lifecycle rule 설정 필요 (Cloudflare 대시보드에서 30일 만료 설정)
|
||
|
||
---
|
||
|
||
# Longhorn 볼륨 백업 (2026-04-14 구축)
|
||
|
||
## Backup Target
|
||
|
||
| 항목 | 값 |
|
||
|---|---|
|
||
| 종류 | Cloudflare R2 (S3 호환) |
|
||
| 버킷 | `longhorn-backup` (APAC 리전) |
|
||
| BackupTarget CR | `longhorn-system/default` → `s3://longhorn-backup@auto/` |
|
||
| 크레덴셜 | K8s Secret `longhorn-system/longhorn-backup-r2` (Vault `secret/cloud/cloudflare/r2` 기반) |
|
||
| Secret 키 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINTS` |
|
||
| 상태 확인 | `kubectl -n longhorn-system get backuptarget default` — AVAILABLE=true 여야 함 |
|
||
|
||
## RecurringJob (4개)
|
||
|
||
| 이름 | 그룹 | Task | Cron | 보존 | Concurrency |
|
||
|------|------|------|------|------|-------------|
|
||
| critical-snapshot | critical | snapshot | `0 * * * *` UTC (매시간) | 24 (1일치) | 2 |
|
||
| critical-backup | critical | backup | `0 */6 * * *` UTC (6h 간격, KST 03/09/15/21시 포함) | 28 (7일치) | 1 |
|
||
| standard-snapshot | standard | snapshot | `0 18 * * *` UTC (= KST 03:00) | 7 (7일치) | 2 |
|
||
| standard-backup | standard | backup | `0 19 * * *` UTC (= KST 04:00) | 7 (7일치) | 1 |
|
||
|
||
> cron 은 UTC 기준. standard 그룹은 KST 새벽 트래픽 저점에 실행되도록 설정 (2026-04-15 조정).
|
||
|
||
> [!info] 보존 정책 통일 (2026-04-14)
|
||
> 백업 보존을 일관적으로 **7일 기준**으로 통일. snapshot은 CoW 체인이라 개수보다 보존 기간이 중요 — critical은 1일치 시간 단위, standard는 7일치 일단위로 유지.
|
||
|
||
## 볼륨 분류 (2026-04-14 기준, 라벨 `recurring-job-group.longhorn.io/<group>=enabled`)
|
||
|
||
> [!warning] 라벨 키 주의 (2026-04-15 정정)
|
||
> 정확한 키는 `recurring-job-group.longhorn.io/<group>` (**대시 포함**). 2026-04-14 초기 구축 시 `recurringjob-group.longhorn.io/<group>` (대시 없음) 오타로 18볼륨 백업이 전부 noop 동작했음. RecurringJob 컨트롤러는 셀렉터 매칭 실패 시 에러 없이 "Found 0 volumes"로 조용히 종료하므로 라벨 키는 반드시 대시 포함 형식으로 부착할 것.
|
||
|
||
### critical (13 볼륨)
|
||
|
||
APISIX etcd ×3, Gitea PostgreSQL, Gitea 저장소, VictoriaMetrics, n8n, OpenMemory data, OpenMemory qdrant, Outline, Portainer, SafeLine DB, Teleport.
|
||
|
||
### standard (5 볼륨)
|
||
|
||
Gitea Valkey, VictoriaLogs (14d 보존), Grafana, RabbitMQ, SFTPGo.
|
||
|
||
### 백업 제외
|
||
|
||
SafeLine 런타임 로그/상태 6종 (휘발성 OK), nfs-provisioner 마운트 (10Mi 시스템).
|
||
|
||
### 신규 볼륨 분류 절차
|
||
|
||
```bash
|
||
vol=$(kubectl -n <ns> get pvc <pvc-name> -o jsonpath='{.spec.volumeName}')
|
||
kubectl -n longhorn-system label volume $vol \
|
||
recurring-job-group.longhorn.io/critical=enabled --overwrite
|
||
# 또는 standard
|
||
```
|
||
|
||
## 복원 절차 (**중요**: PVC annotation 방식 안 됨)
|
||
|
||
Longhorn v1.8+ CSI 동적 프로비저닝에서 `longhorn.io/fromBackup` PVC annotation은 **무시됨** (CSI가 annotation을 드라이버로 전달 안 함). 반드시 Volume CR 경유:
|
||
|
||
1. **Volume CR 생성** (`fromBackup` 스펙)
|
||
```yaml
|
||
apiVersion: longhorn.io/v1beta2
|
||
kind: Volume
|
||
metadata:
|
||
name: restored-<tag>
|
||
namespace: longhorn-system
|
||
spec:
|
||
fromBackup: "s3://longhorn-backup@auto/?backup=<backup-name>&volume=<orig-vol>"
|
||
numberOfReplicas: 3
|
||
size: "<bytes>"
|
||
frontend: blockdev
|
||
accessMode: rwo
|
||
```
|
||
|
||
2. **복원 완료 대기** — `state=detached` 또는 `state=attached` + `restoreRequired=false`
|
||
```bash
|
||
kubectl -n longhorn-system get volume restored-<tag> \
|
||
-o jsonpath='{.status.state} {.status.restoreRequired}'
|
||
```
|
||
|
||
3. **PV 생성** (StorageClass는 `longhorn-static` — 동적 provisioning 회피)
|
||
```yaml
|
||
apiVersion: v1
|
||
kind: PersistentVolume
|
||
metadata: { name: restored-<tag>-pv }
|
||
spec:
|
||
capacity: { storage: <size> }
|
||
accessModes: [ReadWriteOnce]
|
||
storageClassName: longhorn-static
|
||
csi:
|
||
driver: driver.longhorn.io
|
||
fsType: ext4
|
||
volumeHandle: restored-<tag>
|
||
volumeAttributes: { numberOfReplicas: "3", staleReplicaTimeout: "30" }
|
||
```
|
||
|
||
4. **PVC 생성** (PV에 직접 바인딩)
|
||
```yaml
|
||
apiVersion: v1
|
||
kind: PersistentVolumeClaim
|
||
metadata: { name: restored-<tag>-pvc, namespace: <ns> }
|
||
spec:
|
||
storageClassName: longhorn-static
|
||
accessModes: [ReadWriteOnce]
|
||
resources: { requests: { storage: <size> } }
|
||
volumeName: restored-<tag>-pv
|
||
```
|
||
|
||
5. **Pod에 마운트** — 데이터 검증 후 원본 PVC로 swap (앱 재배치 필요)
|
||
|
||
> [!info] 2026-04-14 검증
|
||
> 1Gi 볼륨에 10MB urandom + marker 파일 작성 → snap+backup → 삭제 → 복원 → MD5 완벽 일치 확인.
|
||
|
||
## 운영 명령
|
||
|
||
```bash
|
||
# BackupTarget 상태
|
||
kubectl -n longhorn-system get backuptarget default
|
||
|
||
# 볼륨별 백업 이력
|
||
kubectl -n longhorn-system get backupvolume
|
||
|
||
# 최근 백업 목록
|
||
kubectl -n longhorn-system get backups --sort-by='.metadata.creationTimestamp'
|
||
|
||
# 특정 볼륨의 수동 백업 트리거
|
||
cat <<EOF | kubectl apply -f -
|
||
apiVersion: longhorn.io/v1beta2
|
||
kind: Snapshot
|
||
metadata: { name: manual-$(date +%s), namespace: longhorn-system }
|
||
spec: { volume: <volume-name>, createSnapshot: true }
|
||
EOF
|
||
```
|
||
|
||
Longhorn UI: https://longhorn.inouter.com → Backup 탭에서 시각적 확인 가능.
|
||
|
||
## TODO
|
||
|
||
- [x] **R2 lifecycle rule** — `longhorn-backup` 버킷에 7일 만료 규칙 `longhorn-backup-7d-expire` 등록 완료 (2026-04-14, API 경유). `deleteObjectsTransition.condition.maxAge=604800`. Longhorn retention(7일)과 정합.
|
||
- [ ] vault, openmemory, anvil, ironclad 등 추가 서비스 NFS 백업 CronJob 구성
|
||
- [ ] postgres 백업 CronJob NFS 경로 `/volume1/k3s-backup/postgres`로 변경
|
||
- [ ] 분기별 복원 드릴 (critical 그룹 1건 선정하여 실제 복원 절차 실행)
|