Files
platform-core/docs/runbooks/host-rebuild.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

10 KiB

호스트 재구축 (루트 SSD를 잃었을 때)

desktop의 루트 SSD를 잃고 HDD(WDC 2TB, AIStor 파티션 라벨 AISTOR_DATA)는 살아 있을 때, 새 SSD에서 플랫폼을 되살리는 순서다. 각 단계의 자세한 명령은 링크한 문서를 따른다. 이 문서는 순서와 빠지기 쉬운 것을 정한다.

전제와 확인 — 하나라도 아니면 4·7·8단계에서 멈춘다

전제 확인
HDD의 k3s datastore 로컬 사본이 있다(PR #6 호스트 백업이 설치돼 돌았다) 2단계 mount 뒤 sudo ls /srv/k3s/aistor/host-backups/k3s-datastore/
CNPG 백업이 AIStor에 있다(W1) 6단계 뒤 AIStor platform-postgres-backups bucket
Gitea dump가 AIStor에 있다(PR #6) 6단계 뒤 AIStor platform-host-backups/gitea/

2026-11-12 현재는 세 백업 모두 설치되기 전이다. 그 전에는 datastore 대신 이 저장소의 bootstrap 절차(bootstrap/manual/phase1~4)로 처음부터 다시 세워야 하고, Secret은 소유자가 새로 넣어야 한다.

무엇이 남고 무엇을 잃나

남음 (HDD, xfs AISTOR_DATA) 잃음 (루트 SSD)
AIStor 데이터(/srv/k3s/aistor/data): Loki·Tempo, CNPG 백업, Gitea dump OS, k3s, Docker(/var/lib/docker: runner, workmachine, *cloudflared 컨테이너), 모든 SSD Local PV
k3s datastore 로컬 사본(/srv/k3s/aistor/host-backups/k3s-datastore/) /etc(nginx, certbot 인증서, dnsmasq, /etc/platform-backup), ~/.secrets
/etc/rancher/k3s/platform-post-bundle.env, platform-restore-evidence.env(2026-08 Secret 암호화 hardening의 증거 표시. 운영에는 필요 없고, bootstrap/manual/k3s-secret-encryption.md 검사기가 「증거 없음」으로 볼 뿐이다)

desktop 전체를 잃으면 HDD도 잃는다. 그때는 off-host 사본이 있어야 한다(services/platform-host-checks/README.md).

시작 전에 소유자가 따로 가지고 있어야 하는 것

k3s datastore를 복원하면 쿠버네티스 Secret은 모두 돌아온다. 아래는 그 밖의 것이다.

  • platform-core 저장소 사본(Gitea가 내려가 있으므로 노트북 clone이나 off-host 사본). 이 문서는 desktop의 /home/donghyeon/workspace/platform에 clone했다고 보고, 모든 상대경로는 거기 기준이다.
  • Tailscale 계정(사설 DNS가 Tailscale 주소를 쓴다), Cloudflare API token(certbot DNS 인증), certbot 연락 email
  • Slack webhook 복구 경로(KeePass, scripts/bootstrap/backup-slack-webhook-recovery.sh)
  • off-host 백업을 쓴다면 그 개인 키
  • hyeonworks.com 앞단 설정과 tech-log 이미지·매니페스트: 이 저장소에 없다. tech-log-backend·tech-log-frontend 저장소를 따른다.
  • workmachine과 *cloudflared 컨테이너: 소유자의 별도 설정이다. 이 저장소에 재구축 절차가 없다.

순서

1 OS·이름·도구·시계 → 2 HDD mount → 3 k3s 설치(시작 안 함) + 시간 동기화 drop-in → 4 datastore 복원(첫 시작)
  → 5 Local PV 폴더 → 6 AIStor 확인 → 7 Postgres 복원(CNPG) → 8 호스트 백업 다시 설치 → 9 Gitea 파일 복원
  → 10 호스트 설정(Tailscale·DNS·nginx·TLS·Docker·runner·재시작 묶음) → 11 확인(Gitea 확인 포함)

1. OS, 호스트 이름, 도구, 시계

  • Ubuntu 24.04, 사용자 donghyeon(uid 1000. Gitea rootless와 AIStor 폴더 소유자가 1000이다).

  • 호스트 이름을 donghyeon-system-product-name으로 둔다. 모든 Local PV의 nodeAffinity가 kubernetes.io/hostname=donghyeon-system-product-name을 본다. 이름이 다르면 PV를 쓰는 파드가 전부 Pending이다.

    sudo hostnamectl set-hostname donghyeon-system-product-name
    
  • 패키지: git jq ripgrep sqlite3 curl openssl python3-yaml nginx dnsmasq, snap certbot과 certbot-dns-cloudflare. Docker는 공식 apt 저장소로 설치하고 donghyeon을 docker 그룹에 넣는다. Helm v3.19.4를 ~/.local/bin/helm에 둔다 (렌더 스크립트가 정확한 버전을 요구한다).

  • 시계: sudo timedatectl set-local-rtc 0, sudo timedatectl set-ntp true. Windows 쪽 RealTimeIsUniversal은 W1 infrastructure/host/README.md 3단계(W1 PR).

2. HDD mount

새 SSD를 달면 디스크 이름(sda·sdb·sdc)이 바뀔 수 있다. 이름이 아니라 라벨로 찾는다.

lsblk -o NAME,SIZE,FSTYPE,LABEL,MODEL       # LABEL=AISTOR_DATA, xfs, WDC 2TB 쪽
echo 'LABEL=AISTOR_DATA /srv/k3s/aistor xfs defaults,noatime 0 2' | sudo tee -a /etc/fstab   # 2026-11-12 live fstab과 같은 줄
sudo findmnt --verify                       # 오류가 없어야 한다. 있으면 fstab 줄을 고치고 다시 본다(틀린 fstab은 다음 부팅을 emergency mode로 보낸다)
sudo mkdir -p /srv/k3s/aistor && sudo mount /srv/k3s/aistor
ls /srv/k3s/aistor                          # data  host-backups

3. k3s 설치 (시작하지 않은 채로) + 시간 동기화 drop-in

먼저 HDD의 백업에서 버전을 본다(k3s-datastore-restore.md 1단계: cat "$D/META"의 k3s_version). 아래 <META 버전>에 넣는다.

curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION='<META 버전>' INSTALL_K3S_SKIP_START=true \
  INSTALL_K3S_EXEC='server --disable=servicelb' sh -
cd /home/donghyeon/workspace/platform
sudo install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml
sudo install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml

k3s를 처음 시작하기 전에 W1의 시간 동기화 drop-in을 깐다(infrastructure/host/README.md 2단계, W1 PR). 11-11 사고는 틀린 시계로 k3s가 인증서를 만든 것이었다. 재시작 묶음(PR #5)은 클러스터가 떠 있어야 도는 스크립트라 10단계에서 깐다.

4. datastore 복원 (k3s 첫 시작)

k3s-datastore-restore.md 1·3·4·5단계(2단계는 「새로 설치한 호스트」 경우). 이때 PV 폴더가 없어 Postgres·Gitea 파드는 뜨지 못한다. 정상이다.

5. Local PV 폴더

sudo bash scripts/bootstrap/prepare-ssd-local-paths.sh
sudo bash scripts/bootstrap/prepare-observability-local-paths.sh --execute     # 인자 없으면 dry run이다
sudo install -d -o root -g root -m 0750 /srv/k3s/ssd/pgadmin                   # 위 둘이 만들지 않는다(apply-admin-services.sh가 만들던 것)

빈 폴더가 생긴다. 관측 스택(Prometheus·Loki 캐시·Grafana)은 빈 PV로 다시 쌓인다. Grafana 대시보드는 repo의 ConfigMap에서 다시 생긴다.

6. AIStor

AIStor의 PV는 HDD라 데이터가 그대로다. Secret(라이선스, root 설정)도 datastore에서 돌아왔다.

kubectl -n object-storage get pods
kubectl -n object-storage get objectstore -o wide
bash scripts/validate/aistor-s3-smoke.sh --execute        # 임시 bucket을 만들고 쓰고 지운다(쓰기 작업)

Initialized/green, 마지막 줄 AISTOR_S3_SMOKE_PASS bucket-create object-write object-read object-delete bucket-delete.

7. platform-postgres 복원

datastore에는 Cluster 정의가 있지만 PV는 비어 있다. CNPG를 AIStor 백업(platform-postgres-backups)에서 되살린다. Gitea·Keycloak·tech-log DB가 모두 여기 있다.

먼저 원본 정의를 남긴다(되살린 Cluster가 원래와 같은지 비교할 기준이다):

kubectl -n platform-data get cluster platform-postgres -o yaml > /root/platform-postgres-cluster-before-rebuild.yaml
  • W1의 services/platform-postgres-backup/README.md(W1 PR)에는 임시 Cluster로 하는 「복원 리허설」이 있다. 그 restore-drill/cluster.yaml의 bootstrap.recovery를 쓰는 방식이다.
  • 운영 Cluster를 백업으로 갈아 끼우는 절차(빈 PV의 platform-postgres를 지우고 같은 이름으로 recovery bootstrap)는 아직 문서가 없다(W1 몫). 그 문서가 생기기 전에는 리허설 절차를 이름만 platform-postgres로 바꿔 따르고, 위에서 남긴 원본과 pg_hba(techlog 두 줄 포함)· Secret 참조·resources가 같은지 비교한다.

8. 호스트 백업 다시 설치

/etc/platform-backup/aistor.env와 /usr/local/lib/platform-backup은 SSD와 함께 잃었다. 9단계(Gitea 복원)가 이것을 쓴다. services/platform-host-checks/README.md 「적용」의 create-host-backup-credentials.sh(AIStor에 새 사용자를 하나 더 만든다)와 install-host-checks.sh --execute를 돈다. 첫 실행 백업은 「복원 직후 상태」의 백업이 된다.

9. Gitea 파일 복원

gitea-restore.md의 경우 B(DB는 7에서 되살렸다), 1~5단계. 6단계 확인 중 https·로그인은 10단계(nginx·TLS·DNS) 뒤로 미룬다. 그 전에는 kubectl -n gitea get pods와 저장소 수만 본다.

10. 호스트 설정

무엇 문서
Tailscale 설치·로그인 사설 DNS(infrastructure/networking/private-dns/host/dnsmasq-tailscale.conf)가 Tailscale 주소 100.92.240.34를 고정해 쓴다. 새로 로그인해 주소가 바뀌면 이 파일의 listen-address·address= 줄을 새 주소로 바꾸는 PR을 낸다
사설 DNS(dnsmasq LAN·Tailscale) infrastructure/networking/private-dns/host/README.md
Host Nginx와 TLS infrastructure/networking/host-nginx/README.md는 전환 기록이라 빈 호스트 설치 절차가 아니다. 이 저장소의 learn-services*.conf를 /etc/nginx/sites-available/에 두고, 인증서는 bootstrap/manual/phase3-admin-surfaces.md의 certbot 절차로 다시 받는다. 빈 호스트용 절차는 아직 없다
Docker daemon.json, runner 상한·정리 W1 infrastructure/host/README.md 4단계, infrastructure/ci/gitea-runner/README.md
Gitea Actions runner 재등록 infrastructure/ci/gitea-runner/README.md
k3s 재시작 묶음(kubelet 예약·audit·PSA) infrastructure/host/k3s/README.md(PR #5)
tech-log 운영 이미지 Gitea 패키지 레지스트리에서 다시 받는다(W1의 레지스트리 전환 뒤). 9단계 dump에 패키지가 들어 있다

11. 확인

after-reboot-checks.md를 처음부터 끝까지 돈다(8단계의 workmachine·*cloudflared는 이 저장소 밖이라 없을 수 있다). gitea-restore.md 6단계를 마저 한다. 그다음 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