Files
platform-core/docs/runbooks/k3s-datastore-restore.md
T
DongHyeonka 819f3f14f1 docs(runbooks): add restore, rebuild, upgrade and reboot runbooks
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.
2026-11-12 01:38:58 +09:00

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로.