Author SHA1 Message Date
DongHyeonka cb78ccdb0b feat(backup): store the Gitea version next to each dump
A Gitea dump must be restored with the Gitea version that wrote it, and
a restore checks the repository count against the dump. Neither was
recorded outside the archive, so the restore runbook had nothing to
compare with.

Upload a small .meta file with each dump: creation time, the
Deployment image, the gitea --version output and the repository count.
docs/runbooks/gitea-restore.md reads it.

Risk: none for the backup itself; the file holds no secret.

Verification: bash -n; kubectl -n gitea exec deploy/gitea -c gitea --
gitea --version prints "gitea version 1.27.0 built with ..." on the
desktop, so the third field is the version.
2026-11-12 01:38:24 +09:00
DongHyeonka 9e9ea94461 feat(backup): keep k3s datastore archives outside AIStor on the HDD
AIStor runs inside the k3s cluster that the datastore archive restores.
After losing the whole cluster the AIStor copy cannot be read until k3s
is running again, which is what the archive is for.

Also keep the seven newest archives in
/srv/k3s/aistor/host-backups/k3s-datastore (root 0700) on the same HDD
filesystem (sdb3). The directory is next to AIStor's drive directory
data/, so AIStor does not list it as a bucket, and it is readable by
mounting sdb3 alone. A metric reports how many local copies exist.

Rejected: the NTFS archive partition (sdb2). It has no Unix
permissions and Windows on the same machine can read it; the archive
holds the server token.

Risk: the files live inside the AIStor PersistentVolume root, which is
mounted into the MinIO pod (uid 1000); mode 0700 root keeps the pod
from reading them.

Verification: bash -n; /srv/k3s/aistor contains only data/ (2026-11-12).
2026-11-12 01:14:45 +09:00
DongHyeonka ba3dddc139 feat(validate): add restore drills for the k3s and Gitea backups
A backup nobody has restored is not known to work. The 2026-08 k3s
recovery bundle never got its isolated restore drill.

k3s-datastore-restore-drill.sh downloads the latest archive, checks its
sha256 and integrity, starts the same k3s version in a network-less
throwaway container on the copy, and checks the API comes up, the
Secret count is close to live and every Secret decrypts with the
token. gitea-backup-restore-drill.sh extracts the latest dump and
checks app.ini (INTERNAL_TOKEN, SECRET_KEY), git fsck on every
repository and the repository count against live Gitea. Both accept a
local copy and write a drill timestamp metric.

Risk: read-only for the cluster. The k3s drill runs the restored
control plane with --network none, so its controllers reach nothing.

Verification (desktop):
- test-k3s-datastore-restore-drill.sh: a fresh k3s with three test
  Secrets (stored encrypted, k8s:enc:) restores with all Secrets
  decrypted in 7s; before folding the WAL the test saw 2 of 3 rows,
  which is why the real backup uses sqlite3 .backup.
- gitea-backup-restore-drill.sh on a live repository dump: 29
  repositories, 0 fsck failures, 29 live; the dump was deleted after.
2026-11-12 01:13:02 +09:00
DongHyeonka 012452cf78 feat(observability): alert on host backups, drift and k3s serving certs
Backups, the daily drift check and the k3s serving certificates have no
alert. k3s renews certificates only when it starts within 120 days of
expiry, and the two kube-prometheus-stack kubelet certificate alerts
can never fire because the k3s kubelet exports no
kubelet_certificate_manager_* metric.

Add a PrometheusRule (platform-host-checks) for backup age, failed
runs, missing metrics, drift left for 6h, a stale drift check, and
serving certificate expiry (warning under 100 days, critical under 14).
Add the two remaining host timers (certificate expiry via openssl on
6443 and 10250; the drift check against origin/main) and an installer
that copies the scripts to a root-owned path, creates the textfile and
work directories and enables all four timers. Disable the two dead
kubelet certificate rules in kube-prometheus-stack.

Risk: the metrics need the node-exporter textfile collector, a one-line
change in W1's node-exporter values that was asked of W1. Until then
PlatformHostBackupMetricsAbsent fires after a day, which is the point.

Verification (desktop):
- test-platform-host-checks-alerts.sh: promtool check and unit tests
  pass; with the k3s threshold changed from 2 to 5 days they fail.
- render-observability-core.sh passes; the render has no Kubelet*
  certificate alerts and still has both KubeClientCertificateExpiration.
- k3s-cert-expiry.sh as the desktop user reads both certificates.
- install-host-checks.sh --check: systemd-analyze verify is clean.
2026-11-12 01:13:02 +09:00
DongHyeonka 77daa39a41 feat(backup): back up the k3s datastore and Gitea to AIStor
Nothing backs up the k3s datastore or Gitea's repositories, packages and
app.ini. W1 covers platform-postgres only. One SSD failure loses the
source, CI artefacts, published libraries and every cluster Secret.

