From 96623200fa437c4cb3a2031661d485e6c0b3f230 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 01:38:58 +0900 Subject: [PATCH 1/4] feat(host): keep the k3s nodeport-loopback drop-in in the repository /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml keeps Traefik's NodePorts on 127.0.0.0/8 so the LAN cannot bypass Host Nginx. The Traefik README and validator depend on it, but the file itself was only on the host, so a rebuilt host would not get it. Add the live content as is (kube-proxy-arg nodeport-addresses). The host-rebuild and datastore-restore runbooks install it. Risk: none; nothing installs it automatically. Verification: the file is byte-for-byte the live drop-in (ssh desktop cat ...); 40-secrets-encryption.yaml in the repository already matches the host. --- infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml diff --git a/infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml b/infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml new file mode 100644 index 0000000..453264d --- /dev/null +++ b/infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml @@ -0,0 +1,2 @@ +kube-proxy-arg: + - "nodeport-addresses=127.0.0.0/8" From 819f3f14f1dba8f806c1aa1c6b330118e2e528fd Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 01:38:58 +0900 Subject: [PATCH 2/4] 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. --- docs/README.md | 4 +- docs/runbooks/after-reboot-checks.md | 132 ++++++++++++++++++++ docs/runbooks/gitea-restore.md | 154 +++++++++++++++++++++++ docs/runbooks/host-rebuild.md | 164 +++++++++++++++++++++++++ docs/runbooks/k3s-datastore-restore.md | 154 +++++++++++++++++++++++ docs/runbooks/k3s-restart-window.md | 38 ++++++ docs/runbooks/k3s-upgrade.md | 127 +++++++++++++++++++ 7 files changed, 772 insertions(+), 1 deletion(-) create mode 100644 docs/runbooks/after-reboot-checks.md create mode 100644 docs/runbooks/gitea-restore.md create mode 100644 docs/runbooks/host-rebuild.md create mode 100644 docs/runbooks/k3s-datastore-restore.md create mode 100644 docs/runbooks/k3s-restart-window.md create mode 100644 docs/runbooks/k3s-upgrade.md diff --git a/docs/README.md b/docs/README.md index 2ff8975..f26eae3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,8 @@ | 폴더 | 담는 것 | 수명 | |---|---|---| +| [`runbooks/`](runbooks/) | 운영 절차(복원, 재구축, 업그레이드, 재부팅 뒤 확인, 재시작 창) | 살아 있음 | +| [`design/`](design/) | 설계서(결정 전·후) | 기록(상태가 있다) | | [`reviews/`](reviews/) | 점검·리뷰 결과 | 기록(쓴 날의 상태) | | [`platform/plans/`](platform/plans/) | 설계 메모 | 기록 | | [`superpowers/plans/`](superpowers/plans/) | 실행 계획 | 기록 | @@ -15,7 +17,7 @@ ## 기록 문서의 머리 블록 -`reviews/`에 새로 쓰는 기록은 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다. +`reviews/`·`design/`에 새로 쓰는 기록은 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다. 형식과 상태 어휘는 design-docs `conventions/docs-system.md` 4절이 정본이다. 리뷰의 상태는 「진행 중」·「닫힘」 둘이다. 이 절을 만들기 전에 쓴 `platform/plans/`· `superpowers/plans/` 문서에는 머리 블록이 없다. diff --git a/docs/runbooks/after-reboot-checks.md b/docs/runbooks/after-reboot-checks.md new file mode 100644 index 0000000..a3722ff --- /dev/null +++ b/docs/runbooks/after-reboot-checks.md @@ -0,0 +1,132 @@ +# 재부팅·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 delete pod +``` + +## 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`가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다. diff --git a/docs/runbooks/gitea-restore.md b/docs/runbooks/gitea-restore.md new file mode 100644 index 0000000..1dfacf0 --- /dev/null +++ b/docs/runbooks/gitea-restore.md @@ -0,0 +1,154 @@ +# Gitea 복원 + +Gitea의 파일(저장소, 패키지, 첨부, Actions 산출물, `app.ini`)을 주간 dump에서 되살리는 절차다. +Gitea DB는 dump에 없다(`--skip-db`). DB는 CNPG 백업에 있다. + +## 전제와 확인 — 하나라도 아니면 이 문서는 아직 못 쓴다 + +| 전제 | 확인 | +| --- | --- | +| platform-core checkout이 최신 main이고 호스트 백업(PR #6)이 들어 있다 | `cd /home/donghyeon/workspace/platform && git pull --ff-only && ls scripts/validate/gitea-backup-restore-drill.sh` | +| 호스트 백업이 설치됐다(`/usr/local/lib/platform-backup`, `/etc/platform-backup/aistor.env`) | `sudo ls /usr/local/lib/platform-backup/lib/host-backup.sh /etc/platform-backup/aistor.env` | +| Gitea dump가 하나 이상 있다 | `systemctl list-timers platform-gitea-backup.timer --no-pager`와 `journalctl -u platform-gitea-backup -n 3 --no-pager`의 `uploaded` | +| DB까지 되살릴 때: CNPG 백업이 있다(W1, `services/platform-postgres-backup`) | `kubectl -n platform-data get backup` | +| k3s·AIStor가 정상 | `after-reboot-checks.md` 2~4 | + +2026-11-12 현재는 호스트 백업(PR #6)과 CNPG 백업(W1)이 설치되기 전이라 되살릴 백업이 없다. + +## 어느 경우인가 + +| 경우 | DB | 이 문서 | +| --- | --- | --- | +| A. Gitea PV만 잃었다(DB는 멀쩡) | 그대로 둔다 | 1~6 | +| B. DB도 잃었다(루트 SSD 전체 등) | CNPG로 먼저 되살린다 | 0 → 1~6 | + +**B의 경고**: platform-postgres 하나에 Gitea·Keycloak·tech-log DB가 같이 있다. CNPG를 어떤 시점으로 되돌리면 세 DB가 모두 +그 시점으로 간다. dump 시각(일요일 04:00 KST)에 맞추려고 과거로 PITR하면 Keycloak 사용자 변경과 tech-log 글도 그 시각으로 돌아간다. +그래서 B에서도 DB는 **가장 최근 시점**으로 되살리고, dump 뒤에 만든 저장소는 파일이 없다는 것을 받아들인다(6단계에서 찾아낸다). + +## 0. (B만) DB를 되살린다 + +W1의 CNPG 백업 문서를 따른다. 끝나면 `kubectl -n platform-data get cluster platform-postgres -o jsonpath='{.status.phase}'`가 +`Cluster in healthy state`여야 한다. + +## 1. dump를 내려받고 확인한다 + +```bash +sudo -i +``` + +```bash +TS=$(date +%Y%m%d%H%M) +. /usr/local/lib/platform-backup/lib/host-backup.sh && hb_load_aistor_env +W=$(mktemp -d /var/lib/platform-backup/work/gitea-restore.XXXXXX) +hb_mc "$W" ls "backup/$AISTOR_BUCKET/gitea/" +D=$(hb_mc "$W" ls "backup/$AISTOR_BUCKET/gitea/" | awk '{print $NF}' | grep -E '^gitea-dump-.*\.tar\.gz$' | sort | tail -1); echo "$D" +hb_mc "$W" cp "backup/$AISTOR_BUCKET/gitea/$D" "backup/$AISTOR_BUCKET/gitea/$D.sha256" "backup/$AISTOR_BUCKET/gitea/$D.meta" /work/ +[ "$(sha256sum "$W/$D" | awk '{print $1}')" = "$(cat "$W/$D.sha256")" ] && echo checksum-ok +cat "$W/$D.meta" +bash /home/donghyeon/workspace/platform/scripts/validate/gitea-backup-restore-drill.sh --from-file "$W/$D" +``` + +- `hb_mc <폴더> `는 고정된 AIStor client를 그 폴더를 `/work`로 붙여 돌린다. +- `checksum-ok`, 그리고 리허설 끝의 `repositories in dump: N, fsck failures: 0`과 `GITEA RESTORE DRILL PASS`. +- `.meta`의 `gitea_image`가 지금 Deployment 이미지와 같아야 한다: + `kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}'`. 다르면 먼저 Gitea를 그 버전으로 맞춘다 + (dump를 만든 버전보다 낮은 Gitea로 올리면 DB·파일 형식이 안 맞을 수 있다). + +## 2. 창을 잡고 Gitea를 멈춘다 + +```bash +docker exec gitea-runner docker ps -q | wc -l # 0이어야 한다(CI job 없음) +curl -s -o /dev/null -D - 'https://git.learn.hyeonworks.com/api/v1/repos/search?limit=1' | grep -i '^x-total-count' # 복원 전 공개 저장소 수를 적어 둔다 +kubectl -n gitea scale deploy/gitea --replicas=0 +kubectl -n gitea wait --for=delete pod -l app.kubernetes.io/name=gitea --timeout=5m +``` + +이때부터 git.learn.hyeonworks.com이 내려간다(CI 포함). + +## 3. 지금 PV를 복사해 둔다 (덮어쓰기 전에) + +```bash +df -h /srv/k3s/ssd # Gitea 데이터는 2026-11 기준 약 370MB +cp -a /srv/k3s/ssd/gitea /srv/k3s/ssd/gitea.before-restore-$TS +``` + +PV를 완전히 잃은 경우(빈 폴더)는 건너뛴다. + +## 4. 임시 파드로 PV에 푼다 + +dump 안의 경로와 PV(`/data`) 경로: + +| dump | PV | +| --- | --- | +| `app.ini` | `/data/gitea/conf/app.ini` | +| `data/*` | `/data/*` (actions_artifacts, actions_log, packages, attachments, avatars …) | +| `repos/*` | `/data/git/gitea-repositories/*` | +| `custom/*` | `/data/gitea/*` (있을 때만) | + +```bash +IMAGE=$(kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}') +kubectl -n gitea run gitea-restore --image="$IMAGE" --restart=Never --overrides='{ + "spec": { + "securityContext": {"runAsUser": 1000, "runAsGroup": 1000, "fsGroup": 1000, "runAsNonRoot": true, + "seccompProfile": {"type": "RuntimeDefault"}}, + "containers": [{"name": "restore", "image": "'"$IMAGE"'", "command": ["sleep", "3600"], + "securityContext": {"allowPrivilegeEscalation": false, "capabilities": {"drop": ["ALL"]}}, + "volumeMounts": [{"name": "data", "mountPath": "/data"}]}], + "volumes": [{"name": "data", "persistentVolumeClaim": {"claimName": "gitea-data"}}]}}' +kubectl -n gitea wait --for=condition=Ready pod/gitea-restore --timeout=2m +kubectl -n gitea cp "$W/$D" gitea-restore:/data/restore.tar.gz +kubectl -n gitea exec gitea-restore -- sh -ec ' + cd /data && rm -rf restore && mkdir restore && tar -C restore -xzf restore.tar.gz + mkdir -p /data/gitea/conf /data/git/gitea-repositories + [ -f /data/gitea/conf/app.ini ] && cp /data/gitea/conf/app.ini /data/gitea/conf/app.ini.before-restore || true + cp restore/app.ini /data/gitea/conf/app.ini + cp -a restore/data/. /data/ + cp -a restore/repos/. /data/git/gitea-repositories/ + [ -d restore/custom ] && cp -a restore/custom/. /data/gitea/ || true + rm -rf restore restore.tar.gz + find /data/git/gitea-repositories -mindepth 2 -maxdepth 2 -name "*.git" -type d | wc -l' +kubectl -n gitea delete pod gitea-restore +``` + +- 마지막 숫자가 1단계 리허설의 `N`과 같아야 한다. +- PV에 옛 파일이 남아 있는 경우(A에서 일부만 잃음) `cp -a`는 덮어쓰고 지우지는 않는다. dump에 없는 옛 저장소를 남기고 싶지 + 않으면 `tar` 줄 앞에 `rm -rf /data/git/gitea-repositories/* /data/packages/*`를 넣는다(3의 사본이 있을 때만). + +## 5. Gitea를 다시 띄운다 + +```bash +kubectl -n gitea scale deploy/gitea --replicas=1 +kubectl -n gitea rollout status deploy/gitea --timeout=10m +kubectl -n gitea exec deploy/gitea -c gitea -- gitea admin regenerate hooks +kubectl -n gitea exec deploy/gitea -c gitea -- gitea doctor check --all 2>&1 | tail -20 +``` + +chart의 init 컨테이너가 시작할 때 Secret 값으로 `app.ini`를 다시 맞춘다. dump의 `app.ini`에서 오는 것은 Secret에 없는 생성 값 +(`INTERNAL_TOKEN`, `SECRET_KEY`, JWT 키)이다. 이것이 맞아야 2FA·토큰이 계속 쓰인다. + +## 6. 확인 + +```bash +curl -fsS -o /dev/null -w '%{http_code}\n' https://git.learn.hyeonworks.com/api/healthz +curl -s -o /dev/null -D - 'https://git.learn.hyeonworks.com/api/v1/repos/search?limit=1' | grep -i '^x-total-count' +git ls-remote https://git.learn.hyeonworks.com/donghyeon.kang/platform-core.git HEAD +kubectl -n gitea exec deploy/gitea -c gitea -- gitea doctor check --run check-db-consistency 2>&1 | tail -5 +``` + +- `200`, 2단계에서 적어 둔 공개 저장소 수와 같은 수, `HEAD` 해시. +- 웹에서 로그인(Keycloak OIDC), 패키지 화면의 `grpc-library`·`messaging-library`(1.0.0, `dev.cakit.*`), Actions 기록을 한 번씩 본다. +- DB에는 있는데 파일이 없는 저장소(dump 뒤에 만든 것)는 웹에서 열면 오류가 난다. 노트북 clone에서 다시 push한다. +- runner가 다시 붙었는지 본다(`infrastructure/ci/gitea-runner/README.md`). + +## 되돌리기 + +- 4 도중 실패: Gitea를 0으로 둔 채 임시 파드를 다시 띄워 `cp /data/gitea/conf/app.ini.before-restore /data/gitea/conf/app.ini` + (4의 `kubectl run` 명령, `exec` 부분만 바꿔서). +- 4를 끝낸 뒤: Gitea를 0으로 줄이고 `rm -rf /srv/k3s/ssd/gitea && mv /srv/k3s/ssd/gitea.before-restore-$TS /srv/k3s/ssd/gitea` 후 1로. + +## 끝나면 + +```bash +rm -rf "$W" # 하루 지켜본 뒤: rm -rf /srv/k3s/ssd/gitea.before-restore-$TS +``` diff --git a/docs/runbooks/host-rebuild.md b/docs/runbooks/host-rebuild.md new file mode 100644 index 0000000..b8ec1fb --- /dev/null +++ b/docs/runbooks/host-rebuild.md @@ -0,0 +1,164 @@ +# 호스트 재구축 (루트 SSD를 잃었을 때) + +desktop의 루트 SSD를 잃고 HDD(WDC 2TB, AIStor 파티션 라벨 `AISTOR_DATA`)는 살아 있을 때, 새 SSD에서 플랫폼을 되살리는 순서다. +각 단계의 자세한 명령은 링크한 문서를 따른다. 이 문서는 **순서와 빠지기 쉬운 것**을 정한다. + +## 전제와 확인 — 하나라도 아니면 4·7·8단계에서 멈춘다 + +| 전제 | 확인 | +| --- | --- | +| HDD의 k3s datastore 로컬 사본이 있다(PR #6 호스트 백업이 설치돼 돌았다) | 2단계 mount 뒤 `sudo ls /srv/k3s/aistor/host-backups/k3s-datastore/` | +| CNPG 백업이 AIStor에 있다(W1) | 6단계 뒤 AIStor `platform-postgres-backups` bucket | +| Gitea dump가 AIStor에 있다(PR #6) | 6단계 뒤 AIStor `platform-host-backups/gitea/` | + +2026-11-12 현재는 세 백업 모두 설치되기 전이다. 그 전에는 datastore 대신 이 저장소의 bootstrap 절차(`bootstrap/manual/phase1~4`)로 +처음부터 다시 세워야 하고, Secret은 소유자가 새로 넣어야 한다. + +## 무엇이 남고 무엇을 잃나 + +| 남음 (HDD, xfs `AISTOR_DATA`) | 잃음 (루트 SSD) | +| --- | --- | +| AIStor 데이터(`/srv/k3s/aistor/data`): Loki·Tempo, CNPG 백업, Gitea dump | OS, k3s, Docker(`/var/lib/docker`: runner, `workmachine`, `*cloudflared` 컨테이너), 모든 SSD Local PV | +| k3s datastore 로컬 사본(`/srv/k3s/aistor/host-backups/k3s-datastore/`) | `/etc`(nginx, certbot 인증서, dnsmasq, `/etc/platform-backup`), `~/.secrets` | +| | `/etc/rancher/k3s/platform-post-bundle.env`, `platform-restore-evidence.env`(2026-08 Secret 암호화 hardening의 증거 표시. 운영에는 필요 없고, `bootstrap/manual/k3s-secret-encryption.md` 검사기가 「증거 없음」으로 볼 뿐이다) | + +desktop 전체를 잃으면 HDD도 잃는다. 그때는 off-host 사본이 있어야 한다(`services/platform-host-checks/README.md`). + +## 시작 전에 소유자가 따로 가지고 있어야 하는 것 + +k3s datastore를 복원하면 쿠버네티스 Secret은 모두 돌아온다. 아래는 그 밖의 것이다. + +- platform-core 저장소 사본(Gitea가 내려가 있으므로 노트북 clone이나 off-host 사본). 이 문서는 desktop의 + `/home/donghyeon/workspace/platform`에 clone했다고 보고, 모든 상대경로는 거기 기준이다. +- Tailscale 계정(사설 DNS가 Tailscale 주소를 쓴다), Cloudflare API token(certbot DNS 인증), certbot 연락 email +- Slack webhook 복구 경로(KeePass, `scripts/bootstrap/backup-slack-webhook-recovery.sh`) +- off-host 백업을 쓴다면 그 개인 키 +- hyeonworks.com 앞단 설정과 tech-log 이미지·매니페스트: **이 저장소에 없다.** tech-log-backend·tech-log-frontend 저장소를 따른다. +- `workmachine`과 `*cloudflared` 컨테이너: 소유자의 별도 설정이다. 이 저장소에 재구축 절차가 없다. + +## 순서 + +```text +1 OS·이름·도구·시계 → 2 HDD mount → 3 k3s 설치(시작 안 함) + 시간 동기화 drop-in → 4 datastore 복원(첫 시작) + → 5 Local PV 폴더 → 6 AIStor 확인 → 7 Postgres 복원(CNPG) → 8 호스트 백업 다시 설치 → 9 Gitea 파일 복원 + → 10 호스트 설정(Tailscale·DNS·nginx·TLS·Docker·runner·재시작 묶음) → 11 확인(Gitea 확인 포함) +``` + +### 1. OS, 호스트 이름, 도구, 시계 + +- Ubuntu 24.04, 사용자 `donghyeon`(uid 1000. Gitea rootless와 AIStor 폴더 소유자가 1000이다). +- **호스트 이름을 `donghyeon-system-product-name`으로 둔다.** 모든 Local PV의 `nodeAffinity`가 + `kubernetes.io/hostname=donghyeon-system-product-name`을 본다. 이름이 다르면 PV를 쓰는 파드가 전부 Pending이다. + + ```bash + sudo hostnamectl set-hostname donghyeon-system-product-name + ``` + +- 패키지: `git jq ripgrep sqlite3 curl openssl python3-yaml nginx dnsmasq`, snap `certbot`과 `certbot-dns-cloudflare`. + Docker는 공식 apt 저장소로 설치하고 `donghyeon`을 `docker` 그룹에 넣는다. Helm `v3.19.4`를 `~/.local/bin/helm`에 둔다 + (렌더 스크립트가 정확한 버전을 요구한다). +- 시계: `sudo timedatectl set-local-rtc 0`, `sudo timedatectl set-ntp true`. Windows 쪽 `RealTimeIsUniversal`은 W1 + `infrastructure/host/README.md` 3단계(W1 PR). + +### 2. HDD mount + +새 SSD를 달면 디스크 이름(sda·sdb·sdc)이 바뀔 수 있다. 이름이 아니라 라벨로 찾는다. + +```bash +lsblk -o NAME,SIZE,FSTYPE,LABEL,MODEL # LABEL=AISTOR_DATA, xfs, WDC 2TB 쪽 +echo 'LABEL=AISTOR_DATA /srv/k3s/aistor xfs defaults,noatime 0 2' | sudo tee -a /etc/fstab # 2026-11-12 live fstab과 같은 줄 +sudo findmnt --verify # 오류가 없어야 한다. 있으면 fstab 줄을 고치고 다시 본다(틀린 fstab은 다음 부팅을 emergency mode로 보낸다) +sudo mkdir -p /srv/k3s/aistor && sudo mount /srv/k3s/aistor +ls /srv/k3s/aistor # data host-backups +``` + +### 3. k3s 설치 (시작하지 않은 채로) + 시간 동기화 drop-in + +먼저 HDD의 백업에서 버전을 본다(`k3s-datastore-restore.md` 1단계: `cat "$D/META"`의 `k3s_version`). 아래 ``에 넣는다. + +```bash +curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION='' INSTALL_K3S_SKIP_START=true \ + INSTALL_K3S_EXEC='server --disable=servicelb' sh - +cd /home/donghyeon/workspace/platform +sudo install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml +sudo install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml +``` + +**k3s를 처음 시작하기 전에** W1의 시간 동기화 drop-in을 깐다(`infrastructure/host/README.md` 2단계, W1 PR). 11-11 사고는 +틀린 시계로 k3s가 인증서를 만든 것이었다. 재시작 묶음(PR #5)은 클러스터가 떠 있어야 도는 스크립트라 10단계에서 깐다. + +### 4. datastore 복원 (k3s 첫 시작) + +`k3s-datastore-restore.md` 1·3·4·5단계(2단계는 「새로 설치한 호스트」 경우). 이때 PV 폴더가 없어 Postgres·Gitea 파드는 뜨지 못한다. 정상이다. + +### 5. Local PV 폴더 + +```bash +sudo bash scripts/bootstrap/prepare-ssd-local-paths.sh +sudo bash scripts/bootstrap/prepare-observability-local-paths.sh --execute # 인자 없으면 dry run이다 +sudo install -d -o root -g root -m 0750 /srv/k3s/ssd/pgadmin # 위 둘이 만들지 않는다(apply-admin-services.sh가 만들던 것) +``` + +빈 폴더가 생긴다. 관측 스택(Prometheus·Loki 캐시·Grafana)은 빈 PV로 다시 쌓인다. Grafana 대시보드는 repo의 ConfigMap에서 다시 생긴다. + +### 6. AIStor + +AIStor의 PV는 HDD라 데이터가 그대로다. Secret(라이선스, root 설정)도 datastore에서 돌아왔다. + +```bash +kubectl -n object-storage get pods +kubectl -n object-storage get objectstore -o wide +bash scripts/validate/aistor-s3-smoke.sh --execute # 임시 bucket을 만들고 쓰고 지운다(쓰기 작업) +``` + +`Initialized/green`, 마지막 줄 `AISTOR_S3_SMOKE_PASS bucket-create object-write object-read object-delete bucket-delete`. + +### 7. platform-postgres 복원 + +datastore에는 `Cluster` 정의가 있지만 PV는 비어 있다. CNPG를 AIStor 백업(`platform-postgres-backups`)에서 되살린다. +Gitea·Keycloak·tech-log DB가 모두 여기 있다. + +먼저 원본 정의를 남긴다(되살린 Cluster가 원래와 같은지 비교할 기준이다): + +```bash +kubectl -n platform-data get cluster platform-postgres -o yaml > /root/platform-postgres-cluster-before-rebuild.yaml +``` + +- W1의 `services/platform-postgres-backup/README.md`(W1 PR)에는 임시 Cluster로 하는 「복원 리허설」이 있다. 그 `restore-drill/cluster.yaml`의 + `bootstrap.recovery`를 쓰는 방식이다. +- **운영 Cluster를 백업으로 갈아 끼우는 절차(빈 PV의 `platform-postgres`를 지우고 같은 이름으로 recovery bootstrap)는 아직 문서가 없다(W1 몫).** + 그 문서가 생기기 전에는 리허설 절차를 이름만 `platform-postgres`로 바꿔 따르고, 위에서 남긴 원본과 `pg_hba`(techlog 두 줄 포함)· + Secret 참조·resources가 같은지 비교한다. + +### 8. 호스트 백업 다시 설치 + +`/etc/platform-backup/aistor.env`와 `/usr/local/lib/platform-backup`은 SSD와 함께 잃었다. 9단계(Gitea 복원)가 이것을 쓴다. +`services/platform-host-checks/README.md` 「적용」의 `create-host-backup-credentials.sh`(AIStor에 새 사용자를 하나 더 만든다)와 +`install-host-checks.sh --execute`를 돈다. 첫 실행 백업은 「복원 직후 상태」의 백업이 된다. + +### 9. Gitea 파일 복원 + +`gitea-restore.md`의 경우 B(DB는 7에서 되살렸다), 1~5단계. **6단계 확인 중 https·로그인은 10단계(nginx·TLS·DNS) 뒤로 미룬다.** +그 전에는 `kubectl -n gitea get pods`와 저장소 수만 본다. + +### 10. 호스트 설정 + +| 무엇 | 문서 | +| --- | --- | +| Tailscale 설치·로그인 | 사설 DNS(`infrastructure/networking/private-dns/host/dnsmasq-tailscale.conf`)가 Tailscale 주소 `100.92.240.34`를 고정해 쓴다. 새로 로그인해 주소가 바뀌면 이 파일의 `listen-address`·`address=` 줄을 새 주소로 바꾸는 PR을 낸다 | +| 사설 DNS(dnsmasq LAN·Tailscale) | `infrastructure/networking/private-dns/host/README.md` | +| Host Nginx와 TLS | `infrastructure/networking/host-nginx/README.md`는 전환 기록이라 빈 호스트 설치 절차가 아니다. 이 저장소의 `learn-services*.conf`를 `/etc/nginx/sites-available/`에 두고, 인증서는 `bootstrap/manual/phase3-admin-surfaces.md`의 certbot 절차로 다시 받는다. 빈 호스트용 절차는 아직 없다 | +| Docker daemon.json, runner 상한·정리 | W1 `infrastructure/host/README.md` 4단계, `infrastructure/ci/gitea-runner/README.md` | +| Gitea Actions runner 재등록 | `infrastructure/ci/gitea-runner/README.md` | +| k3s 재시작 묶음(kubelet 예약·audit·PSA) | `infrastructure/host/k3s/README.md`(PR #5) | +| tech-log 운영 이미지 | Gitea 패키지 레지스트리에서 다시 받는다(W1의 레지스트리 전환 뒤). 9단계 dump에 패키지가 들어 있다 | + +### 11. 확인 + +`after-reboot-checks.md`를 처음부터 끝까지 돈다(8단계의 `workmachine`·`*cloudflared`는 이 저장소 밖이라 없을 수 있다). +`gitea-restore.md` 6단계를 마저 한다. 그다음 repo와의 차이를 본다: + +```bash +cd /home/donghyeon/workspace/platform +PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt +``` diff --git a/docs/runbooks/k3s-datastore-restore.md b/docs/runbooks/k3s-datastore-restore.md new file mode 100644 index 0000000..f59a4f8 --- /dev/null +++ b/docs/runbooks/k3s-datastore-restore.md @@ -0,0 +1,154 @@ +# k3s datastore 복원 + +k3s datastore(sqlite)를 백업에서 되살리는 절차다. 쿠버네티스 객체 전부(Deployment, Secret, CNPG Cluster 정의 등)가 여기에 있다. +**PV 안의 데이터(Postgres, Gitea 파일)는 여기에 없다.** 그것은 `gitea-restore.md`와 CNPG 복원으로 따로 되살린다. + +## 전제와 확인 — 하나라도 아니면 이 문서는 아직 못 쓴다 + +| 전제 | 확인 | +| --- | --- | +| platform-core checkout이 최신 main이고 호스트 백업(PR #6)이 들어 있다 | `cd /home/donghyeon/workspace/platform && git pull --ff-only && ls scripts/validate/k3s-datastore-restore-drill.sh` | +| 호스트 백업이 설치돼 백업이 하나 이상 있다(`services/platform-host-checks/README.md`) | `sudo ls -1t /srv/k3s/aistor/host-backups/k3s-datastore/ \| head -3` | +| root 셸 | 아래 `sudo -i`를 **따로 먼저** 친다(블록째 붙이면 비밀번호 줄을 먹는다) | + +2026-11-12 현재 호스트 백업은 PR #6이 설치되기 전이라 백업이 없다. + +## 언제 쓰나 + +| 상황 | 이 문서 | +| --- | --- | +| datastore가 깨져 k3s가 안 뜬다(`journalctl -u k3s`에 sqlite/kine 오류) | 예, 같은 호스트 | +| 루트 SSD를 잃었다 | 예, `host-rebuild.md`의 한 단계로 | +| 객체 몇 개를 실수로 지웠다 | 아니오. repo에서 다시 적용한다(drift 검사로 무엇이 없는지 본다) | + +## 1. 백업을 고르고 확인한다 + +```bash +sudo -i +``` + +```bash +TS=$(date +%Y%m%d%H%M) +cd /srv/k3s/aistor/host-backups/k3s-datastore +B=$(ls -1t k3s-datastore-*.tar.gz | head -1); echo "$B" +[ "$(sha256sum "$B" | awk '{print $1}')" = "$(cat "$B.sha256")" ] && echo checksum-ok # .sha256에는 해시만 들어 있다 +W=/root/k3s-restore-$TS && mkdir -m 0700 "$W" && tar -C "$W" -xzf "$B" && D=$(ls -d "$W"/k3s-datastore-*) && ls "$D" +cat "$D/META" +sqlite3 "$D/state.db" 'PRAGMA integrity_check;' +``` + +`checksum-ok`, `META state.db token`, `ok`가 보여야 한다. + +다른 백업 위치(로컬 사본이 없을 때): + +- AIStor(AIStor가 떠 있을 때). `hb_mc <폴더> `는 고정된 AIStor client를 그 폴더를 `/work`로 붙여 돌린다(키는 그 폴더의 0600 env 파일로 간다). + + ```bash + . /usr/local/lib/platform-backup/lib/host-backup.sh && hb_load_aistor_env + M=$(mktemp -d /root/k3s-fetch.XXXXXX) + hb_mc "$M" ls "backup/$AISTOR_BUCKET/k3s-datastore/" + hb_mc "$M" cp "backup/$AISTOR_BUCKET/k3s-datastore/<이름>" "backup/$AISTOR_BUCKET/k3s-datastore/<이름>.sha256" /work/ + rm -f "$M/.mc.env"; cd "$M" # 이 폴더에서 1단계의 B= 이하를 이어서 한다 + ``` +- off-host 암호화 사본: 소유자가 개인 키가 있는 기계에서 `gpg --decrypt <이름>.tar.gz.gpg > <이름>.tar.gz` 후 desktop으로 옮긴다. + +### 버전을 맞춘다 + +`META`의 `k3s_version`과 지금 k3s가 같아야 한다(`/usr/local/bin/k3s --version | head -1`). 다르면 `k3s-upgrade.md` 3단계 설치 명령에 +`META`의 버전을 넣어 그 버전으로 설치한다. + +### 먼저 리허설한다 (운영에 손대지 않음) + +```bash +bash /home/donghyeon/workspace/platform/scripts/validate/k3s-datastore-restore-drill.sh --from-dir "$D" +``` + +`K3S DATASTORE RESTORE DRILL PASS`와 `restored: namespaces=… secrets=N …` 줄이 나와야 한다. 이 `N`이 5단계의 기준값이다. + +## 2. k3s를 멈추고 지금 상태를 옮겨 둔다 + +같은 호스트에서 깨진 datastore를 바꾸는 경우: + +```bash +systemctl stop k3s +/usr/local/bin/k3s-killall.sh # 컨테이너까지 멈춘다. 복원 중 파드가 옛 상태로 돌지 않게 +mv /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/db.before-restore-$TS +cp -a /var/lib/rancher/k3s/server/token /var/lib/rancher/k3s/server/token.before-restore-$TS +``` + +새로 설치한 호스트(`host-rebuild.md`)는 k3s를 `INSTALL_K3S_SKIP_START=true`로 설치해 **한 번도 시작하지 않은** 상태여야 한다. +실수로 한 번 시작했다면 그때 생긴 빈 클러스터의 파일을 지운다(잃을 것이 없다): + +```bash +systemctl stop k3s && /usr/local/bin/k3s-killall.sh +rm -rf /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/tls /var/lib/rancher/k3s/server/cred /var/lib/rancher/k3s/server/token +``` + +## 3. 백업을 넣는다 + +```bash +install -d -m 0700 /var/lib/rancher/k3s/server/db +install -m 0600 "$D/state.db" /var/lib/rancher/k3s/server/db/state.db +install -m 0600 "$D/token" /var/lib/rancher/k3s/server/token +``` + +k3s 문서(datastore/backup-restore, SQLite)대로 `db/`와 `token`을 함께 넣는다. token이 다르면 datastore 안의 암호화 설정과 인증서를 풀지 못한다. + +## 4. k3s 설정이 백업 때와 같은지 본다 + +`secrets-encryption: true`가 없으면 Secret을 읽지 못한다. 없으면 checkout에서 넣는다. + +```bash +ls /etc/rancher/k3s/config.yaml.d/ +``` + +```bash +cd /home/donghyeon/workspace/platform +install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml +install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml +``` + +재시작 묶음(PR #5)을 적용했던 호스트라면 `bash scripts/bootstrap/apply-k3s-restart-bundle.sh --check`로 무엇이 빠졌는지 보고, +5단계가 끝난 뒤 `--execute`로 다시 깐다. + +## 5. k3s를 시작하고 확인한다 + +```bash +systemctl start k3s +until k3s kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready +k3s kubectl get nodes +k3s kubectl get secrets -A --no-headers | wc -l +k3s kubectl -n object-storage get secret aistor-root-configuration -o jsonpath='{.data}' | wc -c +k3s kubectl get pods -A --no-headers | awk '{split($3, r, "/")} $4 != "Completed" && ($4 != "Running" || r[1] != r[2])' +``` + +- `ready`, 노드 `Ready`, Secret 수가 1단계 리허설의 `N`과 비슷함(±5), 마지막에서 두 번째 숫자가 0보다 큼(복호화 성공). +- 파드는 PV 데이터에 따라 몇 분 걸린다. 그 뒤 `after-reboot-checks.md`를 처음부터 돈다. + +## 되돌리기 (2를 한 경우) + +```bash +systemctl stop k3s && /usr/local/bin/k3s-killall.sh +rm -rf /var/lib/rancher/k3s/server/db +mv /var/lib/rancher/k3s/server/db.before-restore-$TS /var/lib/rancher/k3s/server/db +cp -a /var/lib/rancher/k3s/server/token.before-restore-$TS /var/lib/rancher/k3s/server/token +systemctl start k3s +``` + +`$TS`는 1단계에서 정한 값이다. 셸이 바뀌었으면 `ls -d /var/lib/rancher/k3s/server/db.before-restore-*`로 찾는다. + +## 끝나면 + +```bash +rm -rf /root/k3s-restore-$TS +``` + +복원한 백업 시각 이후에 만든 객체는 없다. repo와의 차이를 보고 필요한 것을 다시 적용한다: + +```bash +cd /home/donghyeon/workspace/platform +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로 센다. +- PV 데이터: platform-postgres는 W1의 CNPG 백업(`services/platform-postgres-backup/README.md`, W1 PR)에서, Gitea 파일은 `gitea-restore.md`로. diff --git a/docs/runbooks/k3s-restart-window.md b/docs/runbooks/k3s-restart-window.md new file mode 100644 index 0000000..861c989 --- /dev/null +++ b/docs/runbooks/k3s-restart-window.md @@ -0,0 +1,38 @@ +# k3s 재시작 창 + +k3s 재시작이나 파드 재시작을 부르는 변경을 **한 번의 창**에 모아서 한다(성숙도 점검 8절 결정 5). +지금 모인 것은 아래 표다. 하나씩 따로 하면 운영 중단이 여러 번 생긴다. + +| 순서 | 변경 | 중단 | 출처 | +| ---: | --- | --- | --- | +| 0 | PR #4 루트 적용(PriorityClass 둘, tech-log tenant, keycloak 정책)과 PR #3 Traefik resources. 재시작 없음 | 없음(Traefik만 몇 초) | `scripts/validate/README.md`, 공유 노트의 소유자 명령 묶음 | +| 1 | k3s 재시작 묶음: kubelet 예약·메모리 축출·graceful shutdown, API 감사 로그, PSA 기본값, local-path 기본 해제, W1 시간 동기화 drop-in | API 1~2분(컨테이너는 계속 돈다) | `infrastructure/host/k3s/README.md` | +| 2 | 받아들인 drift 해소: Keycloak Operator(라벨), prometheus-operator·kube-state-metrics(이미지 문자열), 관측 core의 Kubelet 인증서 경보 제거 | 해당 파드 재시작 | `scripts/validate/live-drift-accepted.txt` | +| 3 | PriorityClass 붙이기(Keycloak, Gitea, Loki, Tempo)와 Keycloak Operator·서버 이미지 digest 고정 | Keycloak 로그인 1~2분, Gitea·Loki·Tempo 재시작 | PR #7 | +| 4 | Postgres `priorityClassName`·Guaranteed QoS | Postgres 재시작(30초 안팎, 모든 서비스의 DB가 끊김) | W1 | + +## 창 전에 + +- 어느 PR이 main에 들어갔는지 본다. 들어가지 않은 줄은 건너뛴다. +- CI job 0개, 에이전트 게이트 없음(`flock -n /tmp/claude-gates/heavy.lock true && echo free`). +- `after-reboot-checks.md` 1~7을 한 번 돌려 지금이 정상인지 본다. 정상이 아닌 상태에서 시작하지 않는다. +- 호스트 백업이 있으면 지금 한 번 돌린다: `sudo systemctl start platform-k3s-datastore-backup.service`. + +## 창 안에서 + +0. **PriorityClass가 먼저 있어야 한다.** `kubectl get priorityclass platform-critical platform-low`가 둘 다 나와야 3을 한다. + 없으면 `kubectl apply -k services/priority-classes`. 없는 클래스를 가리키는 파드는 생성이 거절된다. +1. `sudo bash scripts/bootstrap/apply-k3s-restart-bundle.sh --execute` — 마지막 줄 `K3S RESTART BUNDLE APPLIED`. +2. 받아들인 drift 해소는 각 루트의 기존 적용 스크립트로 한다(Phase 2 Keycloak Operator: `scripts/bootstrap/apply-keycloak.sh --execute`, + 관측 core: `services/observability`의 적용 절차). 끝나면 `live-drift-accepted.txt`에서 해당 줄을 지우는 PR을 낸다. +3. 3은 루트별 기존 적용 경로로 한다: Keycloak Operator·CR `scripts/bootstrap/apply-keycloak.sh --execute`, Gitea + `scripts/bootstrap/apply-gitea-oidc.sh --execute`, Loki·Tempo는 관측 core 적용 절차. 4는 W1 문서를 따른다. +4. 각 단계 뒤에 `after-reboot-checks.md` 4~7을 돈다. 하나라도 실패하면 다음 단계로 가지 않는다. + +## 창 뒤에 + +```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`이어야 한다. diff --git a/docs/runbooks/k3s-upgrade.md b/docs/runbooks/k3s-upgrade.md new file mode 100644 index 0000000..8a59b5c --- /dev/null +++ b/docs/runbooks/k3s-upgrade.md @@ -0,0 +1,127 @@ +# 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 복원이다. From ec9a118d15c84d837726dc5533fae2b853b07fe8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 01:38:58 +0900 Subject: [PATCH 3/4] docs(design): plan the separation of state data from the root SSD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All SSD Local PVs share the root filesystem with the OS, container images and build caches; review A12 and risk 2. Owner decision 3 asks for a plan only. Compare four options (shrink the Windows SSD, a new SSD, the HDD, do nothing), recommend a new SSD and otherwise the Windows SSD, and give the migration: mount the new filesystem at the same /srv/k3s/ssd path so no PV changes, two rsync passes around a short stop, rollback. Note the scripts whose root-SSD findmnt checks must change in the same PR. Risk: documentation only; status 제안. Verification: the PV sizes and paths come from the 2026-11-11 cluster inventory; the findmnt checks were found with git grep. --- ...2026-11-12-state-disk-separation-design.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/design/2026-11-12-state-disk-separation-design.md diff --git a/docs/design/2026-11-12-state-disk-separation-design.md b/docs/design/2026-11-12-state-disk-separation-design.md new file mode 100644 index 0000000..4da28ae --- /dev/null +++ b/docs/design/2026-11-12-state-disk-separation-design.md @@ -0,0 +1,71 @@ + +> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 제안 +- 작성일: 2026-11-12 +- 요약: 상태 데이터 Local PV(`/srv/k3s/ssd`)를 OS·이미지·빌드 캐시와 같은 SSD 파티션에서 떼어 내는 안과 이전 절차를 정리했다. 결정과 실행은 소유자 몫이다. +- 현재 정본: 없음 — 아직 결정 전이다. 지금 배치는 `docs/reviews/2026-11-11-k3s-maturity-review.md` A12. + + +# 상태 데이터 디스크 분리 + +## 문제 + +`/srv/k3s/ssd/*`의 Local PV 8개(platform-postgres 20Gi, Gitea 50Gi, Prometheus 20Gi, Loki·Tempo 5Gi, Grafana·Alloy·pgAdmin·Alertmanager)가 +루트 SSD `sdc1`(232GB, 파티션 하나)에 OS, containerd 이미지, Docker(빌드 캐시·runner), 에이전트 게이트 산출물과 같이 있다. + +- 11-09처럼 빌드 캐시가 디스크를 채우면 Postgres가 WAL을 못 써 멈춘다. PV `capacity`는 아무것도 막지 않는다 + (파드 안 `df`가 루트 전체 228G를 보여 준다). +- SSD 하나가 죽으면 상태와 OS를 함께 잃는다. 백업(CNPG, 호스트 백업)은 HDD에 있지만 되살리는 데 몇 시간이 걸린다. + +## 안 + +| 안 | 내용 | 좋은 점 | 나쁜 점 | +| --- | --- | --- | --- | +| A | sda(1TB SSD, 지금 Windows NTFS 930G) 끝을 줄여 ext4 파티션을 만들고 `/srv/k3s/ssd`를 옮긴다 | 새 하드웨어 없음, SSD 속도 유지, 빌드가 상태를 못 채운다 | Windows 파티션 축소(Windows에서 해야 함, 데이터 위험), 이중 부팅 디스크에 리눅스 데이터 | +| B | 새 SSD(예: 500GB)를 달아 `/srv/k3s/ssd`로 쓴다 | 가장 깨끗하다. 디스크 장애도 분리된다 | 구매·장착, 포트 여유 확인 | +| C | HDD sdb에 둔다 | 지금 바로 가능 | Postgres·Prometheus가 HDD 지연을 받는다. AIStor와 같은 디스크라 장애 분리가 안 된다 | +| D | 그대로 두고 W1의 디스크 상한·경보로만 막는다 | 일이 없다 | 단일 SSD 장애 위험은 그대로 | + +**권하는 안: B, 안 되면 A.** C는 성능 때문에, D는 위험이 남아서 버린다. 어느 안이든 W1의 디스크 경보·상한은 그대로 둔다. + +## 이전 절차 (A·B 공통) + +PV 객체의 `local.path`는 바꾸지 않는다. 새 파일시스템을 **같은 경로 `/srv/k3s/ssd`에 mount**하면 쿠버네티스 쪽 변경이 없다. + +```text +새 파일시스템 준비 → 임시 경로에 mount → 서비스별로 멈추고 rsync → 한 번에 경로 교체 → 다시 시작 → 확인 +``` + +1. 준비: 새 파티션을 ext4로 만들고 `/mnt/new-ssd`에 mount. 용량은 지금 PV 합(약 110Gi)의 두 배 이상. +2. 백업: `k3s-restart-window.md`의 「창 전에」대로 호스트 백업과 CNPG 백업을 한 번씩 돌린다. +3. 1차 복사(서비스 켠 채): `sudo rsync -aHAX --numeric-ids /srv/k3s/ssd/ /mnt/new-ssd/`. +4. 창을 잡고 쓰는 쪽을 멈춘다: Gitea·Keycloak·tech-log를 0으로, CNPG `kubectl cnpg hibernate on platform-postgres`(또는 + `cnpg.io/hibernation: "on"` annotation), 관측 StatefulSet을 0으로. +5. 2차 복사: 3과 같은 명령에 `--delete`. 멈춘 상태라 빠르다. +6. 교체: `/srv/k3s/ssd`를 `/srv/k3s/ssd.old`로 옮기고 새 파일시스템을 `/srv/k3s/ssd`에 mount(fstab UUID, `noatime`). + 소유자·권한(`/srv/k3s/ssd` root 0750, 하위 폴더 소유자)이 같은지 `stat`으로 본다. +7. 다시 시작: 4의 역순. `after-reboot-checks.md` 4~7. +8. 하루 지켜본 뒤 `/srv/k3s/ssd.old`를 지운다(지우기는 소유자가 한다). + +예상 중단: 2차 복사 몇 분 + 재시작 몇 분. Postgres 20Gi·Gitea 370MB 기준 30분 안쪽. + +## 같이 고쳐야 하는 스크립트 + +PV 폴더를 준비·검사하는 스크립트가 「경로가 루트 SSD 파일시스템에 있고 그 아래 다른 mount가 없다」를 검사한다. +`/srv/k3s/ssd`에 새 파일시스템을 mount하면 이 검사가 실패한다. 이전 PR에서 같이 고친다. + +- `scripts/bootstrap/prepare-ssd-local-paths.sh`, `scripts/bootstrap/prepare-observability-local-paths.sh` +- `scripts/bootstrap/apply-admin-services.sh`(pgAdmin 경로: 「`/srv`가 root SSD 파일시스템 경계가 아닙니다」, 「아래에 다른 mount가 있습니다」) +- 같은 `findmnt` 검사를 쓰는 다른 스크립트(`git grep -l findmnt -- scripts`): `apply-aistor.sh`, k3s 로컬 recovery 묶음 등은 + 경로가 다르지만 같이 확인한다. + +## 되돌리기 + +6 이후에 문제가 나면 4처럼 멈추고 새 mount를 내린 뒤 `/srv/k3s/ssd.old`를 원래 이름으로 돌린다. + +## 반증할 수 있는 가정 + +- 「같은 경로에 mount하면 쿠버네티스 변경이 없다」: 틀렸다면 파드가 `local` PV의 노드 affinity나 경로 검사로 뜨지 않는다. + 2차 복사 전에 Grafana(잃어도 되는 PV) 하나로 먼저 시험한다. +- 「빌드 캐시가 상태를 못 채운다」: 틀렸다면 `/srv/k3s/ssd`가 다시 루트와 같은 장치로 보인다(`findmnt -T /srv/k3s/ssd`). From b1140efbb94c567a3e28abcd6cb3037a877303fd Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 01:38:58 +0900 Subject: [PATCH 4/4] docs(reviews): record the phase-two follow-up in the maturity review The owner decisions in section 8 were settled on 2026-11-12 and the section 7 recommendations went into separate PRs. Readers of the review need to know where each one landed and that one recommendation was withdrawn. Add a table from each 7.x item to its PR, withdraw protect-kernel- defaults (CIS dropped it in v1.7 and its kernel.panic_on_oops=1 would reboot this dual-boot desktop on any oops), and note that the API server certificate is measured with openssl on the host instead of a blackbox probe. Risk: documentation only. Verification: the PR numbers match the open and merged platform-core PRs on 2026-11-12. --- .../reviews/2026-11-11-k3s-maturity-review.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/reviews/2026-11-11-k3s-maturity-review.md b/docs/reviews/2026-11-11-k3s-maturity-review.md index 2150c54..9781740 100644 --- a/docs/reviews/2026-11-11-k3s-maturity-review.md +++ b/docs/reviews/2026-11-11-k3s-maturity-review.md @@ -494,3 +494,24 @@ CIS 4.2.6(`protect-kernel-defaults`)은 CIS v1.7부터 빠진 번호라 이 문 - Traefik: `validate.sh` 통과, `kubectl diff`에 resources만 더해진다. - 이 보고서: 반증할 수 있는 가정 — 「repo를 다시 적용해도 운영이 깨지지 않는다」는 w1이 6.1절의 두 줄을 넣은 뒤에는 pg_hba에 대해 참이어야 한다. 남은 반례는 4.3의 객체들이 지워지는 경우다. - 큰 일의 소유자 승인: 소유자 지시 「k3s 구성의 성숙도를 보고 문제 지점을 확인하라」(template-program README 4절 W6, 2026-11-11)를 이 점검의 승인으로 보았다. 구조를 바꾸는 항목은 만들지 않고 8절에 결정으로 올렸다. + +## 2단계 반영 (2026-11-12) + +8절 결정은 2026-11-12 총괄이 「권하는 안으로」 확정했다(결정 1 백업 범위, 2 tech-log 정본 위치, 3 디스크 분리는 계획만, 4 단일 노드 유지, +5 재시작 한 번, 6 AIStor 백업 안 함). 반영한 곳: + +| 7절 | PR | 상태(2026-11-12) | +| --- | --- | --- | +| 7.1 백업(Gitea·k3s datastore, 복원 리허설, 신선도 경보, off-host 변수) | #6 | 열림. 설치는 소유자 sudo | +| 7.2 kubelet 예약·메모리 축출, PriorityClass | #5(drop-in), #4(정의, 병합), #7(붙이기) | #4 병합, 라이브 적용은 소유자 | +| 7.3 감사 로그, graceful shutdown | #5 | 열림 | +| 7.4 업그레이드 runbook, Keycloak 커밋·digest 고정 | runbook PR, #7 | 열림 | +| 7.5 `hyeonworks-prod` PSA, 클러스터 PSA 기본값, keycloak egress | #4(병합), #5 | 라이브 적용은 소유자 | +| 7.6 디스크 분리 | runbook PR의 `docs/design/2026-11-12-state-disk-separation-design.md` | 계획만(결정 3) | +| 7.7 drift 검출, runbook, kubelet 인증서 경보 | #4(병합), #6, runbook PR | — | + +이 문서 7.3절에서 권한 `protect-kernel-defaults`는 **철회한다.** CIS가 v1.7에서 그 항목을 뺐고, 필요한 sysctl 중 +`kernel.panic_on_oops=1`은 커널 oops 한 번에 이 이중 부팅 데스크톱을 재부팅시킨다. 이유는 `infrastructure/host/k3s/README.md`. + +API 서버 인증서 만료는 6443 blackbox probe 대신 호스트 타이머의 `openssl`로 잰다(#6). blackbox 모듈은 모두 검증하는 http라 +k3s CA를 모른다.