The review found no procedure for losing the host, restoring the k3s datastore or Gitea, upgrading k3s, or checking the platform after a reboot, and the existing runbooks live outside version control. Add five runbooks and a restart-window procedure in docs/runbooks: after-reboot-checks (clock, k3s and certificates, node, pods in dependency order, public paths, Prometheus, alerts, runner), k3s-datastore-restore, gitea-restore (file-only vs full restore, with the warning that a PITR of the shared database also rewinds Keycloak and tech-log), k3s-upgrade (patch within a minor), host-rebuild (order and the easy-to-miss parts: host name for PV node affinity, Tailscale address in the DNS config, time sync before the first k3s start), and k3s-restart-window (what to apply in the one restart window, with the PriorityClasses first). The docs map gains runbooks/ and design/. Each runbook starts with its preconditions and the commands that check them; on 2026-11-12 the backups they need are not installed yet, and they say so. Risk: documentation only. Restores and the rebuild were not executed. Verification: a fresh subagent with only these files ran every command in after-reboot-checks on the desktop and walked the others read-only; its findings (about 60, e.g. a READY check that missed 0/1 Running pods, `stable` pointing to another minor, a missing pgAdmin directory, time sync after the first k3s start) are fixed here. The revised after-reboot commands were rerun on the desktop and match the text. Every repository path the runbooks name exists on main or in the named PR.
165 lines
10 KiB
Markdown
165 lines
10 KiB
Markdown
# 호스트 재구축 (루트 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
|
|
```
|