Files
platform-core/docs/runbooks/k3s-restart-window.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

3.0 KiB

k3s 재시작 창

k3s 재시작이나 파드 재시작을 부르는 변경을 한 번의 창에 모아서 한다(성숙도 점검 8절 결정 5). 지금 모인 것은 아래 표다. 하나씩 따로 하면 운영 중단이 여러 번 생긴다.

순서 변경 중단 출처
0 PR #4 루트 적용(PriorityClass 둘, tech-log tenant, keycloak 정책)과 PR #3 Traefik resources. 재시작 없음 없음(Traefik만 몇 초) scripts/validate/README.md, 공유 노트의 소유자 명령 묶음
1 k3s 재시작 묶음: kubelet 예약·메모리 축출·graceful shutdown, API 감사 로그, PSA 기본값, local-path 기본 해제, W1 시간 동기화 drop-in API 1~2분(컨테이너는 계속 돈다) infrastructure/host/k3s/README.md
2 받아들인 drift 해소: Keycloak Operator(라벨), prometheus-operator·kube-state-metrics(이미지 문자열), 관측 core의 Kubelet 인증서 경보 제거 해당 파드 재시작 scripts/validate/live-drift-accepted.txt
3 PriorityClass 붙이기(Keycloak, Gitea, Loki, Tempo)와 Keycloak Operator·서버 이미지 digest 고정 Keycloak 로그인 1~2분, Gitea·Loki·Tempo 재시작 PR #7
4 Postgres priorityClassName·Guaranteed QoS Postgres 재시작(30초 안팎, 모든 서비스의 DB가 끊김) W1

창 전에

  • 어느 PR이 main에 들어갔는지 본다. 들어가지 않은 줄은 건너뛴다.
  • CI job 0개, 에이전트 게이트 없음(flock -n /tmp/claude-gates/heavy.lock true && echo free).
  • after-reboot-checks.md 1~7을 한 번 돌려 지금이 정상인지 본다. 정상이 아닌 상태에서 시작하지 않는다.
  • 호스트 백업이 있으면 지금 한 번 돌린다: sudo systemctl start platform-k3s-datastore-backup.service.

창 안에서

  1. PriorityClass가 먼저 있어야 한다. kubectl get priorityclass platform-critical platform-low가 둘 다 나와야 3을 한다. 없으면 kubectl apply -k services/priority-classes. 없는 클래스를 가리키는 파드는 생성이 거절된다.
  2. sudo bash scripts/bootstrap/apply-k3s-restart-bundle.sh --execute — 마지막 줄 K3S RESTART BUNDLE APPLIED.
  3. 받아들인 drift 해소는 각 루트의 기존 적용 스크립트로 한다(Phase 2 Keycloak Operator: scripts/bootstrap/apply-keycloak.sh --execute, 관측 core: services/observability의 적용 절차). 끝나면 live-drift-accepted.txt에서 해당 줄을 지우는 PR을 낸다.
  4. 3은 루트별 기존 적용 경로로 한다: Keycloak Operator·CR scripts/bootstrap/apply-keycloak.sh --execute, Gitea scripts/bootstrap/apply-gitea-oidc.sh --execute, Loki·Tempo는 관측 core 적용 절차. 4는 W1 문서를 따른다.
  5. 각 단계 뒤에 after-reboot-checks.md 4~7을 돈다. 하나라도 실패하면 다음 단계로 가지 않는다.

창 뒤에

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이어야 한다.