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.
This commit is contained in:
+3
-1
@@ -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,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`가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다.
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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`로.
|
||||
@@ -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`이어야 한다.
|
||||
@@ -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 복원이다.
|
||||
Reference in New Issue
Block a user