The review found no procedure for losing the host, restoring the k3s datastore or Gitea, upgrading k3s, or checking the platform after a reboot, and the existing runbooks live outside version control. Add five runbooks and a restart-window procedure in docs/runbooks: after-reboot-checks (clock, k3s and certificates, node, pods in dependency order, public paths, Prometheus, alerts, runner), k3s-datastore-restore, gitea-restore (file-only vs full restore, with the warning that a PITR of the shared database also rewinds Keycloak and tech-log), k3s-upgrade (patch within a minor), host-rebuild (order and the easy-to-miss parts: host name for PV node affinity, Tailscale address in the DNS config, time sync before the first k3s start), and k3s-restart-window (what to apply in the one restart window, with the PriorityClasses first). The docs map gains runbooks/ and design/. Each runbook starts with its preconditions and the commands that check them; on 2026-11-12 the backups they need are not installed yet, and they say so. Risk: documentation only. Restores and the rebuild were not executed. Verification: a fresh subagent with only these files ran every command in after-reboot-checks on the desktop and walked the others read-only; its findings (about 60, e.g. a READY check that missed 0/1 Running pods, `stable` pointing to another minor, a missing pgAdmin directory, time sync after the first k3s start) are fixed here. The revised after-reboot commands were rerun on the desktop and match the text. Every repository path the runbooks name exists on main or in the named PR.
7.0 KiB
k3s datastore 복원
k3s datastore(sqlite)를 백업에서 되살리는 절차다. 쿠버네티스 객체 전부(Deployment, Secret, CNPG Cluster 정의 등)가 여기에 있다.
PV 안의 데이터(Postgres, Gitea 파일)는 여기에 없다. 그것은 gitea-restore.md와 CNPG 복원으로 따로 되살린다.
전제와 확인 — 하나라도 아니면 이 문서는 아직 못 쓴다
| 전제 | 확인 |
|---|---|
| platform-core checkout이 최신 main이고 호스트 백업(PR #6)이 들어 있다 | cd /home/donghyeon/workspace/platform && git pull --ff-only && ls scripts/validate/k3s-datastore-restore-drill.sh |
호스트 백업이 설치돼 백업이 하나 이상 있다(services/platform-host-checks/README.md) |
sudo ls -1t /srv/k3s/aistor/host-backups/k3s-datastore/ | head -3 |
| root 셸 | 아래 sudo -i를 따로 먼저 친다(블록째 붙이면 비밀번호 줄을 먹는다) |
2026-11-12 현재 호스트 백업은 PR #6이 설치되기 전이라 백업이 없다.
언제 쓰나
| 상황 | 이 문서 |
|---|---|
datastore가 깨져 k3s가 안 뜬다(journalctl -u k3s에 sqlite/kine 오류) |
예, 같은 호스트 |
| 루트 SSD를 잃었다 | 예, host-rebuild.md의 한 단계로 |
| 객체 몇 개를 실수로 지웠다 | 아니오. repo에서 다시 적용한다(drift 검사로 무엇이 없는지 본다) |
1. 백업을 고르고 확인한다
sudo -i
TS=$(date +%Y%m%d%H%M)
cd /srv/k3s/aistor/host-backups/k3s-datastore
B=$(ls -1t k3s-datastore-*.tar.gz | head -1); echo "$B"
[ "$(sha256sum "$B" | awk '{print $1}')" = "$(cat "$B.sha256")" ] && echo checksum-ok # .sha256에는 해시만 들어 있다
W=/root/k3s-restore-$TS && mkdir -m 0700 "$W" && tar -C "$W" -xzf "$B" && D=$(ls -d "$W"/k3s-datastore-*) && ls "$D"
cat "$D/META"
sqlite3 "$D/state.db" 'PRAGMA integrity_check;'
checksum-ok, META state.db token, ok가 보여야 한다.
다른 백업 위치(로컬 사본이 없을 때):
-
AIStor(AIStor가 떠 있을 때).
hb_mc <폴더> <mc 인자>는 고정된 AIStor client를 그 폴더를/work로 붙여 돌린다(키는 그 폴더의 0600 env 파일로 간다).. /usr/local/lib/platform-backup/lib/host-backup.sh && hb_load_aistor_env M=$(mktemp -d /root/k3s-fetch.XXXXXX) hb_mc "$M" ls "backup/$AISTOR_BUCKET/k3s-datastore/" hb_mc "$M" cp "backup/$AISTOR_BUCKET/k3s-datastore/<이름>" "backup/$AISTOR_BUCKET/k3s-datastore/<이름>.sha256" /work/ rm -f "$M/.mc.env"; cd "$M" # 이 폴더에서 1단계의 B= 이하를 이어서 한다 -
off-host 암호화 사본: 소유자가 개인 키가 있는 기계에서
gpg --decrypt <이름>.tar.gz.gpg > <이름>.tar.gz후 desktop으로 옮긴다.
버전을 맞춘다
META의 k3s_version과 지금 k3s가 같아야 한다(/usr/local/bin/k3s --version | head -1). 다르면 k3s-upgrade.md 3단계 설치 명령에
META의 버전을 넣어 그 버전으로 설치한다.
먼저 리허설한다 (운영에 손대지 않음)
bash /home/donghyeon/workspace/platform/scripts/validate/k3s-datastore-restore-drill.sh --from-dir "$D"
K3S DATASTORE RESTORE DRILL PASS와 restored: namespaces=… secrets=N … 줄이 나와야 한다. 이 N이 5단계의 기준값이다.
2. k3s를 멈추고 지금 상태를 옮겨 둔다
같은 호스트에서 깨진 datastore를 바꾸는 경우:
systemctl stop k3s
/usr/local/bin/k3s-killall.sh # 컨테이너까지 멈춘다. 복원 중 파드가 옛 상태로 돌지 않게
mv /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/db.before-restore-$TS
cp -a /var/lib/rancher/k3s/server/token /var/lib/rancher/k3s/server/token.before-restore-$TS
새로 설치한 호스트(host-rebuild.md)는 k3s를 INSTALL_K3S_SKIP_START=true로 설치해 한 번도 시작하지 않은 상태여야 한다.
실수로 한 번 시작했다면 그때 생긴 빈 클러스터의 파일을 지운다(잃을 것이 없다):
systemctl stop k3s && /usr/local/bin/k3s-killall.sh
rm -rf /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/tls /var/lib/rancher/k3s/server/cred /var/lib/rancher/k3s/server/token
3. 백업을 넣는다
install -d -m 0700 /var/lib/rancher/k3s/server/db
install -m 0600 "$D/state.db" /var/lib/rancher/k3s/server/db/state.db
install -m 0600 "$D/token" /var/lib/rancher/k3s/server/token
k3s 문서(datastore/backup-restore, SQLite)대로 db/와 token을 함께 넣는다. token이 다르면 datastore 안의 암호화 설정과 인증서를 풀지 못한다.
4. k3s 설정이 백업 때와 같은지 본다
secrets-encryption: true가 없으면 Secret을 읽지 못한다. 없으면 checkout에서 넣는다.
ls /etc/rancher/k3s/config.yaml.d/
cd /home/donghyeon/workspace/platform
install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml
install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml
재시작 묶음(PR #5)을 적용했던 호스트라면 bash scripts/bootstrap/apply-k3s-restart-bundle.sh --check로 무엇이 빠졌는지 보고,
5단계가 끝난 뒤 --execute로 다시 깐다.
5. k3s를 시작하고 확인한다
systemctl start k3s
until k3s kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready
k3s kubectl get nodes
k3s kubectl get secrets -A --no-headers | wc -l
k3s kubectl -n object-storage get secret aistor-root-configuration -o jsonpath='{.data}' | wc -c
k3s kubectl get pods -A --no-headers | awk '{split($3, r, "/")} $4 != "Completed" && ($4 != "Running" || r[1] != r[2])'
ready, 노드Ready, Secret 수가 1단계 리허설의N과 비슷함(±5), 마지막에서 두 번째 숫자가 0보다 큼(복호화 성공).- 파드는 PV 데이터에 따라 몇 분 걸린다. 그 뒤
after-reboot-checks.md를 처음부터 돈다.
되돌리기 (2를 한 경우)
systemctl stop k3s && /usr/local/bin/k3s-killall.sh
rm -rf /var/lib/rancher/k3s/server/db
mv /var/lib/rancher/k3s/server/db.before-restore-$TS /var/lib/rancher/k3s/server/db
cp -a /var/lib/rancher/k3s/server/token.before-restore-$TS /var/lib/rancher/k3s/server/token
systemctl start k3s
$TS는 1단계에서 정한 값이다. 셸이 바뀌었으면 ls -d /var/lib/rancher/k3s/server/db.before-restore-*로 찾는다.
끝나면
rm -rf /root/k3s-restore-$TS
복원한 백업 시각 이후에 만든 객체는 없다. repo와의 차이를 보고 필요한 것을 다시 적용한다:
cd /home/donghyeon/workspace/platform
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt
SUMMARY drift=0이 목표다.live-drift-accepted.txt의 항목은 기한(지금 2026-11-30)이 지나면 다시 drift로 센다.- PV 데이터: platform-postgres는 W1의 CNPG 백업(
services/platform-postgres-backup/README.md, W1 PR)에서, Gitea 파일은gitea-restore.md로.