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.
133 lines
6.6 KiB
Markdown
133 lines
6.6 KiB
Markdown
# 재부팅·k3s 재시작 뒤 확인 순서
|
|
|
|
desktop을 재부팅했거나 k3s를 재시작한 뒤 위에서부터 차례로 본다. 앞 단계가 틀리면 뒤 단계는 보지 않고 그 단계를 고친다.
|
|
2026-11-11 사고(시계 +9시간 → 인증서 무효 → 502, Prometheus 수집 정지)가 이 순서를 만든 이유다.
|
|
|
|
```text
|
|
1 시계 → 2 k3s·인증서 → 3 노드 → 4 파드(의존 순서) → 5 공개 경로 → 6 Prometheus 수집 → 7 경보 → 8 CI runner·호스트 타이머
|
|
```
|
|
|
|
- 확인 명령은 모두 읽기만 한다. 고치는 명령은 **「고치기」** 표시를 붙였다.
|
|
- desktop에서 일반 사용자 `donghyeon`으로 돈다. 이 사용자는 `adm`(journal 읽기)·`docker` 그룹에 있어야 하고 `~/.kube/config`가 있어야 한다.
|
|
- 한 셸에서 위에서부터 이어서 돈다(6단계의 `$P`를 7단계가 다시 정한다).
|
|
|
|
## 1. 시계
|
|
|
|
```bash
|
|
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가 틀린 시각으로 인증서를 만들기 때문이다).
|
|
|
|
```bash
|
|
sudo timedatectl set-ntp true
|
|
timedatectl timesync-status | grep -E 'Server|Offset'
|
|
sudo systemctl restart k3s
|
|
```
|
|
|
|
## 2. k3s와 인증서
|
|
|
|
```bash
|
|
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. 노드
|
|
|
|
```bash
|
|
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분 기다린 뒤 본다.
|
|
|
|
```bash
|
|
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이 다시 만든다.
|
|
|
|
```bash
|
|
kubectl -n <namespace> delete pod <name>
|
|
```
|
|
|
|
## 5. 공개 경로
|
|
|
|
```bash
|
|
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 수집
|
|
|
|
```bash
|
|
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. 경보
|
|
|
|
```bash
|
|
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와 호스트 타이머
|
|
|
|
```bash
|
|
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`가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다.
|