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.
6.6 KiB
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.md2단계)을 깐 뒤: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, KeycloakTrue, 나머지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가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다.