# 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. 백업을 고르고 확인한다 ```bash sudo -i ``` ```bash 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 <폴더> `는 고정된 AIStor client를 그 폴더를 `/work`로 붙여 돌린다(키는 그 폴더의 0600 env 파일로 간다). ```bash . /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 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를 바꾸는 경우: ```bash 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`로 설치해 **한 번도 시작하지 않은** 상태여야 한다. 실수로 한 번 시작했다면 그때 생긴 빈 클러스터의 파일을 지운다(잃을 것이 없다): ```bash 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. 백업을 넣는다 ```bash 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에서 넣는다. ```bash ls /etc/rancher/k3s/config.yaml.d/ ``` ```bash 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를 시작하고 확인한다 ```bash 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를 한 경우) ```bash 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-*`로 찾는다. ## 끝나면 ```bash rm -rf /root/k3s-restore-$TS ``` 복원한 백업 시각 이후에 만든 객체는 없다. repo와의 차이를 보고 필요한 것을 다시 적용한다: ```bash 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`로.