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

128 lines
5.7 KiB
Markdown

# k3s 업그레이드 (같은 minor 안의 패치)
예: v1.36.2+k3s1 → v1.36.6+k3s1. minor를 올리는 것(1.36 → 1.37)은 이 문서 끝의 「minor」를 먼저 읽는다.
근거: docs.k3s.io upgrades/manual(minor 건너뛰기 금지), Kubernetes version skew policy.
## 전제
- desktop, 사용자 `donghyeon`. 모든 상대경로는 이 checkout 기준이다:
```bash
cd /home/donghyeon/workspace/platform && git pull --ff-only
```
- 이 checkout에 `scripts/validate/live-drift-check.sh`(PR #4)가 있어야 한다.
## 0. 고르기
```bash
curl -s https://update.k3s.io/v1-release/channels | python3 -c 'import json,sys; [print(c["name"], c.get("latest")) for c in json.load(sys.stdin)["data"] if c["name"] in ("stable","v1.36","v1.37")]'
k3s --version | head -1
```
- **패치는 지금 minor의 채널(`v1.36`)의 latest를 쓴다.** `stable`은 다른 minor를 가리킬 수 있다(2026-11-12: stable = v1.37.2).
- GitHub 릴리스 노트에서 Traefik chart, containerd, 보안 수정 항목을 본다.
- **Traefik chart나 이미지가 바뀌는지 본다.** `infrastructure/networking/traefik/scripts/common.sh`의
`EXPECTED_K3S_CHART`·`EXPECTED_TRAEFIK_IMAGE`가 지금 값에 고정돼 있어, 바뀌면 Traefik 스크립트가 멈춘다(의도된 멈춤).
아래에서 `NEW=<0단계에서 고른 버전>`, `OLD=<지금 버전>`으로 둔다(예: `NEW=v1.36.6+k3s1`, `OLD=v1.36.2+k3s1`).
## 1. 창을 잡는다
```bash
docker exec gitea-runner docker ps -q | wc -l # CI job 컨테이너 수. 0이어야 한다
flock -n /tmp/claude-gates/heavy.lock true && echo lock-free # 에이전트 세션의 무거운 빌드·시험이 잡는 lock. lock-free여야 한다
```
재시작 중 API가 1~2분 멈춘다. 컨테이너는 계속 돈다(`KillMode=process`).
## 2. 지금 상태를 남긴다
```bash
systemctl cat platform-k3s-datastore-backup.service >/dev/null 2>&1 && echo host-backup-installed
```
`host-backup-installed`가 나오면:
```bash
sudo systemctl start platform-k3s-datastore-backup.service
journalctl -u platform-k3s-datastore-backup -n 3 --no-pager # 끝에 uploaded
```
안 나오면(호스트 백업 설치 전) 같은 형식의 사본을 손으로 만든다. `k3s-datastore-restore.md`가 이 형식을 읽는다.
```bash
sudo bash -c 'set -e; TS=$(date -u +%Y%m%dT%H%M%SZ); D=/var/backups/k3s-datastore-$TS; install -d -m 0700 $D
sqlite3 /var/lib/rancher/k3s/server/db/state.db ".backup $D/state.db"
install -m 0600 /var/lib/rancher/k3s/server/token $D/token
printf "created=%s\nk3s_version=%s\n" $TS "$(/usr/local/bin/k3s --version | head -1)" > $D/META
tar -C /var/backups -czf $D.tar.gz k3s-datastore-$TS && sha256sum $D.tar.gz | awk "{print \$1}" > $D.tar.gz.sha256
rm -rf $D; ls -l $D.tar.gz*'
```
그리고 repo와 차이가 없는지 본다. 업그레이드 뒤의 차이를 업그레이드 탓으로 볼 수 있게 하려는 것이다.
```bash
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`이어야 한다. `live-drift-accepted.txt` 항목은 기한(지금 2026-11-30)이 지나면 다시 drift로 센다.
지금 바이너리를 남긴다(되돌리기에 쓴다):
```bash
sudo cp -a /usr/local/bin/k3s "/usr/local/bin/k3s.$OLD"
```
## 3. 올린다
```bash
curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION="$NEW" INSTALL_K3S_EXEC='server --disable=servicelb' sh -
until kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready
```
- `INSTALL_K3S_EXEC`는 지금 unit과 같아야 한다(`systemctl cat k3s`의 ExecStart: `server --disable=servicelb`).
설치 스크립트가 `/etc/systemd/system/k3s.service`를 다시 쓰고 k3s를 재시작한다. `k3s.service.d/` drop-in과
`/etc/rancher/k3s/config.yaml.d/`는 그대로 남는다.
## 4. 확인
```bash
k3s --version | head -1
kubectl get nodes -o wide
kubectl -n kube-system get pods
kubectl -n kube-system get helmchart traefik -o jsonpath='{.spec.chart}{"\n"}'
kubectl -n kube-system get deploy traefik -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
```
그다음 `after-reboot-checks.md` 2~8을 돌고, 2단계의 drift 검사를 다시 돌려 `SUMMARY drift=0`인지 본다(이 검사가 live Traefik
HelmChartConfig를 trust overlay와 비교한다).
Traefik chart·이미지가 바뀌었으면:
1. `infrastructure/networking/traefik/scripts/common.sh`의 두 값과 `infrastructure/networking/traefik/README.md`
「현재 live 상태」 표를 새 값으로 고치는 PR을 낸다.
2. `bash infrastructure/networking/traefik/scripts/validate.sh`(정적 렌더 검사).
`scripts/validate/render-phase1.sh`와 `scripts/validate/render-phase2.sh`의 `TARGET_KUBERNETES_VERSION`(지금 `1.36.2`)도 새 버전으로 고친다.
## 되돌리기
같은 minor 안이면 남겨 둔 바이너리로 돌아간다.
```bash
sudo install -m 0755 "/usr/local/bin/k3s.$OLD" /usr/local/bin/k3s
sudo systemctl restart k3s
until kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready
```
API가 뜨지 않거나 datastore 오류가 나면 2단계의 사본으로 `k3s-datastore-restore.md`를 따른다
(호스트 백업 설치 전에 만든 손 사본은 `/var/backups/k3s-datastore-*.tar.gz`에 있다).
## minor
- 한 번에 한 minor만 올린다(1.36 → 1.37 → 1.38). 건너뛰지 않는다.
- 릴리스 노트의 deprecation·제거 API를 본다. `kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis`로 지금 쓰는 deprecated API를 본다.
- CNPG·Keycloak·AIStor·kube-prometheus-stack이 새 Kubernetes 버전을 지원하는지 각 문서에서 확인한다.
- k3s는 minor 다운그레이드를 공식 지원하지 않는다. 되돌리기는 datastore 복원이다.