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

5.7 KiB

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 기준이다:

    cd /home/donghyeon/workspace/platform && git pull --ff-only
    
  • 이 checkout에 scripts/validate/live-drift-check.sh(PR #4)가 있어야 한다.

0. 고르기

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. 창을 잡는다

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. 지금 상태를 남긴다

systemctl cat platform-k3s-datastore-backup.service >/dev/null 2>&1 && echo host-backup-installed

host-backup-installed가 나오면:

sudo systemctl start platform-k3s-datastore-backup.service
journalctl -u platform-k3s-datastore-backup -n 3 --no-pager        # 끝에 uploaded

안 나오면(호스트 백업 설치 전) 같은 형식의 사본을 손으로 만든다. k3s-datastore-restore.md가 이 형식을 읽는다.

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와 차이가 없는지 본다. 업그레이드 뒤의 차이를 업그레이드 탓으로 볼 수 있게 하려는 것이다.

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로 센다.

지금 바이너리를 남긴다(되돌리기에 쓴다):

sudo cp -a /usr/local/bin/k3s "/usr/local/bin/k3s.$OLD"

3. 올린다

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. 확인

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 안이면 남겨 둔 바이너리로 돌아간다.

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 복원이다.