docs(runbooks): add restore, rebuild, upgrade and reboot runbooks #8
+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,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를 모른다.
|
||||
|
||||
@@ -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 복원이다.
|
||||
@@ -0,0 +1,2 @@
|
||||
kube-proxy-arg:
|
||||
- "nodeport-addresses=127.0.0.0/8"
|
||||
Reference in New Issue
Block a user