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.
128 lines
5.7 KiB
Markdown
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 복원이다.
|