Files
DongHyeonka 9e9ea94461 feat(backup): keep k3s datastore archives outside AIStor on the HDD
AIStor runs inside the k3s cluster that the datastore archive restores.
After losing the whole cluster the AIStor copy cannot be read until k3s
is running again, which is what the archive is for.

Also keep the seven newest archives in
/srv/k3s/aistor/host-backups/k3s-datastore (root 0700) on the same HDD
filesystem (sdb3). The directory is next to AIStor's drive directory
data/, so AIStor does not list it as a bucket, and it is readable by
mounting sdb3 alone. A metric reports how many local copies exist.

Rejected: the NTFS archive partition (sdb2). It has no Unix
permissions and Windows on the same machine can read it; the archive
holds the server token.

Risk: the files live inside the AIStor PersistentVolume root, which is
mounted into the MinIO pod (uid 1000); mode 0700 root keeps the pod
from reading them.

Verification: bash -n; /srv/k3s/aistor contains only data/ (2026-11-12).
2026-11-12 01:14:45 +09:00
..

호스트 백업과 점검

desktop 호스트에서 systemd 타이머로 도는 백업과 점검이다. 결과는 node-exporter textfile 수집기 (/var/lib/node_exporter/textfile_collector/*.prom)로 Prometheus에 올라가고, 이 폴더의 PrometheusRule이 경보를 낸다. 근거와 결정은 docs/reviews/2026-11-11-k3s-maturity-review.md A1·A11·A13·A14, 8절 결정 1·6이다.

무엇을 어디에 얼마나

대상 방법 주기 보관 위치
k3s datastore + server/token sqlite3 .backup → tar.gz + sha256 매일 03:30 KST AIStor 30일 + 로컬 최근 7개 AIStor platform-host-backups/k3s-datastore/와 /srv/k3s/aistor/host-backups/k3s-datastore/(root 0700). 둘 다 HDD sdb3
Gitea (저장소·패키지·첨부·Actions·app.ini) 라이브 파드에서 gitea dump --skip-db 일요일 04:00 KST 56일(8주) AIStor platform-host-backups/gitea/
platform-postgres (Gitea·Keycloak·tech-log DB) CloudNativePG base backup + WAL 매일 03:00 KST 30일 AIStor platform-postgres-backups/ (W1, services/platform-postgres-backup)
AIStor 데이터(Loki·Tempo) 백업하지 않는다 — — 8절 결정 6: 잃어도 되는 관측 데이터. 디스크를 잃으면 로그·추적 기록만 사라진다
Prometheus·Grafana·Alertmanager PV 백업하지 않는다 — — 설정은 이 저장소가 정본이고, 지표는 다시 쌓인다
  • Gitea DB는 dump에 없다(--skip-db). Gitea를 복원하려면 CNPG 복원이 먼저다(docs/runbooks/gitea-restore.md).
  • k3s 백업에는 token이 들어 있다. token과 datastore가 같이 있으면 클러스터의 모든 Secret을 풀 수 있다. Gitea dump의 app.ini에도 비밀 값이 있다. 그래서 둘 다 AIStor의 전용 사용자만 읽고 쓴다.
  • AIStor는 같은 desktop의 HDD다. SSD가 죽으면 남지만 desktop 자체를 잃으면 같이 잃는다.
  • k3s 백업을 AIStor 밖에도 두는 이유: AIStor는 바로 그 k3s 위에서 돈다. 클러스터를 통째로 잃으면 AIStor를 다시 띄우기 전에는 AIStor 안의 사본을 꺼낼 수 없다. 로컬 사본은 sdb3를 mount하기만 하면 읽힌다 (docs/runbooks/k3s-datastore-restore.md). 폴더는 AIStor 드라이브 폴더(data/) 옆이라 bucket으로 보이지 않는다.

off-host 사본 (준비만, 기본 꺼짐)

위치는 소유자가 정한다(8절 결정 1). /etc/platform-backup/aistor.env에 두 줄을 넣으면 k3s datastore 백업이 그 공개 키로 암호화한 사본을 rclone으로 보낸다.

OFFHOST_GPG_RECIPIENT_FILE=/etc/platform-backup/offhost-recipient.asc   # 공개 키. 개인 키는 desktop에 두지 않는다
OFFHOST_RCLONE_TARGET=<rclone remote>:<path>                             # rclone 설치·설정 필요

지표 platform_backup_offhost_copy{backup="k3s-datastore"}가 1이 된다. Gitea dump의 off-host 사본은 아직 없다.

점검

타이머 사용자 하는 일 지표
platform-k3s-cert-expiry donghyeon 6443·10250 serving 인증서 notAfter platform_k3s_certificate_not_after_seconds
platform-live-drift-check donghyeon origin/main 렌더 → kubectl diff(서버 dry-run) platform_live_drift_objects

경보 (prometheus-rules.yaml)

경보 조건
PlatformK3sDatastoreBackupTooOld 마지막 성공이 2일보다 오래됨
PlatformGiteaBackupTooOld 8일보다 오래됨
PlatformHostBackupFailed 마지막 실행 실패
PlatformHostBackupMetricsAbsent 지표가 하루 동안 없음(타이머나 textfile 수집기가 안 돎)
PlatformLiveDriftDetected drift가 6시간 넘게 남음
PlatformLiveDriftCheckStale drift 검사가 2일 넘게 완료되지 않음
PlatformK3sServingCertificateExpiry 100일 미만 warning, 14일 미만 critical
PlatformK3sCertificateCheckStale 인증서 점검이 2일 넘게 안 돎

scripts/validate/test-platform-host-checks-alerts.sh가 promtool 단위 시험으로 각 경보가 울려야 할 때 울리고 아닐 때 안 울리는지 본다. 같은 PR에서 kube-prometheus-stack의 KubeletClientCertificateExpiration· KubeletServerCertificateExpiration을 껐다. k3s kubelet은 그 지표를 내지 않아 울릴 수 없었다.

적용 (소유자, 순서대로)

전제: node-exporter textfile 수집기(W1, services/observability/node-exporter/values/home.yaml의 --collector.textfile.directory=/host/root/var/lib/node_exporter/textfile_collector)가 들어간 main checkout.

cd /home/donghyeon/workspace/platform && git pull --ff-only
sudo bash scripts/bootstrap/create-host-backup-credentials.sh         # bucket·정책·사용자·/etc/platform-backup/aistor.env (APPLY 입력)
bash scripts/bootstrap/install-host-checks.sh --check
sudo bash scripts/bootstrap/install-host-checks.sh --execute           # 타이머 설치·켜기·첫 실행
kubectl apply -k services/platform-host-checks                         # 경보 규칙
sudo bash scripts/validate/k3s-datastore-restore-drill.sh              # 첫 백업으로 복원 리허설
sudo bash scripts/validate/gitea-backup-restore-drill.sh

install-host-checks.sh --execute 마지막에 platform_backup_last_run_success{backup="k3s-datastore"} 1과 {backup="gitea"} 1이 보여야 한다. 리허설 둘은 각각 K3S DATASTORE RESTORE DRILL PASS, GITEA RESTORE DRILL PASS로 끝나야 한다.

복원 리허설

  • k3s: 백업을 내려받아 sha256을 맞춘 뒤, 운영과 같은 버전의 k3s를 네트워크 없는 일회용 컨테이너로 띄워 API가 뜨는지, Secret 수가 라이브와 비슷한지(±5), 모든 Secret이 복호화되는지 본다. scripts/validate/test-k3s-datastore-restore-drill.sh는 운영 데이터 없이 같은 경로를 시험한다(새 k3s에 시험 Secret 셋 → 암호화돼 저장된 것을 확인 → 복원).
  • Gitea: dump를 풀어 app.ini(INTERNAL_TOKEN·SECRET_KEY), 모든 저장소의 git fsck, 라이브와 저장소 수를 본다.
  • 분기마다 한 번 돌린다. 성공하면 platform_backup_restore_drill_last_success_timestamp_seconds가 갱신된다.