Add two root systemd timers that write to a new AIStor bucket on the
HDD (platform-host-backups, same AIStor as W1's postgres backups):
- k3s datastore, daily: sqlite3 .backup of the live state.db plus the
  server token (k3s backup/restore docs: the token is needed to read
  it back), integrity_check, tar.gz, sha256, upload. Off-host copy is
  prepared behind two variables (gpg recipient file, rclone target) and
  stays off until the owner chooses a place.
- Gitea, weekly: gitea dump --skip-db streamed from the live container,
  listing checked for app.ini and repositories, sha256, upload. The DB
  is in the CNPG backup.
Each run writes textfile metrics for the alerts in the next commit.
create-host-backup-credentials.sh makes the bucket (50GiB quota,
lifecycle 56 days for gitea/, 30 days for k3s-datastore/), a
bucket-scoped policy and user, and a root-only env file; no key is
printed and mc gets keys only through a 0600 env file.

Rejected: in-cluster CronJobs. The datastore is a root-owned host file
and the dump needs the Gitea DB connection; a hostPath root pod or a
second Gitea-labelled pod is a larger privilege than a root timer.

Risk: not installed here (owner sudo steps). The k3s archive holds the
token; together with the datastore it decrypts every Secret. It lives
in a bucket only the backup user can read.

Verification (desktop): a dump streamed with --file - is a valid
tar.gz with app.ini; repositories appear as repos/<owner>/<name>.git
(29, matching the live count). The scripts parse with bash -n.
2026-11-12 01:13:02 +09:00
35 changed files with 1084 additions and 866 deletions
+1 -3
View File
@@ -6,8 +6,6 @@
| 폴더 | 담는 것 | 수명 |
|---|---|---|
| [`runbooks/`](runbooks/) | 운영 절차(복원, 재구축, 업그레이드, 재부팅 뒤 확인, 재시작 창) | 살아 있음 |
| [`design/`](design/) | 설계서(결정 전·후) | 기록(상태가 있다) |
| [`reviews/`](reviews/) | 점검·리뷰 결과 | 기록(쓴 날의 상태) |
| [`platform/plans/`](platform/plans/) | 설계 메모 | 기록 |
| [`superpowers/plans/`](superpowers/plans/) | 실행 계획 | 기록 |
@@ -17,7 +15,7 @@
## 기록 문서의 머리 블록
`reviews/`·`design/`에 새로 쓰는 기록은 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
`reviews/`에 새로 쓰는 기록은 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
형식과 상태 어휘는 design-docs `conventions/docs-system.md` 4절이 정본이다. 리뷰의
상태는 「진행 중」·「닫힘」 둘이다. 이 절을 만들기 전에 쓴 `platform/plans/`·
`superpowers/plans/` 문서에는 머리 블록이 없다.
@@ -1,71 +0,0 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 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,24 +494,3 @@ 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
@@ -1,132 +0,0 @@
# 재부팅·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
@@ -1,154 +0,0 @@
# 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
@@ -1,164 +0,0 @@
# 호스트 재구축 (루트 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
@@ -1,154 +0,0 @@
# 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
@@ -1,38 +0,0 @@
# 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
@@ -1,127 +0,0 @@
# 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,12 @@
[Unit]
Description=Back up Gitea (gitea dump --skip-db) to AIStor (platform-host-backups)
Documentation=file:///usr/local/lib/platform-backup/README.md
After=k3s.service docker.service
Requires=docker.service
[Service]
Type=oneshot
ExecStart=/bin/bash /usr/local/lib/platform-backup/backup/gitea-backup.sh
Nice=10
IOSchedulingClass=idle
TimeoutStartSec=1h
@@ -0,0 +1,10 @@
[Unit]
Description=Weekly Gitea backup
[Timer]
OnCalendar=Sun *-*-* 04:00:00
RandomizedDelaySec=10min
Persistent=true
[Install]
WantedBy=timers.target
@@ -0,0 +1,8 @@
[Unit]
Description=Record the k3s API server and kubelet serving certificate expiry
After=k3s.service
[Service]
Type=oneshot
User=donghyeon
ExecStart=/bin/bash /usr/local/lib/platform-backup/validate/k3s-cert-expiry.sh
@@ -0,0 +1,9 @@
[Unit]
Description=Daily k3s certificate expiry check
[Timer]
OnCalendar=*-*-* 05:00:00
Persistent=true
[Install]
WantedBy=timers.target
@@ -0,0 +1,11 @@
[Unit]
Description=Back up the k3s datastore and token to AIStor (platform-host-backups)
Documentation=file:///usr/local/lib/platform-backup/README.md
After=k3s.service docker.service
Requires=docker.service
[Service]
Type=oneshot
ExecStart=/bin/bash /usr/local/lib/platform-backup/backup/k3s-datastore-backup.sh
Nice=10
IOSchedulingClass=idle
@@ -0,0 +1,10 @@
[Unit]
Description=Daily k3s datastore backup
[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=10min
Persistent=true
[Install]
WantedBy=timers.target
@@ -0,0 +1,16 @@
[Unit]
Description=Compare the cluster with platform-core origin/main (kubectl diff, server dry-run)
After=k3s.service network-online.target
Wants=network-online.target
[Service]
Type=oneshot
User=donghyeon
Environment=PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm
Environment=PLATFORM_CHECKOUT=/home/donghyeon/workspace/platform
ExecStart=/bin/bash /usr/local/lib/platform-backup/validate/live-drift-check-main.sh
# Exit 1 means "drift found"; the metric and its alert report that. Only 2 (the
# check itself failed) marks the unit failed.
SuccessExitStatus=1
Nice=10
TimeoutStartSec=30min
@@ -0,0 +1,10 @@
[Unit]
Description=Daily live drift check
[Timer]
OnCalendar=*-*-* 05:15:00
RandomizedDelaySec=10min
Persistent=true
[Install]
WantedBy=timers.target
@@ -1,2 +0,0 @@
kube-proxy-arg:
- "nodeport-addresses=127.0.0.0/8"
+68
View File
@@ -0,0 +1,68 @@
#!/usr/bin/env bash
# Back up Gitea (repositories, packages, attachments, Actions data, app.ini) to
# AIStor (HDD sdb3). Root only. Run by platform-gitea-backup.timer.
#
# `gitea dump --skip-db` runs inside the live Gitea container and streams a
# tar.gz to stdout (logs go to stderr). The database is backed up separately by
# CloudNativePG (services/platform-postgres-backup). The dump contains app.ini,
# whose secrets are needed to restore, so the archive is sensitive.
set -Eeuo pipefail
umask 077
# shellcheck source=../lib/host-backup.sh
source "$(dirname -- "${BASH_SOURCE[0]}")/../lib/host-backup.sh"
readonly NAME=gitea_backup
readonly KCFG=/etc/rancher/k3s/k3s.yaml
[[ "$(id -u)" -eq 0 ]] || hb_fail "run as root"
hb_load_aistor_env
kubectl() { command /usr/local/bin/k3s kubectl --kubeconfig "$KCFG" "$@"; }
started="$(date +%s)"
previous_success="$(awk '/^platform_backup_last_success_timestamp_seconds/ {print $2}' "$TEXTFILE_DIR/$NAME.prom" 2>/dev/null || echo 0)"
on_error() {
hb_write_metrics "$NAME" <<PROM
platform_backup_last_run_success{backup="gitea"} 0
platform_backup_last_run_timestamp_seconds{backup="gitea"} $(date +%s)
platform_backup_last_success_timestamp_seconds{backup="gitea"} ${previous_success:-0}
PROM
}
trap on_error ERR
work="$(mktemp -d "$HB_WORK_ROOT/gitea.XXXXXX")"
trap 'rm -rf -- "$work"' EXIT
ts="$(date -u +%Y%m%dT%H%M%SZ)"
archive="gitea-dump-$ts.tar.gz"
kubectl -n gitea exec deploy/gitea -c gitea -- \
gitea dump --skip-db --type tar.gz --file - >"$work/$archive" 2>"$work/dump.log"
tar -tzf "$work/$archive" >"$work/list.txt"
grep -qx 'app.ini' "$work/list.txt" || hb_fail "the dump has no app.ini"
repos="$(grep -c -E '^repos/[^/]+/[^/]+\.git/HEAD$' "$work/list.txt" || true)"
(( repos > 0 )) || hb_fail "the dump has no repositories"
sha256sum "$work/$archive" | awk '{print $1}' >"$work/$archive.sha256"
size="$(stat -c %s "$work/$archive")"
# What a restore must match: restore with the same Gitea version (docs/runbooks/gitea-restore.md).
{
echo "created=$ts"
echo "gitea_image=$(kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}')"
echo "gitea_version=$(kubectl -n gitea exec deploy/gitea -c gitea -- gitea --version 2>/dev/null | awk '{print $3}')"
echo "repositories=$repos"
} >"$work/$archive.meta"
hb_mc "$work" cp --quiet "/work/$archive" "/work/$archive.sha256" "/work/$archive.meta" "backup/$AISTOR_BUCKET/gitea/" >/dev/null
hb_mc "$work" stat "backup/$AISTOR_BUCKET/gitea/$archive" >/dev/null
trap - ERR
hb_write_metrics "$NAME" <<PROM
# HELP platform_backup_last_success_timestamp_seconds Unix time of the last successful backup.
# TYPE platform_backup_last_success_timestamp_seconds gauge
platform_backup_last_success_timestamp_seconds{backup="gitea"} $(date +%s)
platform_backup_last_run_success{backup="gitea"} 1
platform_backup_last_run_timestamp_seconds{backup="gitea"} $(date +%s)
platform_backup_last_size_bytes{backup="gitea"} $size
platform_backup_last_duration_seconds{backup="gitea"} $(( $(date +%s) - started ))
# HELP platform_backup_gitea_repositories Repositories in the last successful Gitea dump.
# TYPE platform_backup_gitea_repositories gauge
platform_backup_gitea_repositories $repos
PROM
hb_log "gitea backup $archive ($size bytes, $repos repositories) uploaded"
+99
View File
@@ -0,0 +1,99 @@
#!/usr/bin/env bash
# Back up the k3s datastore (sqlite) and the server token to AIStor (HDD sdb3).
# Root only. Run by platform-k3s-datastore-backup.timer (infrastructure/host/backup).
#
# k3s docs (datastore/backup-restore, SQLite): copy server/db and server/token;
# the token is required to read the datastore back. `sqlite3 .backup` takes a
# consistent copy of the live database.
#
# Off-host copy (prepared, off by default): set in /etc/platform-backup/aistor.env
# OFFHOST_GPG_RECIPIENT_FILE=/etc/platform-backup/offhost-recipient.asc
# OFFHOST_RCLONE_TARGET=<rclone remote:path>
# The archive is then encrypted to that public key and copied with rclone.
set -Eeuo pipefail
umask 077
# shellcheck source=../lib/host-backup.sh
source "$(dirname -- "${BASH_SOURCE[0]}")/../lib/host-backup.sh"
readonly SERVER=/var/lib/rancher/k3s/server
readonly NAME=k3s_datastore_backup
[[ "$(id -u)" -eq 0 ]] || hb_fail "run as root"
command -v sqlite3 >/dev/null || hb_fail "sqlite3 is required"
hb_load_aistor_env
started="$(date +%s)"
on_error() {
hb_write_metrics "$NAME" <<PROM
# HELP platform_backup_last_run_success 1 when the last run of this backup succeeded.
# TYPE platform_backup_last_run_success gauge
platform_backup_last_run_success{backup="k3s-datastore"} 0
platform_backup_last_run_timestamp_seconds{backup="k3s-datastore"} $(date +%s)
platform_backup_last_success_timestamp_seconds{backup="k3s-datastore"} ${previous_success:-0}
PROM
}
previous_success="$(awk '/^platform_backup_last_success_timestamp_seconds/ {print $2}' "$TEXTFILE_DIR/$NAME.prom" 2>/dev/null || echo 0)"
trap on_error ERR
work="$(mktemp -d "$HB_WORK_ROOT/k3s.XXXXXX")"
trap 'rm -rf -- "$work"' EXIT
ts="$(date -u +%Y%m%dT%H%M%SZ)"
stage="$work/k3s-datastore-$ts"
mkdir -m 0700 "$stage"
sqlite3 "$SERVER/db/state.db" ".backup '$stage/state.db'"
check="$(sqlite3 "$stage/state.db" 'PRAGMA integrity_check;')"
[[ "$check" == "ok" ]] || hb_fail "integrity_check on the copy returned: $check"
install -m 0600 "$SERVER/token" "$stage/token"
{
echo "created=$ts"
echo "k3s_version=$(/usr/local/bin/k3s --version | head -1)"
echo "host=$(hostname)"
echo "kine_rows=$(sqlite3 "$stage/state.db" 'SELECT COUNT(*) FROM kine;')"
} >"$stage/META"
tar -C "$work" -czf "$work/k3s-datastore-$ts.tar.gz" "k3s-datastore-$ts"
sha256sum "$work/k3s-datastore-$ts.tar.gz" | awk '{print $1}' >"$work/k3s-datastore-$ts.tar.gz.sha256"
size="$(stat -c %s "$work/k3s-datastore-$ts.tar.gz")"
hb_mc "$work" cp --quiet "/work/k3s-datastore-$ts.tar.gz" "/work/k3s-datastore-$ts.tar.gz.sha256" "backup/$AISTOR_BUCKET/k3s-datastore/" >/dev/null
hb_mc "$work" stat "backup/$AISTOR_BUCKET/k3s-datastore/k3s-datastore-$ts.tar.gz" >/dev/null
# Local copy outside AIStor on the same HDD (sdb3). AIStor runs inside the
# cluster this archive restores, so after losing the cluster the AIStor copy
# cannot be read until k3s is back; this copy can. The directory sits next to
# AIStor's drive directory (data/), so AIStor does not see it as a bucket.
readonly LOCAL_DIR=/srv/k3s/aistor/host-backups/k3s-datastore
install -d -m 0700 -o root -g root "$(dirname "$LOCAL_DIR")" "$LOCAL_DIR"
install -m 0600 "$work/k3s-datastore-$ts.tar.gz" "$work/k3s-datastore-$ts.tar.gz.sha256" "$LOCAL_DIR/"
ls -1t "$LOCAL_DIR"/k3s-datastore-*.tar.gz | tail -n +8 | while read -r old; do rm -f -- "$old" "$old.sha256"; done
local_copies="$(ls -1 "$LOCAL_DIR"/k3s-datastore-*.tar.gz | wc -l)"
offhost=0
if [[ -n "${OFFHOST_GPG_RECIPIENT_FILE:-}" && -n "${OFFHOST_RCLONE_TARGET:-}" ]]; then
command -v rclone >/dev/null || hb_fail "OFFHOST_RCLONE_TARGET is set but rclone is not installed"
gpg --batch --yes --trust-model always --recipient-file "$OFFHOST_GPG_RECIPIENT_FILE" \
--output "$work/k3s-datastore-$ts.tar.gz.gpg" --encrypt "$work/k3s-datastore-$ts.tar.gz"
rclone copyto "$work/k3s-datastore-$ts.tar.gz.gpg" "$OFFHOST_RCLONE_TARGET/k3s-datastore-$ts.tar.gz.gpg"
offhost=1
fi
trap - ERR
hb_write_metrics "$NAME" <<PROM
# HELP platform_backup_last_success_timestamp_seconds Unix time of the last successful backup.
# TYPE platform_backup_last_success_timestamp_seconds gauge
platform_backup_last_success_timestamp_seconds{backup="k3s-datastore"} $(date +%s)
# HELP platform_backup_last_run_success 1 when the last run of this backup succeeded.
# TYPE platform_backup_last_run_success gauge
platform_backup_last_run_success{backup="k3s-datastore"} 1
platform_backup_last_run_timestamp_seconds{backup="k3s-datastore"} $(date +%s)
# HELP platform_backup_last_size_bytes Size of the last successful backup archive.
# TYPE platform_backup_last_size_bytes gauge
platform_backup_last_size_bytes{backup="k3s-datastore"} $size
platform_backup_last_duration_seconds{backup="k3s-datastore"} $(( $(date +%s) - started ))
# HELP platform_backup_local_copies Archives kept outside AIStor on the HDD.
# TYPE platform_backup_local_copies gauge
platform_backup_local_copies{backup="k3s-datastore"} $local_copies
# HELP platform_backup_offhost_copy 1 when the last run also wrote the encrypted off-host copy.
# TYPE platform_backup_offhost_copy gauge
platform_backup_offhost_copy{backup="k3s-datastore"} $offhost
PROM
hb_log "k3s datastore backup k3s-datastore-$ts.tar.gz ($size bytes) uploaded; off-host=$offhost"
@@ -0,0 +1,81 @@
#!/usr/bin/env bash
# Create the AIStor bucket, lifecycle rules, policy and user that the host backup
# timers use, and the root-only /etc/platform-backup/aistor.env.
#
# sudo bash scripts/bootstrap/create-host-backup-credentials.sh
#
# Run once, by the owner, on the desktop. Refuses to run when the env file exists;
# never rotates or deletes a bucket, policy, user or object. No key is printed.
set -Eeuo pipefail
set +x
umask 077
readonly ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
# shellcheck source=../lib/host-backup.sh
source "$ROOT/scripts/lib/host-backup.sh"
readonly BUCKET=platform-host-backups
readonly POLICY=platform-host-backups
readonly QUOTA=50GiB
readonly POLICY_FILE="$ROOT/services/platform-host-checks/bucket-policy.json"
readonly PASS_LINE=PLATFORM_HOST_BACKUP_BOOTSTRAP_PASS
kubectl() { command /usr/local/bin/k3s kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml "$@"; }
[[ "$(id -u)" -eq 0 ]] || hb_fail "run with sudo"
for c in docker jq openssl; do command -v "$c" >/dev/null || hb_fail "missing command: $c"; done
jq -e . "$POLICY_FILE" >/dev/null || hb_fail "bucket policy is not valid JSON"
[[ ! -e "$HOST_BACKUP_ENV" ]] || hb_fail "$HOST_BACKUP_ENV already exists; this script does not rotate it"
ip="$(kubectl -n object-storage get service minio -o jsonpath='{.spec.clusterIP}')"
[[ -n "$ip" ]] || hb_fail "object-storage/minio Service not found"
endpoint="http://${ip}:80"
work="$(mktemp -d)"
trap 'rm -rf -- "$work"' EXIT
kubectl -n object-storage get secret aistor-root-configuration -o jsonpath='{.data.config\.env}' | base64 -d >"$work/root.env"
grep -q '^export MINIO_ROOT_USER=' "$work/root.env" || hb_fail "aistor-root-configuration has an unexpected format"
printf 'pcbackup%s' "$(openssl rand -hex 8)" >"$work/ACCESS_KEY"
openssl rand -hex 32 | tr -d '\n' >"$work/SECRET_KEY"
cp "$POLICY_FILE" "$work/policy.json"
printf '%s\n' \
"Bucket: $BUCKET (quota $QUOTA; expire gitea/ after 56 days, k3s-datastore/ after 30 days) on $endpoint" \
"Policy: $POLICY (${POLICY_FILE#"$ROOT/"})" \
"User: a new generated access key attached to $POLICY" \
"File: $HOST_BACKUP_ENV (root, 0600)" \
'No key value will be printed.'
printf 'Type APPLY to create them: '
IFS= read -r confirmation
[[ "$confirmation" == "APPLY" ]] || hb_fail "confirmation did not match APPLY"
# Every mc call is silenced so no key reaches the terminal.
docker run --rm --network host -v "$work:/run/b:ro" --tmpfs /tmp -e MC_CONFIG_DIR=/tmp/mc \
--entrypoint /bin/sh "$MC_IMAGE" -ec '
. /run/b/root.env
ak="$(cat /run/b/ACCESS_KEY)"; sk="$(cat /run/b/SECRET_KEY)"
mc alias set root "'"$endpoint"'" "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" --api S3v4 >/dev/null
mc mb --ignore-existing "root/'"$BUCKET"'" >/dev/null
mc quota set "root/'"$BUCKET"'" --size "'"$QUOTA"'" >/dev/null
mc ilm rule add --prefix gitea/ --expire-days 56 "root/'"$BUCKET"'" >/dev/null
mc ilm rule add --prefix k3s-datastore/ --expire-days 30 "root/'"$BUCKET"'" >/dev/null
mc admin policy create root "'"$POLICY"'" /run/b/policy.json >/dev/null
mc admin user add root "$ak" "$sk" >/dev/null
mc admin policy attach root "'"$POLICY"'" --user "$ak" >/dev/null
mc alias set backup "'"$endpoint"'" "$ak" "$sk" --api S3v4 >/dev/null
probe=".bootstrap-probe-$(date +%s)"
printf probe | mc pipe "backup/'"$BUCKET"'/$probe" >/dev/null
[ "$(mc cat "backup/'"$BUCKET"'/$probe")" = probe ]
mc rm "backup/'"$BUCKET"'/$probe" >/dev/null
if mc ls backup/loki >/dev/null 2>&1; then echo "the backup user can list another bucket" >&2; exit 1; fi
echo "'"$PASS_LINE"'"' | grep -qx "$PASS_LINE" || hb_fail "bootstrap did not finish; $HOST_BACKUP_ENV was not written"
install -d -m 0700 -o root -g root "$(dirname "$HOST_BACKUP_ENV")"
{
echo "AISTOR_BUCKET=$BUCKET"
echo "AISTOR_ACCESS_KEY=$(cat "$work/ACCESS_KEY")"
echo "AISTOR_SECRET_KEY=$(cat "$work/SECRET_KEY")"
echo "# Off-host encrypted copy of the k3s datastore archive (off until both are set):"
echo "# OFFHOST_GPG_RECIPIENT_FILE=/etc/platform-backup/offhost-recipient.asc"
echo "# OFFHOST_RCLONE_TARGET=remote:path"
} >"$HOST_BACKUP_ENV"
chmod 0600 "$HOST_BACKUP_ENV"
printf '%s\n' "$PASS_LINE" "Created bucket $BUCKET, policy $POLICY, one user and $HOST_BACKUP_ENV."
+78
View File
@@ -0,0 +1,78 @@
#!/usr/bin/env bash
# Install the host backup and check timers (infrastructure/host/backup).
#
# bash scripts/bootstrap/install-host-checks.sh --check # no root, changes nothing
# sudo bash scripts/bootstrap/install-host-checks.sh --execute # install, enable, first runs
#
# Scripts are copied to /usr/local/lib/platform-backup (root-owned) so the root
# timers never execute files the desktop user can edit.
set -Eeuo pipefail
umask 022
readonly ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
readonly LIB=/usr/local/lib/platform-backup
readonly UNIT_DIR=/etc/systemd/system
readonly TEXTFILE_DIR=/var/lib/node_exporter/textfile_collector
readonly WORK_ROOT=/var/lib/platform-backup/work
readonly USER_NAME=donghyeon
readonly -a SCRIPTS=(
scripts/lib/host-backup.sh:lib/host-backup.sh
scripts/backup/k3s-datastore-backup.sh:backup/k3s-datastore-backup.sh
scripts/backup/gitea-backup.sh:backup/gitea-backup.sh
scripts/validate/live-drift-check-main.sh:validate/live-drift-check-main.sh
scripts/validate/k3s-cert-expiry.sh:validate/k3s-cert-expiry.sh
services/platform-host-checks/README.md:README.md
)
readonly -a TIMERS=(platform-k3s-datastore-backup platform-gitea-backup platform-live-drift-check platform-k3s-cert-expiry)
fail() { printf 'ERROR: %s\n' "$*" >&2; exit 1; }
mode="${1:-}"
[[ "$#" -eq 1 && ( "$mode" == "--check" || "$mode" == "--execute" ) ]] || { sed -n '2,8p' "$0" >&2; exit 2; }
echo "== check"
for pair in "${SCRIPTS[@]}"; do
src="${pair%%:*}"
[[ -f "$ROOT/$src" ]] || fail "missing $src"
[[ "$src" != *.sh ]] || bash -n "$ROOT/$src" || fail "syntax error in $src"
done
for t in "${TIMERS[@]}"; do
for u in service timer; do [[ -f "$ROOT/infrastructure/host/backup/$t.$u" ]] || fail "missing $t.$u"; done
done
if command -v systemd-analyze >/dev/null; then
verify_dir="$(mktemp -d)"
trap 'rm -rf -- "$verify_dir"' EXIT
cp "$ROOT"/infrastructure/host/backup/*.service "$ROOT"/infrastructure/host/backup/*.timer "$verify_dir/"
# ExecStart paths do not exist before installation; only syntax and keys are checked.
out="$(cd "$verify_dir" && systemd-analyze verify ./*.timer ./*.service 2>&1 | grep -v -E 'is not executable|No such file|Command .* is not executable' || true)"
[[ -z "$out" ]] || { printf '%s\n' "$out" >&2; fail "systemd-analyze verify reported problems"; }
echo " units: systemd-analyze verify clean"
fi
echo "== plan"
for pair in "${SCRIPTS[@]}"; do echo " install ${pair%%:*} -> $LIB/${pair##*:}"; done
for t in "${TIMERS[@]}"; do echo " install $UNIT_DIR/$t.service, $UNIT_DIR/$t.timer; enable --now $t.timer"; done
echo " mkdir $TEXTFILE_DIR (root:$USER_NAME 0775), $WORK_ROOT (root 0700)"
echo " first runs: k3s-cert-expiry, k3s-datastore-backup, gitea-backup, live-drift-check"
[[ "$mode" == "--execute" ]] || { echo "CHECK ONLY: nothing changed"; exit 0; }
[[ "$(id -u)" -eq 0 ]] || fail "--execute needs root (sudo)"
[[ -f /etc/platform-backup/aistor.env ]] || fail "run scripts/bootstrap/create-host-backup-credentials.sh first"
echo "== install"
for pair in "${SCRIPTS[@]}"; do
install -D -o root -g root -m 0755 "$ROOT/${pair%%:*}" "$LIB/${pair##*:}"
done
install -d -o root -g "$USER_NAME" -m 0775 "$TEXTFILE_DIR"
install -d -o root -g root -m 0700 "$WORK_ROOT"
for t in "${TIMERS[@]}"; do
install -o root -g root -m 0644 "$ROOT/infrastructure/host/backup/$t.service" "$ROOT/infrastructure/host/backup/$t.timer" "$UNIT_DIR/"
done
systemctl daemon-reload
for t in "${TIMERS[@]}"; do systemctl enable --now "$t.timer"; done
echo "== first runs"
for t in platform-k3s-cert-expiry platform-k3s-datastore-backup platform-gitea-backup platform-live-drift-check; do
if systemctl start "$t.service"; then echo " $t: ok"; else echo " $t: FAILED (journalctl -u $t)"; fi
done
echo "== metrics"
grep -h -E '^platform_' "$TEXTFILE_DIR"/*.prom || echo " no metrics yet"
systemctl list-timers 'platform-*' --no-pager
echo "HOST CHECKS INSTALLED"
+55
View File
@@ -0,0 +1,55 @@
#!/usr/bin/env bash
# Shared helpers for the host backup and host check scripts. Source only.
# shellcheck shell=bash
readonly HOST_BACKUP_ENV=/etc/platform-backup/aistor.env
readonly TEXTFILE_DIR=/var/lib/node_exporter/textfile_collector
# Backup staging (root 0700, same SSD). Not /var/tmp: dockerd must see the path.
readonly HB_WORK_ROOT=/var/lib/platform-backup/work
# Same pinned AIStor client as scripts/validate/aistor-s3-smoke.sh.
readonly MC_IMAGE="quay.io/minio/aistor/mc@sha256:c5ec777c080fd6292b7529309a0f311c58c3a92e268c9c57c0901da86881949b"
hb_log() { printf '%s %s\n' "$(date -u +%FT%TZ)" "$*"; }
hb_fail() { hb_log "FAIL: $*" >&2; exit 1; }
# Write Prometheus textfile metrics atomically: hb_write_metrics NAME <<'PROM' ... PROM
hb_write_metrics() {
local name="$1" tmp
[[ -d "$TEXTFILE_DIR" ]] || { hb_log "textfile dir $TEXTFILE_DIR missing; metrics not written"; cat >/dev/null; return 0; }
tmp="$(mktemp "$TEXTFILE_DIR/.${name}.XXXXXX")"
cat >"$tmp"
chmod 0644 "$tmp"
mv -f -- "$tmp" "$TEXTFILE_DIR/${name}.prom"
}
# Load the AIStor endpoint and the backup user's keys (root-only file).
hb_load_aistor_env() {
[[ -f "$HOST_BACKUP_ENV" ]] || hb_fail "$HOST_BACKUP_ENV is missing; run scripts/bootstrap/create-host-backup-credentials.sh"
[[ "$(stat -c '%u %a' "$HOST_BACKUP_ENV")" == "0 600" ]] || hb_fail "$HOST_BACKUP_ENV must be owned by root with mode 0600"
# shellcheck disable=SC1090
. "$HOST_BACKUP_ENV"
: "${AISTOR_BUCKET:?}" "${AISTOR_ACCESS_KEY:?}" "${AISTOR_SECRET_KEY:?}"
# The host cannot resolve cluster DNS, so use the Service ClusterIP (port 80 -> 9000).
if [[ -z "${AISTOR_ENDPOINT:-}" ]]; then
local ip
ip="$(/usr/local/bin/k3s kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml -n object-storage \
get service minio -o jsonpath='{.spec.clusterIP}')"
[[ -n "$ip" ]] || hb_fail "cannot find the object-storage/minio Service"
AISTOR_ENDPOINT="http://${ip}:80"
fi
}
# Run the pinned mc client on the host network with the backup user's keys.
# The keys go through a 0600 env file, never the command line (ps would show it).
# Usage: hb_mc <dir mounted at /work> <mc args...>
hb_mc() {
local work="$1"; shift
local envfile="$work/.mc.env"
if [[ ! -f "$envfile" ]]; then
( umask 077; printf 'MC_HOST_backup=%s\nMC_CONFIG_DIR=/tmp/mc\n' \
"${AISTOR_ENDPOINT/:\/\//://${AISTOR_ACCESS_KEY}:${AISTOR_SECRET_KEY}@}" >"$envfile" )
fi
docker run --rm --network host --user "$(id -u):$(id -g)" \
--env-file "$envfile" -v "$work:/work" --tmpfs /tmp \
"$MC_IMAGE" "$@"
}
+10
View File
@@ -596,3 +596,13 @@ PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
- `--textfile FILE`: `platform_live_drift_objects`, `platform_live_drift_check_success`,
`platform_live_drift_last_run_timestamp_seconds`를 Prometheus textfile 형식으로 쓴다.
- Secret 값의 차이는 보지 않는다.
## 호스트 백업·점검 시험
- `test-platform-host-checks-alerts.sh`: `services/platform-host-checks/prometheus-rules.yaml`의 promtool
단위 시험(백업 신선도, 실패, 지표 없음, drift, k3s 인증서). docker 필요, 클러스터 접근 없음.
- `k3s-cert-expiry.sh`: 6443·10250 serving 인증서 만료를 textfile 지표로 쓴다(타이머가 매일 돌림).
- `live-drift-check-main.sh`: checkout의 작업 트리가 아니라 `origin/main`으로 `live-drift-check.sh`를 돌린다.
- `k3s-datastore-restore-drill.sh`, `gitea-backup-restore-drill.sh`: 복원 리허설. 인자 없이 root로 돌리면 AIStor의
최신 백업을 쓰고, `--from-dir`·`--from-file`로 로컬 사본을 줄 수 있다.
- `test-k3s-datastore-restore-drill.sh`: 운영 데이터 없이 k3s 복원 리허설 경로를 시험한다(일회용 k3s, 시험 Secret 셋).
@@ -0,0 +1,75 @@
#!/usr/bin/env bash
# Restore drill for the Gitea backup (file level).
#
# sudo bash scripts/validate/gitea-backup-restore-drill.sh # latest dump in AIStor
# bash scripts/validate/gitea-backup-restore-drill.sh --from-file DUMP.tar.gz
#
# Extracts the dump into a throwaway directory and checks what a restore needs:
# app.ini is present, every repository passes `git fsck`, and the repository
# count matches the live Gitea. The database is restored from the CloudNativePG
# backup instead (services/platform-postgres-backup); the full restore order is
# in docs/runbooks/gitea-restore.md. Nothing is written to the cluster.
set -Eeuo pipefail
umask 077
readonly ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
# shellcheck source=../lib/host-backup.sh
source "$ROOT/scripts/lib/host-backup.sh"
readonly NAME=gitea_restore_drill
from_file=""
case "${1:-}" in
--from-file) from_file="${2:?--from-file needs a path}" ;;
"") ;;
*) sed -n '2,11p' "$0" >&2; exit 2 ;;
esac
if [[ "$(id -u)" -eq 0 ]]; then
kubectl() { command /usr/local/bin/k3s kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml "$@"; }
fi
base="$HB_WORK_ROOT"; [[ -w "$base" ]] || base="$(mktemp -d)"
work="$(mktemp -d "$base/gitea-drill.XXXXXX")"
trap 'rm -rf -- "$work"' EXIT
if [[ -z "$from_file" ]]; then
[[ "$(id -u)" -eq 0 ]] || hb_fail "run as root to read the backup credentials"
hb_load_aistor_env
latest="$(hb_mc "$work" ls "backup/$AISTOR_BUCKET/gitea/" | awk '{print $NF}' | grep -E '^gitea-dump-.*\.tar\.gz$' | sort | tail -1)"
[[ -n "$latest" ]] || hb_fail "no Gitea dump found"
hb_mc "$work" cp --quiet "backup/$AISTOR_BUCKET/gitea/$latest" "backup/$AISTOR_BUCKET/gitea/$latest.sha256" /work/ >/dev/null
[[ "$(sha256sum "$work/$latest" | awk '{print $1}')" == "$(cat "$work/$latest.sha256")" ]] || hb_fail "checksum mismatch for $latest"
from_file="$work/$latest"
hb_log "drill on $latest"
fi
mkdir "$work/restore"
tar -C "$work/restore" -xzf "$from_file"
[[ -s "$work/restore/app.ini" ]] || hb_fail "app.ini is missing from the dump"
for key in INTERNAL_TOKEN SECRET_KEY; do
grep -q "^${key}[[:space:]]*=" "$work/restore/app.ini" || hb_fail "app.ini has no ${key} (needed to restore)"
done
total=0 broken=0
while IFS= read -r -d '' repo; do
total=$((total + 1))
if ! git -c safe.directory='*' --git-dir="$repo" fsck --no-dangling --no-progress >/dev/null 2>"$work/fsck.err"; then
broken=$((broken + 1))
hb_log "fsck failed: ${repo#"$work/restore/"}: $(head -1 "$work/fsck.err")"
fi
done < <(find "$work/restore/repos" -mindepth 2 -maxdepth 2 -type d -name '*.git' -print0)
hb_log "repositories in dump: $total, fsck failures: $broken"
(( total > 0 )) || hb_fail "the dump has no repositories"
(( broken == 0 )) || hb_fail "$broken repositories failed git fsck"
live="$(kubectl -n gitea exec deploy/gitea -c gitea -- sh -c 'find /data/git/gitea-repositories -mindepth 2 -maxdepth 2 -name "*.git" -type d | wc -l' 2>/dev/null || echo "")"
if [[ -n "$live" ]]; then
hb_log "live Gitea repositories: $live"
(( total >= live - 2 )) || hb_fail "the dump has $total repositories, live Gitea has $live"
fi
hb_write_metrics "$NAME" <<PROM
# HELP platform_backup_restore_drill_last_success_timestamp_seconds Unix time of the last successful restore drill.
# TYPE platform_backup_restore_drill_last_success_timestamp_seconds gauge
platform_backup_restore_drill_last_success_timestamp_seconds{backup="gitea"} $(date +%s)
PROM
echo "GITEA RESTORE DRILL PASS"
+25
View File
@@ -0,0 +1,25 @@
#!/usr/bin/env bash
# Write the notAfter time of the k3s API server (6443) and kubelet (10250)
# serving certificates as Prometheus textfile metrics. No root needed.
# k3s renews these only when it starts and they are within 120 days of expiry
# (docs.k3s.io cli/certificate), and the kubelet exposes no certificate metric,
# so nothing else in the cluster watches them.
set -Eeuo pipefail
# shellcheck source=../lib/host-backup.sh
source "$(dirname -- "${BASH_SOURCE[0]}")/../lib/host-backup.sh"
lines=""
for target in apiserver:6443 kubelet:10250; do
name="${target%%:*}" port="${target##*:}"
end="$(echo | timeout 10 openssl s_client -connect "127.0.0.1:$port" 2>/dev/null | openssl x509 -noout -enddate 2>/dev/null | sed 's/^notAfter=//')" || true
[[ -n "$end" ]] || hb_fail "could not read the $name certificate on 127.0.0.1:$port"
lines+="platform_k3s_certificate_not_after_seconds{certificate=\"$name\"} $(date -d "$end" +%s)"$'\n'
hb_log "$name certificate notAfter $end"
done
hb_write_metrics platform_k3s_certificates <<PROM
# HELP platform_k3s_certificate_not_after_seconds notAfter of a k3s serving certificate (Unix time).
# TYPE platform_k3s_certificate_not_after_seconds gauge
${lines}# HELP platform_k3s_certificate_check_timestamp_seconds Unix time of the last certificate check.
# TYPE platform_k3s_certificate_check_timestamp_seconds gauge
platform_k3s_certificate_check_timestamp_seconds $(date +%s)
PROM
@@ -0,0 +1,99 @@
#!/usr/bin/env bash
# Restore drill for the k3s datastore backup.
#
# sudo bash scripts/validate/k3s-datastore-restore-drill.sh # latest backup in AIStor
# bash scripts/validate/k3s-datastore-restore-drill.sh --from-dir DIR [--expect-secrets N]
# DIR holds state.db and token (an extracted archive, or a test datastore)
#
# Starts a throwaway k3s server (same version as production, --network none,
# no agent) on a copy of the backup, and checks that the API answers, that the
# Secret count matches and that every Secret decrypts (the token unlocks the
# encryption config stored in the datastore). Prints no Secret value. The
# container and the copy are removed at the end.
set -Eeuo pipefail
umask 077
readonly ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
# shellcheck source=../lib/host-backup.sh
source "$ROOT/scripts/lib/host-backup.sh"
# Same version as the desktop server (k3s --version: v1.36.2+k3s1).
readonly K3S_IMAGE="docker.io/rancher/k3s:v1.36.2-k3s1@sha256:6a47cea22c4b834d4ba72c89d291696b79ebe406251f90b446e4dff03513dd87"
readonly NAME=k3s_datastore_restore_drill
from_dir="" expect_secrets=""
while (( $# > 0 )); do
case "$1" in
--from-dir) from_dir="${2:?}"; shift 2 ;;
--expect-secrets) expect_secrets="${2:?}"; shift 2 ;;
*) sed -n '2,13p' "$0" >&2; exit 2 ;;
esac
done
base="${HB_WORK_ROOT}"
[[ -w "$base" ]] || base="$(mktemp -d)"
work="$(mktemp -d "$base/k3s-drill.XXXXXX")"
container="k3s-restore-drill-$$"
cleanup() {
docker rm -f "$container" >/dev/null 2>&1 || true
# The drill container writes as root; remove its files with the same image.
docker run --rm -v "$work:/w" --entrypoint /bin/sh "$K3S_IMAGE" -c 'rm -rf /w/*' >/dev/null 2>&1 || true
rm -rf -- "$work"
}
trap cleanup EXIT
if [[ -z "$from_dir" ]]; then
[[ "$(id -u)" -eq 0 ]] || hb_fail "run as root to read the backup credentials"
hb_load_aistor_env
latest="$(hb_mc "$work" ls "backup/$AISTOR_BUCKET/k3s-datastore/" | awk '{print $NF}' | grep -E '^k3s-datastore-.*\.tar\.gz$' | sort | tail -1)"
[[ -n "$latest" ]] || hb_fail "no k3s datastore backup found"
hb_mc "$work" cp --quiet "backup/$AISTOR_BUCKET/k3s-datastore/$latest" "backup/$AISTOR_BUCKET/k3s-datastore/$latest.sha256" /work/ >/dev/null
[[ "$(sha256sum "$work/$latest" | awk '{print $1}')" == "$(cat "$work/$latest.sha256")" ]] || hb_fail "checksum mismatch for $latest"
tar -C "$work" -xzf "$work/$latest"
from_dir="$(find "$work" -mindepth 1 -maxdepth 1 -type d -name 'k3s-datastore-*' | head -1)"
hb_log "drill on $latest"
if [[ -z "$expect_secrets" ]]; then
expect_secrets="$(/usr/local/bin/k3s kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml get secrets -A --no-headers | wc -l)"
hb_log "live cluster has $expect_secrets Secrets (counts may differ by objects created since the backup)"
fi
fi
[[ -f "$from_dir/state.db" && -f "$from_dir/token" ]] || hb_fail "$from_dir must contain state.db and token"
install -d -m 0700 "$work/server/db"
cp "$from_dir/state.db" "$work/server/db/state.db"
cp "$from_dir/token" "$work/server/token"
[[ "$(sqlite3 "$work/server/db/state.db" 'PRAGMA integrity_check;')" == "ok" ]] || hb_fail "integrity_check failed"
started="$(date +%s)"
docker run -d --name "$container" --network none --tmpfs /run --tmpfs /var/run \
-v "$work/server:/var/lib/rancher/k3s/server" \
"$K3S_IMAGE" server --disable-agent --secrets-encryption \
--token-file /var/lib/rancher/k3s/server/token \
--bind-address 127.0.0.1 --advertise-address 127.0.0.1 --node-ip 127.0.0.1 \
--disable traefik,servicelb,metrics-server,local-storage,coredns >/dev/null
ready=0
for _ in $(seq 1 60); do
if docker exec "$container" kubectl get --raw /readyz >/dev/null 2>&1; then ready=1; break; fi
sleep 5
done
if (( ready == 0 )); then
docker logs --tail 20 "$container" 2>&1 | sed 's/^/ k3s: /' >&2
hb_fail "restored k3s did not become ready in 5 minutes"
fi
namespaces="$(docker exec "$container" kubectl get namespaces --no-headers | wc -l)"
secrets="$(docker exec "$container" kubectl get secrets -A --no-headers | wc -l)"
# -o json decrypts every Secret on the server side; any failure makes kubectl exit non-zero.
decrypted="$(docker exec "$container" kubectl get secrets -A -o json | python3 -I -c 'import json,sys; d=json.load(sys.stdin)["items"]; print(sum(1 for s in d if s.get("data")))')"
hb_log "restored: namespaces=$namespaces secrets=$secrets with-data=$decrypted in $(( $(date +%s) - started ))s"
if [[ -n "$expect_secrets" ]]; then
diff=$(( secrets - expect_secrets ))
(( ${diff#-} <= 5 )) || hb_fail "Secret count $secrets is far from the expected $expect_secrets"
fi
(( decrypted > 0 )) || hb_fail "no Secret carried data after restore"
hb_write_metrics "$NAME" <<PROM
# HELP platform_backup_restore_drill_last_success_timestamp_seconds Unix time of the last successful restore drill.
# TYPE platform_backup_restore_drill_last_success_timestamp_seconds gauge
platform_backup_restore_drill_last_success_timestamp_seconds{backup="k3s-datastore"} $(date +%s)
PROM
echo "K3S DATASTORE RESTORE DRILL PASS"
+16
View File
@@ -0,0 +1,16 @@
#!/usr/bin/env bash
# Daily drift check against origin/main (not the working tree of the checkout),
# so local edits or a stale checkout do not hide or invent drift.
# Run by platform-live-drift-check.timer as the desktop user.
set -Eeuo pipefail
readonly CHECKOUT="${PLATFORM_CHECKOUT:-/home/donghyeon/workspace/platform}"
readonly TEXTFILE=/var/lib/node_exporter/textfile_collector/platform_live_drift.prom
git -C "$CHECKOUT" fetch --quiet origin main
work="$(mktemp -d /tmp/platform-drift-main.XXXXXX)"
trap 'rm -rf -- "$work"' EXIT
git -C "$CHECKOUT" archive origin/main | tar -x -C "$work"
printf 'origin/main %s\n' "$(git -C "$CHECKOUT" rev-parse --short origin/main)"
args=(--accepted "$work/scripts/validate/live-drift-accepted.txt")
[[ -d "$(dirname "$TEXTFILE")" ]] && args+=(--textfile "$TEXTFILE")
bash "$work/scripts/validate/live-drift-check.sh" "${args[@]}"
@@ -0,0 +1,41 @@
#!/usr/bin/env bash
# Test k3s-datastore-restore-drill.sh without production data: start a fresh,
# network-less k3s with secrets encryption, add three test Secrets, stop it,
# and run the drill on its state.db and token. Needs docker; no root.
set -Eeuo pipefail
umask 077
readonly ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
readonly K3S_IMAGE="$(sed -n 's/^readonly K3S_IMAGE="\(.*\)"$/\1/p' "$ROOT/scripts/validate/k3s-datastore-restore-drill.sh")"
[[ -n "$K3S_IMAGE" ]] || { echo "cannot read K3S_IMAGE from the drill script" >&2; exit 1; }
work="$(mktemp -d)"
seed="w6-k3s-drill-seed-$$"
cleanup() {
docker rm -f "$seed" >/dev/null 2>&1 || true
docker run --rm -v "$work:/w" --entrypoint /bin/sh "$K3S_IMAGE" -c 'rm -rf /w/*' >/dev/null 2>&1 || true
rm -rf -- "$work"
}
trap cleanup EXIT
mkdir -p "$work/server" "$work/copy"
docker run -d --name "$seed" --network none --tmpfs /run --tmpfs /var/run \
-v "$work/server:/var/lib/rancher/k3s/server" "$K3S_IMAGE" server --disable-agent --secrets-encryption \
--bind-address 127.0.0.1 --advertise-address 127.0.0.1 --node-ip 127.0.0.1 \
--disable traefik,servicelb,metrics-server,local-storage,coredns >/dev/null
for _ in $(seq 1 60); do docker exec "$seed" kubectl get --raw /readyz >/dev/null 2>&1 && break; sleep 5; done
for i in 1 2 3; do docker exec "$seed" kubectl create secret generic "drill-test-$i" --from-literal=value="test-$i" >/dev/null; done
expected="$(docker exec "$seed" kubectl get secrets -A --no-headers | wc -l)"
docker stop -t 30 "$seed" >/dev/null
docker run --rm -v "$work:/w" --entrypoint /bin/sh "$K3S_IMAGE" -c \
"cp /w/server/db/state.db* /w/server/token /w/copy/ && chown $(id -u):$(id -g) /w/copy/*"
# Fold the WAL into state.db, as `sqlite3 .backup` does in the real backup.
sqlite3 "$work/copy/state.db" 'PRAGMA wal_checkpoint(TRUNCATE);' >/dev/null
rm -f "$work/copy/state.db-wal" "$work/copy/state.db-shm"
# The test Secrets must be stored encrypted (k8s:enc:...), so the drill really
# proves that the token unlocks the encryption key.
encrypted="$(sqlite3 "$work/copy/state.db" "SELECT COUNT(*) FROM kine WHERE name LIKE '/registry/secrets/default/drill-test-%' AND CAST(value AS TEXT) LIKE 'k8s:enc:%';")"
echo "seed: $expected Secrets, encrypted test Secret rows=$encrypted"
(( encrypted >= 3 )) || { echo "test Secrets are not encrypted at rest in the seed datastore" >&2; exit 1; }
bash "$ROOT/scripts/validate/k3s-datastore-restore-drill.sh" --from-dir "$work/copy" --expect-secrets "$expected"
echo "K3S DATASTORE RESTORE DRILL TEST PASS"
@@ -0,0 +1,151 @@
#!/usr/bin/env bash
# promtool unit tests for services/platform-host-checks/prometheus-rules.yaml.
# Needs docker and python3 (PyYAML). No cluster access.
set -Eeuo pipefail
readonly ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
# Same pinned image as test-platform-observability-rules.sh.
readonly PROMETHEUS_IMAGE="quay.io/prometheus/prometheus:v3.13.2-distroless@sha256:ce95cfa77eff5aad28bd7a65aff19868cf78d9e17e4c254da7dfe22ade78318b"
work="$(mktemp -d)"
trap 'rm -rf -- "$work"' EXIT
python3 -I - "$ROOT/services/platform-host-checks/prometheus-rules.yaml" "$work/rules.yaml" <<'PY'
import sys, yaml
rule = yaml.safe_load(open(sys.argv[1]))
yaml.safe_dump({"groups": rule["spec"]["groups"]}, open(sys.argv[2], "w"), sort_keys=False)
PY
# promtool evaluates from Unix time 0, so "now" in each test is the eval_time.
cat >"$work/tests.yaml" <<'EOF'
rule_files:
- rules.yaml
evaluation_interval: 1m
tests:
# k3s datastore: last success at t=0; stale after 2 days, alert after 1h more.
- interval: 1m
input_series:
- series: 'platform_backup_last_success_timestamp_seconds{backup="k3s-datastore"}'
values: '0x5500'
- series: 'platform_backup_last_run_timestamp_seconds{backup="k3s-datastore"}'
values: '0x5500'
- series: 'platform_backup_last_run_timestamp_seconds{backup="gitea"}'
values: '0x5500'
- series: 'platform_backup_last_success_timestamp_seconds{backup="gitea"}'
values: '0x5500'
alert_rule_test:
- eval_time: 24h
alertname: PlatformK3sDatastoreBackupTooOld
exp_alerts: []
- eval_time: 50h
alertname: PlatformK3sDatastoreBackupTooOld
exp_alerts:
- exp_labels: {severity: warning}
exp_annotations:
summary: k3s datastore has not been backed up for more than 2 days
description: Check `journalctl -u platform-k3s-datastore-backup` on desktop. Daily timer, 03:30 KST.
- eval_time: 90h
alertname: PlatformGiteaBackupTooOld
exp_alerts: []
- eval_time: 90h
alertname: PlatformHostBackupMetricsAbsent
exp_alerts: []
- interval: 1m
input_series:
- series: 'platform_backup_last_success_timestamp_seconds{backup="gitea"}'
values: '0x11700'
alert_rule_test:
- eval_time: 194h
alertname: PlatformGiteaBackupTooOld
exp_alerts:
- exp_labels: {severity: warning}
exp_annotations:
summary: Gitea has not been backed up for more than 8 days
description: Check `journalctl -u platform-gitea-backup` on desktop. Weekly timer, Sunday 04:00 KST.
# A failed run is reported with its backup label.
- interval: 1m
input_series:
- series: 'platform_backup_last_run_success{backup="gitea",instance="desktop"}'
values: '0x30'
- series: 'platform_backup_last_run_success{backup="k3s-datastore",instance="desktop"}'
values: '1x30'
alert_rule_test:
- eval_time: 15m
alertname: PlatformHostBackupFailed
exp_alerts:
- exp_labels: {severity: warning, backup: gitea}
exp_annotations:
summary: "The last gitea backup run failed"
description: "Check `journalctl -u platform-gitea-backup` on desktop."
# Metrics never written (timers or textfile collector missing).
- interval: 1h
input_series:
- series: 'up{job="prometheus-node-exporter"}'
values: '1x30'
alert_rule_test:
- eval_time: 25h
alertname: PlatformHostBackupMetricsAbsent
exp_alerts:
- exp_labels: {severity: warning, backup: k3s-datastore}
exp_annotations:
summary: Host backup metrics are missing
description: The backup timers or the node-exporter textfile collector (/var/lib/node_exporter/textfile_collector) are not running.
- exp_labels: {severity: warning, backup: gitea}
exp_annotations:
summary: Host backup metrics are missing
description: The backup timers or the node-exporter textfile collector (/var/lib/node_exporter/textfile_collector) are not running.
# Drift for 7h fires; drift 0 does not.
- interval: 1m
input_series:
- series: 'platform_live_drift_objects'
values: '3x500'
- series: 'platform_live_drift_last_run_timestamp_seconds'
values: '0x500'
- series: 'platform_live_drift_check_success'
values: '1x500'
alert_rule_test:
- eval_time: 5h
alertname: PlatformLiveDriftDetected
exp_alerts: []
- eval_time: 7h
alertname: PlatformLiveDriftDetected
exp_alerts:
- exp_labels: {severity: warning}
exp_annotations:
summary: "3 live objects differ from platform-core origin/main"
description: Run `scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt` on desktop to list them.
- eval_time: 7h
alertname: PlatformLiveDriftCheckStale
exp_alerts: []
# Certificates: 50 days left -> warning only; 10 days left -> warning and critical.
- interval: 1m
input_series:
- series: 'platform_k3s_certificate_not_after_seconds{certificate="apiserver"}'
values: '4320000x200'
- series: 'platform_k3s_certificate_not_after_seconds{certificate="kubelet"}'
values: '864000x200'
- series: 'platform_k3s_certificate_check_timestamp_seconds'
values: '0x200'
alert_rule_test:
- eval_time: 2h
alertname: PlatformK3sServingCertificateExpiry
exp_alerts:
- exp_labels: {severity: warning, certificate: apiserver}
exp_annotations:
summary: "k3s apiserver serving certificate expires in less than 100 days"
description: k3s renews certificates only when it starts within 120 days of expiry. Plan a k3s restart window (docs/runbooks).
- exp_labels: {severity: warning, certificate: kubelet}
exp_annotations:
summary: "k3s kubelet serving certificate expires in less than 100 days"
description: k3s renews certificates only when it starts within 120 days of expiry. Plan a k3s restart window (docs/runbooks).
- exp_labels: {severity: critical, certificate: kubelet}
exp_annotations:
summary: "k3s kubelet serving certificate expires in less than 14 days"
description: Restart k3s (it renews certificates within 120 days of expiry) or run `k3s certificate rotate`.
- eval_time: 2h
alertname: PlatformK3sCertificateCheckStale
exp_alerts: []
EOF
docker run --rm --user "$(id -u):$(id -g)" -v "$work:/work:ro" -w /work --entrypoint /bin/promtool "$PROMETHEUS_IMAGE" check rules rules.yaml
docker run --rm --user "$(id -u):$(id -g)" -v "$work:/work:ro" -w /work --entrypoint /bin/promtool "$PROMETHEUS_IMAGE" test rules tests.yaml
echo "PLATFORM HOST CHECK ALERTS PASS"
@@ -34,6 +34,11 @@ kubeProxy:
defaultRules:
disabled:
Watchdog: true
# k3s kubelet exposes no kubelet_certificate_manager_* metrics, so these two
# can never fire. Serving certificates are watched by platform-host-checks
# (PlatformK3sServingCertificateExpiry) instead. Review 2026-11-11 A11.
KubeletClientCertificateExpiration: true
KubeletServerCertificateExpiration: true
rules:
etcd: false
kubeControllerManager: false
+86
View File
@@ -0,0 +1,86 @@
# 호스트 백업과 점검
desktop 호스트에서 systemd 타이머로 도는 백업과 점검이다. 결과는 node-exporter textfile 수집기
(`/var/lib/node_exporter/textfile_collector/*.prom`)로 Prometheus에 올라가고, 이 폴더의 PrometheusRule이
경보를 낸다. 근거와 결정은 `docs/reviews/2026-11-11-k3s-maturity-review.md` A1·A11·A13·A14, 8절 결정 1·6이다.
## 무엇을 어디에 얼마나
| 대상 | 방법 | 주기 | 보관 | 위치 |
| --- | --- | --- | --- | --- |
| k3s datastore + `server/token` | `sqlite3 .backup` → tar.gz + sha256 | 매일 03:30 KST | AIStor 30일 + 로컬 최근 7개 | AIStor `platform-host-backups/k3s-datastore/`와 `/srv/k3s/aistor/host-backups/k3s-datastore/`(root 0700). 둘 다 HDD sdb3 |
| Gitea (저장소·패키지·첨부·Actions·`app.ini`) | 라이브 파드에서 `gitea dump --skip-db` | 일요일 04:00 KST | 56일(8주) | AIStor `platform-host-backups/gitea/` |
| platform-postgres (Gitea·Keycloak·tech-log DB) | CloudNativePG base backup + WAL | 매일 03:00 KST | 30일 | AIStor `platform-postgres-backups/` (W1, `services/platform-postgres-backup`) |
| AIStor 데이터(Loki·Tempo) | **백업하지 않는다** | — | — | 8절 결정 6: 잃어도 되는 관측 데이터. 디스크를 잃으면 로그·추적 기록만 사라진다 |
| Prometheus·Grafana·Alertmanager PV | 백업하지 않는다 | — | — | 설정은 이 저장소가 정본이고, 지표는 다시 쌓인다 |
- Gitea DB는 dump에 없다(`--skip-db`). Gitea를 복원하려면 CNPG 복원이 먼저다(`docs/runbooks/gitea-restore.md`).
- k3s 백업에는 `token`이 들어 있다. token과 datastore가 같이 있으면 클러스터의 모든 Secret을 풀 수 있다.
Gitea dump의 `app.ini`에도 비밀 값이 있다. 그래서 둘 다 AIStor의 전용 사용자만 읽고 쓴다.
- AIStor는 같은 desktop의 HDD다. SSD가 죽으면 남지만 desktop 자체를 잃으면 같이 잃는다.
- k3s 백업을 AIStor 밖에도 두는 이유: AIStor는 바로 그 k3s 위에서 돈다. 클러스터를 통째로 잃으면 AIStor를
다시 띄우기 전에는 AIStor 안의 사본을 꺼낼 수 없다. 로컬 사본은 sdb3를 mount하기만 하면 읽힌다
(`docs/runbooks/k3s-datastore-restore.md`). 폴더는 AIStor 드라이브 폴더(`data/`) 옆이라 bucket으로 보이지 않는다.
## off-host 사본 (준비만, 기본 꺼짐)
위치는 소유자가 정한다(8절 결정 1). `/etc/platform-backup/aistor.env`에 두 줄을 넣으면 k3s datastore
백업이 그 공개 키로 암호화한 사본을 `rclone`으로 보낸다.
```bash
OFFHOST_GPG_RECIPIENT_FILE=/etc/platform-backup/offhost-recipient.asc # 공개 키. 개인 키는 desktop에 두지 않는다
OFFHOST_RCLONE_TARGET=<rclone remote>:<path> # rclone 설치·설정 필요
```
지표 `platform_backup_offhost_copy{backup="k3s-datastore"}`가 1이 된다. Gitea dump의 off-host 사본은 아직 없다.
## 점검
| 타이머 | 사용자 | 하는 일 | 지표 |
| --- | --- | --- | --- |
| `platform-k3s-cert-expiry` | donghyeon | 6443·10250 serving 인증서 notAfter | `platform_k3s_certificate_not_after_seconds` |
| `platform-live-drift-check` | donghyeon | origin/main 렌더 → `kubectl diff`(서버 dry-run) | `platform_live_drift_objects` |
## 경보 (`prometheus-rules.yaml`)
| 경보 | 조건 |
| --- | --- |
| `PlatformK3sDatastoreBackupTooOld` | 마지막 성공이 2일보다 오래됨 |
| `PlatformGiteaBackupTooOld` | 8일보다 오래됨 |
| `PlatformHostBackupFailed` | 마지막 실행 실패 |
| `PlatformHostBackupMetricsAbsent` | 지표가 하루 동안 없음(타이머나 textfile 수집기가 안 돎) |
| `PlatformLiveDriftDetected` | drift가 6시간 넘게 남음 |
| `PlatformLiveDriftCheckStale` | drift 검사가 2일 넘게 완료되지 않음 |
| `PlatformK3sServingCertificateExpiry` | 100일 미만 warning, 14일 미만 critical |
| `PlatformK3sCertificateCheckStale` | 인증서 점검이 2일 넘게 안 돎 |
`scripts/validate/test-platform-host-checks-alerts.sh`가 promtool 단위 시험으로 각 경보가 울려야 할 때 울리고
아닐 때 안 울리는지 본다. 같은 PR에서 kube-prometheus-stack의 `KubeletClientCertificateExpiration`·
`KubeletServerCertificateExpiration`을 껐다. k3s kubelet은 그 지표를 내지 않아 울릴 수 없었다.
## 적용 (소유자, 순서대로)
전제: node-exporter textfile 수집기(W1, `services/observability/node-exporter/values/home.yaml`의
`--collector.textfile.directory=/host/root/var/lib/node_exporter/textfile_collector`)가 들어간 main checkout.
```bash
cd /home/donghyeon/workspace/platform && git pull --ff-only
sudo bash scripts/bootstrap/create-host-backup-credentials.sh # bucket·정책·사용자·/etc/platform-backup/aistor.env (APPLY 입력)
bash scripts/bootstrap/install-host-checks.sh --check
sudo bash scripts/bootstrap/install-host-checks.sh --execute # 타이머 설치·켜기·첫 실행
kubectl apply -k services/platform-host-checks # 경보 규칙
sudo bash scripts/validate/k3s-datastore-restore-drill.sh # 첫 백업으로 복원 리허설
sudo bash scripts/validate/gitea-backup-restore-drill.sh
```
`install-host-checks.sh --execute` 마지막에 `platform_backup_last_run_success{backup="k3s-datastore"} 1`과
`{backup="gitea"} 1`이 보여야 한다. 리허설 둘은 각각 `K3S DATASTORE RESTORE DRILL PASS`, `GITEA RESTORE DRILL PASS`로 끝나야 한다.
## 복원 리허설
- k3s: 백업을 내려받아 sha256을 맞춘 뒤, 운영과 같은 버전의 k3s를 **네트워크 없는** 일회용 컨테이너로
띄워 API가 뜨는지, Secret 수가 라이브와 비슷한지(±5), 모든 Secret이 복호화되는지 본다.
`scripts/validate/test-k3s-datastore-restore-drill.sh`는 운영 데이터 없이 같은 경로를 시험한다(새 k3s에
시험 Secret 셋 → 암호화돼 저장된 것을 확인 → 복원).
- Gitea: dump를 풀어 `app.ini`(INTERNAL_TOKEN·SECRET_KEY), 모든 저장소의 `git fsck`, 라이브와 저장소 수를 본다.
- 분기마다 한 번 돌린다. 성공하면 `platform_backup_restore_drill_last_success_timestamp_seconds`가 갱신된다.
@@ -0,0 +1,15 @@
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetBucketLocation", "s3:ListBucket"],
"Resource": ["arn:aws:s3:::platform-host-backups"]
},
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
"Resource": ["arn:aws:s3:::platform-host-backups/*"]
}
]
}
@@ -0,0 +1,5 @@
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- prometheus-rules.yaml
@@ -0,0 +1,88 @@
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
name: platform-host-checks
namespace: observability
labels:
observability.hyeonworks.com/instance: home
app.kubernetes.io/part-of: platform
spec:
groups:
- name: platform-host-backups
rules:
- alert: PlatformK3sDatastoreBackupTooOld
expr: time() - max(platform_backup_last_success_timestamp_seconds{backup="k3s-datastore"}) > 2 * 86400
for: 1h
labels:
severity: warning
annotations:
summary: k3s datastore has not been backed up for more than 2 days
description: Check `journalctl -u platform-k3s-datastore-backup` on desktop. Daily timer, 03:30 KST.
- alert: PlatformGiteaBackupTooOld
expr: time() - max(platform_backup_last_success_timestamp_seconds{backup="gitea"}) > 8 * 86400
for: 1h
labels:
severity: warning
annotations:
summary: Gitea has not been backed up for more than 8 days
description: Check `journalctl -u platform-gitea-backup` on desktop. Weekly timer, Sunday 04:00 KST.
- alert: PlatformHostBackupFailed
expr: max by (backup) (platform_backup_last_run_success) == 0
for: 10m
labels:
severity: warning
annotations:
summary: "The last {{ $labels.backup }} backup run failed"
description: "Check `journalctl -u platform-{{ $labels.backup }}-backup` on desktop."
- alert: PlatformHostBackupMetricsAbsent
expr: absent(platform_backup_last_run_timestamp_seconds{backup="k3s-datastore"}) or absent(platform_backup_last_run_timestamp_seconds{backup="gitea"})
for: 1d
labels:
severity: warning
annotations:
summary: Host backup metrics are missing
description: The backup timers or the node-exporter textfile collector (/var/lib/node_exporter/textfile_collector) are not running.
- name: platform-host-drift
rules:
- alert: PlatformLiveDriftDetected
expr: max(platform_live_drift_objects) > 0
for: 6h
labels:
severity: warning
annotations:
summary: "{{ $value }} live objects differ from platform-core origin/main"
description: Run `scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt` on desktop to list them.
- alert: PlatformLiveDriftCheckStale
expr: time() - max(platform_live_drift_last_run_timestamp_seconds) > 2 * 86400 or max(platform_live_drift_check_success) == 0
for: 1h
labels:
severity: warning
annotations:
summary: The daily live drift check has not completed
description: Check `journalctl -u platform-live-drift-check` on desktop.
- name: platform-k3s-certificates
rules:
- alert: PlatformK3sServingCertificateExpiry
expr: (min by (certificate) (platform_k3s_certificate_not_after_seconds) - time()) < 100 * 86400
for: 1h
labels:
severity: warning
annotations:
summary: "k3s {{ $labels.certificate }} serving certificate expires in less than 100 days"
description: k3s renews certificates only when it starts within 120 days of expiry. Plan a k3s restart window (docs/runbooks).
- alert: PlatformK3sServingCertificateExpiry
expr: (min by (certificate) (platform_k3s_certificate_not_after_seconds) - time()) < 14 * 86400
for: 10m
labels:
severity: critical
annotations:
summary: "k3s {{ $labels.certificate }} serving certificate expires in less than 14 days"
description: Restart k3s (it renews certificates within 120 days of expiry) or run `k3s certificate rotate`.
- alert: PlatformK3sCertificateCheckStale
expr: time() - max(platform_k3s_certificate_check_timestamp_seconds) > 2 * 86400
for: 1h
labels:
severity: warning
annotations:
summary: The daily k3s certificate expiry check has not run
description: Check `journalctl -u platform-k3s-cert-expiry` on desktop.