Author SHA1 Message Date
DongHyeonka b1140efbb9 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.
2026-11-12 01:38:58 +09:00
DongHyeonka ec9a118d15 docs(design): plan the separation of state data from the root SSD
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 01:38:58 +09:00
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
DongHyeonka 96623200fa 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.
2026-11-12 01:38:58 +09:00
donghyeon.kang b484110b6b Merge pull request 'feat(tenants): declare tech-log platform objects and keycloak egress' (#4) from donghyeon.kang/w6-tenant-and-policies into main 2026-11-11 15:43:42 +00:00
10 changed files with 866 additions and 1 deletions
+3 -1
View File
@@ -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/` 문서에는 머리 블록이 없다.
@@ -0,0 +1,71 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 제안
- 작성일: 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`).
@@ -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를 모른다.
+132
View File
@@ -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 <namespace> delete pod <name>
```
## 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`가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다.
+154
View File
@@ -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 <폴더> <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
```
+164
View File
@@ -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`). 아래 `<META 버전>`에 넣는다.
```bash
curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION='<META 버전>' 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
```
+154
View File
@@ -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 <폴더> <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`로.
+38
View File
@@ -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`이어야 한다.
+127
View File
@@ -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 복원이다.
@@ -0,0 +1,2 @@
kube-proxy-arg:
- "nodeport-addresses=127.0.0.0/8"