Files
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

6.6 KiB

재부팅·k3s 재시작 뒤 확인 순서

desktop을 재부팅했거나 k3s를 재시작한 뒤 위에서부터 차례로 본다. 앞 단계가 틀리면 뒤 단계는 보지 않고 그 단계를 고친다. 2026-11-11 사고(시계 +9시간 → 인증서 무효 → 502, Prometheus 수집 정지)가 이 순서를 만든 이유다.

1 시계 → 2 k3s·인증서 → 3 노드 → 4 파드(의존 순서) → 5 공개 경로 → 6 Prometheus 수집 → 7 경보 → 8 CI runner·호스트 타이머
  • 확인 명령은 모두 읽기만 한다. 고치는 명령은 「고치기」 표시를 붙였다.
  • desktop에서 일반 사용자 donghyeon으로 돈다. 이 사용자는 adm(journal 읽기)·docker 그룹에 있어야 하고 ~/.kube/config가 있어야 한다.
  • 한 셸에서 위에서부터 이어서 돈다(6단계의 $P를 7단계가 다시 정한다).

1. 시계

date -u
timedatectl | grep -E 'Universal time|synchronized|RTC in local TZ'
systemctl is-enabled systemd-time-wait-sync.service
systemctl show k3s -p After | tr ' ' '\n' | grep -E 'time-sync|network-online'
journalctl -b -o short-monotonic -u systemd-time-wait-sync -u k3s --no-pager | head -5
  • System clock synchronized: yes, RTC in local TZ: no.
  • W1의 시간 동기화 drop-in(infrastructure/host/README.md 2단계)을 깐 뒤: enabled, After에 time-sync.target, monotonic 시각으로 time-wait-sync 줄이 k3s 시작 줄보다 앞.
  • 깔기 전: disabled이고 time-wait-sync 줄이 없다. 그때는 시계만 본다.
  • 부팅 때 시계가 틀렸으면 journal의 벽시계 시각은 믿을 수 없다(미래로 찍힌다). 그래서 순서는 short-monotonic으로 본다.

고치기 — 시계가 틀렸으면 동기화를 켜고 맞춘 뒤 k3s를 재시작한다(k3s가 틀린 시각으로 인증서를 만들기 때문이다).

sudo timedatectl set-ntp true
timedatectl timesync-status | grep -E 'Server|Offset'
sudo systemctl restart k3s

2. k3s와 인증서

date -u
systemctl is-active k3s
for p in 6443 10250; do echo | openssl s_client -connect 127.0.0.1:$p 2>/dev/null | openssl x509 -noout -startdate -enddate; done
kubectl get --raw /readyz; echo
  • active, 두 인증서 모두 notBefore가 맨 위 date -u보다 과거, 마지막 줄 ok.
  • notBefore가 미래면 1로 돌아간다.

3. 노드

kubectl get nodes -o wide
kubectl describe node | sed -n '/Conditions:/,/Addresses:/p'

Ready, MemoryPressure·DiskPressure·PIDPressure 모두 False.

4. 파드 (의존 순서대로)

재시작 직후에는 의존 순서 때문에 몇 번 재시작이 난다(Keycloak은 Postgres 전, tech-log는 Keycloak 전). 1~2분 기다린 뒤 본다.

kubectl -n platform-data get cluster platform-postgres -o jsonpath='{.status.phase}{"\n"}'
kubectl -n object-storage get pods
kubectl -n keycloak get keycloak keycloak -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
kubectl -n gitea get pods
kubectl -n hyeonworks-prod get pods
kubectl get pods -A --no-headers | awk '{split($3, r, "/")} $4 != "Completed" && ($4 != "Running" || r[1] != r[2])'
  • Postgres Cluster in healthy state, Keycloak True, 나머지 Running이고 READY가 n/n.
  • 마지막 명령은 아무것도 안 나와야 한다. Running인데 0/1인 파드도 여기서 나온다.

고치기 — DaemonSet 파드가 0/1로 멈춰 있으면(시계가 튀었을 때 생긴다) 그 파드를 지운다. DaemonSet이 다시 만든다.

kubectl -n <namespace> delete pod <name>

5. 공개 경로

for u in https://git.learn.hyeonworks.com/api/healthz \
         https://id.learn.hyeonworks.com/realms/hyeonworks/.well-known/openid-configuration \
         https://hyeonworks.com/ https://hyeonworks.com/api/healthcheck \
         https://grafana.learn.hyeonworks.com/api/health; do
  printf '%s %s\n' "$(curl -s -o /dev/null -m 15 -w '%{http_code}' "$u")" "$u"
done
  • 모두 200.
  • 502: 2(인증서)와 Traefik(kubectl -n kube-system get pods -l app.kubernetes.io/name=traefik)을 본다.
  • 000(연결 실패): desktop에서 *.learn.hyeonworks.com은 사설 DNS가 Tailscale IP로 돌려주고 Host Nginx가 받는다. getent hosts git.learn.hyeonworks.com, systemctl is-active nginx hyeonworks-dnsmasq-tailscale를 본다.

6. Prometheus 수집

P=$(kubectl -n observability get pod -l app.kubernetes.io/name=prometheus -o name | head -1)
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'count(up == 1)'
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'count(up == 0)'
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'rate(prometheus_tsdb_out_of_bound_samples_total[5m])'
  • up == 0이 비어 있고, out-of-bound 비율이 0이어야 한다.
  • 0이 아니면 시계가 튄 동안 미래 시각 샘플이 들어간 것이다. outOfOrderTimeWindow(10h, PR #2)가 있으면 스스로 풀린다.

7. 경보

P=$(kubectl -n observability get pod -l app.kubernetes.io/name=prometheus -o name | head -1)
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'ALERTS{alertstate="firing"}'
  • 비어 있거나 InfoInhibitor만 있으면 정상이다(InfoInhibitor는 info 경보가 있을 때만 뜬다).
  • 알고 있는 경보: 호스트 백업을 설치했지만 node-exporter textfile 수집기가 아직 없으면 PlatformHostBackupMetricsAbsent가 하루 뒤부터 뜬다.
  • 그 밖의 경보, 특히 critical은 원인을 먼저 본다.

8. CI runner와 호스트 타이머

docker ps --format '{{.Names}} {{.Status}}'
for c in $(docker ps --format '{{.Names}}'); do printf '%s ' "$c"; docker inspect -f '{{.State.Status}} restarts={{.RestartCount}} started={{.State.StartedAt}}' "$c"; done
systemctl list-timers 'platform-*' --no-pager
  • runner(gitea-runner)가 running restarts=0이어야 한다.
  • Up Less than a second로 보여도 restarts=0이고 started가 미래 시각이면 크래시가 아니다. 부팅 때 시계가 +9시간이던 동안 시작된 컨테이너라 Docker가 시작 시각을 미래로 적은 것이다(2026-11-11에 실제로 있었다).
  • 다른 컨테이너: workmachine은 소유자의 작업용 컨테이너, *cloudflared는 Cloudflare 터널이다. 둘 다 이 저장소 밖이라 여기서는 떠 있는지만 본다.
  • 호스트 타이머(services/platform-host-checks/README.md)를 설치하기 전에는 0 timers listed가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다.