docs(runbooks): add restore, rebuild, upgrade and reboot runbooks #8

Merged
donghyeon.kang merged 4 commits from donghyeon.kang/w6-runbooks AGit into main 2026-11-11 16:48:53 +00:00
Owner

무엇을, 왜

k3s 성숙도 점검 A15·7.7절: 호스트를 잃었을 때, datastore·Gitea를 되살릴 때, k3s를 올릴 때, 재부팅 뒤에 무엇을 어떤 순서로 하는지 문서가 없었고, 있던 runbook은 버전 관리 밖(/home/donghyeon/workspace/docs, desktop에만)에 있었다. 8절 결정 3(디스크 분리는 계획만)도 이 PR에 넣는다.

  • docs/runbooks/: after-reboot-checks, k3s-datastore-restore, gitea-restore, k3s-upgrade, host-rebuild, k3s-restart-window
  • docs/design/2026-11-12-state-disk-separation-design.md(상태: 제안)
  • infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml: 호스트에만 있던 k3s drop-in을 그대로 repo에(재구축에 필요)
  • 점검 보고서에 2단계 반영 표, protect-kernel-defaults 권고 철회
  • docs/README.md 지도에 runbooks/·design/

고른 방법과 버린 대안

  • runbook은 중앙 문서가 아니라 이 repo docs/runbooks/에 둔다. 가리키는 스크립트와 같은 PR 흐름으로 고칠 수 있고, 중앙 문서 폴더는 아직 git이 아니다(비공개 repo platform-docs로 옮기는 것은 repo가 만들어지면 따로 한다).
  • 각 runbook 맨 앞에 「전제와 확인」 표를 둔다. 2026-11-12에는 호스트 백업(PR #6)·CNPG 백업(W1)이 설치 전이라 복원 문서를 아직 따라 할 수 없고, 문서가 그렇게 말한다.
  • Gitea 복원은 「파일만 잃음」과 「DB까지」를 나눴다. 공용 DB를 dump 시각으로 PITR하면 Keycloak·tech-log DB도 되돌아가므로 DB는 최신 시점으로 되살리게 했다.
  • 업그레이드는 지금 minor의 채널(v1.36)을 쓴다. stable은 지금 1.37을 가리켜 패치가 아니라 minor 업그레이드가 된다.

위험과 영향

  • 문서와 drop-in 파일 하나다. 아무것도 설치·적용하지 않는다. 복원·재구축은 실행하지 않았다.
  • 운영 Cluster(platform-postgres)를 백업으로 갈아 끼우는 절차는 W1 몫이라 이 PR에 없다. host-rebuild 7단계가 그 빈틈과 임시 방법을 적었다.
  • Host Nginx를 빈 호스트에 까는 절차, workmachine·*cloudflared 재구축은 이 repo에 없다고 적었다.
  • 디스크 분리 설계: prepare-*-local-paths.sh·apply-admin-services.sh가 「PV 경로가 루트 SSD에 있고 아래 mount가 없음」을 검사하므로 이전 PR에서 같이 고쳐야 한다고 적었다.

검증

  • cold-read: 이전 대화를 모르는 새 서브에이전트에게 다섯 runbook만 주었다. after-reboot-checks의 모든 명령을 desktop에서 그대로 실행하고, 나머지 넷은 바꾸는 명령 없이 따라갔다. 지적 약 60개를 반영했다. 주요한 것: Running인데 0/1인 파드를 놓치는 READY 검사, stable 채널, pgAdmin PV 폴더 누락, prepare-observability-local-paths.sh의 --execute, k3s 첫 시작보다 늦은 시간 동기화, 호스트 이름(PV nodeAffinity)과 Tailscale 주소, sudo -i를 블록째 붙일 때의 문제, 시각 변수가 두 번 바뀌는 문제, 덮어쓰기 전 PV 사본.
  • 고친 after-reboot-checks의 새 명령(시간 동기화 확인, READY awk, docker inspect, 경보 조회, DNS)을 desktop에서 다시 돌려 문서 설명과 맞는 것을 봤다.
  • runbook이 가리키는 repo 경로는 모두 main이나 열린 PR(#5·#6·#7)·W1 브랜치에 있다(대조 스크립트 MISSING 0).

리뷰어가 볼 곳

  • docs/runbooks/host-rebuild.md: 순서(1~11)와 「전제」.
  • docs/runbooks/gitea-restore.md: 경우 A·B와 PITR 경고.
  • docs/runbooks/k3s-restart-window.md: 0단계(PriorityClass 먼저).

관련

  • docs/reviews/2026-11-11-k3s-maturity-review.md A12·A15, 7.6·7.7, 8절 결정 3
  • PR #5(재시작 묶음), #6(백업), #7(Keycloak 고정·PriorityClass), W1 브랜치
## 무엇을, 왜 k3s 성숙도 점검 A15·7.7절: 호스트를 잃었을 때, datastore·Gitea를 되살릴 때, k3s를 올릴 때, 재부팅 뒤에 무엇을 어떤 순서로 하는지 문서가 없었고, 있던 runbook은 버전 관리 밖(`/home/donghyeon/workspace/docs`, desktop에만)에 있었다. 8절 결정 3(디스크 분리는 계획만)도 이 PR에 넣는다. - `docs/runbooks/`: `after-reboot-checks`, `k3s-datastore-restore`, `gitea-restore`, `k3s-upgrade`, `host-rebuild`, `k3s-restart-window` - `docs/design/2026-11-12-state-disk-separation-design.md`(상태: 제안) - `infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml`: 호스트에만 있던 k3s drop-in을 그대로 repo에(재구축에 필요) - 점검 보고서에 2단계 반영 표, `protect-kernel-defaults` 권고 철회 - `docs/README.md` 지도에 `runbooks/`·`design/` ## 고른 방법과 버린 대안 - runbook은 중앙 문서가 아니라 이 repo `docs/runbooks/`에 둔다. 가리키는 스크립트와 같은 PR 흐름으로 고칠 수 있고, 중앙 문서 폴더는 아직 git이 아니다(비공개 repo `platform-docs`로 옮기는 것은 repo가 만들어지면 따로 한다). - 각 runbook 맨 앞에 「전제와 확인」 표를 둔다. 2026-11-12에는 호스트 백업(PR #6)·CNPG 백업(W1)이 설치 전이라 복원 문서를 아직 따라 할 수 없고, 문서가 그렇게 말한다. - Gitea 복원은 「파일만 잃음」과 「DB까지」를 나눴다. 공용 DB를 dump 시각으로 PITR하면 Keycloak·tech-log DB도 되돌아가므로 DB는 최신 시점으로 되살리게 했다. - 업그레이드는 지금 minor의 채널(`v1.36`)을 쓴다. `stable`은 지금 1.37을 가리켜 패치가 아니라 minor 업그레이드가 된다. ## 위험과 영향 - 문서와 drop-in 파일 하나다. 아무것도 설치·적용하지 않는다. 복원·재구축은 실행하지 않았다. - 운영 Cluster(platform-postgres)를 백업으로 갈아 끼우는 절차는 W1 몫이라 이 PR에 없다. host-rebuild 7단계가 그 빈틈과 임시 방법을 적었다. - Host Nginx를 빈 호스트에 까는 절차, `workmachine`·`*cloudflared` 재구축은 이 repo에 없다고 적었다. - 디스크 분리 설계: `prepare-*-local-paths.sh`·`apply-admin-services.sh`가 「PV 경로가 루트 SSD에 있고 아래 mount가 없음」을 검사하므로 이전 PR에서 같이 고쳐야 한다고 적었다. ## 검증 - **cold-read**: 이전 대화를 모르는 새 서브에이전트에게 다섯 runbook만 주었다. `after-reboot-checks`의 모든 명령을 desktop에서 그대로 실행하고, 나머지 넷은 바꾸는 명령 없이 따라갔다. 지적 약 60개를 반영했다. 주요한 것: Running인데 `0/1`인 파드를 놓치는 READY 검사, `stable` 채널, pgAdmin PV 폴더 누락, `prepare-observability-local-paths.sh`의 `--execute`, k3s 첫 시작보다 늦은 시간 동기화, 호스트 이름(PV nodeAffinity)과 Tailscale 주소, `sudo -i`를 블록째 붙일 때의 문제, 시각 변수가 두 번 바뀌는 문제, 덮어쓰기 전 PV 사본. - 고친 `after-reboot-checks`의 새 명령(시간 동기화 확인, READY awk, `docker inspect`, 경보 조회, DNS)을 desktop에서 다시 돌려 문서 설명과 맞는 것을 봤다. - runbook이 가리키는 repo 경로는 모두 main이나 열린 PR(#5·#6·#7)·W1 브랜치에 있다(대조 스크립트 MISSING 0). ## 리뷰어가 볼 곳 - `docs/runbooks/host-rebuild.md`: 순서(1~11)와 「전제」. - `docs/runbooks/gitea-restore.md`: 경우 A·B와 PITR 경고. - `docs/runbooks/k3s-restart-window.md`: 0단계(PriorityClass 먼저). ## 관련 - `docs/reviews/2026-11-11-k3s-maturity-review.md` A12·A15, 7.6·7.7, 8절 결정 3 - PR #5(재시작 묶음), #6(백업), #7(Keycloak 고정·PriorityClass), W1 브랜치
donghyeon.kang added 4 commits 2026-11-11 16:39:25 +00:00
/etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml keeps Traefik's
NodePorts on 127.0.0.0/8 so the LAN cannot bypass Host Nginx. The
Traefik README and validator depend on it, but the file itself was only
on the host, so a rebuilt host would not get it.

Add the live content as is (kube-proxy-arg nodeport-addresses). The
host-rebuild and datastore-restore runbooks install it.

Risk: none; nothing installs it automatically.

Verification: the file is byte-for-byte the live drop-in
(ssh desktop cat ...); 40-secrets-encryption.yaml in the repository
already matches the host.
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.
All SSD Local PVs share the root filesystem with the OS, container
images and build caches; review A12 and risk 2. Owner decision 3 asks
for a plan only.

Compare four options (shrink the Windows SSD, a new SSD, the HDD, do
nothing), recommend a new SSD and otherwise the Windows SSD, and give
the migration: mount the new filesystem at the same /srv/k3s/ssd path
so no PV changes, two rsync passes around a short stop, rollback. Note
the scripts whose root-SSD findmnt checks must change in the same PR.

Risk: documentation only; status 제안.

Verification: the PV sizes and paths come from the 2026-11-11 cluster
inventory; the findmnt checks were found with git grep.
The owner decisions in section 8 were settled on 2026-11-12 and the
section 7 recommendations went into separate PRs. Readers of the
review need to know where each one landed and that one recommendation
was withdrawn.

Add a table from each 7.x item to its PR, withdraw protect-kernel-
defaults (CIS dropped it in v1.7 and its kernel.panic_on_oops=1 would
reboot this dual-boot desktop on any oops), and note that the API
server certificate is measured with openssl on the host instead of a
blackbox probe.

Risk: documentation only.

Verification: the PR numbers match the open and merged platform-core
PRs on 2026-11-12.
donghyeon.kang merged commit 8b019d26a0 into main 2026-11-11 16:48:53 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/platform-core#8