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