Compare commits
17
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b1140efbb9 | ||
|
|
ec9a118d15 | ||
|
|
819f3f14f1 | ||
|
|
96623200fa | ||
|
|
b484110b6b | ||
|
|
3eafb7e1d8 | ||
|
|
ebdf33f072 | ||
|
|
c0749ec8a4 | ||
|
|
c2a3f75bc3 | ||
|
|
7580eb7f75 | ||
|
|
4fa02fb43d | ||
|
|
388eb74d4c | ||
|
|
18638f3782 | ||
|
|
497c37b44b | ||
|
|
1c4ef9affd | ||
|
|
41b46f64ea | ||
|
|
af5a90bef8 |
@@ -0,0 +1,23 @@
|
||||
# platform-core 문서 지도
|
||||
|
||||
이 폴더는 이 저장소 안에 두는 기록 문서만 담는다. 아키텍처·운영 절차·결정 기록의
|
||||
정본은 루트 [README](../README.md)가 가리키는 중앙 Platform 문서다. 구성요소의 사용법과
|
||||
적용 절차는 각 디렉터리의 `README.md`와 [`bootstrap/manual/`](../bootstrap/manual/)에 있다.
|
||||
|
||||
| 폴더 | 담는 것 | 수명 |
|
||||
|---|---|---|
|
||||
| [`runbooks/`](runbooks/) | 운영 절차(복원, 재구축, 업그레이드, 재부팅 뒤 확인, 재시작 창) | 살아 있음 |
|
||||
| [`design/`](design/) | 설계서(결정 전·후) | 기록(상태가 있다) |
|
||||
| [`reviews/`](reviews/) | 점검·리뷰 결과 | 기록(쓴 날의 상태) |
|
||||
| [`platform/plans/`](platform/plans/) | 설계 메모 | 기록 |
|
||||
| [`superpowers/plans/`](superpowers/plans/) | 실행 계획 | 기록 |
|
||||
|
||||
폴더 이름과 수명 구분은 design-docs `conventions/docs-system.md` 2절을 따른다.
|
||||
새 폴더를 만들면 같은 변경에서 이 표에 더한다.
|
||||
|
||||
## 기록 문서의 머리 블록
|
||||
|
||||
`reviews/`·`design/`에 새로 쓰는 기록은 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
|
||||
형식과 상태 어휘는 design-docs `conventions/docs-system.md` 4절이 정본이다. 리뷰의
|
||||
상태는 「진행 중」·「닫힘」 둘이다. 이 절을 만들기 전에 쓴 `platform/plans/`·
|
||||
`superpowers/plans/` 문서에는 머리 블록이 없다.
|
||||
@@ -0,0 +1,71 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 제안
|
||||
- 작성일: 2026-11-12
|
||||
- 요약: 상태 데이터 Local PV(`/srv/k3s/ssd`)를 OS·이미지·빌드 캐시와 같은 SSD 파티션에서 떼어 내는 안과 이전 절차를 정리했다. 결정과 실행은 소유자 몫이다.
|
||||
- 현재 정본: 없음 — 아직 결정 전이다. 지금 배치는 `docs/reviews/2026-11-11-k3s-maturity-review.md` A12.
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 상태 데이터 디스크 분리
|
||||
|
||||
## 문제
|
||||
|
||||
`/srv/k3s/ssd/*`의 Local PV 8개(platform-postgres 20Gi, Gitea 50Gi, Prometheus 20Gi, Loki·Tempo 5Gi, Grafana·Alloy·pgAdmin·Alertmanager)가
|
||||
루트 SSD `sdc1`(232GB, 파티션 하나)에 OS, containerd 이미지, Docker(빌드 캐시·runner), 에이전트 게이트 산출물과 같이 있다.
|
||||
|
||||
- 11-09처럼 빌드 캐시가 디스크를 채우면 Postgres가 WAL을 못 써 멈춘다. PV `capacity`는 아무것도 막지 않는다
|
||||
(파드 안 `df`가 루트 전체 228G를 보여 준다).
|
||||
- SSD 하나가 죽으면 상태와 OS를 함께 잃는다. 백업(CNPG, 호스트 백업)은 HDD에 있지만 되살리는 데 몇 시간이 걸린다.
|
||||
|
||||
## 안
|
||||
|
||||
| 안 | 내용 | 좋은 점 | 나쁜 점 |
|
||||
| --- | --- | --- | --- |
|
||||
| A | sda(1TB SSD, 지금 Windows NTFS 930G) 끝을 줄여 ext4 파티션을 만들고 `/srv/k3s/ssd`를 옮긴다 | 새 하드웨어 없음, SSD 속도 유지, 빌드가 상태를 못 채운다 | Windows 파티션 축소(Windows에서 해야 함, 데이터 위험), 이중 부팅 디스크에 리눅스 데이터 |
|
||||
| B | 새 SSD(예: 500GB)를 달아 `/srv/k3s/ssd`로 쓴다 | 가장 깨끗하다. 디스크 장애도 분리된다 | 구매·장착, 포트 여유 확인 |
|
||||
| C | HDD sdb에 둔다 | 지금 바로 가능 | Postgres·Prometheus가 HDD 지연을 받는다. AIStor와 같은 디스크라 장애 분리가 안 된다 |
|
||||
| D | 그대로 두고 W1의 디스크 상한·경보로만 막는다 | 일이 없다 | 단일 SSD 장애 위험은 그대로 |
|
||||
|
||||
**권하는 안: B, 안 되면 A.** C는 성능 때문에, D는 위험이 남아서 버린다. 어느 안이든 W1의 디스크 경보·상한은 그대로 둔다.
|
||||
|
||||
## 이전 절차 (A·B 공통)
|
||||
|
||||
PV 객체의 `local.path`는 바꾸지 않는다. 새 파일시스템을 **같은 경로 `/srv/k3s/ssd`에 mount**하면 쿠버네티스 쪽 변경이 없다.
|
||||
|
||||
```text
|
||||
새 파일시스템 준비 → 임시 경로에 mount → 서비스별로 멈추고 rsync → 한 번에 경로 교체 → 다시 시작 → 확인
|
||||
```
|
||||
|
||||
1. 준비: 새 파티션을 ext4로 만들고 `/mnt/new-ssd`에 mount. 용량은 지금 PV 합(약 110Gi)의 두 배 이상.
|
||||
2. 백업: `k3s-restart-window.md`의 「창 전에」대로 호스트 백업과 CNPG 백업을 한 번씩 돌린다.
|
||||
3. 1차 복사(서비스 켠 채): `sudo rsync -aHAX --numeric-ids /srv/k3s/ssd/ /mnt/new-ssd/`.
|
||||
4. 창을 잡고 쓰는 쪽을 멈춘다: Gitea·Keycloak·tech-log를 0으로, CNPG `kubectl cnpg hibernate on platform-postgres`(또는
|
||||
`cnpg.io/hibernation: "on"` annotation), 관측 StatefulSet을 0으로.
|
||||
5. 2차 복사: 3과 같은 명령에 `--delete`. 멈춘 상태라 빠르다.
|
||||
6. 교체: `/srv/k3s/ssd`를 `/srv/k3s/ssd.old`로 옮기고 새 파일시스템을 `/srv/k3s/ssd`에 mount(fstab UUID, `noatime`).
|
||||
소유자·권한(`/srv/k3s/ssd` root 0750, 하위 폴더 소유자)이 같은지 `stat`으로 본다.
|
||||
7. 다시 시작: 4의 역순. `after-reboot-checks.md` 4~7.
|
||||
8. 하루 지켜본 뒤 `/srv/k3s/ssd.old`를 지운다(지우기는 소유자가 한다).
|
||||
|
||||
예상 중단: 2차 복사 몇 분 + 재시작 몇 분. Postgres 20Gi·Gitea 370MB 기준 30분 안쪽.
|
||||
|
||||
## 같이 고쳐야 하는 스크립트
|
||||
|
||||
PV 폴더를 준비·검사하는 스크립트가 「경로가 루트 SSD 파일시스템에 있고 그 아래 다른 mount가 없다」를 검사한다.
|
||||
`/srv/k3s/ssd`에 새 파일시스템을 mount하면 이 검사가 실패한다. 이전 PR에서 같이 고친다.
|
||||
|
||||
- `scripts/bootstrap/prepare-ssd-local-paths.sh`, `scripts/bootstrap/prepare-observability-local-paths.sh`
|
||||
- `scripts/bootstrap/apply-admin-services.sh`(pgAdmin 경로: 「`/srv`가 root SSD 파일시스템 경계가 아닙니다」, 「아래에 다른 mount가 있습니다」)
|
||||
- 같은 `findmnt` 검사를 쓰는 다른 스크립트(`git grep -l findmnt -- scripts`): `apply-aistor.sh`, k3s 로컬 recovery 묶음 등은
|
||||
경로가 다르지만 같이 확인한다.
|
||||
|
||||
## 되돌리기
|
||||
|
||||
6 이후에 문제가 나면 4처럼 멈추고 새 mount를 내린 뒤 `/srv/k3s/ssd.old`를 원래 이름으로 돌린다.
|
||||
|
||||
## 반증할 수 있는 가정
|
||||
|
||||
- 「같은 경로에 mount하면 쿠버네티스 변경이 없다」: 틀렸다면 파드가 `local` PV의 노드 affinity나 경로 검사로 뜨지 않는다.
|
||||
2차 복사 전에 Grafana(잃어도 되는 PV) 하나로 먼저 시험한다.
|
||||
- 「빌드 캐시가 상태를 못 채운다」: 틀렸다면 `/srv/k3s/ssd`가 다시 루트와 같은 장치로 보인다(`findmnt -T /srv/k3s/ssd`).
|
||||
@@ -0,0 +1,517 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 리뷰** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 진행 중
|
||||
- 작성일: 2026-11-11
|
||||
- 요약: desktop 단일 노드 운영 k3s의 구성 성숙도를 16개 축으로 매기고, 위험 순서의 문제 목록과 drift 표, 점검 도구 결과, 소유자 결정 항목을 정리했다.
|
||||
- 현재 정본: 없음 — 점검 기록이다. 구성의 정본은 루트 `README.md`와 각 디렉터리 `README.md`다.
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# desktop 운영 k3s 성숙도 점검 (2026-11-11)
|
||||
|
||||
점검 대상은 desktop 한 대(`donghyeon-system-product-name`, k3s `v1.36.2+k3s1`)에서 도는 운영 k3s다. Gitea(소스·CI·패키지), platform-postgres(CNPG), Keycloak, AIStor, 관측 스택, tech-log 운영(hyeonworks.com)이 여기에 있다. 클러스터는 읽기만 했다. 바꾼 것은 이 문서와 같은 PR의 매니페스트 두 가지뿐이고, 적용은 PR 병합 뒤 총괄과 소유자가 정한다.
|
||||
|
||||
이번 주 사고 셋(11-09 디스크 90% 축출, 11-11 RTC +9시간, 그 여파의 Prometheus 정지)과 운영 DB 백업 없음은 W1 세션이 고치는 중이다. 이 문서는 그 항목을 「w1 진행 중」으로만 적고 같은 일을 하지 않는다.
|
||||
|
||||
## 0. 한눈에
|
||||
|
||||
### 0.1 성숙도 단계
|
||||
|
||||
| 단계 | 뜻 |
|
||||
|---|---|
|
||||
| 0 | 장치가 없다 |
|
||||
| 1 | 한 번 손으로 했다. 문서·자동화가 없거나 기억에 기댄다 |
|
||||
| 2 | 선언·문서가 있다. 자동 검사나 리허설은 없다 |
|
||||
| 3 | 선언과 자동 검사(렌더 불변식, 경보)가 있고 대부분에 적용됐다 |
|
||||
| 4 | 정기 리허설·drift 자동 검출이 있어 깨지면 바로 드러난다 |
|
||||
| 5 | 측정으로 개선하고, 흔한 실패는 사람 없이 회복한다 |
|
||||
|
||||
### 0.2 축별 성숙도
|
||||
|
||||
| # | 축 | 단계 | 한 줄 근거 |
|
||||
|---|---|---|---|
|
||||
| A1 | 백업·복구 | **1** | CNPG 백업 0개(w1 진행 중). Gitea 저장소 PV·k3s datastore·AIStor는 백업 자체가 없다. k3s는 2026-08-09 수동 번들 한 번, 복원 리허설 없음 |
|
||||
| A2 | 업그레이드 경로 | **1** | 설치(2026-07-18) 뒤 한 번도 올리지 않았다. v1.36 최신은 v1.36.6(4개 뒤). 절차·사전 백업·되돌리기 문서 없음 |
|
||||
| A3 | 리소스·QoS·축출 | **2** | 대부분 requests·limits 있음. 하지만 kubelet 메모리 축출 문턱·예약(kube/systemReserved)·PriorityClass가 없다. limits 합이 메모리의 95% |
|
||||
| A4 | probe·시작 순서 | **3** | 주요 파드에 probe 있음. 재시작 때 의존 순서(DB → Keycloak → 앱)로 재시작이 몇 번 나지만 1분 안에 스스로 회복 |
|
||||
| A5 | 이미지 출처·pull·서명 | **2** | 관측 스택은 digest 고정. 나머지는 태그만. 운영 이미지 `Never`(w1 진행 중). Keycloak은 가변 태그 + `Always`. 서명 검증 없음 |
|
||||
| A6 | 비밀 값 관리 | **3** | k3s Secret 암호화(aescbc) 켜짐, repo에 Secret 없음, 생성 스크립트가 계약 검사. 키 회전·외부 비밀 저장소 없음. tech-log 비밀은 계약 문서 밖 |
|
||||
| A7 | RBAC·ServiceAccount | **3** | cluster-admin은 k3s 기본 묶음뿐, 장기 SA 토큰 0. 다만 매일 쓰는 kubeconfig가 `system:masters` 인증서(회수 불가) |
|
||||
| A8 | NetworkPolicy | **3** | 플랫폼 namespace 대부분 기본 차단 + 허용 목록. `keycloak`은 ingress 정책 하나뿐, egress 제한 없음 |
|
||||
| A9 | Pod Security | **3** | namespace마다 PSA 라벨(baseline·restricted). 클러스터 기본값 없음. 운영 `hyeonworks-prod`는 라벨이 없어 제한 없음 |
|
||||
| A10 | 컨트롤 플레인·노드 설정 | **2** | anonymous-auth 끔, profiling 끔, API는 127.0.0.1. 감사 로그 없음, `protect-kernel-defaults` 없음, graceful shutdown 꺼짐. kube-bench 결과는 5절 |
|
||||
| A11 | 인증서·시계 | **3** | 인증서 만료 2027-07-18, 클라이언트 인증서 7일 전 경보. kubelet 인증서 경보 둘은 k3s에 지표가 없어 울릴 수 없다. 시계는 w1 진행 중 |
|
||||
| A12 | 저장소 | **2** | 정적 Local PV + Retain. 그런데 DB·Gitea·Prometheus PV가 OS·이미지·빌드 캐시와 같은 SSD 한 장(파티션 하나)에 있다. 용량 격리 없음 |
|
||||
| A13 | 관측·경보 | **3** | 기본 규칙 + 플랫폼 규칙 다수, Slack 전송. Watchdog 꺼짐(w1 진행 중). 백업·인증서 갱신 실패 같은 경보는 대상이 없어서 없다 |
|
||||
| A14 | GitOps 일치(drift) | **1** | GitOps 컨트롤러 없음(`clusters/home` 비어 있음). 손으로 적용. repo 밖에서 `kubectl apply`로 들어간 객체 27개(4절) |
|
||||
| A15 | runbook·복구 문서 | **2** | 구축·전환 runbook은 많다. 그런데 중앙 문서 폴더가 git이 아니고 desktop에만 있다. 호스트 전체를 잃었을 때의 재구축 절차가 없다 |
|
||||
| A16 | 단일 노드 구조·자원 공유 | **1** | 노드 1대, 디스크 1장. 같은 호스트가 CI runner·Gradle·Playwright·데스크톱 앱을 같이 돌린다. 점검 중 노드 CPU 89% |
|
||||
|
||||
### 0.3 위험 상위 10개
|
||||
|
||||
위험 = 일어날 가능성 × 일어났을 때 피해. 크기: 작음(파일 몇 개·되돌리기 쉬움) · 중간(경계 하나 안, 재시작 동반) · 큼(구조·데이터·소유자 결정).
|
||||
|
||||
| 순위 | 문제 | 왜 위험한가 | 고치는 법 | 크기 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | **백업이 하나도 없다** (CNPG는 w1 진행 중. Gitea 저장소 PV 50Gi, k3s datastore, AIStor는 w1 범위 밖) | SSD 한 장이 죽거나 사람이 실수하면 소스·CI·패키지·인증·운영 데이터가 전부 사라진다. timer·cron·CronJob·ScheduledBackup이 0개다 | Gitea: `gitea dump` 또는 PV 스냅숏을 HDD(sdb)와 off-host로. k3s: `state.db`·token 정기 복사. 모두 복원 리허설까지(7.1절) | 큼 |
|
||||
| 2 | **상태 데이터가 OS·빌드와 같은 SSD 파티션에 있다** | `/srv/k3s/ssd/*`(Postgres·Gitea·Prometheus·Loki 등 PV 8개)가 `/dev/sdc1` 루트와 같은 파일시스템이다. 11-09처럼 빌드 캐시가 디스크를 채우면 DB가 WAL을 못 써 멈추고, PV `capacity`는 아무것도 막지 않는다 | 단기: w1의 디스크 상한·경보. 중기: 상태 PV를 별도 파티션이나 디스크로 옮긴다(데이터 이전이라 소유자 결정) | 큼 |
|
||||
| 3 | **메모리가 모자랄 때 보호 장치가 없다** | kubelet `evictionHard`가 디스크 두 항목뿐이라 메모리 축출이 없다. 예약도 없다. 그러면 커널 OOM killer가 고르는데 Postgres `oom_score_adj` 985, Traefik 1000이라 DB와 입구가 먼저 죽는다. 호스트는 CI·Gradle도 같이 돌린다 | kubelet `system-reserved`·`kube-reserved`·`eviction-hard memory.available`·`eviction-soft`(k3s 설정 drop-in, 재시작). Postgres는 requests=limits(Guaranteed)로 | 중간 |
|
||||
| 4 | **repo를 다시 적용하면 운영이 깨지는 drift** | 공용 DB `pg_hba`의 techlog 두 줄이 repo에 없었다. 렌더를 그대로 적용하면 hyeonworks.com backend가 DB에 못 붙는다. tech-log 운영 객체 17개와 플랫폼 쪽 허용 객체 10개도 repo 밖이다 | pg_hba는 고칠 변경을 만들어 **w1에 넘김**(같은 파일을 CNPG 백업이 고친다, 6.1절). 나머지는 둘 곳을 정한다(8절 결정 2) | 작음 + 결정 |
|
||||
| 5 | **감사 로그가 없고, 일상 kubeconfig가 회수 불가 인증서** | 누가 무엇을 바꿨는지 남지 않는다. `~/.kube/config`는 `system:masters` 클라이언트 인증서(2027-07-18까지)라 유출돼도 끌 방법이 CA 교체뿐이다 | k3s `audit-log-path`·audit policy(hardening 가이드), 일상용은 RBAC 바인딩한 별도 사용자, `system:masters`는 비상용 | 중간 |
|
||||
| 6 | **업그레이드 경로가 없다** | v1.36.2에서 멈춰 있다(v1.36.6까지 패치 4개). 올릴 때 쓸 절차·사전 datastore 백업·되돌리기가 없고, CNPG PDB(`disruptionsAllowed: 0`)가 `kubectl drain`을 막는다. Traefik chart도 k3s 버전에 묶여 있다 | runbook: datastore 백업 → 같은 minor 최신 패치 → 검증 목록(Traefik chart·이미지 검사 스크립트 포함). drain 대신 정지·재시작 절차 | 중간 |
|
||||
| 7 | **PriorityClass가 없다** | 플랫폼 파드는 전부 우선순위 0이다. 11-09 디스크 축출 때 tech-log 운영 파드가 grafana·kube-state-metrics와 같은 순위로 내보내졌다 | `platform-critical`(DB·Gitea·Keycloak·운영)과 `platform-low`(관측·관리 도구) 두 개를 만들고 붙인다. 붙이면 파드가 재시작된다 | 중간 |
|
||||
| 8 | **운영 namespace와 Keycloak의 파드 보안이 비어 있다** | `hyeonworks-prod`에 PSA 라벨이 없고 컨테이너 3개 모두 securityContext가 없다(frontend는 root 실행). Keycloak도 securityContext 없음 | `hyeonworks-prod`에 `enforce=baseline`·`warn=restricted`, 컨테이너에 restricted 수준 설정. Keycloak은 CR의 podTemplate로 | 중간 |
|
||||
| 9 | **이미지·원격 매니페스트가 고정돼 있지 않다** | Keycloak Operator 원격 리소스 `?ref=26.7.0`의 내용이 실제로 바뀌었다(라이브 build-timestamp 07-09, 지금 렌더 07-23). Keycloak 두 이미지는 가변 태그 + `Always`라 재시작마다 quay.io에 기대고, 그 사이에 이미지가 바뀔 수 있다 | 원격 ref를 커밋 SHA(`38fd7a0c…`)로, 이미지를 digest로, pull은 `IfNotPresent`로. 렌더·apply 스크립트의 검사 문자열도 같이 | 작음 |
|
||||
| 10 | **복구 문서가 버전 관리 밖, 같은 디스크에 있다** | 중앙 문서(`/home/donghyeon/workspace/docs/platform`, runbook 20개)가 git이 아니고 desktop에만 있다. 디스크를 잃으면 복구 절차도 같이 잃는다. 호스트 전체 재구축 절차가 없다 | 중앙 문서를 Gitea repo로(그 Gitea도 같은 호스트라 off-host 사본도). 재구축 runbook 작성 | 중간 |
|
||||
|
||||
그다음 순위: graceful node shutdown 꺼짐(재부팅 때 DB 정상 종료 보장 없음), `keycloak` namespace egress 무제한, 기본 StorageClass `local-path`(Delete, 루트 디스크)가 살아 있음, Traefik BestEffort(**이 PR에서 고침**), 시작 의존 순서로 인한 재시작.
|
||||
|
||||
## 1. 기준과 점검 방법
|
||||
|
||||
### 1.1 기준
|
||||
|
||||
축은 다음 출처에서 골랐다. 각 축의 조항 번호는 9절 출처 표에 있다.
|
||||
|
||||
- Kubernetes 공식: 보안 체크리스트, 운영 환경 고려 사항, 노드 압박 축출, 노드 종료, RBAC 좋은 관행, 이미지, local 볼륨
|
||||
- NSA/CISA Kubernetes Hardening Guide v1.2(2022-08)
|
||||
- k3s 공식: Hardening Guide, CIS 자기 평가, 백업·복원, 업그레이드, 인증서 회전
|
||||
- CIS Kubernetes Benchmark(k3s 판) — kube-bench로 기계 점검
|
||||
- OpenGitOps 원칙(선언·버전 관리·자동 pull·지속 조정)
|
||||
|
||||
### 1.2 수집한 것 (모두 읽기)
|
||||
|
||||
| 무엇 | 어떻게 |
|
||||
|---|---|
|
||||
| 클러스터 객체 127종 | `kubectl get <종류> -A -o json`. Secret은 이름·타입·키 이름만 |
|
||||
| kubelet 설정 | `kubectl get --raw /api/v1/nodes/<노드>/proxy/configz` |
|
||||
| API 서버 인자 | k3s journal의 `Running kube-apiserver` 줄(비밀 경로·값 제외) |
|
||||
| k3s 설정 | `/etc/rancher/k3s/config.yaml.d/*`(읽기 가능한 두 파일), `systemctl cat k3s` |
|
||||
| 인증서 | `openssl s_client`로 6443·10250, kubeconfig 클라이언트 인증서의 기간 |
|
||||
| repo 렌더 | platform-core `main`(`89e8130`)을 desktop 임시 폴더에 풀고 `scripts/validate/render-{phase1,phase2,admin-services,observability-core}.sh` + Traefik overlay 세 개 |
|
||||
| 값 차이 | 렌더 결과(Secret 제외)로 `kubectl diff`(서버 dry-run, 저장 안 함) |
|
||||
| 점검 도구 | 5절 |
|
||||
|
||||
## 2. 축별 상세
|
||||
|
||||
각 축은 「본 것 → 판단 → 다음 단계로 가려면」 순서다.
|
||||
|
||||
### A1 백업·복구 — 1
|
||||
|
||||
- 본 것:
|
||||
- CNPG `Backup`·`ScheduledBackup` 0개, `Cluster.spec.backup` 없음(w1 진행 중).
|
||||
- Gitea PV `gitea-local-pv` 50Gi(저장소, 패키지, Actions 산출물)를 복사하는 장치가 없다. CNPG 백업은 Gitea DB만 덮고 git 저장소 파일은 덮지 않는다.
|
||||
- k3s datastore는 sqlite(kine, `--etcd-servers=unix://kine.sock`)다. 2026-08-09에 암호화 recovery 번들을 손으로 한 번 만들었다(`bootstrap/manual/k3s-secret-encryption-restore-drill.md`). 격리 환경 복원 리허설·주기 실행·off-host 사본은 그 문서도 「미완료」로 적고 있다.
|
||||
- AIStor(HDD `sdb3`, 19G 사용)는 Loki·Tempo 데이터만 있고 백업이 없다. 잃어도 되는 데이터인지는 정해지지 않았다.
|
||||
- 호스트의 systemd timer·cron·k8s CronJob에 백업 작업이 하나도 없다.
|
||||
- 판단: 복구할 수 있는 것은 노트북 clone에 남은 소스뿐이다. Gitea 패키지(라이브러리 1.0.0 둘), Keycloak realm, 운영 DB는 복구 수단이 없다.
|
||||
- 다음 단계(2): 데이터마다 「무엇을·어디로·얼마나 자주·얼마나 보관」을 표로 정한다. (3): 주기 실행 + 실패 경보. (4): 분기마다 복원 리허설.
|
||||
|
||||
### A2 업그레이드 경로 — 1
|
||||
|
||||
- 본 것: `/usr/local/bin/k3s` 2026-07-18 설치 그대로. 채널 정보(`update.k3s.io`)로 v1.36 최신 v1.36.6, stable v1.37.2. system-upgrade-controller 없음. 업그레이드 runbook 없음. 렌더 도구 버전(Helm 3.19.4, Kustomize 5.8.1)은 스크립트가 정확히 맞는지 검사한다(좋음).
|
||||
- 판단: 패치를 못 따라가고 있고, 올릴 때 무엇을 확인할지 정해 둔 것이 없다. k3s가 Traefik chart(`40.1.3+up40.1.0`)와 coredns·metrics-server·local-path를 같이 바꾸므로, Traefik 검사 스크립트(`common.sh`의 chart·이미지 고정값)가 업그레이드 직후 실패하게 돼 있다. 이건 의도된 멈춤이지만 절차가 없다.
|
||||
- 다음 단계(2): 같은 minor 안 패치 업그레이드 runbook(사전 백업, 검사 목록, 되돌리기 = 이전 바이너리 + datastore 복원). (3): 새 패치가 나오면 알림.
|
||||
|
||||
### A3 리소스·QoS·축출 — 2
|
||||
|
||||
- 본 것:
|
||||
- 컨테이너 40개 중 Traefik·local-path-provisioner 둘만 BestEffort. 나머지는 Burstable(requests·limits 있음). Guaranteed는 없다.
|
||||
- 노드 할당: requests CPU 42%·메모리 34%, limits CPU 176%·메모리 95%.
|
||||
- kubelet: `evictionHard`가 `imagefs.available 5%`·`nodefs.available 5%`뿐이고 `mergeDefaultEvictionSettings: false`라 메모리 축출 문턱이 없다. `systemReserved`·`kubeReserved` 없음(Allocatable = Capacity). `evictionSoft` 없음.
|
||||
- 프로세스 `oom_score_adj`: Traefik 1000, Postgres 985.
|
||||
- PriorityClass: 시스템 기본 둘뿐, 플랫폼 파드는 모두 0. PDB는 CNPG가 만든 `platform-postgres-primary` 하나(`disruptionsAllowed: 0`).
|
||||
- LimitRange·ResourceQuota 없음.
|
||||
- 판단: 디스크 압박은 kubelet이 처리하지만 메모리 압박은 커널이 처리한다. 커널은 requests 비율로 고르므로 메모리 요청이 작은 DB가 거의 첫 대상이다. 같은 호스트의 Gradle·Playwright·runner가 메모리를 잡으면 파드 밖 프로세스 때문에 파드가 죽는다.
|
||||
- 다음 단계(3): 예약·메모리 축출 문턱·PriorityClass·DB Guaranteed. PDB는 노드가 한 대라 가용성을 올리지 못하고 drain만 막으므로 더 만들지 않는다.
|
||||
|
||||
### A4 probe·시작 순서 — 3
|
||||
|
||||
- 본 것: 앱·DB·관측 주요 컨테이너는 liveness·readiness가 있고, 느리게 뜨는 것(Gitea, Keycloak, Prometheus, CNPG, pgAdmin, tech-log backend)은 startup probe도 있다. probe가 없는 것: AIStor operator 둘·MinIO 본 컨테이너(operator가 만듦), alloy liveness, sidecar류.
|
||||
- 11-11 k3s 재시작 때의 재시작: tech-log backend 3(Keycloak 준비 전 OIDC discovery 503), Keycloak 1(Postgres 연결 실패), Tempo 2(MinIO 실패), Gitea init 4(DB·Keycloak 전). 모두 1분 안에 회복(`desktop-pod-recovery-2026-11-11` 공유 노트).
|
||||
- 판단: 의존 순서를 재시작으로 푸는 구조다. 지금은 회복되지만, 재시작 backoff가 길어지면 회복 시간이 늘어난다.
|
||||
- 다음 단계(4): 재부팅 리허설에서 「모든 파드 Ready까지 걸린 시간」을 잰다. tech-log backend는 issuer discovery 대신 endpoint를 직접 주는 안(공유 노트 후보 4).
|
||||
|
||||
### A5 이미지 출처·pull·서명 — 2
|
||||
|
||||
- 본 것: digest 고정은 관측 스택 전부와 pgAdmin, runner. 태그만: CNPG, Postgres, Gitea, Keycloak 둘, AIStor 셋, k3s 구성요소, tech-log 셋(`redis:7-alpine`은 움직이는 태그). `Always`: Keycloak 둘. `Never`: tech-log 둘(w1 진행 중).
|
||||
- Keycloak Operator 원격 kustomize 리소스가 태그 ref다. 지금 렌더한 내용의 `app.quarkus.io/build-timestamp`는 `2026-07-23 07:31:25`, 라이브는 `2026-07-09 07:13:57`이다. 같은 태그가 다른 내용을 준 적이 있다는 뜻이다. 태그 `26.7.0`은 지금 커밋 `38fd7a0c84e15d4b66b37d1c2ea728ca2f5416a4`를 가리킨다.
|
||||
- 서명 검증(admission 정책) 없음.
|
||||
- 다음 단계(3): Keycloak 원격 ref·이미지 digest 고정, `redis` 태그 고정. (4): 서명 검증은 노드 한 대 규모에선 비용 대비 효과가 낮아 마지막.
|
||||
|
||||
### A6 비밀 값 관리 — 3
|
||||
|
||||
- 본 것: `secrets-encryption: true`, provider `aescbc`(drop-in `40-secrets-encryption.yaml`). Kubernetes 문서는 `aescbc`를 「약함」(CBC padding oracle)으로, `secretbox`를 「강함」으로 분류한다. k3s는 `secretbox`를 지원한다. repo에 `kind: Secret` 없음(렌더 스크립트가 검사). 생성 스크립트가 계약(존재·타입·키·교차 namespace 동일성)을 검사한다. Slack webhook은 KeePass 복구 경로가 있다.
|
||||
- 계약 문서 밖 Secret: `platform-data/techlog-db-credentials`, `hyeonworks-prod/hyeonworks-secrets`. 누가 언제 만들었는지 repo에 기록이 없다.
|
||||
- Keycloak `keycloak-initial-admin`이 남아 있다. Operator가 만든 임시 관리자다. 영구 관리자로 바꾸고 지웠는지는 이번에 확인하지 않았다(로그인 필요).
|
||||
- 다음 단계(4): provider를 `secretbox`로 바꾸고 키 회전(`k3s secrets-encrypt rotate-keys`)을 한 번 돌려 본다. 순서를 틀리면 datastore가 복구 불가가 될 수 있다고 문서가 경고하므로 datastore 백업(A1) 뒤에 한다. tech-log 비밀을 계약 문서에 올린다.
|
||||
|
||||
### A7 RBAC·ServiceAccount — 3
|
||||
|
||||
- 본 것: `cluster-admin` 바인딩은 `system:masters`와 k3s helm-controller 작업 SA 둘(k3s 설계). 비밀을 쓰는 권한은 operator들(CNPG, AIStor, prometheus-operator)과 Traefik(읽기)뿐. `kubernetes.io/service-account-token` Secret 0개.
|
||||
- 사람이 쓰는 kubeconfig(`~/.kube/config`)는 `CN=system:admin, O=system:masters` 인증서, 2027-07-18 만료. Kubernetes RBAC 좋은 관행은 `system:masters`를 비상용으로만 쓰라고 한다. 이 그룹은 RBAC·webhook을 모두 건너뛰고 인증서는 개별 회수가 안 된다.
|
||||
- API 토큰이 필요 없는데 마운트된 파드: Gitea(default SA, 토큰 자동 마운트). Gitea egress 허용 목록(DNS, Postgres, `192.168.0.107:443`, 사설 대역을 뺀 `:443`)에 API 서버(`:6443`)가 없어 실제 위험은 작다.
|
||||
- 다음 단계(4): 일상용 사용자(인증서나 OIDC) + `cluster-admin`이 아닌 바인딩, `system:masters` 인증서는 오프라인 보관.
|
||||
|
||||
### A8 NetworkPolicy — 3
|
||||
|
||||
- 본 것: `aistor`·`gitea`·`hyeonworks-prod`·`object-storage`·`observability`·`observability-agent`·`platform-admin`은 기본 차단 + 허용 목록이다. `platform-data`는 ingress 허용 목록(기본 차단 정책 이름은 없지만 Postgres 파드를 고르는 ingress 정책이 있어 그 밖은 막힌다). `keycloak`은 Operator가 만든 ingress 정책 하나뿐이라 egress가 열려 있고 Operator 파드는 정책이 없다. `kube-system`은 Traefik ingress 하나.
|
||||
- 다음 단계(4): `keycloak`에 기본 차단과 egress 허용 목록(DNS, Postgres, API 서버). 정책을 실제로 통과·차단하는지 보는 시험(지금은 렌더 불변식만).
|
||||
|
||||
### A9 Pod Security — 3
|
||||
|
||||
- 본 것: PSA 라벨 — restricted 강제: `observability`·`platform-admin`. baseline 강제(+restricted 경고): `aistor`·`cnpg-system`·`gitea`·`keycloak`·`object-storage`·`platform-data`. privileged: `observability-agent`(node-exporter·alloy가 hostPath 필요). 라벨 없음: `hyeonworks-prod`·`default`·`kube-system`.
|
||||
- API 서버에 PodSecurity admission 설정 파일이 없어 라벨 없는 namespace는 privileged와 같다. k3s hardening 가이드는 클러스터 기본값을 restricted로 두고 예외를 적는 방식을 권한다.
|
||||
- 다음 단계(4): `hyeonworks-prod` 라벨, 클러스터 기본 `baseline` 강제 + `kube-system` 예외.
|
||||
|
||||
### A10 컨트롤 플레인·노드 설정 — 2
|
||||
|
||||
- 본 것(API 서버 인자): `--anonymous-auth=false`, `--profiling=false`, `--bind-address=127.0.0.1`, `--authorization-mode=Node,RBAC`, `--encryption-provider-config` 있음, `--enable-admission-plugins=NodeRestriction`. `--audit-log-*` 없음, admission 설정 파일 없음.
|
||||
- kubelet: anonymous 끔, webhook 인증·인가, `protectKernelDefaults` 없음, `seccompDefault: false`, `shutdownGracePeriod: 0s`(graceful node shutdown 꺼짐), `streamingConnectionIdleTimeout: 4h`.
|
||||
- k3s 설정 파일: `config.yaml`은 없고 drop-in 둘(`30-nodeport-loopback.yaml`, `40-secrets-encryption.yaml`)만 있다. unit의 인자는 `--disable=servicelb` 하나.
|
||||
- 다음 단계(3): k3s hardening 가이드의 `audit-log-*`·`protect-kernel-defaults`(sysctl 먼저)·`kubelet-arg` 묶음을 drop-in 하나로. graceful shutdown(`shutdownGracePeriod` 60s, critical 20s 정도).
|
||||
|
||||
### A11 인증서·시계 — 3
|
||||
|
||||
- 본 것:
|
||||
- API 서버 serving(6443)·관리자 클라이언트 인증서 notAfter 2027-07-18. kubelet serving(10250) 2027-11-11(11-11 재시작 때 새로 발급).
|
||||
- k3s는 만료가 가까운 인증서를 **재시작할 때만** 갱신한다(기간은 9절 출처).
|
||||
- 경보: `KubeClientCertificateExpiration`(API 서버에 들어온 클라이언트 인증서, 7일·1일 전), `PlatformCertificateExpiry`(Host Nginx 공개·사설 엣지, 14일 전).
|
||||
- `KubeletClientCertificateExpiration`·`KubeletServerCertificateExpiration`은 규칙은 있지만 **울릴 수 없다.** k3s kubelet은 `kubelet_certificate_manager_*` 지표를 내지 않는다(`/api/v1/nodes/<노드>/proxy/metrics`에서 0줄). API 서버 serving 인증서를 보는 경보도 없다.
|
||||
- 시계는 w1 진행 중.
|
||||
- 판단: 만료 7일 전 경보 하나에 기대고 있다. 경보를 받고 7일 안에 k3s를 재시작하면 되지만, 재시작 자체가 운영 중단(1~2분)이라 계획할 여유가 짧다.
|
||||
- 다음 단계(4): 6443 serving 인증서를 blackbox로 보고 만료 90일 전에 경고, 계획된 재시작을 runbook에 둔다. 울릴 수 없는 kubelet 인증서 규칙 둘은 끈다.
|
||||
|
||||
### A12 저장소 — 2
|
||||
|
||||
- 본 것:
|
||||
- 디스크: `sdc`(SSD 250GB, 파티션 하나 `/`)에 OS·containerd·Docker·빌드 캐시·`/srv/k3s/ssd`(PV 8개). `sdb3`(HDD xfs 932G)에 AIStor. `sda`(SSD 1TB)는 Windows NTFS. RAID 없음.
|
||||
- StorageClass: 정적 `no-provisioner` + `Retain` + `WaitForFirstConsumer` 10개(좋음). 기본 StorageClass는 k3s `local-path`(Delete, `/var/lib/rancher/k3s/storage`, 루트 디스크)인데 쓰는 PVC가 없다.
|
||||
- 파드 안에서 본 `/var/lib/postgresql/data`는 루트 파일시스템 전체(228G, 67%)다. PV `capacity: 20Gi`는 쓰기를 막지 않는다.
|
||||
- 판단: 정적 PV 구성은 잘 돼 있다. 문제는 물리 배치다. 상태 데이터와 「아무 때나 커지는 것」(이미지, 빌드 캐시)이 한 파일시스템을 나눠 쓴다.
|
||||
- 다음 단계(3): 상태 PV를 별도 파티션(또는 sda 일부)으로. 기본 StorageClass 표시를 없앤다(k3s `--disable=local-storage` 또는 annotation).
|
||||
|
||||
### A13 관측·경보 — 3
|
||||
|
||||
- 본 것: kube-prometheus-stack 기본 규칙 + 플랫폼 규칙(루트 디스크, PVC, 재시작 폭주, OOM, 인증서·엣지 probe, CNPG collector, Loki·Alloy, tech-log). Alertmanager → Slack. `defaultRules.disabled.Watchdog: true`(w1 진행 중).
|
||||
- 빈틈(w1 범위 밖): 백업 성공·실패, k3s datastore 크기, 호스트 Docker·runner 상태, 메모리 압박 중 OOM kill 수(노드 수준 `node_vmstat_oom_kill`)에 대한 경보가 없다. 백업이 생기면 같이 넣어야 한다.
|
||||
- 다음 단계(4): 경보 하나마다 「울렸을 때 할 일」 runbook 링크.
|
||||
|
||||
### A14 GitOps 일치 — 1
|
||||
|
||||
- 본 것: `clusters/home/{applications,projects}`는 `.gitkeep`뿐. Argo CD·Flux 없음. 적용은 `scripts/bootstrap/*.sh`를 사람이 실행. 렌더 스크립트의 불변식은 촘촘하다. 하지만 라이브와 비교하는 자동 검사가 없어 이번 점검 전까지 pg_hba drift를 아무도 몰랐다.
|
||||
- project-gitops·project-infra는 다른 클러스터(dev-k3s, lab)를 겨냥한다. 둘의 선언(Argo CD, Vault, auth-system, forward-auth 등)은 desktop에 하나도 없다.
|
||||
- 다음 단계(2→3): 렌더 → `kubectl diff`를 주기적으로 돌려 차이가 있으면 경보(이번에 쓴 방법을 스크립트로). GitOps 컨트롤러는 그다음.
|
||||
|
||||
### A15 runbook·복구 문서 — 2
|
||||
|
||||
- 본 것: platform-core `bootstrap/manual/` 6개, 중앙 문서 `docs/platform/runbooks` 20개(구축·전환·사고 기록). 중앙 문서 폴더는 git 저장소가 아니고 desktop에만 있다(`README.md.orig`, `platform-overview.md.orig` 같은 편집 잔재도 있다). 이 repo의 README가 그 경로를 정본으로 가리킨다.
|
||||
- 없는 것: 호스트 전체 재구축, k3s datastore 복원, Gitea 복원, 업그레이드, 재부팅 후 확인 순서.
|
||||
- 다음 단계(3): 중앙 문서를 버전 관리 + off-host 사본. 빠진 runbook을 쓰고 새 세션 cold-read로 시험.
|
||||
|
||||
### A16 단일 노드 구조·자원 공유 — 1
|
||||
|
||||
- 본 것: 노드 1대(12 CPU, 32GiB, swap 8GiB). 같은 호스트에서 Gitea Actions runner(privileged dind, job 컨테이너는 비특권), 에이전트 세션의 Gradle·Playwright 게이트, 데스크톱 앱이 돈다. 점검 중 노드 CPU 사용 89%, load average 11~20.
|
||||
- 판단: 이번 주 사고 셋 모두 「같은 호스트의 다른 일」(빌드 캐시, Windows 이중 부팅)이 운영을 넘어뜨린 경우다. 노드를 더하지 않는 한 남는 위험이다.
|
||||
- 다음 단계: 구조를 바꾸는 일이라 8절 결정 4.
|
||||
|
||||
## 3. w1·PR #2와 겹치는 항목
|
||||
|
||||
| 항목 | 지금 상태 | 담당 |
|
||||
|---|---|---|
|
||||
| 디스크 경보 80/85%·6시간 예측, 빌드 캐시 상한, runner 정리 | 브랜치 `claude/vigorous-booth-e9c7b9`, PR 전 | w1 진행 중 |
|
||||
| k3s를 시간 동기화 뒤에 시작, RTC UTC | 같은 브랜치 + 소유자 sudo 단계 | w1 진행 중 |
|
||||
| CNPG `platform-postgres` 백업·WAL을 HDD로, 복원 리허설 | 소유자 결정 i(2026-11-11) | w1 진행 중 |
|
||||
| Prometheus 자기 감시(Watchdog이 `values/home.yaml`에서 꺼져 있음) | — | w1 진행 중 |
|
||||
| node-exporter CPU limit 쓰로틀링 | — | w1 진행 중 |
|
||||
| Prometheus `outOfOrderTimeWindow` 10h | 라이브 적용됨, PR #2가 점검 중 main에 병합됨(`41b46f6`, 2026-11-11 23:18 KST) | 끝남 |
|
||||
| 운영 이미지 `imagePullPolicy: Never` → 레지스트리 | 소유자 단계 C·D | w1 진행 중 |
|
||||
| platform-postgres `pg_hba` techlog 두 줄(이 점검에서 찾은 drift) | 변경 `1c4ef9a` 준비됨. CNPG 백업과 같은 파일이라 이 PR에서는 되돌림(`388eb74`) | w1에 넘김(6.1절) |
|
||||
|
||||
점검 중 본 사실 하나를 w1에 넘긴다: `journalctl --list-boots`를 보면 시작 시각이 끝 시각보다 늦은 부팅이 11-11 말고도 07-18, 10-29에 있다. 시계 +9시간이 처음이 아니다.
|
||||
|
||||
## 4. drift 표
|
||||
|
||||
비교 기준: platform-core `main` `89e8130`(점검 시작 때)의 렌더 결과(objects 312개)와 2026-11-11 23:10 KST 클러스터의 최상위 객체(ownerReference 없는 것, Event·Pod 같은 자동 생성 종류 제외). 값 비교는 Secret을 뺀 렌더 결과로 `kubectl diff`(서버 dry-run)를 돌렸다.
|
||||
|
||||
### 4.1 요약
|
||||
|
||||
| 구분 | 개수 | 뜻 |
|
||||
|---|---|---|
|
||||
| repo에 있고 클러스터에도 있음 | 312 | platform-core 선언은 하나도 빠지지 않고 적용돼 있다 |
|
||||
| 그중 값이 다른 것 | 9 | 4.2(객체 기준. Traefik 행은 drift가 아니라 세지 않음) |
|
||||
| repo에 없는데 클러스터에 있음 — `kubectl apply`로 직접 넣은 것 | 27 (+ Secret 2) | 4.3. 전부 tech-log 운영과 그 허용 객체 |
|
||||
| repo에 없는데 클러스터에 있음 — 정상 | 135 (+ CRD 37) | k3s 내장 구성요소, 기본 RBAC·컨트롤러 SA, operator·StatefulSet이 만든 객체, 계약 Secret(4.4) |
|
||||
| repo에 있는데 클러스터에 없음 | platform-core 0 · project-gitops·project-infra 전부 | 4.5 |
|
||||
|
||||
### 4.2 값이 다른 것
|
||||
|
||||
| 객체 | 라이브 | repo 렌더 | 다시 적용하면 | 처리 |
|
||||
|---|---|---|---|---|
|
||||
| `platform-data` Cluster `platform-postgres` `pg_hba` | techlog 두 줄 있음 | 없음 | **운영 backend가 DB에 못 붙음** | **repo를 라이브에 맞추는 변경을 w1에 넘김(6.1절)** |
|
||||
| `observability` Prometheus `tsdb.outOfOrderTimeWindow` | `10h` | `0s` | 시계가 다시 튀면 수집이 멈춤 | PR #2가 병합돼(`41b46f6`) 지금 main은 라이브와 같다 |
|
||||
| `kube-system` HelmChartConfig `traefik` | trust overlay와 같음 | 루트 `kustomization.yaml`은 observe overlay | 루트로 적용하면 trusted IP가 빠짐 | 의도된 구조(Traefik README). drift 아님 |
|
||||
| `keycloak` Operator Deployment·SA·Service | build-timestamp `2026-07-09` | `2026-07-23` | 라벨만 바뀌고 Operator 재시작 | 원격 ref를 커밋 SHA로(7.4) |
|
||||
| `observability` prometheus-operator·kube-state-metrics 이미지 문자열 | `repo:tag@sha256:…` | `repo@sha256:…`(같은 digest) | 같은 이미지로 재시작 | 낮음. 렌더 경로 확인만 |
|
||||
| `platform-data` DatabaseRole `gitea`·`keycloak` | 기본값 필드 생략 | `bypassrls`·`createdb` 등 `false` 명시 | 값은 같음 | 없음 |
|
||||
|
||||
### 4.3 repo 밖에서 들어간 것 (tech-log 운영)
|
||||
|
||||
모두 `kubectl.kubernetes.io/last-applied-configuration`이 있어 `kubectl apply`로 들어왔다. 어느 repo(platform-core, project-gitops, project-infra, tech-log 두 repo)에도 정본 파일이 없다. w1도 Deployment 쪽을 같은 결론으로 적었다.
|
||||
|
||||
| namespace | 객체 | 개수 |
|
||||
|---|---|---|
|
||||
| (클러스터) | Namespace `hyeonworks-prod` | 1 |
|
||||
| `hyeonworks-prod` | Deployment `techlog-backend`·`techlog-frontend`·`redis`, Service 4(`techlog-backend`·`techlog-frontend`·`techlog-management`·`redis`), Ingress `hyeonworks-core`, ConfigMap `techlog-logging`, ServiceMonitor `techlog-backend`, NetworkPolicy 6 | 16 |
|
||||
| `platform-data` | Database·DatabaseRole `platform-postgres-techlog`, NetworkPolicy `allow-techlog-backend` | 3 |
|
||||
| `object-storage` | NetworkPolicy `allow-techlog-backend` | 1 |
|
||||
| `observability` | Probe `techlog-edge`·`techlog-readiness`, PrometheusRule `techlog`, ConfigMap `grafana-dashboard-techlog`, NetworkPolicy `blackbox-allow-techlog-health`·`observability-allow-techlog-scrape` | 6 |
|
||||
| Secret(계약 문서 밖) | `hyeonworks-prod/hyeonworks-secrets`, `platform-data/techlog-db-credentials` | 2 |
|
||||
|
||||
위험: 이 객체들은 지워져도 다시 만들 원본이 없다. 그리고 플랫폼 쪽 객체(Cluster 등)를 repo대로 다시 적용하면 tech-log 쪽 허용이 사라질 수 있다. pg_hba가 그 예였다.
|
||||
|
||||
### 4.4 repo 밖이지만 정상인 것
|
||||
|
||||
| 무엇 | 예 |
|
||||
|---|---|
|
||||
| k3s 내장(addon, `objectset.rio.cattle.io/hash`) | coredns, metrics-server, local-path-provisioner·StorageClass `local-path`, HelmChart `traefik`·`traefik-crd`, RuntimeClass 10개 |
|
||||
| k3s Traefik chart가 만든 것(Helm) | Deployment·Service·IngressClass·ServiceMonitor `traefik` |
|
||||
| 쿠버네티스 기본 | `cluster-admin`·`admin`·`edit`·`view`, 컨트롤러 SA 약 40개, PriorityClass 둘 |
|
||||
| operator·StatefulSet이 만든 것 | PVC 5(StatefulSet volumeClaimTemplates), `cnpg-default-monitoring`, `minio-aistor-sa`·RoleBinding·PolicyBinding, Service `observability-core-kube-pr-kubelet` |
|
||||
| 계약 Secret(repo에 두지 않는 것이 규칙) | Phase 1·2 계약 8개, 관측·관리 도구 Secret(생성 스크립트가 만듦) |
|
||||
|
||||
### 4.5 repo에 있는데 클러스터에 없는 것
|
||||
|
||||
- platform-core: 없음. `services/gitea`(baseline 프로필)는 신규 설치용이고 라이브는 OIDC 프로필이다(README의 설계).
|
||||
- project-gitops(`e4a7f2a`): Argo CD 부트스트랩·AppProject·ApplicationSet, `auth-system`(Keycloak·Postgres), Vault, `auth-server`·`api-server` 워크로드. 대상 클러스터가 `dev-k3s`이고 desktop에는 하나도 없다.
|
||||
- project-infra(`80f58cd`): Vault, `identity-postgres`, `forward-auth`, Keycloak Operator, `mnt` tenant. 대상이 `lab`이고 desktop에는 하나도 없다(Keycloak Operator는 platform-core 것이 돌고 있다).
|
||||
- 판단: 두 repo는 desktop 운영의 drift 대상이 아니다. 다만 둘 다 「Kubernetes desired state의 정본」을 자처하므로(`project-infra/AGENTS.md`), desktop 운영의 정본이 platform-core라는 것을 어딘가에 한 번 적어야 혼동이 없다(8절 결정 2).
|
||||
|
||||
## 5. 점검 도구 결과
|
||||
|
||||
desktop 호스트 Docker에서 버전을 고정해 돌렸다. 모두 읽기만 했고(kube-bench는 `/etc`·`/var`를 읽기 전용 mount, 나머지는 kubeconfig로 list·get), 끝난 뒤 이미지를 지웠다(`docker image ls`에 남은 것 없음). heavy.lock 앞에 다른 세션 작업이 4개 줄 서 있었고 네 도구 모두 빌드급 부하가 아니어서, lock 대신 `nice -n 10`으로 돌렸다(2026-11-11 14:29~14:33Z).
|
||||
|
||||
| 도구 | 이미지(digest) | 대상 |
|
||||
|---|---|---|
|
||||
| kube-bench | `aquasec/kube-bench:v0.16.0` (`sha256:75506f22…`) | 노드·컨트롤 플레인, 프로필 `k3s-cis-1.9` |
|
||||
| kube-linter | `stackrox/kube-linter:v0.8.3` (`sha256:f2bfce78…`) | repo 렌더 결과(Secret 제외) + 라이브 `hyeonworks-prod` |
|
||||
| Polaris | `quay.io/fairwinds/polaris:10.1.8` (`sha256:7af68852…`) | 라이브 클러스터 |
|
||||
| kubescape | `quay.io/kubescape/kubescape-cli:v4.0.16` (`sha256:d575d4f2…`) | 라이브 클러스터, 프레임워크 NSA·CIS v1.10.0. 결과는 로컬 파일만 |
|
||||
|
||||
버전은 릴리스된 지 2주 넘은 것으로 골랐다(kubescape는 v4.0.20이 최신이지만 5일 전 릴리스라 v4.0.16).
|
||||
|
||||
### 5.1 kube-bench (`k3s-cis-1.9`)
|
||||
|
||||
- 합계: PASS 34 · FAIL 25 · WARN 57 · INFO 14.
|
||||
- **FAIL 25개 중 21개는 도구 쪽 문제다.** 이 이미지에 `journalctl`이 없어서, journal에서 인자를 읽는 항목이 「출력 없음」으로 FAIL이 됐다(1.2.1·1.2.4~1.2.8·1.2.10·1.2.14·1.2.15·1.2.22·1.2.24~1.2.26·1.2.29·1.3.2~1.3.5·1.4.1·1.4.2·4.2.4). 호스트 journal에서 직접 읽은 인자로 판정하면 1.2.26(etcd CA)은 sqlite라 해당 없음이고 나머지 20개는 모두 기준을 만족한다. 4.2.4(read-only port)는 kubelet configz로 0을 확인했다.
|
||||
- **진짜 FAIL 4개:**
|
||||
- 1.1.20 PKI 인증서 파일 권한 644(기준 600). 인증서는 공개 정보라 위험은 낮다. k3s 기본값이다.
|
||||
- 5.1.3 Role·ClusterRole의 wildcard. k3s 내장과 operator 것이다.
|
||||
- 5.1.5 namespace `default` SA의 토큰 자동 마운트를 끄지 않았다. k3s hardening 가이드의 수동 조치 항목이다.
|
||||
- 5.1.6 SA 토큰이 필요 없는 파드에도 마운트된다.
|
||||
- 주목할 WARN(수동 항목): 1.2.16~1.2.19 감사 로그 없음, 1.2.9 EventRateLimit 없음, 1.2.11 AlwaysPullImages 없음(k3s 가이드는 오프라인 운영에 안 맞을 수 있다고 본다), 4.2.13 파드 PID 제한 없음, 5.2.1 클러스터 기본 정책 없음, 5.7.2 seccomp 기본값 없음.
|
||||
- 한계: k3s 공식 CIS 자기 평가는 k3s v1.34~v1.37에 「CIS v2.0」 판을 쓴다. kube-bench v0.16.0의 k3s 프로필은 1.9가 가장 새 것이라 판 차이가 있다. 처음 실행에서 이름 정렬로 옛 프로필 `k3s-cis-1.24`가 골라져 1.9로 다시 돌렸다.
|
||||
|
||||
### 5.2 kube-linter (기본 검사)
|
||||
|
||||
| 대상 | 건수 | 내용 |
|
||||
|---|---|---|
|
||||
| repo 렌더 | 17 | 읽기 전용 루트 FS 아님 9(AIStor operator 셋, Gitea 넷 등), 짝 파드 없는 Service 4(렌더에 파드가 없는 kube-system 대상 등 — 정적 검사 한계), 민감한 hostPath 3(node-exporter `/proc`·`/sys`·`/` — 설계상 필요), `runAsNonRoot` 없음 1(Keycloak Operator) |
|
||||
| 라이브 `hyeonworks-prod` | 6 | 세 Deployment 모두 `runAsNonRoot` 없음, 읽기 전용 루트 FS 아님 |
|
||||
|
||||
### 5.3 Polaris
|
||||
|
||||
- 점수 88(Polaris 산식), 검사 1,134개 중 913개 통과.
|
||||
- 「위험」 등급 23건:
|
||||
- root 실행 허용 6·권한 상승 허용 5: tech-log 셋, Keycloak Operator, coredns·local-path(k3s 내장). 8번 위험과 같은 대상이다.
|
||||
- RBAC 10건: k3s helm 작업 SA의 cluster-admin, CNPG operator의 `pods/exec`, AIStor 바인딩. 모두 upstream 설계다. `loki-clusterrole`은 규칙이 비어 있는데 잡혔다(오탐).
|
||||
- `sensitiveContainerEnvVar` 2건(AIStor `TOKEN_VALIDATION`, Gitea `GITEA_ADMIN_PASSWORD_MODE`): 이름만 걸린 설정값이다(오탐).
|
||||
- 「경고」에서 의미 있는 것: PriorityClass 없음 18, Ingress TLS 없음 6(TLS는 Host Nginx가 끝내는 설계라 해당 없음), Traefik·local-path·metrics-server의 requests·limits 없음.
|
||||
|
||||
### 5.4 kubescape
|
||||
|
||||
- 점수: NSA 71, CIS v1.10.0 48.
|
||||
- 「높음」 실패 중 진짜인 것: 5.7.3 securityContext 없음 28(tech-log·Keycloak·k3s 내장·sidecar), 5.2.2·5.2.11 등 「namespace에 정책 강제 없음」 6(`hyeonworks-prod`, `default`, `kube-system`, `kube-public`, `kube-node-lease`, `observability-agent`), CPU limit 없음 7·메모리 limit 없음 3(tech-log와 k3s 내장).
|
||||
- 오탐: C-0012 「설정 안의 자격 증명」 8건. 값을 보지 않고 형태만 확인했다. env는 이름에 AUTH·KEY가 들어간 모드·ID·URI이고, Loki ConfigMap의 키 둘은 `${…}` env 참조다. 평문 자격 증명은 없다.
|
||||
- 중간 등급 다수(SA 토큰 마운트 18, secret 접근 22 등)는 operator 권한이 대부분이다.
|
||||
|
||||
### 5.5 도구 결과가 판단을 바꾼 곳
|
||||
|
||||
- 도구 넷이 공통으로 가리킨 곳은 `hyeonworks-prod`와 Keycloak의 securityContext, PriorityClass 없음, k3s 내장의 requests·limits 없음이다. 0.3절 7·8번 순위의 근거가 됐다.
|
||||
- kube-bench FAIL 25를 그대로 믿었다면 A10을 1로 매겼을 것이다. journal 인자를 직접 대조하니 컨트롤 플레인 인자는 기준을 만족했고, 빈 곳은 감사 로그·PSA 기본값·kubelet 하드닝뿐이라 2로 두었다.
|
||||
|
||||
## 6. 이 PR에서 고친 것과 넘긴 것
|
||||
|
||||
위험이 낮고 되돌릴 수 있는 매니페스트·문서만 고쳤다. 클러스터에는 아무것도 적용하지 않았다.
|
||||
|
||||
| 변경 | 파일 | 라이브에 적용하면 | 되돌리기 |
|
||||
|---|---|---|---|
|
||||
| Traefik requests `cpu: 50m`·`memory: 64Mi`, limit `memory: 256Mi` | `infrastructure/networking/traefik/base/helm-chart-config.yaml`, overlay patch 둘, `infrastructure/networking/traefik/README.md` | k3s helm-controller가 Traefik을 다시 배포한다(RollingUpdate, 몇 초). 적용은 기존 `apply-trust.sh` | 이전 HelmChartConfig 다시 적용 |
|
||||
| 이 보고서와 `docs/README.md` 지도 | `docs/` | 없음 | — |
|
||||
|
||||
### 6.1 w1에 넘긴 것: platform-postgres `pg_hba`
|
||||
|
||||
CNPG 백업(w1 범위)이 같은 파일 `services/platform-postgres/base/cluster.yaml`을 고친다. 프로그램 규칙상 w1 범위의 파일은 다른 세션이 고치지 않으므로, 이 PR에서 한 번 넣었던 변경(`1c4ef9a`)을 되돌리고(`388eb74`) w1에 넘겼다. w1은 `1c4ef9a`를 그대로 cherry-pick하면 된다.
|
||||
|
||||
- 넣을 것: `pg_hba`의 keycloak 두 줄 다음에 `- host techlog techlog all scram-sha-256`, `- host all techlog all reject`(라이브와 같은 순서). `scripts/validate/render-phase1.sh`에 Gitea·Keycloak 쌍과 같은 형식의 불변식 둘. `services/platform-postgres/README.md`의 `pg_hba` 문단에 techlog 쌍과 그 출처.
|
||||
- 이 변경으로 확인한 것(desktop, 2026-11-11):
|
||||
|
||||
```text
|
||||
$ bash scripts/validate/render-phase1.sh # 수정 전 cluster.yaml + 새 불변식
|
||||
ERROR: the tech-log role must authenticate only to the tech-log database (exit 1)
|
||||
$ bash scripts/validate/render-phase1.sh # 수정 후
|
||||
Phase 1 baseline and Gitea OIDC desired rendering invariants passed. (exit 0)
|
||||
|
||||
$ kubectl diff -f platform-postgres.yaml # 수정 후 렌더 vs 라이브
|
||||
(Cluster 차이 없음. DatabaseRole gitea의 기본값 필드 5줄만 +)
|
||||
```
|
||||
|
||||
- 넣기 전까지는 platform-postgres 렌더를 그대로 적용하지 않는다. 적용하면 hyeonworks.com backend가 DB에 못 붙는다.
|
||||
|
||||
### 6.2 Traefik 렌더 결과
|
||||
|
||||
```text
|
||||
$ kubectl kustomize infrastructure/networking/traefik/overlays/trust | kubectl diff -f -
|
||||
+ resources:
|
||||
+ requests:
|
||||
+ cpu: 50m
|
||||
+ memory: 64Mi
|
||||
+ limits:
|
||||
+ memory: 256Mi
|
||||
|
||||
$ bash infrastructure/networking/traefik/scripts/validate.sh
|
||||
Traefik observation and trust overlays rendered successfully. (exit 0)
|
||||
```
|
||||
|
||||
일부러 넣지 않은 것과 이유:
|
||||
|
||||
- PriorityClass: 붙이는 순간 Postgres·Gitea·Keycloak이 재시작된다. 재시작 시간을 소유자가 정해야 한다(7.2).
|
||||
- PDB 추가: 노드가 한 대라 가용성을 올리지 못하고 drain만 막는다. Kubernetes 문서도 단일 인스턴스는 PDB를 두지 않거나 운영자와 따로 합의하라고 한다.
|
||||
- Keycloak 원격 ref·이미지 고정: `render-phase2.sh`와 운영 적용 스크립트 `apply-keycloak.sh`가 `?ref=26.7.0` 문자열을 검사한다. 적용 스크립트의 방어 조건을 바꾸는 일이라 따로 낸다(7.4).
|
||||
- tech-log 객체 27개를 repo로 옮기기: 둘 곳이 소유자 결정이다(8절 결정 2).
|
||||
|
||||
## 7. 권하는 안과 순서 (바꾸지 않은 것)
|
||||
|
||||
위에서부터 한다. 앞 단계가 뒤 단계의 안전망이다.
|
||||
|
||||
### 7.1 백업을 먼저 (위험 1)
|
||||
|
||||
1. w1의 CNPG 백업이 들어오는 것을 기다린다(같은 HDD 경로를 쓰면 관리가 쉽다).
|
||||
2. Gitea: 주 1회 `gitea dump`(저장소·DB·설정·패키지)를 HDD로. DB는 CNPG가 따로 받으므로 `--skip-db`도 된다. 복원 리허설은 일회용 namespace에서.
|
||||
3. k3s datastore: k3s 문서대로 `/var/lib/rancher/k3s/server/db/`와 `server/token`을 같이 복사한다. token 없이는 백업을 못 쓴다. sqlite라 복사 중 쓰기를 피하려면 `sqlite3 .backup`이 안전하다(문서는 멈춤 여부를 말하지 않는다).
|
||||
4. off-host: HDD는 같은 컴퓨터 안이다. 화재·도난·전원 사고에는 소용없다. 최소 한 사본은 다른 곳으로(암호화).
|
||||
5. 경보: 「마지막 성공 백업이 N시간보다 오래됨」. Google SRE 책의 권고대로 성공 신호가 끊기면 울리게 한다.
|
||||
|
||||
### 7.2 메모리 보호와 우선순위 (위험 3, 7)
|
||||
|
||||
1. k3s drop-in 하나(`/etc/rancher/k3s/config.yaml.d/50-kubelet-reserve.yaml`)로:
|
||||
- `kubelet-arg: system-reserved=cpu=1,memory=2Gi`, `kube-reserved=cpu=500m,memory=1Gi`
|
||||
- `eviction-hard=memory.available<500Mi,nodefs.available<5%,imagefs.available<5%`(디스크 두 항목을 같이 써야 기본값이 0이 되지 않는다)
|
||||
- `eviction-soft=memory.available<1Gi`, `eviction-soft-grace-period=memory.available=1m`
|
||||
- k3s 재시작이 필요하다(운영 1~2분 중단). w1의 time-sync drop-in과 같은 창에 하면 재시작이 한 번이다.
|
||||
2. PriorityClass 둘: `platform-critical`(Postgres·Gitea·Keycloak·tech-log), `platform-low`(Grafana·pgAdmin·Loki·Tempo). 붙이는 변경은 재시작을 부르므로 1과 같은 창에.
|
||||
3. Postgres를 Guaranteed로(requests = limits, 예: CPU 2·메모리 4Gi). `oom_score_adj`가 985에서 -997로 내려간다. 노드 requests가 그만큼 늘어나니 위 예약과 같이 계산한다.
|
||||
|
||||
### 7.3 감사 로그와 관리자 자격 (위험 5)
|
||||
|
||||
1. k3s hardening 가이드의 audit policy(Metadata 수준)와 `audit-log-path`·`maxage=30`·`maxbackup=10`·`maxsize=100`. 로그는 Alloy가 Loki로 보내게 한다(호스트 밖으로는 아직 못 보낸다).
|
||||
2. 일상용 kubeconfig: 사람용 인증서(또는 Keycloak OIDC)를 새로 만들고 `cluster-admin`이 아닌 바인딩. 지금 `system:admin` 인증서는 비상용으로 오프라인 보관.
|
||||
3. 같은 drop-in 창에 `protect-kernel-defaults`(sysctl 먼저 설정), graceful node shutdown(`shutdown-grace-period=60s`, `shutdown-grace-period-critical-pods=20s`).
|
||||
|
||||
### 7.4 업그레이드·공급망 (위험 6, 9)
|
||||
|
||||
1. 업그레이드 runbook: 백업(7.1) → 같은 minor의 최신 패치(v1.36.6) → Traefik chart·이미지 고정값 갱신 → 렌더·`kubectl diff`·스모크 → 실패 시 이전 바이너리 + datastore 복원. minor는 건너뛰지 않는다(쿠버네티스 버전 차이 정책).
|
||||
2. Keycloak Operator `?ref=` 를 커밋 SHA로, Keycloak 두 이미지를 digest로, pull policy `IfNotPresent`. `render-phase2.sh`·`apply-keycloak.sh`의 검사 문자열을 같은 PR에서.
|
||||
3. `redis:7-alpine` → 고정 태그 + digest(tech-log 쪽).
|
||||
|
||||
### 7.5 파드 보안 (위험 8)
|
||||
|
||||
1. `hyeonworks-prod`에 PSA `enforce=baseline`, `warn=restricted`, `audit=restricted`. 먼저 `warn`만 붙여 경고가 없는지 본 뒤 `enforce`.
|
||||
2. tech-log 세 컨테이너에 `runAsNonRoot`, `allowPrivilegeEscalation: false`, `capabilities.drop: [ALL]`, `seccompProfile: RuntimeDefault`. frontend 이미지는 root 사용자라 이미지부터 고친다(tech-log-frontend repo).
|
||||
3. 클러스터 PSA 기본값(`admission-control-config-file`): 기본 `baseline` 강제, `kube-system`·`observability-agent` 예외. 7.3의 drop-in 창에.
|
||||
4. `keycloak` namespace 기본 차단 + egress 허용 목록.
|
||||
|
||||
### 7.6 저장소 (위험 2)
|
||||
|
||||
1. 단기(w1): 디스크 상한·경보.
|
||||
2. 중기: 상태 PV(`/srv/k3s/ssd`)를 별도 파일시스템으로. 후보는 sda(1TB SSD, 지금 Windows) 일부를 줄여 만든 파티션이나 새 SSD. 데이터 이전·Windows 디스크 변경이 걸려 소유자 결정(8절 결정 3).
|
||||
3. 기본 StorageClass `local-path`의 기본 표시를 없앤다(k3s `--disable=local-storage`나 annotation). 실수로 만든 PVC가 루트 디스크에 Delete 정책으로 생기는 것을 막는다.
|
||||
|
||||
### 7.7 drift 검출과 문서 (위험 4, 10)
|
||||
|
||||
1. 이번에 손으로 한 「렌더 → `kubectl diff`」를 스크립트로 만들어 하루 한 번 돌리고, 차이가 있으면 경보. GitOps 컨트롤러는 그다음 단계.
|
||||
2. 중앙 문서(`/home/donghyeon/workspace/docs/platform`)를 Gitea repo로 옮기고, off-host 사본을 둔다.
|
||||
3. 새 runbook: 호스트 재구축, datastore 복원, Gitea 복원, 업그레이드, 재부팅 후 확인 순서. 각각 새 세션 cold-read로 시험.
|
||||
4. kubelet 인증서 경보 둘(울릴 수 없음)을 끄고, 6443 serving 인증서 blackbox probe를 넣는다.
|
||||
|
||||
## 8. 소유자 결정이 필요한 것
|
||||
|
||||
| # | 결정 | 권하는 안 | 왜 소유자인가 |
|
||||
|---|---|---|---|
|
||||
| 1 | 백업 범위와 off-host 위치 | Gitea·k3s datastore도 w1 백업과 같은 HDD 경로에 + 암호화 off-host 사본 하나 | 비용·외부 저장소 선택·보관 기간 |
|
||||
| 2 | tech-log 운영 매니페스트의 정본 위치 | 앱 쪽(Deployment·Service·Ingress·ServiceMonitor·앱 NetworkPolicy)은 tech-log repo `deploy/`, 플랫폼 쪽 허용(DB Role·Database·pg_hba·플랫폼 namespace NetworkPolicy·Probe·PrometheusRule·대시보드)은 platform-core에 tenant 단위로. desktop 운영의 정본이 platform-core라는 것을 project-infra·project-gitops README에 한 줄 | 저장소 경계 결정. w1의 이미지 레지스트리 전환(단계 D)과 같은 결정이다 |
|
||||
| 3 | 상태 데이터 디스크 분리 | sda 일부나 새 SSD로 `/srv/k3s/ssd` 이전 | Windows 디스크 변경·데이터 이전·중단 시간 |
|
||||
| 4 | 단일 노드 구조 | 당장은 유지. CI runner와 에이전트 게이트를 다른 기계로 옮기는 것이 노드 추가보다 싸고 효과가 크다 | 하드웨어·비용 |
|
||||
| 5 | k3s 재시작 창 | 7.2·7.3·7.5의 drop-in과 w1의 time-sync drop-in을 한 번의 재시작에 | 운영 중단 시간 |
|
||||
| 6 | AIStor(Loki·Tempo) 데이터 | 잃어도 되는 데이터로 정하고 백업하지 않음 | 보관 정책 |
|
||||
|
||||
## 9. 출처
|
||||
|
||||
| 축 | 출처 | 조항·절 |
|
||||
|---|---|---|
|
||||
| A1 | <https://docs.k3s.io/datastore/backup-restore> | Backup and Restore with SQLite — `db/`와 `token`을 함께 |
|
||||
| A1·A15 | <https://sre.google/sre-book/data-integrity/> | 26장 — 복원이 되는지 정기적으로 증명, 성공 신호가 끊기면 경보 |
|
||||
| A2 | <https://docs.k3s.io/upgrades/manual>, <https://kubernetes.io/releases/version-skew-policy/> | stable 채널 권장, minor 건너뛰기 금지 |
|
||||
| A3 | <https://kubernetes.io/docs/concepts/scheduling-eviction/node-pressure-eviction/> | 기본 문턱, 하나를 바꾸면 나머지가 0이 됨(`MergeDefaultEvictionSettings`), 축출 순위 |
|
||||
| A3 | <https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/> | kubeReserved·systemReserved |
|
||||
| A3 | <https://kubernetes.io/docs/tasks/run-application/configure-pdb/> | 단일 인스턴스 stateful 앱의 PDB |
|
||||
| A3 | <https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/> | PriorityClass |
|
||||
| A4 | <https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/> | probe 종류별 쓰임 |
|
||||
| A5 | <https://kubernetes.io/docs/concepts/containers/images/> | 태그는 움직이고 digest는 고정 |
|
||||
| A5·A7·A8 | <https://kubernetes.io/docs/concepts/security/security-checklist/> | Images, Authentication & Authorization, Network security |
|
||||
| A6 | <https://docs.k3s.io/security/secrets-encryption>, <https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/> | provider 선택, aescbc 「약함」·secretbox 「강함」 |
|
||||
| A7 | <https://kubernetes.io/docs/concepts/security/rbac-good-practices/> | `system:masters`를 쓰지 말 것, 토큰 자동 마운트 끄기 |
|
||||
| A9 | <https://docs.k3s.io/security/hardening-guide> | Pod Security(`psa.yaml`), API Server audit configuration, `protect-kernel-defaults`, NetworkPolicies |
|
||||
| A9·A10 | <https://docs.k3s.io/security/self-assessment-2.0> | k3s v1.34~v1.37용 CIS v2.0 자기 평가(1.2.16~1.2.19 감사, 5.1.5·5.1.6·5.2.1·5.3.2) |
|
||||
| A10 | <https://kubernetes.io/docs/concepts/cluster-administration/node-shutdown/> | `shutdownGracePeriod` 둘 다 0이면 꺼짐 |
|
||||
| A11 | <https://docs.k3s.io/cli/certificate> | 유효 365일, 만료 120일 안이면 시작할 때 갱신(2025-05 릴리스 전에는 90일), `k3s certificate rotate` |
|
||||
| A12 | <https://kubernetes.io/docs/concepts/storage/volumes/#local>, <https://github.com/rancher/local-path-provisioner> | local PV 제약, local-path 용량 제한 없음 |
|
||||
| A13 | <https://runbooks.prometheus-operator.dev/runbooks/general/watchdog/> | Watchdog과 외부 dead man's switch |
|
||||
| A14 | <https://opengitops.dev/> | 원칙 1~4(선언, 버전 관리, 자동 pull, 지속 조정) |
|
||||
| 전체 | <https://kubernetes.io/docs/setup/production-environment/> | 단일 기계는 단일 장애점 |
|
||||
| 전체 | NSA/CISA Kubernetes Hardening Guide v1.2(2022-08), <https://media.defense.gov/2022/Aug/29/2003066362/-1/-1/0/CTR_KUBERNETES_HARDENING_GUIDANCE_1.2_20220829.PDF> | Pod security, Network separation, Authentication and authorization, Audit logging. PDF가 열리지 않아(403) 절 이름은 2차 자료로만 확인했다 |
|
||||
|
||||
CIS 4.2.6(`protect-kernel-defaults`)은 CIS v1.7부터 빠진 번호라 이 문서에서는 번호 없이 k3s hardening 가이드만 근거로 쓴다.
|
||||
|
||||
## 사고 순서 흔적 (크기: 큼)
|
||||
|
||||
1. 목적: 운영과 프로그램 전체 CI가 걸린 단일 노드 k3s의 남은 약점을 사고 전에 찾는다. 성공 기준은 축별 단계와 근거, 위험 순서 목록, drift 표, 도구 결과, 낮은 위험 수정 PR.
|
||||
2. 선행 사례: 이번 주 공유 노트 셋(디스크 복구 11-09, 파드 복구 11-11, w1 재발 방지), 이 repo의 k3s Secret 암호화·recovery drill 문서, k3s hardening 가이드·CIS 자기 평가, NSA/CISA 가이드, Kubernetes 보안 체크리스트·운영 환경 문서, OpenGitOps, Google SRE 26장. 출처는 9절.
|
||||
3. 방법: 체크리스트를 그대로 채우지 않고, 출처의 항목을 「이 노드에서 실제로 일어날 실패」로 묶어 16축으로 만들었다. 도구 점수는 그대로 쓰지 않고 FAIL마다 원인을 대조했다(kube-bench 21개, kubescape C-0012, Polaris RBAC가 오탐이었다). GitOps 컨트롤러 도입 같은 큰 처방은 버리고, 지금 손으로 한 「렌더 → `kubectl diff`」를 자동화하는 것을 먼저 권했다.
|
||||
4. 필요한 정보: 클러스터 객체 127종, kubelet configz, API 서버·컨트롤러 인자(journal), 인증서 기간, 디스크 배치(`lsblk`·`findmnt`), 렌더 결과 312개와 `kubectl diff`, 도구 넷의 결과. 모두 읽기만.
|
||||
5. 격차: 백업 0개, 상태 PV와 빌드가 같은 파일시스템, 메모리 축출 문턱 0, 우선순위 0, repo 밖 객체 27개와 그로 인한 pg_hba drift, 감사 로그 없음, 업그레이드 116일 없음(패치 4개 뒤).
|
||||
6. 만들고 시험:
|
||||
- pg_hba(w1에 넘김): 새 불변식이 수정 전 파일에서 실패(RED)하고 수정 후 통과(GREEN). 수정 후 렌더로 `kubectl diff`하면 Cluster 차이가 없다.
|
||||
- Traefik: `validate.sh` 통과, `kubectl diff`에 resources만 더해진다.
|
||||
- 이 보고서: 반증할 수 있는 가정 — 「repo를 다시 적용해도 운영이 깨지지 않는다」는 w1이 6.1절의 두 줄을 넣은 뒤에는 pg_hba에 대해 참이어야 한다. 남은 반례는 4.3의 객체들이 지워지는 경우다.
|
||||
- 큰 일의 소유자 승인: 소유자 지시 「k3s 구성의 성숙도를 보고 문제 지점을 확인하라」(template-program README 4절 W6, 2026-11-11)를 이 점검의 승인으로 보았다. 구조를 바꾸는 항목은 만들지 않고 8절에 결정으로 올렸다.
|
||||
|
||||
## 2단계 반영 (2026-11-12)
|
||||
|
||||
8절 결정은 2026-11-12 총괄이 「권하는 안으로」 확정했다(결정 1 백업 범위, 2 tech-log 정본 위치, 3 디스크 분리는 계획만, 4 단일 노드 유지,
|
||||
5 재시작 한 번, 6 AIStor 백업 안 함). 반영한 곳:
|
||||
|
||||
| 7절 | PR | 상태(2026-11-12) |
|
||||
| --- | --- | --- |
|
||||
| 7.1 백업(Gitea·k3s datastore, 복원 리허설, 신선도 경보, off-host 변수) | #6 | 열림. 설치는 소유자 sudo |
|
||||
| 7.2 kubelet 예약·메모리 축출, PriorityClass | #5(drop-in), #4(정의, 병합), #7(붙이기) | #4 병합, 라이브 적용은 소유자 |
|
||||
| 7.3 감사 로그, graceful shutdown | #5 | 열림 |
|
||||
| 7.4 업그레이드 runbook, Keycloak 커밋·digest 고정 | runbook PR, #7 | 열림 |
|
||||
| 7.5 `hyeonworks-prod` PSA, 클러스터 PSA 기본값, keycloak egress | #4(병합), #5 | 라이브 적용은 소유자 |
|
||||
| 7.6 디스크 분리 | runbook PR의 `docs/design/2026-11-12-state-disk-separation-design.md` | 계획만(결정 3) |
|
||||
| 7.7 drift 검출, runbook, kubelet 인증서 경보 | #4(병합), #6, runbook PR | — |
|
||||
|
||||
이 문서 7.3절에서 권한 `protect-kernel-defaults`는 **철회한다.** CIS가 v1.7에서 그 항목을 뺐고, 필요한 sysctl 중
|
||||
`kernel.panic_on_oops=1`은 커널 oops 한 번에 이 이중 부팅 데스크톱을 재부팅시킨다. 이유는 `infrastructure/host/k3s/README.md`.
|
||||
|
||||
API 서버 인증서 만료는 6443 blackbox probe 대신 호스트 타이머의 `openssl`로 잰다(#6). blackbox 모듈은 모두 검증하는 http라
|
||||
k3s CA를 모른다.
|
||||
@@ -0,0 +1,132 @@
|
||||
# 재부팅·k3s 재시작 뒤 확인 순서
|
||||
|
||||
desktop을 재부팅했거나 k3s를 재시작한 뒤 위에서부터 차례로 본다. 앞 단계가 틀리면 뒤 단계는 보지 않고 그 단계를 고친다.
|
||||
2026-11-11 사고(시계 +9시간 → 인증서 무효 → 502, Prometheus 수집 정지)가 이 순서를 만든 이유다.
|
||||
|
||||
```text
|
||||
1 시계 → 2 k3s·인증서 → 3 노드 → 4 파드(의존 순서) → 5 공개 경로 → 6 Prometheus 수집 → 7 경보 → 8 CI runner·호스트 타이머
|
||||
```
|
||||
|
||||
- 확인 명령은 모두 읽기만 한다. 고치는 명령은 **「고치기」** 표시를 붙였다.
|
||||
- desktop에서 일반 사용자 `donghyeon`으로 돈다. 이 사용자는 `adm`(journal 읽기)·`docker` 그룹에 있어야 하고 `~/.kube/config`가 있어야 한다.
|
||||
- 한 셸에서 위에서부터 이어서 돈다(6단계의 `$P`를 7단계가 다시 정한다).
|
||||
|
||||
## 1. 시계
|
||||
|
||||
```bash
|
||||
date -u
|
||||
timedatectl | grep -E 'Universal time|synchronized|RTC in local TZ'
|
||||
systemctl is-enabled systemd-time-wait-sync.service
|
||||
systemctl show k3s -p After | tr ' ' '\n' | grep -E 'time-sync|network-online'
|
||||
journalctl -b -o short-monotonic -u systemd-time-wait-sync -u k3s --no-pager | head -5
|
||||
```
|
||||
|
||||
- `System clock synchronized: yes`, `RTC in local TZ: no`.
|
||||
- W1의 시간 동기화 drop-in(`infrastructure/host/README.md` 2단계)을 깐 뒤: `enabled`, `After`에 `time-sync.target`, monotonic 시각으로
|
||||
time-wait-sync 줄이 k3s 시작 줄보다 앞.
|
||||
- 깔기 전: `disabled`이고 time-wait-sync 줄이 없다. 그때는 시계만 본다.
|
||||
- 부팅 때 시계가 틀렸으면 journal의 벽시계 시각은 믿을 수 없다(미래로 찍힌다). 그래서 순서는 `short-monotonic`으로 본다.
|
||||
|
||||
**고치기** — 시계가 틀렸으면 동기화를 켜고 맞춘 뒤 k3s를 재시작한다(k3s가 틀린 시각으로 인증서를 만들기 때문이다).
|
||||
|
||||
```bash
|
||||
sudo timedatectl set-ntp true
|
||||
timedatectl timesync-status | grep -E 'Server|Offset'
|
||||
sudo systemctl restart k3s
|
||||
```
|
||||
|
||||
## 2. k3s와 인증서
|
||||
|
||||
```bash
|
||||
date -u
|
||||
systemctl is-active k3s
|
||||
for p in 6443 10250; do echo | openssl s_client -connect 127.0.0.1:$p 2>/dev/null | openssl x509 -noout -startdate -enddate; done
|
||||
kubectl get --raw /readyz; echo
|
||||
```
|
||||
|
||||
- `active`, 두 인증서 모두 `notBefore`가 맨 위 `date -u`보다 **과거**, 마지막 줄 `ok`.
|
||||
- `notBefore`가 미래면 1로 돌아간다.
|
||||
|
||||
## 3. 노드
|
||||
|
||||
```bash
|
||||
kubectl get nodes -o wide
|
||||
kubectl describe node | sed -n '/Conditions:/,/Addresses:/p'
|
||||
```
|
||||
|
||||
`Ready`, `MemoryPressure`·`DiskPressure`·`PIDPressure` 모두 `False`.
|
||||
|
||||
## 4. 파드 (의존 순서대로)
|
||||
|
||||
재시작 직후에는 의존 순서 때문에 몇 번 재시작이 난다(Keycloak은 Postgres 전, tech-log는 Keycloak 전). 1~2분 기다린 뒤 본다.
|
||||
|
||||
```bash
|
||||
kubectl -n platform-data get cluster platform-postgres -o jsonpath='{.status.phase}{"\n"}'
|
||||
kubectl -n object-storage get pods
|
||||
kubectl -n keycloak get keycloak keycloak -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
|
||||
kubectl -n gitea get pods
|
||||
kubectl -n hyeonworks-prod get pods
|
||||
kubectl get pods -A --no-headers | awk '{split($3, r, "/")} $4 != "Completed" && ($4 != "Running" || r[1] != r[2])'
|
||||
```
|
||||
|
||||
- Postgres `Cluster in healthy state`, Keycloak `True`, 나머지 `Running`이고 READY가 `n/n`.
|
||||
- 마지막 명령은 아무것도 안 나와야 한다. Running인데 `0/1`인 파드도 여기서 나온다.
|
||||
|
||||
**고치기** — DaemonSet 파드가 `0/1`로 멈춰 있으면(시계가 튀었을 때 생긴다) 그 파드를 지운다. DaemonSet이 다시 만든다.
|
||||
|
||||
```bash
|
||||
kubectl -n <namespace> delete pod <name>
|
||||
```
|
||||
|
||||
## 5. 공개 경로
|
||||
|
||||
```bash
|
||||
for u in https://git.learn.hyeonworks.com/api/healthz \
|
||||
https://id.learn.hyeonworks.com/realms/hyeonworks/.well-known/openid-configuration \
|
||||
https://hyeonworks.com/ https://hyeonworks.com/api/healthcheck \
|
||||
https://grafana.learn.hyeonworks.com/api/health; do
|
||||
printf '%s %s\n' "$(curl -s -o /dev/null -m 15 -w '%{http_code}' "$u")" "$u"
|
||||
done
|
||||
```
|
||||
|
||||
- 모두 `200`.
|
||||
- `502`: 2(인증서)와 Traefik(`kubectl -n kube-system get pods -l app.kubernetes.io/name=traefik`)을 본다.
|
||||
- `000`(연결 실패): desktop에서 `*.learn.hyeonworks.com`은 사설 DNS가 Tailscale IP로 돌려주고 Host Nginx가 받는다.
|
||||
`getent hosts git.learn.hyeonworks.com`, `systemctl is-active nginx hyeonworks-dnsmasq-tailscale`를 본다.
|
||||
|
||||
## 6. Prometheus 수집
|
||||
|
||||
```bash
|
||||
P=$(kubectl -n observability get pod -l app.kubernetes.io/name=prometheus -o name | head -1)
|
||||
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'count(up == 1)'
|
||||
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'count(up == 0)'
|
||||
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'rate(prometheus_tsdb_out_of_bound_samples_total[5m])'
|
||||
```
|
||||
|
||||
- `up == 0`이 비어 있고, out-of-bound 비율이 0이어야 한다.
|
||||
- 0이 아니면 시계가 튄 동안 미래 시각 샘플이 들어간 것이다. `outOfOrderTimeWindow`(10h, PR #2)가 있으면 스스로 풀린다.
|
||||
|
||||
## 7. 경보
|
||||
|
||||
```bash
|
||||
P=$(kubectl -n observability get pod -l app.kubernetes.io/name=prometheus -o name | head -1)
|
||||
kubectl -n observability exec "$P" -c prometheus -- promtool query instant http://localhost:9090 'ALERTS{alertstate="firing"}'
|
||||
```
|
||||
|
||||
- 비어 있거나 `InfoInhibitor`만 있으면 정상이다(`InfoInhibitor`는 info 경보가 있을 때만 뜬다).
|
||||
- 알고 있는 경보: 호스트 백업을 설치했지만 node-exporter textfile 수집기가 아직 없으면 `PlatformHostBackupMetricsAbsent`가 하루 뒤부터 뜬다.
|
||||
- 그 밖의 경보, 특히 critical은 원인을 먼저 본다.
|
||||
|
||||
## 8. CI runner와 호스트 타이머
|
||||
|
||||
```bash
|
||||
docker ps --format '{{.Names}} {{.Status}}'
|
||||
for c in $(docker ps --format '{{.Names}}'); do printf '%s ' "$c"; docker inspect -f '{{.State.Status}} restarts={{.RestartCount}} started={{.State.StartedAt}}' "$c"; done
|
||||
systemctl list-timers 'platform-*' --no-pager
|
||||
```
|
||||
|
||||
- runner(`gitea-runner`)가 `running restarts=0`이어야 한다.
|
||||
- `Up Less than a second`로 보여도 `restarts=0`이고 `started`가 미래 시각이면 크래시가 아니다. 부팅 때 시계가 +9시간이던 동안 시작된
|
||||
컨테이너라 Docker가 시작 시각을 미래로 적은 것이다(2026-11-11에 실제로 있었다).
|
||||
- 다른 컨테이너: `workmachine`은 소유자의 작업용 컨테이너, `*cloudflared`는 Cloudflare 터널이다. 둘 다 이 저장소 밖이라 여기서는 떠 있는지만 본다.
|
||||
- 호스트 타이머(`services/platform-host-checks/README.md`)를 설치하기 전에는 `0 timers listed`가 정상이다. 설치 뒤에는 네 개가 다음 실행 시각을 갖는다.
|
||||
@@ -0,0 +1,154 @@
|
||||
# Gitea 복원
|
||||
|
||||
Gitea의 파일(저장소, 패키지, 첨부, Actions 산출물, `app.ini`)을 주간 dump에서 되살리는 절차다.
|
||||
Gitea DB는 dump에 없다(`--skip-db`). DB는 CNPG 백업에 있다.
|
||||
|
||||
## 전제와 확인 — 하나라도 아니면 이 문서는 아직 못 쓴다
|
||||
|
||||
| 전제 | 확인 |
|
||||
| --- | --- |
|
||||
| platform-core checkout이 최신 main이고 호스트 백업(PR #6)이 들어 있다 | `cd /home/donghyeon/workspace/platform && git pull --ff-only && ls scripts/validate/gitea-backup-restore-drill.sh` |
|
||||
| 호스트 백업이 설치됐다(`/usr/local/lib/platform-backup`, `/etc/platform-backup/aistor.env`) | `sudo ls /usr/local/lib/platform-backup/lib/host-backup.sh /etc/platform-backup/aistor.env` |
|
||||
| Gitea dump가 하나 이상 있다 | `systemctl list-timers platform-gitea-backup.timer --no-pager`와 `journalctl -u platform-gitea-backup -n 3 --no-pager`의 `uploaded` |
|
||||
| DB까지 되살릴 때: CNPG 백업이 있다(W1, `services/platform-postgres-backup`) | `kubectl -n platform-data get backup` |
|
||||
| k3s·AIStor가 정상 | `after-reboot-checks.md` 2~4 |
|
||||
|
||||
2026-11-12 현재는 호스트 백업(PR #6)과 CNPG 백업(W1)이 설치되기 전이라 되살릴 백업이 없다.
|
||||
|
||||
## 어느 경우인가
|
||||
|
||||
| 경우 | DB | 이 문서 |
|
||||
| --- | --- | --- |
|
||||
| A. Gitea PV만 잃었다(DB는 멀쩡) | 그대로 둔다 | 1~6 |
|
||||
| B. DB도 잃었다(루트 SSD 전체 등) | CNPG로 먼저 되살린다 | 0 → 1~6 |
|
||||
|
||||
**B의 경고**: platform-postgres 하나에 Gitea·Keycloak·tech-log DB가 같이 있다. CNPG를 어떤 시점으로 되돌리면 세 DB가 모두
|
||||
그 시점으로 간다. dump 시각(일요일 04:00 KST)에 맞추려고 과거로 PITR하면 Keycloak 사용자 변경과 tech-log 글도 그 시각으로 돌아간다.
|
||||
그래서 B에서도 DB는 **가장 최근 시점**으로 되살리고, dump 뒤에 만든 저장소는 파일이 없다는 것을 받아들인다(6단계에서 찾아낸다).
|
||||
|
||||
## 0. (B만) DB를 되살린다
|
||||
|
||||
W1의 CNPG 백업 문서를 따른다. 끝나면 `kubectl -n platform-data get cluster platform-postgres -o jsonpath='{.status.phase}'`가
|
||||
`Cluster in healthy state`여야 한다.
|
||||
|
||||
## 1. dump를 내려받고 확인한다
|
||||
|
||||
```bash
|
||||
sudo -i
|
||||
```
|
||||
|
||||
```bash
|
||||
TS=$(date +%Y%m%d%H%M)
|
||||
. /usr/local/lib/platform-backup/lib/host-backup.sh && hb_load_aistor_env
|
||||
W=$(mktemp -d /var/lib/platform-backup/work/gitea-restore.XXXXXX)
|
||||
hb_mc "$W" ls "backup/$AISTOR_BUCKET/gitea/"
|
||||
D=$(hb_mc "$W" ls "backup/$AISTOR_BUCKET/gitea/" | awk '{print $NF}' | grep -E '^gitea-dump-.*\.tar\.gz$' | sort | tail -1); echo "$D"
|
||||
hb_mc "$W" cp "backup/$AISTOR_BUCKET/gitea/$D" "backup/$AISTOR_BUCKET/gitea/$D.sha256" "backup/$AISTOR_BUCKET/gitea/$D.meta" /work/
|
||||
[ "$(sha256sum "$W/$D" | awk '{print $1}')" = "$(cat "$W/$D.sha256")" ] && echo checksum-ok
|
||||
cat "$W/$D.meta"
|
||||
bash /home/donghyeon/workspace/platform/scripts/validate/gitea-backup-restore-drill.sh --from-file "$W/$D"
|
||||
```
|
||||
|
||||
- `hb_mc <폴더> <mc 인자>`는 고정된 AIStor client를 그 폴더를 `/work`로 붙여 돌린다.
|
||||
- `checksum-ok`, 그리고 리허설 끝의 `repositories in dump: N, fsck failures: 0`과 `GITEA RESTORE DRILL PASS`.
|
||||
- `.meta`의 `gitea_image`가 지금 Deployment 이미지와 같아야 한다:
|
||||
`kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}'`. 다르면 먼저 Gitea를 그 버전으로 맞춘다
|
||||
(dump를 만든 버전보다 낮은 Gitea로 올리면 DB·파일 형식이 안 맞을 수 있다).
|
||||
|
||||
## 2. 창을 잡고 Gitea를 멈춘다
|
||||
|
||||
```bash
|
||||
docker exec gitea-runner docker ps -q | wc -l # 0이어야 한다(CI job 없음)
|
||||
curl -s -o /dev/null -D - 'https://git.learn.hyeonworks.com/api/v1/repos/search?limit=1' | grep -i '^x-total-count' # 복원 전 공개 저장소 수를 적어 둔다
|
||||
kubectl -n gitea scale deploy/gitea --replicas=0
|
||||
kubectl -n gitea wait --for=delete pod -l app.kubernetes.io/name=gitea --timeout=5m
|
||||
```
|
||||
|
||||
이때부터 git.learn.hyeonworks.com이 내려간다(CI 포함).
|
||||
|
||||
## 3. 지금 PV를 복사해 둔다 (덮어쓰기 전에)
|
||||
|
||||
```bash
|
||||
df -h /srv/k3s/ssd # Gitea 데이터는 2026-11 기준 약 370MB
|
||||
cp -a /srv/k3s/ssd/gitea /srv/k3s/ssd/gitea.before-restore-$TS
|
||||
```
|
||||
|
||||
PV를 완전히 잃은 경우(빈 폴더)는 건너뛴다.
|
||||
|
||||
## 4. 임시 파드로 PV에 푼다
|
||||
|
||||
dump 안의 경로와 PV(`/data`) 경로:
|
||||
|
||||
| dump | PV |
|
||||
| --- | --- |
|
||||
| `app.ini` | `/data/gitea/conf/app.ini` |
|
||||
| `data/*` | `/data/*` (actions_artifacts, actions_log, packages, attachments, avatars …) |
|
||||
| `repos/*` | `/data/git/gitea-repositories/*` |
|
||||
| `custom/*` | `/data/gitea/*` (있을 때만) |
|
||||
|
||||
```bash
|
||||
IMAGE=$(kubectl -n gitea get deploy gitea -o jsonpath='{.spec.template.spec.containers[0].image}')
|
||||
kubectl -n gitea run gitea-restore --image="$IMAGE" --restart=Never --overrides='{
|
||||
"spec": {
|
||||
"securityContext": {"runAsUser": 1000, "runAsGroup": 1000, "fsGroup": 1000, "runAsNonRoot": true,
|
||||
"seccompProfile": {"type": "RuntimeDefault"}},
|
||||
"containers": [{"name": "restore", "image": "'"$IMAGE"'", "command": ["sleep", "3600"],
|
||||
"securityContext": {"allowPrivilegeEscalation": false, "capabilities": {"drop": ["ALL"]}},
|
||||
"volumeMounts": [{"name": "data", "mountPath": "/data"}]}],
|
||||
"volumes": [{"name": "data", "persistentVolumeClaim": {"claimName": "gitea-data"}}]}}'
|
||||
kubectl -n gitea wait --for=condition=Ready pod/gitea-restore --timeout=2m
|
||||
kubectl -n gitea cp "$W/$D" gitea-restore:/data/restore.tar.gz
|
||||
kubectl -n gitea exec gitea-restore -- sh -ec '
|
||||
cd /data && rm -rf restore && mkdir restore && tar -C restore -xzf restore.tar.gz
|
||||
mkdir -p /data/gitea/conf /data/git/gitea-repositories
|
||||
[ -f /data/gitea/conf/app.ini ] && cp /data/gitea/conf/app.ini /data/gitea/conf/app.ini.before-restore || true
|
||||
cp restore/app.ini /data/gitea/conf/app.ini
|
||||
cp -a restore/data/. /data/
|
||||
cp -a restore/repos/. /data/git/gitea-repositories/
|
||||
[ -d restore/custom ] && cp -a restore/custom/. /data/gitea/ || true
|
||||
rm -rf restore restore.tar.gz
|
||||
find /data/git/gitea-repositories -mindepth 2 -maxdepth 2 -name "*.git" -type d | wc -l'
|
||||
kubectl -n gitea delete pod gitea-restore
|
||||
```
|
||||
|
||||
- 마지막 숫자가 1단계 리허설의 `N`과 같아야 한다.
|
||||
- PV에 옛 파일이 남아 있는 경우(A에서 일부만 잃음) `cp -a`는 덮어쓰고 지우지는 않는다. dump에 없는 옛 저장소를 남기고 싶지
|
||||
않으면 `tar` 줄 앞에 `rm -rf /data/git/gitea-repositories/* /data/packages/*`를 넣는다(3의 사본이 있을 때만).
|
||||
|
||||
## 5. Gitea를 다시 띄운다
|
||||
|
||||
```bash
|
||||
kubectl -n gitea scale deploy/gitea --replicas=1
|
||||
kubectl -n gitea rollout status deploy/gitea --timeout=10m
|
||||
kubectl -n gitea exec deploy/gitea -c gitea -- gitea admin regenerate hooks
|
||||
kubectl -n gitea exec deploy/gitea -c gitea -- gitea doctor check --all 2>&1 | tail -20
|
||||
```
|
||||
|
||||
chart의 init 컨테이너가 시작할 때 Secret 값으로 `app.ini`를 다시 맞춘다. dump의 `app.ini`에서 오는 것은 Secret에 없는 생성 값
|
||||
(`INTERNAL_TOKEN`, `SECRET_KEY`, JWT 키)이다. 이것이 맞아야 2FA·토큰이 계속 쓰인다.
|
||||
|
||||
## 6. 확인
|
||||
|
||||
```bash
|
||||
curl -fsS -o /dev/null -w '%{http_code}\n' https://git.learn.hyeonworks.com/api/healthz
|
||||
curl -s -o /dev/null -D - 'https://git.learn.hyeonworks.com/api/v1/repos/search?limit=1' | grep -i '^x-total-count'
|
||||
git ls-remote https://git.learn.hyeonworks.com/donghyeon.kang/platform-core.git HEAD
|
||||
kubectl -n gitea exec deploy/gitea -c gitea -- gitea doctor check --run check-db-consistency 2>&1 | tail -5
|
||||
```
|
||||
|
||||
- `200`, 2단계에서 적어 둔 공개 저장소 수와 같은 수, `HEAD` 해시.
|
||||
- 웹에서 로그인(Keycloak OIDC), 패키지 화면의 `grpc-library`·`messaging-library`(1.0.0, `dev.cakit.*`), Actions 기록을 한 번씩 본다.
|
||||
- DB에는 있는데 파일이 없는 저장소(dump 뒤에 만든 것)는 웹에서 열면 오류가 난다. 노트북 clone에서 다시 push한다.
|
||||
- runner가 다시 붙었는지 본다(`infrastructure/ci/gitea-runner/README.md`).
|
||||
|
||||
## 되돌리기
|
||||
|
||||
- 4 도중 실패: Gitea를 0으로 둔 채 임시 파드를 다시 띄워 `cp /data/gitea/conf/app.ini.before-restore /data/gitea/conf/app.ini`
|
||||
(4의 `kubectl run` 명령, `exec` 부분만 바꿔서).
|
||||
- 4를 끝낸 뒤: Gitea를 0으로 줄이고 `rm -rf /srv/k3s/ssd/gitea && mv /srv/k3s/ssd/gitea.before-restore-$TS /srv/k3s/ssd/gitea` 후 1로.
|
||||
|
||||
## 끝나면
|
||||
|
||||
```bash
|
||||
rm -rf "$W" # 하루 지켜본 뒤: rm -rf /srv/k3s/ssd/gitea.before-restore-$TS
|
||||
```
|
||||
@@ -0,0 +1,164 @@
|
||||
# 호스트 재구축 (루트 SSD를 잃었을 때)
|
||||
|
||||
desktop의 루트 SSD를 잃고 HDD(WDC 2TB, AIStor 파티션 라벨 `AISTOR_DATA`)는 살아 있을 때, 새 SSD에서 플랫폼을 되살리는 순서다.
|
||||
각 단계의 자세한 명령은 링크한 문서를 따른다. 이 문서는 **순서와 빠지기 쉬운 것**을 정한다.
|
||||
|
||||
## 전제와 확인 — 하나라도 아니면 4·7·8단계에서 멈춘다
|
||||
|
||||
| 전제 | 확인 |
|
||||
| --- | --- |
|
||||
| HDD의 k3s datastore 로컬 사본이 있다(PR #6 호스트 백업이 설치돼 돌았다) | 2단계 mount 뒤 `sudo ls /srv/k3s/aistor/host-backups/k3s-datastore/` |
|
||||
| CNPG 백업이 AIStor에 있다(W1) | 6단계 뒤 AIStor `platform-postgres-backups` bucket |
|
||||
| Gitea dump가 AIStor에 있다(PR #6) | 6단계 뒤 AIStor `platform-host-backups/gitea/` |
|
||||
|
||||
2026-11-12 현재는 세 백업 모두 설치되기 전이다. 그 전에는 datastore 대신 이 저장소의 bootstrap 절차(`bootstrap/manual/phase1~4`)로
|
||||
처음부터 다시 세워야 하고, Secret은 소유자가 새로 넣어야 한다.
|
||||
|
||||
## 무엇이 남고 무엇을 잃나
|
||||
|
||||
| 남음 (HDD, xfs `AISTOR_DATA`) | 잃음 (루트 SSD) |
|
||||
| --- | --- |
|
||||
| AIStor 데이터(`/srv/k3s/aistor/data`): Loki·Tempo, CNPG 백업, Gitea dump | OS, k3s, Docker(`/var/lib/docker`: runner, `workmachine`, `*cloudflared` 컨테이너), 모든 SSD Local PV |
|
||||
| k3s datastore 로컬 사본(`/srv/k3s/aistor/host-backups/k3s-datastore/`) | `/etc`(nginx, certbot 인증서, dnsmasq, `/etc/platform-backup`), `~/.secrets` |
|
||||
| | `/etc/rancher/k3s/platform-post-bundle.env`, `platform-restore-evidence.env`(2026-08 Secret 암호화 hardening의 증거 표시. 운영에는 필요 없고, `bootstrap/manual/k3s-secret-encryption.md` 검사기가 「증거 없음」으로 볼 뿐이다) |
|
||||
|
||||
desktop 전체를 잃으면 HDD도 잃는다. 그때는 off-host 사본이 있어야 한다(`services/platform-host-checks/README.md`).
|
||||
|
||||
## 시작 전에 소유자가 따로 가지고 있어야 하는 것
|
||||
|
||||
k3s datastore를 복원하면 쿠버네티스 Secret은 모두 돌아온다. 아래는 그 밖의 것이다.
|
||||
|
||||
- platform-core 저장소 사본(Gitea가 내려가 있으므로 노트북 clone이나 off-host 사본). 이 문서는 desktop의
|
||||
`/home/donghyeon/workspace/platform`에 clone했다고 보고, 모든 상대경로는 거기 기준이다.
|
||||
- Tailscale 계정(사설 DNS가 Tailscale 주소를 쓴다), Cloudflare API token(certbot DNS 인증), certbot 연락 email
|
||||
- Slack webhook 복구 경로(KeePass, `scripts/bootstrap/backup-slack-webhook-recovery.sh`)
|
||||
- off-host 백업을 쓴다면 그 개인 키
|
||||
- hyeonworks.com 앞단 설정과 tech-log 이미지·매니페스트: **이 저장소에 없다.** tech-log-backend·tech-log-frontend 저장소를 따른다.
|
||||
- `workmachine`과 `*cloudflared` 컨테이너: 소유자의 별도 설정이다. 이 저장소에 재구축 절차가 없다.
|
||||
|
||||
## 순서
|
||||
|
||||
```text
|
||||
1 OS·이름·도구·시계 → 2 HDD mount → 3 k3s 설치(시작 안 함) + 시간 동기화 drop-in → 4 datastore 복원(첫 시작)
|
||||
→ 5 Local PV 폴더 → 6 AIStor 확인 → 7 Postgres 복원(CNPG) → 8 호스트 백업 다시 설치 → 9 Gitea 파일 복원
|
||||
→ 10 호스트 설정(Tailscale·DNS·nginx·TLS·Docker·runner·재시작 묶음) → 11 확인(Gitea 확인 포함)
|
||||
```
|
||||
|
||||
### 1. OS, 호스트 이름, 도구, 시계
|
||||
|
||||
- Ubuntu 24.04, 사용자 `donghyeon`(uid 1000. Gitea rootless와 AIStor 폴더 소유자가 1000이다).
|
||||
- **호스트 이름을 `donghyeon-system-product-name`으로 둔다.** 모든 Local PV의 `nodeAffinity`가
|
||||
`kubernetes.io/hostname=donghyeon-system-product-name`을 본다. 이름이 다르면 PV를 쓰는 파드가 전부 Pending이다.
|
||||
|
||||
```bash
|
||||
sudo hostnamectl set-hostname donghyeon-system-product-name
|
||||
```
|
||||
|
||||
- 패키지: `git jq ripgrep sqlite3 curl openssl python3-yaml nginx dnsmasq`, snap `certbot`과 `certbot-dns-cloudflare`.
|
||||
Docker는 공식 apt 저장소로 설치하고 `donghyeon`을 `docker` 그룹에 넣는다. Helm `v3.19.4`를 `~/.local/bin/helm`에 둔다
|
||||
(렌더 스크립트가 정확한 버전을 요구한다).
|
||||
- 시계: `sudo timedatectl set-local-rtc 0`, `sudo timedatectl set-ntp true`. Windows 쪽 `RealTimeIsUniversal`은 W1
|
||||
`infrastructure/host/README.md` 3단계(W1 PR).
|
||||
|
||||
### 2. HDD mount
|
||||
|
||||
새 SSD를 달면 디스크 이름(sda·sdb·sdc)이 바뀔 수 있다. 이름이 아니라 라벨로 찾는다.
|
||||
|
||||
```bash
|
||||
lsblk -o NAME,SIZE,FSTYPE,LABEL,MODEL # LABEL=AISTOR_DATA, xfs, WDC 2TB 쪽
|
||||
echo 'LABEL=AISTOR_DATA /srv/k3s/aistor xfs defaults,noatime 0 2' | sudo tee -a /etc/fstab # 2026-11-12 live fstab과 같은 줄
|
||||
sudo findmnt --verify # 오류가 없어야 한다. 있으면 fstab 줄을 고치고 다시 본다(틀린 fstab은 다음 부팅을 emergency mode로 보낸다)
|
||||
sudo mkdir -p /srv/k3s/aistor && sudo mount /srv/k3s/aistor
|
||||
ls /srv/k3s/aistor # data host-backups
|
||||
```
|
||||
|
||||
### 3. k3s 설치 (시작하지 않은 채로) + 시간 동기화 drop-in
|
||||
|
||||
먼저 HDD의 백업에서 버전을 본다(`k3s-datastore-restore.md` 1단계: `cat "$D/META"`의 `k3s_version`). 아래 `<META 버전>`에 넣는다.
|
||||
|
||||
```bash
|
||||
curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION='<META 버전>' INSTALL_K3S_SKIP_START=true \
|
||||
INSTALL_K3S_EXEC='server --disable=servicelb' sh -
|
||||
cd /home/donghyeon/workspace/platform
|
||||
sudo install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml
|
||||
sudo install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml
|
||||
```
|
||||
|
||||
**k3s를 처음 시작하기 전에** W1의 시간 동기화 drop-in을 깐다(`infrastructure/host/README.md` 2단계, W1 PR). 11-11 사고는
|
||||
틀린 시계로 k3s가 인증서를 만든 것이었다. 재시작 묶음(PR #5)은 클러스터가 떠 있어야 도는 스크립트라 10단계에서 깐다.
|
||||
|
||||
### 4. datastore 복원 (k3s 첫 시작)
|
||||
|
||||
`k3s-datastore-restore.md` 1·3·4·5단계(2단계는 「새로 설치한 호스트」 경우). 이때 PV 폴더가 없어 Postgres·Gitea 파드는 뜨지 못한다. 정상이다.
|
||||
|
||||
### 5. Local PV 폴더
|
||||
|
||||
```bash
|
||||
sudo bash scripts/bootstrap/prepare-ssd-local-paths.sh
|
||||
sudo bash scripts/bootstrap/prepare-observability-local-paths.sh --execute # 인자 없으면 dry run이다
|
||||
sudo install -d -o root -g root -m 0750 /srv/k3s/ssd/pgadmin # 위 둘이 만들지 않는다(apply-admin-services.sh가 만들던 것)
|
||||
```
|
||||
|
||||
빈 폴더가 생긴다. 관측 스택(Prometheus·Loki 캐시·Grafana)은 빈 PV로 다시 쌓인다. Grafana 대시보드는 repo의 ConfigMap에서 다시 생긴다.
|
||||
|
||||
### 6. AIStor
|
||||
|
||||
AIStor의 PV는 HDD라 데이터가 그대로다. Secret(라이선스, root 설정)도 datastore에서 돌아왔다.
|
||||
|
||||
```bash
|
||||
kubectl -n object-storage get pods
|
||||
kubectl -n object-storage get objectstore -o wide
|
||||
bash scripts/validate/aistor-s3-smoke.sh --execute # 임시 bucket을 만들고 쓰고 지운다(쓰기 작업)
|
||||
```
|
||||
|
||||
`Initialized/green`, 마지막 줄 `AISTOR_S3_SMOKE_PASS bucket-create object-write object-read object-delete bucket-delete`.
|
||||
|
||||
### 7. platform-postgres 복원
|
||||
|
||||
datastore에는 `Cluster` 정의가 있지만 PV는 비어 있다. CNPG를 AIStor 백업(`platform-postgres-backups`)에서 되살린다.
|
||||
Gitea·Keycloak·tech-log DB가 모두 여기 있다.
|
||||
|
||||
먼저 원본 정의를 남긴다(되살린 Cluster가 원래와 같은지 비교할 기준이다):
|
||||
|
||||
```bash
|
||||
kubectl -n platform-data get cluster platform-postgres -o yaml > /root/platform-postgres-cluster-before-rebuild.yaml
|
||||
```
|
||||
|
||||
- W1의 `services/platform-postgres-backup/README.md`(W1 PR)에는 임시 Cluster로 하는 「복원 리허설」이 있다. 그 `restore-drill/cluster.yaml`의
|
||||
`bootstrap.recovery`를 쓰는 방식이다.
|
||||
- **운영 Cluster를 백업으로 갈아 끼우는 절차(빈 PV의 `platform-postgres`를 지우고 같은 이름으로 recovery bootstrap)는 아직 문서가 없다(W1 몫).**
|
||||
그 문서가 생기기 전에는 리허설 절차를 이름만 `platform-postgres`로 바꿔 따르고, 위에서 남긴 원본과 `pg_hba`(techlog 두 줄 포함)·
|
||||
Secret 참조·resources가 같은지 비교한다.
|
||||
|
||||
### 8. 호스트 백업 다시 설치
|
||||
|
||||
`/etc/platform-backup/aistor.env`와 `/usr/local/lib/platform-backup`은 SSD와 함께 잃었다. 9단계(Gitea 복원)가 이것을 쓴다.
|
||||
`services/platform-host-checks/README.md` 「적용」의 `create-host-backup-credentials.sh`(AIStor에 새 사용자를 하나 더 만든다)와
|
||||
`install-host-checks.sh --execute`를 돈다. 첫 실행 백업은 「복원 직후 상태」의 백업이 된다.
|
||||
|
||||
### 9. Gitea 파일 복원
|
||||
|
||||
`gitea-restore.md`의 경우 B(DB는 7에서 되살렸다), 1~5단계. **6단계 확인 중 https·로그인은 10단계(nginx·TLS·DNS) 뒤로 미룬다.**
|
||||
그 전에는 `kubectl -n gitea get pods`와 저장소 수만 본다.
|
||||
|
||||
### 10. 호스트 설정
|
||||
|
||||
| 무엇 | 문서 |
|
||||
| --- | --- |
|
||||
| Tailscale 설치·로그인 | 사설 DNS(`infrastructure/networking/private-dns/host/dnsmasq-tailscale.conf`)가 Tailscale 주소 `100.92.240.34`를 고정해 쓴다. 새로 로그인해 주소가 바뀌면 이 파일의 `listen-address`·`address=` 줄을 새 주소로 바꾸는 PR을 낸다 |
|
||||
| 사설 DNS(dnsmasq LAN·Tailscale) | `infrastructure/networking/private-dns/host/README.md` |
|
||||
| Host Nginx와 TLS | `infrastructure/networking/host-nginx/README.md`는 전환 기록이라 빈 호스트 설치 절차가 아니다. 이 저장소의 `learn-services*.conf`를 `/etc/nginx/sites-available/`에 두고, 인증서는 `bootstrap/manual/phase3-admin-surfaces.md`의 certbot 절차로 다시 받는다. 빈 호스트용 절차는 아직 없다 |
|
||||
| Docker daemon.json, runner 상한·정리 | W1 `infrastructure/host/README.md` 4단계, `infrastructure/ci/gitea-runner/README.md` |
|
||||
| Gitea Actions runner 재등록 | `infrastructure/ci/gitea-runner/README.md` |
|
||||
| k3s 재시작 묶음(kubelet 예약·audit·PSA) | `infrastructure/host/k3s/README.md`(PR #5) |
|
||||
| tech-log 운영 이미지 | Gitea 패키지 레지스트리에서 다시 받는다(W1의 레지스트리 전환 뒤). 9단계 dump에 패키지가 들어 있다 |
|
||||
|
||||
### 11. 확인
|
||||
|
||||
`after-reboot-checks.md`를 처음부터 끝까지 돈다(8단계의 `workmachine`·`*cloudflared`는 이 저장소 밖이라 없을 수 있다).
|
||||
`gitea-restore.md` 6단계를 마저 한다. 그다음 repo와의 차이를 본다:
|
||||
|
||||
```bash
|
||||
cd /home/donghyeon/workspace/platform
|
||||
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt
|
||||
```
|
||||
@@ -0,0 +1,154 @@
|
||||
# k3s datastore 복원
|
||||
|
||||
k3s datastore(sqlite)를 백업에서 되살리는 절차다. 쿠버네티스 객체 전부(Deployment, Secret, CNPG Cluster 정의 등)가 여기에 있다.
|
||||
**PV 안의 데이터(Postgres, Gitea 파일)는 여기에 없다.** 그것은 `gitea-restore.md`와 CNPG 복원으로 따로 되살린다.
|
||||
|
||||
## 전제와 확인 — 하나라도 아니면 이 문서는 아직 못 쓴다
|
||||
|
||||
| 전제 | 확인 |
|
||||
| --- | --- |
|
||||
| platform-core checkout이 최신 main이고 호스트 백업(PR #6)이 들어 있다 | `cd /home/donghyeon/workspace/platform && git pull --ff-only && ls scripts/validate/k3s-datastore-restore-drill.sh` |
|
||||
| 호스트 백업이 설치돼 백업이 하나 이상 있다(`services/platform-host-checks/README.md`) | `sudo ls -1t /srv/k3s/aistor/host-backups/k3s-datastore/ \| head -3` |
|
||||
| root 셸 | 아래 `sudo -i`를 **따로 먼저** 친다(블록째 붙이면 비밀번호 줄을 먹는다) |
|
||||
|
||||
2026-11-12 현재 호스트 백업은 PR #6이 설치되기 전이라 백업이 없다.
|
||||
|
||||
## 언제 쓰나
|
||||
|
||||
| 상황 | 이 문서 |
|
||||
| --- | --- |
|
||||
| datastore가 깨져 k3s가 안 뜬다(`journalctl -u k3s`에 sqlite/kine 오류) | 예, 같은 호스트 |
|
||||
| 루트 SSD를 잃었다 | 예, `host-rebuild.md`의 한 단계로 |
|
||||
| 객체 몇 개를 실수로 지웠다 | 아니오. repo에서 다시 적용한다(drift 검사로 무엇이 없는지 본다) |
|
||||
|
||||
## 1. 백업을 고르고 확인한다
|
||||
|
||||
```bash
|
||||
sudo -i
|
||||
```
|
||||
|
||||
```bash
|
||||
TS=$(date +%Y%m%d%H%M)
|
||||
cd /srv/k3s/aistor/host-backups/k3s-datastore
|
||||
B=$(ls -1t k3s-datastore-*.tar.gz | head -1); echo "$B"
|
||||
[ "$(sha256sum "$B" | awk '{print $1}')" = "$(cat "$B.sha256")" ] && echo checksum-ok # .sha256에는 해시만 들어 있다
|
||||
W=/root/k3s-restore-$TS && mkdir -m 0700 "$W" && tar -C "$W" -xzf "$B" && D=$(ls -d "$W"/k3s-datastore-*) && ls "$D"
|
||||
cat "$D/META"
|
||||
sqlite3 "$D/state.db" 'PRAGMA integrity_check;'
|
||||
```
|
||||
|
||||
`checksum-ok`, `META state.db token`, `ok`가 보여야 한다.
|
||||
|
||||
다른 백업 위치(로컬 사본이 없을 때):
|
||||
|
||||
- AIStor(AIStor가 떠 있을 때). `hb_mc <폴더> <mc 인자>`는 고정된 AIStor client를 그 폴더를 `/work`로 붙여 돌린다(키는 그 폴더의 0600 env 파일로 간다).
|
||||
|
||||
```bash
|
||||
. /usr/local/lib/platform-backup/lib/host-backup.sh && hb_load_aistor_env
|
||||
M=$(mktemp -d /root/k3s-fetch.XXXXXX)
|
||||
hb_mc "$M" ls "backup/$AISTOR_BUCKET/k3s-datastore/"
|
||||
hb_mc "$M" cp "backup/$AISTOR_BUCKET/k3s-datastore/<이름>" "backup/$AISTOR_BUCKET/k3s-datastore/<이름>.sha256" /work/
|
||||
rm -f "$M/.mc.env"; cd "$M" # 이 폴더에서 1단계의 B= 이하를 이어서 한다
|
||||
```
|
||||
- off-host 암호화 사본: 소유자가 개인 키가 있는 기계에서 `gpg --decrypt <이름>.tar.gz.gpg > <이름>.tar.gz` 후 desktop으로 옮긴다.
|
||||
|
||||
### 버전을 맞춘다
|
||||
|
||||
`META`의 `k3s_version`과 지금 k3s가 같아야 한다(`/usr/local/bin/k3s --version | head -1`). 다르면 `k3s-upgrade.md` 3단계 설치 명령에
|
||||
`META`의 버전을 넣어 그 버전으로 설치한다.
|
||||
|
||||
### 먼저 리허설한다 (운영에 손대지 않음)
|
||||
|
||||
```bash
|
||||
bash /home/donghyeon/workspace/platform/scripts/validate/k3s-datastore-restore-drill.sh --from-dir "$D"
|
||||
```
|
||||
|
||||
`K3S DATASTORE RESTORE DRILL PASS`와 `restored: namespaces=… secrets=N …` 줄이 나와야 한다. 이 `N`이 5단계의 기준값이다.
|
||||
|
||||
## 2. k3s를 멈추고 지금 상태를 옮겨 둔다
|
||||
|
||||
같은 호스트에서 깨진 datastore를 바꾸는 경우:
|
||||
|
||||
```bash
|
||||
systemctl stop k3s
|
||||
/usr/local/bin/k3s-killall.sh # 컨테이너까지 멈춘다. 복원 중 파드가 옛 상태로 돌지 않게
|
||||
mv /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/db.before-restore-$TS
|
||||
cp -a /var/lib/rancher/k3s/server/token /var/lib/rancher/k3s/server/token.before-restore-$TS
|
||||
```
|
||||
|
||||
새로 설치한 호스트(`host-rebuild.md`)는 k3s를 `INSTALL_K3S_SKIP_START=true`로 설치해 **한 번도 시작하지 않은** 상태여야 한다.
|
||||
실수로 한 번 시작했다면 그때 생긴 빈 클러스터의 파일을 지운다(잃을 것이 없다):
|
||||
|
||||
```bash
|
||||
systemctl stop k3s && /usr/local/bin/k3s-killall.sh
|
||||
rm -rf /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/tls /var/lib/rancher/k3s/server/cred /var/lib/rancher/k3s/server/token
|
||||
```
|
||||
|
||||
## 3. 백업을 넣는다
|
||||
|
||||
```bash
|
||||
install -d -m 0700 /var/lib/rancher/k3s/server/db
|
||||
install -m 0600 "$D/state.db" /var/lib/rancher/k3s/server/db/state.db
|
||||
install -m 0600 "$D/token" /var/lib/rancher/k3s/server/token
|
||||
```
|
||||
|
||||
k3s 문서(datastore/backup-restore, SQLite)대로 `db/`와 `token`을 함께 넣는다. token이 다르면 datastore 안의 암호화 설정과 인증서를 풀지 못한다.
|
||||
|
||||
## 4. k3s 설정이 백업 때와 같은지 본다
|
||||
|
||||
`secrets-encryption: true`가 없으면 Secret을 읽지 못한다. 없으면 checkout에서 넣는다.
|
||||
|
||||
```bash
|
||||
ls /etc/rancher/k3s/config.yaml.d/
|
||||
```
|
||||
|
||||
```bash
|
||||
cd /home/donghyeon/workspace/platform
|
||||
install -D -m 0644 infrastructure/host/k3s/config.yaml.d/30-nodeport-loopback.yaml /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml
|
||||
install -D -m 0644 infrastructure/security/k3s/40-secrets-encryption.yaml /etc/rancher/k3s/config.yaml.d/40-secrets-encryption.yaml
|
||||
```
|
||||
|
||||
재시작 묶음(PR #5)을 적용했던 호스트라면 `bash scripts/bootstrap/apply-k3s-restart-bundle.sh --check`로 무엇이 빠졌는지 보고,
|
||||
5단계가 끝난 뒤 `--execute`로 다시 깐다.
|
||||
|
||||
## 5. k3s를 시작하고 확인한다
|
||||
|
||||
```bash
|
||||
systemctl start k3s
|
||||
until k3s kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready
|
||||
k3s kubectl get nodes
|
||||
k3s kubectl get secrets -A --no-headers | wc -l
|
||||
k3s kubectl -n object-storage get secret aistor-root-configuration -o jsonpath='{.data}' | wc -c
|
||||
k3s kubectl get pods -A --no-headers | awk '{split($3, r, "/")} $4 != "Completed" && ($4 != "Running" || r[1] != r[2])'
|
||||
```
|
||||
|
||||
- `ready`, 노드 `Ready`, Secret 수가 1단계 리허설의 `N`과 비슷함(±5), 마지막에서 두 번째 숫자가 0보다 큼(복호화 성공).
|
||||
- 파드는 PV 데이터에 따라 몇 분 걸린다. 그 뒤 `after-reboot-checks.md`를 처음부터 돈다.
|
||||
|
||||
## 되돌리기 (2를 한 경우)
|
||||
|
||||
```bash
|
||||
systemctl stop k3s && /usr/local/bin/k3s-killall.sh
|
||||
rm -rf /var/lib/rancher/k3s/server/db
|
||||
mv /var/lib/rancher/k3s/server/db.before-restore-$TS /var/lib/rancher/k3s/server/db
|
||||
cp -a /var/lib/rancher/k3s/server/token.before-restore-$TS /var/lib/rancher/k3s/server/token
|
||||
systemctl start k3s
|
||||
```
|
||||
|
||||
`$TS`는 1단계에서 정한 값이다. 셸이 바뀌었으면 `ls -d /var/lib/rancher/k3s/server/db.before-restore-*`로 찾는다.
|
||||
|
||||
## 끝나면
|
||||
|
||||
```bash
|
||||
rm -rf /root/k3s-restore-$TS
|
||||
```
|
||||
|
||||
복원한 백업 시각 이후에 만든 객체는 없다. repo와의 차이를 보고 필요한 것을 다시 적용한다:
|
||||
|
||||
```bash
|
||||
cd /home/donghyeon/workspace/platform
|
||||
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt
|
||||
```
|
||||
|
||||
- `SUMMARY drift=0`이 목표다. `live-drift-accepted.txt`의 항목은 기한(지금 2026-11-30)이 지나면 다시 drift로 센다.
|
||||
- PV 데이터: platform-postgres는 W1의 CNPG 백업(`services/platform-postgres-backup/README.md`, W1 PR)에서, Gitea 파일은 `gitea-restore.md`로.
|
||||
@@ -0,0 +1,38 @@
|
||||
# k3s 재시작 창
|
||||
|
||||
k3s 재시작이나 파드 재시작을 부르는 변경을 **한 번의 창**에 모아서 한다(성숙도 점검 8절 결정 5).
|
||||
지금 모인 것은 아래 표다. 하나씩 따로 하면 운영 중단이 여러 번 생긴다.
|
||||
|
||||
| 순서 | 변경 | 중단 | 출처 |
|
||||
| ---: | --- | --- | --- |
|
||||
| 0 | PR #4 루트 적용(PriorityClass 둘, tech-log tenant, keycloak 정책)과 PR #3 Traefik resources. 재시작 없음 | 없음(Traefik만 몇 초) | `scripts/validate/README.md`, 공유 노트의 소유자 명령 묶음 |
|
||||
| 1 | k3s 재시작 묶음: kubelet 예약·메모리 축출·graceful shutdown, API 감사 로그, PSA 기본값, local-path 기본 해제, W1 시간 동기화 drop-in | API 1~2분(컨테이너는 계속 돈다) | `infrastructure/host/k3s/README.md` |
|
||||
| 2 | 받아들인 drift 해소: Keycloak Operator(라벨), prometheus-operator·kube-state-metrics(이미지 문자열), 관측 core의 Kubelet 인증서 경보 제거 | 해당 파드 재시작 | `scripts/validate/live-drift-accepted.txt` |
|
||||
| 3 | PriorityClass 붙이기(Keycloak, Gitea, Loki, Tempo)와 Keycloak Operator·서버 이미지 digest 고정 | Keycloak 로그인 1~2분, Gitea·Loki·Tempo 재시작 | PR #7 |
|
||||
| 4 | Postgres `priorityClassName`·Guaranteed QoS | Postgres 재시작(30초 안팎, 모든 서비스의 DB가 끊김) | W1 |
|
||||
|
||||
## 창 전에
|
||||
|
||||
- 어느 PR이 main에 들어갔는지 본다. 들어가지 않은 줄은 건너뛴다.
|
||||
- CI job 0개, 에이전트 게이트 없음(`flock -n /tmp/claude-gates/heavy.lock true && echo free`).
|
||||
- `after-reboot-checks.md` 1~7을 한 번 돌려 지금이 정상인지 본다. 정상이 아닌 상태에서 시작하지 않는다.
|
||||
- 호스트 백업이 있으면 지금 한 번 돌린다: `sudo systemctl start platform-k3s-datastore-backup.service`.
|
||||
|
||||
## 창 안에서
|
||||
|
||||
0. **PriorityClass가 먼저 있어야 한다.** `kubectl get priorityclass platform-critical platform-low`가 둘 다 나와야 3을 한다.
|
||||
없으면 `kubectl apply -k services/priority-classes`. 없는 클래스를 가리키는 파드는 생성이 거절된다.
|
||||
1. `sudo bash scripts/bootstrap/apply-k3s-restart-bundle.sh --execute` — 마지막 줄 `K3S RESTART BUNDLE APPLIED`.
|
||||
2. 받아들인 drift 해소는 각 루트의 기존 적용 스크립트로 한다(Phase 2 Keycloak Operator: `scripts/bootstrap/apply-keycloak.sh --execute`,
|
||||
관측 core: `services/observability`의 적용 절차). 끝나면 `live-drift-accepted.txt`에서 해당 줄을 지우는 PR을 낸다.
|
||||
3. 3은 루트별 기존 적용 경로로 한다: Keycloak Operator·CR `scripts/bootstrap/apply-keycloak.sh --execute`, Gitea
|
||||
`scripts/bootstrap/apply-gitea-oidc.sh --execute`, Loki·Tempo는 관측 core 적용 절차. 4는 W1 문서를 따른다.
|
||||
4. 각 단계 뒤에 `after-reboot-checks.md` 4~7을 돈다. 하나라도 실패하면 다음 단계로 가지 않는다.
|
||||
|
||||
## 창 뒤에
|
||||
|
||||
```bash
|
||||
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt
|
||||
```
|
||||
|
||||
`SUMMARY drift=0`이어야 한다.
|
||||
@@ -0,0 +1,127 @@
|
||||
# k3s 업그레이드 (같은 minor 안의 패치)
|
||||
|
||||
예: v1.36.2+k3s1 → v1.36.6+k3s1. minor를 올리는 것(1.36 → 1.37)은 이 문서 끝의 「minor」를 먼저 읽는다.
|
||||
근거: docs.k3s.io upgrades/manual(minor 건너뛰기 금지), Kubernetes version skew policy.
|
||||
|
||||
## 전제
|
||||
|
||||
- desktop, 사용자 `donghyeon`. 모든 상대경로는 이 checkout 기준이다:
|
||||
|
||||
```bash
|
||||
cd /home/donghyeon/workspace/platform && git pull --ff-only
|
||||
```
|
||||
|
||||
- 이 checkout에 `scripts/validate/live-drift-check.sh`(PR #4)가 있어야 한다.
|
||||
|
||||
## 0. 고르기
|
||||
|
||||
```bash
|
||||
curl -s https://update.k3s.io/v1-release/channels | python3 -c 'import json,sys; [print(c["name"], c.get("latest")) for c in json.load(sys.stdin)["data"] if c["name"] in ("stable","v1.36","v1.37")]'
|
||||
k3s --version | head -1
|
||||
```
|
||||
|
||||
- **패치는 지금 minor의 채널(`v1.36`)의 latest를 쓴다.** `stable`은 다른 minor를 가리킬 수 있다(2026-11-12: stable = v1.37.2).
|
||||
- GitHub 릴리스 노트에서 Traefik chart, containerd, 보안 수정 항목을 본다.
|
||||
- **Traefik chart나 이미지가 바뀌는지 본다.** `infrastructure/networking/traefik/scripts/common.sh`의
|
||||
`EXPECTED_K3S_CHART`·`EXPECTED_TRAEFIK_IMAGE`가 지금 값에 고정돼 있어, 바뀌면 Traefik 스크립트가 멈춘다(의도된 멈춤).
|
||||
|
||||
아래에서 `NEW=<0단계에서 고른 버전>`, `OLD=<지금 버전>`으로 둔다(예: `NEW=v1.36.6+k3s1`, `OLD=v1.36.2+k3s1`).
|
||||
|
||||
## 1. 창을 잡는다
|
||||
|
||||
```bash
|
||||
docker exec gitea-runner docker ps -q | wc -l # CI job 컨테이너 수. 0이어야 한다
|
||||
flock -n /tmp/claude-gates/heavy.lock true && echo lock-free # 에이전트 세션의 무거운 빌드·시험이 잡는 lock. lock-free여야 한다
|
||||
```
|
||||
|
||||
재시작 중 API가 1~2분 멈춘다. 컨테이너는 계속 돈다(`KillMode=process`).
|
||||
|
||||
## 2. 지금 상태를 남긴다
|
||||
|
||||
```bash
|
||||
systemctl cat platform-k3s-datastore-backup.service >/dev/null 2>&1 && echo host-backup-installed
|
||||
```
|
||||
|
||||
`host-backup-installed`가 나오면:
|
||||
|
||||
```bash
|
||||
sudo systemctl start platform-k3s-datastore-backup.service
|
||||
journalctl -u platform-k3s-datastore-backup -n 3 --no-pager # 끝에 uploaded
|
||||
```
|
||||
|
||||
안 나오면(호스트 백업 설치 전) 같은 형식의 사본을 손으로 만든다. `k3s-datastore-restore.md`가 이 형식을 읽는다.
|
||||
|
||||
```bash
|
||||
sudo bash -c 'set -e; TS=$(date -u +%Y%m%dT%H%M%SZ); D=/var/backups/k3s-datastore-$TS; install -d -m 0700 $D
|
||||
sqlite3 /var/lib/rancher/k3s/server/db/state.db ".backup $D/state.db"
|
||||
install -m 0600 /var/lib/rancher/k3s/server/token $D/token
|
||||
printf "created=%s\nk3s_version=%s\n" $TS "$(/usr/local/bin/k3s --version | head -1)" > $D/META
|
||||
tar -C /var/backups -czf $D.tar.gz k3s-datastore-$TS && sha256sum $D.tar.gz | awk "{print \$1}" > $D.tar.gz.sha256
|
||||
rm -rf $D; ls -l $D.tar.gz*'
|
||||
```
|
||||
|
||||
그리고 repo와 차이가 없는지 본다. 업그레이드 뒤의 차이를 업그레이드 탓으로 볼 수 있게 하려는 것이다.
|
||||
|
||||
```bash
|
||||
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm bash scripts/validate/live-drift-check.sh --accepted scripts/validate/live-drift-accepted.txt
|
||||
```
|
||||
|
||||
`SUMMARY drift=0`이어야 한다. `live-drift-accepted.txt` 항목은 기한(지금 2026-11-30)이 지나면 다시 drift로 센다.
|
||||
|
||||
지금 바이너리를 남긴다(되돌리기에 쓴다):
|
||||
|
||||
```bash
|
||||
sudo cp -a /usr/local/bin/k3s "/usr/local/bin/k3s.$OLD"
|
||||
```
|
||||
|
||||
## 3. 올린다
|
||||
|
||||
```bash
|
||||
curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION="$NEW" INSTALL_K3S_EXEC='server --disable=servicelb' sh -
|
||||
until kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready
|
||||
```
|
||||
|
||||
- `INSTALL_K3S_EXEC`는 지금 unit과 같아야 한다(`systemctl cat k3s`의 ExecStart: `server --disable=servicelb`).
|
||||
설치 스크립트가 `/etc/systemd/system/k3s.service`를 다시 쓰고 k3s를 재시작한다. `k3s.service.d/` drop-in과
|
||||
`/etc/rancher/k3s/config.yaml.d/`는 그대로 남는다.
|
||||
|
||||
## 4. 확인
|
||||
|
||||
```bash
|
||||
k3s --version | head -1
|
||||
kubectl get nodes -o wide
|
||||
kubectl -n kube-system get pods
|
||||
kubectl -n kube-system get helmchart traefik -o jsonpath='{.spec.chart}{"\n"}'
|
||||
kubectl -n kube-system get deploy traefik -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
|
||||
```
|
||||
|
||||
그다음 `after-reboot-checks.md` 2~8을 돌고, 2단계의 drift 검사를 다시 돌려 `SUMMARY drift=0`인지 본다(이 검사가 live Traefik
|
||||
HelmChartConfig를 trust overlay와 비교한다).
|
||||
|
||||
Traefik chart·이미지가 바뀌었으면:
|
||||
|
||||
1. `infrastructure/networking/traefik/scripts/common.sh`의 두 값과 `infrastructure/networking/traefik/README.md`
|
||||
「현재 live 상태」 표를 새 값으로 고치는 PR을 낸다.
|
||||
2. `bash infrastructure/networking/traefik/scripts/validate.sh`(정적 렌더 검사).
|
||||
|
||||
`scripts/validate/render-phase1.sh`와 `scripts/validate/render-phase2.sh`의 `TARGET_KUBERNETES_VERSION`(지금 `1.36.2`)도 새 버전으로 고친다.
|
||||
|
||||
## 되돌리기
|
||||
|
||||
같은 minor 안이면 남겨 둔 바이너리로 돌아간다.
|
||||
|
||||
```bash
|
||||
sudo install -m 0755 "/usr/local/bin/k3s.$OLD" /usr/local/bin/k3s
|
||||
sudo systemctl restart k3s
|
||||
until kubectl get --raw /readyz >/dev/null 2>&1; do sleep 5; done; echo ready
|
||||
```
|
||||
|
||||
API가 뜨지 않거나 datastore 오류가 나면 2단계의 사본으로 `k3s-datastore-restore.md`를 따른다
|
||||
(호스트 백업 설치 전에 만든 손 사본은 `/var/backups/k3s-datastore-*.tar.gz`에 있다).
|
||||
|
||||
## minor
|
||||
|
||||
- 한 번에 한 minor만 올린다(1.36 → 1.37 → 1.38). 건너뛰지 않는다.
|
||||
- 릴리스 노트의 deprecation·제거 API를 본다. `kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis`로 지금 쓰는 deprecated API를 본다.
|
||||
- CNPG·Keycloak·AIStor·kube-prometheus-stack이 새 Kubernetes 버전을 지원하는지 각 문서에서 확인한다.
|
||||
- k3s는 minor 다운그레이드를 공식 지원하지 않는다. 되돌리기는 datastore 복원이다.
|
||||
@@ -0,0 +1,2 @@
|
||||
kube-proxy-arg:
|
||||
- "nodeport-addresses=127.0.0.0/8"
|
||||
@@ -0,0 +1,38 @@
|
||||
# keycloak namespace NetworkPolicy
|
||||
|
||||
2026-11-11 점검 전 `keycloak` namespace에는 Keycloak Operator가 만든 ingress 정책 하나뿐이었다.
|
||||
Keycloak 파드와 Operator 파드의 egress는 막혀 있지 않았다. 다른 플랫폼 namespace처럼 기본 차단에
|
||||
필요한 것만 연다.
|
||||
|
||||
| 정책 | 대상 | 허용 |
|
||||
| --- | --- | --- |
|
||||
| `keycloak-default-deny` | 모든 파드 | ingress·egress 기본 차단 |
|
||||
| `keycloak-allow-dns` | 모든 파드 | kube-dns 53 |
|
||||
| `keycloak-allow-platform-postgres` | 모든 파드(서버와 realm import Job) | `platform-data` Postgres 5432 |
|
||||
| `keycloak-allow-cluster-peers` | Keycloak 파드 | 같은 Keycloak 파드 JGroups 7800·57800 |
|
||||
| `keycloak-operator-allow-egress` | Operator | API 서버(`10.43.0.1:443`, `192.168.0.107:6443`), Keycloak 8080·9000 |
|
||||
|
||||
- Keycloak 파드의 **ingress**는 계속 Keycloak CR `spec.networkPolicy`로 Operator가 만드는
|
||||
`keycloak-network-policy`가 소유한다(Traefik 8080, 관리 9000, JGroups).
|
||||
- 바깥(인터넷)으로 나가는 길은 없다. 2026-11-12에 repo와 Keycloak CR에 SMTP·외부 IdP 설정이
|
||||
없고, Keycloak 파드의 열린 TCP 연결이 Postgres뿐인 것을 확인했다. SMTP나 외부 IdP를 붙이면
|
||||
여기에 egress를 더해야 한다(안 더하면 메일·외부 로그인만 조용히 실패한다).
|
||||
- kubelet probe는 노드에서 오므로 막히지 않는다.
|
||||
|
||||
## 적용과 확인
|
||||
|
||||
```sh
|
||||
bash scripts/validate/render-tenants-and-policies.sh
|
||||
kubectl kustomize infrastructure/networking/keycloak | kubectl diff -f -
|
||||
kubectl apply -k infrastructure/networking/keycloak
|
||||
```
|
||||
|
||||
적용 뒤 확인(모두 통과해야 한다):
|
||||
|
||||
```sh
|
||||
kubectl -n keycloak get pods
|
||||
curl -fsS -o /dev/null -w '%{http_code}\n' https://id.learn.hyeonworks.com/realms/hyeonworks/.well-known/openid-configuration
|
||||
kubectl -n keycloak logs deploy/keycloak-operator --since=5m | grep -i -E 'error|exception|timeout' || echo no-operator-errors
|
||||
```
|
||||
|
||||
되돌리기: `kubectl delete -k infrastructure/networking/keycloak`(Operator 정책은 남는다).
|
||||
@@ -0,0 +1,12 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
namespace: keycloak
|
||||
|
||||
labels:
|
||||
- pairs:
|
||||
app.kubernetes.io/part-of: platform
|
||||
includeSelectors: false
|
||||
|
||||
resources:
|
||||
- network-policies.yaml
|
||||
@@ -0,0 +1,117 @@
|
||||
# keycloak namespace: 기본 차단 + 필요한 것만 허용.
|
||||
# Keycloak 파드의 ingress는 Keycloak CR(spec.networkPolicy)로 Operator가 만드는
|
||||
# keycloak-network-policy가 계속 소유한다. 여기서는 기본 차단과 egress만 정한다.
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: keycloak-default-deny
|
||||
spec:
|
||||
podSelector: {}
|
||||
policyTypes:
|
||||
- Ingress
|
||||
- Egress
|
||||
---
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: keycloak-allow-dns
|
||||
spec:
|
||||
podSelector: {}
|
||||
policyTypes:
|
||||
- Egress
|
||||
egress:
|
||||
- to:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: kube-system
|
||||
podSelector:
|
||||
matchLabels:
|
||||
k8s-app: kube-dns
|
||||
ports:
|
||||
- port: 53
|
||||
protocol: UDP
|
||||
- port: 53
|
||||
protocol: TCP
|
||||
---
|
||||
# Keycloak 서버와 realm import Job이 공용 PostgreSQL에 붙는다.
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: keycloak-allow-platform-postgres
|
||||
spec:
|
||||
podSelector: {}
|
||||
policyTypes:
|
||||
- Egress
|
||||
egress:
|
||||
- to:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: platform-data
|
||||
podSelector:
|
||||
matchLabels:
|
||||
cnpg.io/cluster: platform-postgres
|
||||
ports:
|
||||
- port: 5432
|
||||
protocol: TCP
|
||||
---
|
||||
# 같은 Keycloak 인스턴스끼리의 JGroups(7800, 57800). Operator ingress 정책과 짝이다.
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: keycloak-allow-cluster-peers
|
||||
spec:
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app: keycloak
|
||||
app.kubernetes.io/instance: keycloak
|
||||
app.kubernetes.io/managed-by: keycloak-operator
|
||||
policyTypes:
|
||||
- Egress
|
||||
egress:
|
||||
- to:
|
||||
- podSelector:
|
||||
matchLabels:
|
||||
app: keycloak
|
||||
app.kubernetes.io/instance: keycloak
|
||||
app.kubernetes.io/managed-by: keycloak-operator
|
||||
ports:
|
||||
- port: 7800
|
||||
protocol: TCP
|
||||
- port: 57800
|
||||
protocol: TCP
|
||||
---
|
||||
# Operator: Kubernetes API(ClusterIP와 실제 API 서버 주소)와 Keycloak 관리 포트.
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: keycloak-operator-allow-egress
|
||||
spec:
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/name: keycloak-operator
|
||||
policyTypes:
|
||||
- Egress
|
||||
egress:
|
||||
- to:
|
||||
- ipBlock:
|
||||
cidr: 10.43.0.1/32
|
||||
ports:
|
||||
- port: 443
|
||||
protocol: TCP
|
||||
- to:
|
||||
- ipBlock:
|
||||
cidr: 192.168.0.107/32
|
||||
ports:
|
||||
- port: 6443
|
||||
protocol: TCP
|
||||
- to:
|
||||
- podSelector:
|
||||
matchLabels:
|
||||
app: keycloak
|
||||
app.kubernetes.io/instance: keycloak
|
||||
app.kubernetes.io/managed-by: keycloak-operator
|
||||
ports:
|
||||
- port: 8080
|
||||
protocol: TCP
|
||||
- port: 9000
|
||||
protocol: TCP
|
||||
@@ -101,6 +101,15 @@ infrastructure/networking/traefik/
|
||||
세 overlay는 모두 Service `NodePort`, `externalTrafficPolicy: Cluster`와
|
||||
`30080/30443`을 명시적으로 소유한다.
|
||||
|
||||
세 overlay는 같은 `resources`도 소유한다: requests `cpu: 50m`·`memory: 64Mi`,
|
||||
limit `memory: 256Mi`, CPU limit 없음. k3s 기본 Traefik은 requests·limits가 없는
|
||||
BestEffort다. 이 노드의 kubelet에는 메모리 축출 문턱이 없어(k3s 기본 `evictionHard`는
|
||||
디스크 두 항목뿐) 메모리가 모자라면 커널 OOM killer가 고르는데, BestEffort 컨테이너는
|
||||
`oom_score_adj` 1000이라 가장 먼저 죽는다. 모든 공개 경로가 Traefik 하나를 지나므로
|
||||
Burstable로 올린다. 2026-11-11 실측 사용량은 CPU 약 5m,
|
||||
메모리 약 42Mi다. CPU limit은 throttling을 피하려고 두지 않는다. overlay 둘이
|
||||
`valuesContent`를 통째로 바꾸므로 값을 바꿀 때는 base와 두 patch를 함께 고친다.
|
||||
|
||||
- `baseline`: Service 경계만 남긴다. access log와 forwarded-header trust는 없다.
|
||||
- `observe`: Service 경계와 header를 버리는 JSON access log를 적용한다. trust는 없다.
|
||||
- `trust`: observe 설정에 `web.forwardedHeaders.trustedIPs=10.42.0.1/32`만 추가한다.
|
||||
|
||||
@@ -14,6 +14,12 @@ spec:
|
||||
prometheus.io/path: /metrics
|
||||
prometheus.io/port: "9100"
|
||||
prometheus.io/scrape: "true"
|
||||
resources:
|
||||
requests:
|
||||
cpu: 50m
|
||||
memory: 64Mi
|
||||
limits:
|
||||
memory: 256Mi
|
||||
service:
|
||||
spec:
|
||||
type: NodePort
|
||||
|
||||
@@ -6,6 +6,12 @@
|
||||
prometheus.io/path: /metrics
|
||||
prometheus.io/port: "9100"
|
||||
prometheus.io/scrape: "true"
|
||||
resources:
|
||||
requests:
|
||||
cpu: 50m
|
||||
memory: 64Mi
|
||||
limits:
|
||||
memory: 256Mi
|
||||
service:
|
||||
spec:
|
||||
type: NodePort
|
||||
|
||||
@@ -6,6 +6,12 @@
|
||||
prometheus.io/path: /metrics
|
||||
prometheus.io/port: "9100"
|
||||
prometheus.io/scrape: "true"
|
||||
resources:
|
||||
requests:
|
||||
cpu: 50m
|
||||
memory: 64Mi
|
||||
limits:
|
||||
memory: 256Mi
|
||||
service:
|
||||
spec:
|
||||
type: NodePort
|
||||
|
||||
@@ -559,3 +559,40 @@ parser와 세 mode의 fixture 회귀는 live cluster에 연결하지 않고 다
|
||||
```sh
|
||||
bash scripts/validate/test-k3s-secret-encryption-status.sh
|
||||
```
|
||||
|
||||
## 테넌트·우선순위·keycloak 정책 렌더 검사
|
||||
|
||||
`render-tenants-and-policies.sh`는 클러스터에 닿지 않고 세 빌드 루트를 렌더해 불변식을
|
||||
확인한다.
|
||||
|
||||
- `services/tenants/techlog`: tech-log 테넌트의 플랫폼 쪽 객체 11개(목록이 정확히 같아야
|
||||
한다), `hyeonworks-prod` PSA 라벨, techlog DatabaseRole 권한 플래그, 대시보드 이름
|
||||
- `services/priority-classes`: `platform-critical`(0보다 크고 시스템 클래스보다 작다),
|
||||
`platform-low`(0보다 작고 선점하지 않는다), 둘 다 global default가 아니다
|
||||
- `infrastructure/networking/keycloak`: namespace 전체 기본 차단, egress 규칙마다 포트,
|
||||
허용 CIDR은 API 서버 둘뿐
|
||||
|
||||
```sh
|
||||
bash scripts/validate/render-tenants-and-policies.sh
|
||||
```
|
||||
|
||||
## 라이브 drift 검사
|
||||
|
||||
`live-drift-check.sh`는 이 저장소의 라이브 빌드 루트를 모두 렌더하고(Phase 1·2, 관리 도구,
|
||||
관측 core, Traefik trust overlay, 위 세 루트) Secret을 뺀 뒤 `kubectl diff`(서버 dry-run,
|
||||
저장하지 않음)로 클러스터와 비교한다. 렌더에는 위 render 스크립트의 `--verified-output-dir`
|
||||
출력을 읽기만 하는 용도로 쓴다(그 디렉터리는 스크립트가 끝날 때 지운다).
|
||||
|
||||
```sh
|
||||
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
|
||||
bash scripts/validate/live-drift-check.sh \
|
||||
--accepted scripts/validate/live-drift-accepted.txt
|
||||
```
|
||||
|
||||
- 종료 코드: 0 차이 없음, 1 차이 있음, 2 검사 자체 실패.
|
||||
- `DRIFT <Kind> <ns>/<name> (+추가 -삭제) [입력 파일]`로 객체마다 한 줄을 쓴다.
|
||||
`generation` 줄만 다른 것은 세지 않는다.
|
||||
- `--accepted`: 알고 있는 차이를 기한과 이유를 달아 적는다. 기한이 지나면 다시 drift로 센다.
|
||||
- `--textfile FILE`: `platform_live_drift_objects`, `platform_live_drift_check_success`,
|
||||
`platform_live_drift_last_run_timestamp_seconds`를 Prometheus textfile 형식으로 쓴다.
|
||||
- Secret 값의 차이는 보지 않는다.
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
# 알고 있는 라이브 drift. 형식: <Kind> <namespace 또는 -> <name> <기한 YYYY-MM-DD> <이유>
|
||||
# 기한이 지나면 live-drift-check.sh가 다시 drift로 센다. 해소하면 줄을 지운다.
|
||||
Cluster platform-data platform-postgres 2026-11-30 pg_hba의 techlog 두 줄이 repo에 없다. w1이 CNPG 백업과 함께 넣는다(1c4ef9a).
|
||||
DatabaseRole platform-data platform-postgres-gitea 2026-11-30 렌더가 false 기본값 필드를 명시할 뿐 값은 같다. 다음 Phase 1 적용 때 사라진다.
|
||||
DatabaseRole platform-data platform-postgres-keycloak 2026-11-30 렌더가 false 기본값 필드를 명시할 뿐 값은 같다. 다음 Phase 2 적용 때 사라진다.
|
||||
Deployment keycloak keycloak-operator 2026-11-30 원격 ref 26.7.0 태그 내용이 바뀌어 build-timestamp 라벨만 다르다. 재시작 창에 커밋 SHA 고정과 함께 적용한다.
|
||||
Service keycloak keycloak-operator 2026-11-30 위와 같은 build-timestamp 라벨.
|
||||
ServiceAccount keycloak keycloak-operator 2026-11-30 위와 같은 build-timestamp 라벨.
|
||||
Deployment observability observability-core-kube-pr-operator 2026-11-30 이미지 문자열이 tag@digest와 digest로 다르고 digest는 같다. 적용하면 재시작되므로 재시작 창에.
|
||||
Deployment observability observability-core-kube-state-metrics 2026-11-30 위와 같은 이미지 문자열 차이.
|
||||
@@ -0,0 +1,173 @@
|
||||
#!/usr/bin/env bash
|
||||
# Render every live build root of this repository and compare it with the
|
||||
# cluster using `kubectl diff` (server-side dry-run: nothing is persisted).
|
||||
#
|
||||
# Usage:
|
||||
# PLATFORM_HELM_BIN=/abs/helm bash scripts/validate/live-drift-check.sh \
|
||||
# [--accepted FILE] [--textfile FILE]
|
||||
#
|
||||
# --accepted FILE known differences, one per line:
|
||||
# `<Kind> <namespace or -> <name> <until YYYY-MM-DD> <reason...>`
|
||||
# Expired entries count as drift again.
|
||||
# --textfile FILE also write Prometheus textfile metrics (atomic rename).
|
||||
#
|
||||
# Exit status: 0 no drift, 1 drift found, 2 the check itself failed.
|
||||
# Secrets are removed from the renders before diffing; Secret drift is out of scope.
|
||||
set -Eeuo pipefail
|
||||
|
||||
readonly REPOSITORY_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
|
||||
accepted_file=""
|
||||
textfile=""
|
||||
while (( $# > 0 )); do
|
||||
case "$1" in
|
||||
--accepted) accepted_file="${2:?--accepted needs a file}"; shift 2 ;;
|
||||
--textfile) textfile="${2:?--textfile needs a file}"; shift 2 ;;
|
||||
-h|--help) sed -n '2,16p' "${BASH_SOURCE[0]}"; exit 0 ;;
|
||||
*) printf 'unknown argument: %s\n' "$1" >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
|
||||
declare -a made_dirs=()
|
||||
cleanup() {
|
||||
local d
|
||||
for d in "${made_dirs[@]}"; do
|
||||
case "$d" in /tmp/platform-*) rm -rf -- "$d" ;; esac
|
||||
done
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
write_textfile() {
|
||||
local drift="$1" ok="$2"
|
||||
[[ -n "$textfile" ]] || return 0
|
||||
local tmp="${textfile}.tmp.$$"
|
||||
{
|
||||
echo '# HELP platform_live_drift_objects Objects whose live state differs from the repository render.'
|
||||
echo '# TYPE platform_live_drift_objects gauge'
|
||||
echo "platform_live_drift_objects ${drift}"
|
||||
echo '# HELP platform_live_drift_check_success 1 when the drift check itself completed.'
|
||||
echo '# TYPE platform_live_drift_check_success gauge'
|
||||
echo "platform_live_drift_check_success ${ok}"
|
||||
echo '# HELP platform_live_drift_last_run_timestamp_seconds Unix time the drift check finished.'
|
||||
echo '# TYPE platform_live_drift_last_run_timestamp_seconds gauge'
|
||||
echo "platform_live_drift_last_run_timestamp_seconds $(date +%s)"
|
||||
} >"$tmp"
|
||||
mv -f -- "$tmp" "$textfile"
|
||||
}
|
||||
|
||||
die() {
|
||||
printf 'DRIFT CHECK ERROR: %s\n' "$*" >&2
|
||||
write_textfile 0 0
|
||||
exit 2
|
||||
}
|
||||
|
||||
work="$(mktemp -d /tmp/platform-drift.XXXXXX)"; made_dirs+=("$work")
|
||||
mkdir -p "$work/in" "$work/out"
|
||||
|
||||
render_root() {
|
||||
local script="$1" prefix="$2" dir
|
||||
dir="$(mktemp -d "/tmp/${prefix}.XXXXXX")"; made_dirs+=("$dir")
|
||||
bash "$REPOSITORY_ROOT/scripts/validate/${script}" --verified-output-dir "$dir" \
|
||||
>"$work/${script}.log" 2>&1 || { tail -5 "$work/${script}.log" >&2; die "${script} failed"; }
|
||||
printf '%s\n' "$dir"
|
||||
}
|
||||
|
||||
phase1="$(render_root render-phase1.sh platform-phase1-apply)"
|
||||
phase2="$(render_root render-phase2.sh platform-phase2-apply)"
|
||||
admin="$(render_root render-admin-services.sh platform-admin-apply)"
|
||||
observability="$(render_root render-observability-core.sh platform-observability-core-apply)"
|
||||
|
||||
# The live Gitea is the OIDC profile; gitea.yaml is the fresh-install baseline only.
|
||||
declare -a inputs=(
|
||||
"$phase1/namespaces.yaml" "$phase1/ssd-local-pv.yaml" "$phase1/cnpg-operator.yaml"
|
||||
"$phase1/platform-postgres.yaml" "$phase1/gitea-oidc.yaml"
|
||||
"$observability/aggregate.yaml"
|
||||
)
|
||||
for f in "$phase2"/*.yaml "$admin"/*.yaml; do inputs+=("$f"); done
|
||||
|
||||
# Live Traefik is the trust overlay (infrastructure/networking/traefik/README.md).
|
||||
kubectl kustomize "$REPOSITORY_ROOT/infrastructure/networking/traefik/overlays/trust" >"$work/traefik-trust.yaml" || die "traefik render failed"
|
||||
kubectl kustomize "$REPOSITORY_ROOT/services/tenants/techlog" >"$work/tenant-techlog.yaml" || die "tenant render failed"
|
||||
kubectl kustomize "$REPOSITORY_ROOT/services/priority-classes" >"$work/priority-classes.yaml" || die "priority class render failed"
|
||||
kubectl kustomize "$REPOSITORY_ROOT/infrastructure/networking/keycloak" >"$work/keycloak-network-policies.yaml" || die "keycloak policy render failed"
|
||||
inputs+=("$work/traefik-trust.yaml" "$work/tenant-techlog.yaml" "$work/priority-classes.yaml" "$work/keycloak-network-policies.yaml")
|
||||
|
||||
n=0
|
||||
for f in "${inputs[@]}"; do
|
||||
n=$((n + 1))
|
||||
python3 -I - "$f" "$work/in/$(printf '%02d' "$n")-$(basename "$f")" <<'PY' || die "could not strip Secrets from $f"
|
||||
import sys, yaml
|
||||
yaml.SafeLoader.add_constructor("tag:yaml.org,2002:value", lambda l, n: l.construct_scalar(n))
|
||||
docs = [d for d in yaml.safe_load_all(open(sys.argv[1])) if isinstance(d, dict) and d.get("kind") not in (None, "Secret")]
|
||||
yaml.safe_dump_all(docs, open(sys.argv[2], "w"), sort_keys=False)
|
||||
PY
|
||||
done
|
||||
|
||||
for f in "$work"/in/*.yaml; do
|
||||
set +e
|
||||
KUBECTL_EXTERNAL_DIFF="diff -u -N" kubectl diff -f "$f" >"$work/out/$(basename "$f").diff" 2>"$work/out/$(basename "$f").err"
|
||||
rc=$?
|
||||
set -e
|
||||
if (( rc > 1 )); then
|
||||
sed -n '1,5p' "$work/out/$(basename "$f").err" >&2
|
||||
die "kubectl diff failed for $(basename "$f")"
|
||||
fi
|
||||
done
|
||||
|
||||
set +e
|
||||
python3 -I - "$work/out" "${accepted_file:-}" "$work/drift-count" <<'PY'
|
||||
import sys, pathlib, re, datetime
|
||||
out, accepted_path, count_path = pathlib.Path(sys.argv[1]), sys.argv[2], pathlib.Path(sys.argv[3])
|
||||
today = datetime.date.today()
|
||||
accepted, expired = {}, set()
|
||||
if accepted_path:
|
||||
for line in pathlib.Path(accepted_path).read_text().splitlines():
|
||||
line = line.strip()
|
||||
if not line or line.startswith("#"):
|
||||
continue
|
||||
kind, ns, name, until, *reason = line.split()
|
||||
key = (kind, "" if ns == "-" else ns, name)
|
||||
if datetime.date.fromisoformat(until) < today:
|
||||
expired.add(key)
|
||||
else:
|
||||
accepted[key] = " ".join(reason)
|
||||
version = re.compile(r"^v\d+((alpha|beta)\d+)?$")
|
||||
objects = {}
|
||||
for diff in sorted(out.glob("*.diff")):
|
||||
current = None
|
||||
for line in diff.read_text().splitlines():
|
||||
if line.startswith("diff -u -N "):
|
||||
parts = line.split()[3].rsplit("/", 1)[-1].split(".")
|
||||
i = next(i for i, p in enumerate(parts) if version.match(p))
|
||||
current = (parts[i + 1], parts[i + 2], ".".join(parts[i + 3:]))
|
||||
objects.setdefault(current, [0, 0, diff.name])
|
||||
elif current and line[:1] in "+-" and not line.startswith(("+++", "---")):
|
||||
if re.match(r"^[+-]\s+generation:", line):
|
||||
continue
|
||||
objects[current][0 if line[0] == "+" else 1] += 1
|
||||
drift = accepted_seen = 0
|
||||
for key, (plus, minus, src) in sorted(objects.items()):
|
||||
if plus == 0 and minus == 0:
|
||||
continue
|
||||
kind, ns, name = key
|
||||
label = f"{kind} {ns or '-'}/{name} (+{plus} -{minus}) [{src}]"
|
||||
if key in accepted:
|
||||
accepted_seen += 1
|
||||
print(f"ACCEPTED {label}: {accepted[key]}")
|
||||
continue
|
||||
drift += 1
|
||||
print(f"DRIFT {label}" + (" (accepted entry expired)" if key in expired else ""))
|
||||
print(f"SUMMARY drift={drift} accepted={accepted_seen}")
|
||||
count_path.write_text(str(drift))
|
||||
PY
|
||||
rc=$?
|
||||
set -e
|
||||
(( rc == 0 )) || die "could not summarize the diffs"
|
||||
drift_count="$(cat "$work/drift-count")"
|
||||
write_textfile "$drift_count" 1
|
||||
if (( drift_count == 0 )); then
|
||||
echo "LIVE DRIFT CHECK PASS"
|
||||
exit 0
|
||||
fi
|
||||
echo "LIVE DRIFT CHECK FOUND DRIFT"
|
||||
exit 1
|
||||
@@ -0,0 +1,126 @@
|
||||
#!/usr/bin/env bash
|
||||
# Render the tech-log tenant root, the platform PriorityClasses and the keycloak
|
||||
# namespace NetworkPolicies, and check their invariants. Static: no cluster access.
|
||||
set -Eeuo pipefail
|
||||
|
||||
readonly EXPECTED_KUSTOMIZE_VERSION="v5.8.1"
|
||||
readonly REPOSITORY_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd -P)"
|
||||
|
||||
fail() {
|
||||
printf 'ERROR: %s\n' "$*" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
kustomize_version="$(kubectl version --client --output=yaml | sed -n 's/^kustomizeVersion: //p')"
|
||||
[[ "$kustomize_version" == "$EXPECTED_KUSTOMIZE_VERSION" ]] || \
|
||||
fail "expected Kustomize ${EXPECTED_KUSTOMIZE_VERSION}, found ${kustomize_version:-unknown}"
|
||||
|
||||
work="$(mktemp -d "${TMPDIR:-/tmp}/platform-tenants-render.XXXXXX")"
|
||||
trap 'rm -rf -- "$work"' EXIT
|
||||
|
||||
kubectl kustomize "$REPOSITORY_ROOT/services/tenants/techlog" >"$work/techlog.yaml"
|
||||
kubectl kustomize "$REPOSITORY_ROOT/services/priority-classes" >"$work/priority-classes.yaml"
|
||||
kubectl kustomize "$REPOSITORY_ROOT/infrastructure/networking/keycloak" >"$work/keycloak-network-policies.yaml"
|
||||
|
||||
python3 -I - "$work" <<'PY'
|
||||
import sys, pathlib, yaml
|
||||
|
||||
work = pathlib.Path(sys.argv[1])
|
||||
errors = []
|
||||
|
||||
def load(name):
|
||||
return [d for d in yaml.safe_load_all((work / name).read_text()) if d]
|
||||
|
||||
def keyset(docs):
|
||||
return sorted((d["kind"], d["metadata"].get("namespace", ""), d["metadata"]["name"]) for d in docs)
|
||||
|
||||
for name in ("techlog.yaml", "priority-classes.yaml", "keycloak-network-policies.yaml"):
|
||||
for d in load(name):
|
||||
if d["kind"] == "Secret":
|
||||
errors.append(f"{name}: Secret objects must not be rendered")
|
||||
|
||||
techlog = load("techlog.yaml")
|
||||
expected = sorted([
|
||||
("Namespace", "", "hyeonworks-prod"),
|
||||
("Database", "platform-data", "platform-postgres-techlog"),
|
||||
("DatabaseRole", "platform-data", "platform-postgres-techlog"),
|
||||
("NetworkPolicy", "platform-data", "allow-techlog-backend"),
|
||||
("NetworkPolicy", "object-storage", "allow-techlog-backend"),
|
||||
("Probe", "observability", "techlog-edge"),
|
||||
("Probe", "observability", "techlog-readiness"),
|
||||
("PrometheusRule", "observability", "techlog"),
|
||||
("ConfigMap", "observability", "grafana-dashboard-techlog"),
|
||||
("NetworkPolicy", "observability", "blackbox-allow-techlog-health"),
|
||||
("NetworkPolicy", "observability", "observability-allow-techlog-scrape"),
|
||||
])
|
||||
if keyset(techlog) != expected:
|
||||
errors.append(f"tech-log tenant objects differ: {keyset(techlog)}")
|
||||
for d in techlog:
|
||||
kind = d["kind"]
|
||||
if kind == "Namespace":
|
||||
labels = d["metadata"].get("labels", {})
|
||||
want = {
|
||||
"pod-security.kubernetes.io/enforce": "baseline",
|
||||
"pod-security.kubernetes.io/warn": "restricted",
|
||||
"pod-security.kubernetes.io/audit": "restricted",
|
||||
"observability.hyeonworks.com/enabled": "true",
|
||||
}
|
||||
for k, v in want.items():
|
||||
if labels.get(k) != v:
|
||||
errors.append(f"hyeonworks-prod label {k} must be {v}")
|
||||
if kind == "DatabaseRole":
|
||||
spec = d["spec"]
|
||||
if spec.get("passwordSecret", {}).get("name") != "techlog-db-credentials":
|
||||
errors.append("techlog DatabaseRole must reference techlog-db-credentials")
|
||||
for flag in ("superuser", "createdb", "createrole", "replication", "bypassrls"):
|
||||
if spec.get(flag) is not False:
|
||||
errors.append(f"techlog DatabaseRole {flag} must be false")
|
||||
if kind in ("Database", "DatabaseRole"):
|
||||
policy = d["spec"].get("databaseReclaimPolicy") or d["spec"].get("databaseRoleReclaimPolicy")
|
||||
if policy != "retain":
|
||||
errors.append(f"{kind} must keep the retain reclaim policy")
|
||||
if kind == "ConfigMap":
|
||||
labels = d["metadata"].get("labels", {})
|
||||
if labels.get("grafana_dashboard") != "1":
|
||||
errors.append("tech-log dashboard ConfigMap needs grafana_dashboard=1")
|
||||
if d["metadata"]["name"] != "grafana-dashboard-techlog":
|
||||
errors.append("tech-log dashboard ConfigMap must keep its name (no hash suffix)")
|
||||
|
||||
classes = {d["metadata"]["name"]: d for d in load("priority-classes.yaml")}
|
||||
if sorted(classes) != ["platform-critical", "platform-low"]:
|
||||
errors.append(f"PriorityClasses differ: {sorted(classes)}")
|
||||
else:
|
||||
crit, low = classes["platform-critical"], classes["platform-low"]
|
||||
if not (0 < crit["value"] < 1_000_000_000):
|
||||
errors.append("platform-critical must be above 0 and below the system classes")
|
||||
if not low["value"] < 0:
|
||||
errors.append("platform-low must be below the default priority 0")
|
||||
if low.get("preemptionPolicy") != "Never":
|
||||
errors.append("platform-low must never preempt")
|
||||
for d in classes.values():
|
||||
if d.get("globalDefault") is not False:
|
||||
errors.append(f"{d['metadata']['name']} must not be the global default")
|
||||
|
||||
policies = {d["metadata"]["name"]: d for d in load("keycloak-network-policies.yaml")}
|
||||
deny = policies.get("keycloak-default-deny")
|
||||
if not deny or deny["spec"].get("podSelector") != {} or sorted(deny["spec"].get("policyTypes", [])) != ["Egress", "Ingress"]:
|
||||
errors.append("keycloak needs a namespace-wide default deny for ingress and egress")
|
||||
for d in policies.values():
|
||||
if d["metadata"].get("namespace") != "keycloak":
|
||||
errors.append(f"{d['metadata']['name']} must live in the keycloak namespace")
|
||||
for rule in d["spec"].get("egress", []) or []:
|
||||
for peer in rule.get("to", []):
|
||||
cidr = peer.get("ipBlock", {}).get("cidr")
|
||||
if cidr and cidr not in ("10.43.0.1/32", "192.168.0.107/32"):
|
||||
errors.append(f"{d['metadata']['name']}: unexpected egress CIDR {cidr}")
|
||||
if not rule.get("ports"):
|
||||
errors.append(f"{d['metadata']['name']}: every egress rule must name its ports")
|
||||
|
||||
if errors:
|
||||
for e in errors:
|
||||
print(f"ERROR: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
print(f"tech-log tenant: {len(techlog)} objects; PriorityClasses: {len(classes)}; keycloak NetworkPolicies: {len(policies)}")
|
||||
PY
|
||||
|
||||
echo "TENANTS AND POLICIES STATIC RENDER PASS"
|
||||
@@ -13,3 +13,10 @@ Alertmanager source는 selector discovery 대신 global
|
||||
`alertmanagerConfiguration.name=platform-alertmanager`를 참조한다. 참조 대상의
|
||||
Slack Secret이 준비되기 전에는 이 변경을 live에 적용하지 않고 기존 null 구성을
|
||||
유지한다.
|
||||
|
||||
Prometheus TSDB는 `outOfOrderTimeWindow: 10h`로 늦게 도착한 샘플을 받는다. 시계가
|
||||
앞으로 튀었다가 되돌아오면 TSDB 머리에 미래 시각 샘플이 남고, 창이 0이면 그 시각이
|
||||
지날 때까지 모든 수집이 `out of bounds`로 버려진다. 메트릭과 경보가 함께 멈추고,
|
||||
`absent()` 경보(`KubeAPIDown` 등)는 거짓으로 울린다. 10시간은 재부팅 때 RTC의 KST를
|
||||
UTC로 읽는 +9시간 오차를 덮는 값이다(2026-11-11 사고). 늦은 샘플이 없으면 추가 메모리는
|
||||
거의 들지 않는다. 시계 자체를 막는 설정은 `infrastructure/host`가 맡는다.
|
||||
|
||||
@@ -219,6 +219,8 @@ prometheus:
|
||||
scrapeInterval: 30s
|
||||
evaluationInterval: 30s
|
||||
walCompression: true
|
||||
tsdb:
|
||||
outOfOrderTimeWindow: 10h
|
||||
automountServiceAccountToken: true
|
||||
image:
|
||||
registry: quay.io
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# 플랫폼 PriorityClass
|
||||
|
||||
노드가 한 대라 자원이 모자라면 kubelet이 파드를 내보낸다. 내보낼 순서는 requests를 넘었는지,
|
||||
그다음 우선순위로 정한다. 2026-11-09 디스크 축출 때 플랫폼 파드는 모두 우선순위 0이라 tech-log
|
||||
운영 파드가 Grafana·kube-state-metrics와 같은 순위로 나갔다.
|
||||
|
||||
| 이름 | 값 | 선점 | 붙일 곳 |
|
||||
| --- | --- | --- | --- |
|
||||
| `platform-critical` | 1000000 | 낮은 것을 선점 | platform-postgres, Gitea, Keycloak, tech-log |
|
||||
| `platform-low` | -1000 | 선점 안 함 | Grafana, pgAdmin, Loki, Tempo |
|
||||
|
||||
- 아무것도 안 붙인 파드는 기본값 0이다. 시스템 클래스(`system-*`, 20억)는 그대로 가장 높다.
|
||||
- `globalDefault`는 둘 다 끈다. 새 파드가 모르게 우선순위를 얻지 않게 하려는 것이다.
|
||||
- 클래스를 만드는 것은 아무 파드도 바꾸지 않는다. **붙이는 것은 파드 재시작을 부르므로**
|
||||
k3s 재시작 창에 한다(`infrastructure/host/k3s/README.md`).
|
||||
|
||||
```sh
|
||||
kubectl apply -k services/priority-classes
|
||||
kubectl get priorityclass platform-critical platform-low
|
||||
```
|
||||
@@ -0,0 +1,5 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- priority-classes.yaml
|
||||
@@ -0,0 +1,25 @@
|
||||
apiVersion: scheduling.k8s.io/v1
|
||||
kind: PriorityClass
|
||||
metadata:
|
||||
name: platform-critical
|
||||
labels:
|
||||
app.kubernetes.io/part-of: platform
|
||||
value: 1000000
|
||||
globalDefault: false
|
||||
preemptionPolicy: PreemptLowerPriority
|
||||
description: >-
|
||||
Stateful platform services and production workloads that other services depend on
|
||||
(platform-postgres, Gitea, Keycloak, tech-log). Evicted after everything else.
|
||||
---
|
||||
apiVersion: scheduling.k8s.io/v1
|
||||
kind: PriorityClass
|
||||
metadata:
|
||||
name: platform-low
|
||||
labels:
|
||||
app.kubernetes.io/part-of: platform
|
||||
value: -1000
|
||||
globalDefault: false
|
||||
preemptionPolicy: Never
|
||||
description: >-
|
||||
Tools whose loss does not stop a user-facing service (Grafana, pgAdmin, Loki, Tempo).
|
||||
Evicted first and never preempts another pod.
|
||||
@@ -0,0 +1,44 @@
|
||||
# tech-log 테넌트 — 플랫폼 쪽 객체
|
||||
|
||||
tech-log(hyeonworks.com 운영)가 플랫폼을 쓰려면 플랫폼 namespace 안에 허용 객체가 있어야 한다.
|
||||
이 빌드 루트가 그 객체를 소유한다. 앱 자체(Deployment·Service·Ingress·ServiceMonitor·앱
|
||||
namespace 안의 NetworkPolicy)는 tech-log 저장소의 `deploy/`가 소유한다.
|
||||
|
||||
2026-11-11 점검(`docs/reviews/2026-11-11-k3s-maturity-review.md` 4.3절) 전까지 이 객체들은
|
||||
`kubectl apply`로만 들어가 있었고 어느 저장소에도 없었다. 처음 내용은 라이브 객체의
|
||||
`last-applied-configuration`을 그대로 옮겼다. 라이브와 다른 것은 `hyeonworks-prod`의 PSA 라벨뿐이다.
|
||||
|
||||
| 파일 | 객체 |
|
||||
| --- | --- |
|
||||
| `namespace.yaml` | Namespace `hyeonworks-prod`: 관측 대상 라벨, PSA `enforce=baseline`·`warn=restricted`·`audit=restricted` |
|
||||
| `platform-data.yaml` | `techlog` Database와 DatabaseRole(로그인만, 연결 30), Postgres로 들어오는 ingress |
|
||||
| `object-storage.yaml` | AIStor 9000으로 들어오는 ingress |
|
||||
| `observability-probes.yaml` | blackbox Probe 둘(공개 HTTPS, 내부 readiness) |
|
||||
| `observability-rules.yaml` | PrometheusRule `techlog` 일곱 개 |
|
||||
| `dashboards/techlog-operations.json` | Grafana 대시보드(`grafana-dashboard-techlog` ConfigMap으로 생성) |
|
||||
| `observability-network-policies.yaml` | blackbox → readiness, Prometheus → management scrape egress |
|
||||
|
||||
## 여기에 없는 것
|
||||
|
||||
- `platform-data/platform-postgres`의 `pg_hba` techlog 두 줄: Cluster 객체는
|
||||
`services/platform-postgres`가 소유한다.
|
||||
- Secret: `platform-data/techlog-db-credentials`(`kubernetes.io/basic-auth`, `username`은 정확히
|
||||
`techlog`)는 DatabaseRole이 참조한다. 앱 쪽 `hyeonworks-prod/hyeonworks-secrets`는 tech-log가
|
||||
소유한다. 둘 다 Git에 두지 않는다.
|
||||
|
||||
## PSA
|
||||
|
||||
`enforce=baseline`은 2026-11-12에 서버 dry-run(`kubectl label --dry-run=server`)으로 위반 0을
|
||||
확인하고 붙였다. `restricted`로 강제하면 지금 파드 셋(redis, backend, frontend)이 모두 걸린다
|
||||
(`allowPrivilegeEscalation`, capabilities, `runAsNonRoot`, seccomp). tech-log 쪽 securityContext가
|
||||
고쳐진 뒤 같은 dry-run이 경고 없이 통과하면 `enforce`를 `restricted`로 올린다.
|
||||
|
||||
## 렌더·적용
|
||||
|
||||
```sh
|
||||
bash scripts/validate/render-tenants-and-policies.sh
|
||||
kubectl kustomize services/tenants/techlog | kubectl diff -f -
|
||||
kubectl apply -k services/tenants/techlog
|
||||
```
|
||||
|
||||
새로 설치할 때는 이 루트를 tech-log `deploy/`보다 먼저 적용한다(namespace를 여기서 만든다).
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,23 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
# tech-log(hyeonworks.com) 테넌트의 플랫폼 쪽 객체. 앱 쪽 매니페스트는 tech-log repo가 소유한다.
|
||||
resources:
|
||||
- namespace.yaml
|
||||
- platform-data.yaml
|
||||
- object-storage.yaml
|
||||
- observability-probes.yaml
|
||||
- observability-rules.yaml
|
||||
- observability-network-policies.yaml
|
||||
|
||||
generatorOptions:
|
||||
disableNameSuffixHash: true
|
||||
labels:
|
||||
app.kubernetes.io/part-of: techlog
|
||||
grafana_dashboard: "1"
|
||||
|
||||
configMapGenerator:
|
||||
- name: grafana-dashboard-techlog
|
||||
namespace: observability
|
||||
files:
|
||||
- dashboards/techlog-operations.json
|
||||
@@ -0,0 +1,12 @@
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: hyeonworks-prod
|
||||
labels:
|
||||
observability.hyeonworks.com/enabled: 'true'
|
||||
pod-security.kubernetes.io/enforce: baseline
|
||||
pod-security.kubernetes.io/enforce-version: latest
|
||||
pod-security.kubernetes.io/warn: restricted
|
||||
pod-security.kubernetes.io/warn-version: latest
|
||||
pod-security.kubernetes.io/audit: restricted
|
||||
pod-security.kubernetes.io/audit-version: latest
|
||||
@@ -0,0 +1,22 @@
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: allow-techlog-backend
|
||||
namespace: object-storage
|
||||
spec:
|
||||
ingress:
|
||||
- from:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: hyeonworks-prod
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app: techlog-backend
|
||||
ports:
|
||||
- port: 9000
|
||||
protocol: TCP
|
||||
podSelector:
|
||||
matchLabels:
|
||||
aistor.min.io/objectStore: minio-aistor
|
||||
policyTypes:
|
||||
- Ingress
|
||||
@@ -0,0 +1,45 @@
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: blackbox-allow-techlog-health
|
||||
namespace: observability
|
||||
spec:
|
||||
egress:
|
||||
- ports:
|
||||
- port: 9001
|
||||
protocol: TCP
|
||||
to:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: hyeonworks-prod
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app: techlog-backend
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/name: prometheus-blackbox-exporter
|
||||
policyTypes:
|
||||
- Egress
|
||||
---
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: observability-allow-techlog-scrape
|
||||
namespace: observability
|
||||
spec:
|
||||
egress:
|
||||
- ports:
|
||||
- port: 9001
|
||||
protocol: TCP
|
||||
to:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: hyeonworks-prod
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app: techlog-backend
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/name: prometheus
|
||||
policyTypes:
|
||||
- Egress
|
||||
@@ -0,0 +1,46 @@
|
||||
apiVersion: monitoring.coreos.com/v1
|
||||
kind: Probe
|
||||
metadata:
|
||||
labels:
|
||||
observability.hyeonworks.com/instance: home
|
||||
name: techlog-edge
|
||||
namespace: observability
|
||||
spec:
|
||||
interval: 30s
|
||||
jobName: techlog-edge
|
||||
module: http_2xx
|
||||
prober:
|
||||
path: /probe
|
||||
scheme: http
|
||||
url: blackbox-exporter.observability.svc.cluster.local:9115
|
||||
scrapeTimeout: 15s
|
||||
targets:
|
||||
staticConfig:
|
||||
labels:
|
||||
application: techlog
|
||||
static:
|
||||
- https://hyeonworks.com/
|
||||
- https://hyeonworks.com/api/healthcheck
|
||||
---
|
||||
apiVersion: monitoring.coreos.com/v1
|
||||
kind: Probe
|
||||
metadata:
|
||||
labels:
|
||||
observability.hyeonworks.com/instance: home
|
||||
name: techlog-readiness
|
||||
namespace: observability
|
||||
spec:
|
||||
interval: 30s
|
||||
jobName: techlog-readiness
|
||||
module: http_2xx
|
||||
prober:
|
||||
path: /probe
|
||||
scheme: http
|
||||
url: blackbox-exporter.observability.svc.cluster.local:9115
|
||||
scrapeTimeout: 15s
|
||||
targets:
|
||||
staticConfig:
|
||||
labels:
|
||||
application: techlog
|
||||
static:
|
||||
- http://techlog-management.hyeonworks-prod.svc.cluster.local:9001/actuator/health/readiness
|
||||
@@ -0,0 +1,67 @@
|
||||
apiVersion: monitoring.coreos.com/v1
|
||||
kind: PrometheusRule
|
||||
metadata:
|
||||
labels:
|
||||
observability.hyeonworks.com/instance: home
|
||||
name: techlog
|
||||
namespace: observability
|
||||
spec:
|
||||
groups:
|
||||
- name: techlog
|
||||
rules:
|
||||
- alert: TechLogMetricsDown
|
||||
annotations:
|
||||
summary: TechLog metrics target is unreachable
|
||||
expr: up{namespace="hyeonworks-prod",service="techlog-management"} == 0
|
||||
for: 5m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: warning
|
||||
- alert: TechLogReadinessDown
|
||||
annotations:
|
||||
summary: TechLog dependency readiness is DOWN
|
||||
expr: probe_success{job="techlog-readiness"} == 0
|
||||
for: 3m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: critical
|
||||
- alert: TechLogHTTPSDown
|
||||
annotations:
|
||||
summary: TechLog HTTPS or API health is failing
|
||||
expr: probe_success{job="techlog-edge"} == 0
|
||||
for: 3m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: critical
|
||||
- alert: TechLogHTTP5xx
|
||||
annotations:
|
||||
summary: TechLog HTTP 5xx exceeds 5%
|
||||
expr: (sum(rate(http_server_requests_seconds_count{namespace="hyeonworks-prod",status=~"5.."}[5m])) / clamp_min(sum(rate(http_server_requests_seconds_count{namespace="hyeonworks-prod"}[5m])),0.001)) > 0.05 and sum(increase(http_server_requests_seconds_count{namespace="hyeonworks-prod"}[5m])) > 20
|
||||
for: 5m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: warning
|
||||
- alert: TechLogLatencyHigh
|
||||
annotations:
|
||||
summary: TechLog p99 latency exceeds 2 seconds
|
||||
expr: histogram_quantile(0.99,sum by(le)(rate(http_server_requests_seconds_bucket{namespace="hyeonworks-prod",uri!~"/actuator.*"}[5m]))) > 2
|
||||
for: 10m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: warning
|
||||
- alert: TechLogHeapPressure
|
||||
annotations:
|
||||
summary: TechLog heap usage exceeds 85%
|
||||
expr: sum(jvm_memory_used_bytes{namespace="hyeonworks-prod",area="heap"}) / sum(jvm_memory_max_bytes{namespace="hyeonworks-prod",area="heap"}) > 0.85
|
||||
for: 10m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: warning
|
||||
- alert: TechLogDatabasePoolWaiting
|
||||
annotations:
|
||||
summary: TechLog database connections are queued
|
||||
expr: hikaricp_connections_pending{namespace="hyeonworks-prod"} > 0
|
||||
for: 5m
|
||||
labels:
|
||||
application: techlog
|
||||
severity: warning
|
||||
@@ -0,0 +1,55 @@
|
||||
apiVersion: postgresql.cnpg.io/v1
|
||||
kind: Database
|
||||
metadata:
|
||||
name: platform-postgres-techlog
|
||||
namespace: platform-data
|
||||
spec:
|
||||
cluster:
|
||||
name: platform-postgres
|
||||
databaseReclaimPolicy: retain
|
||||
ensure: present
|
||||
name: techlog
|
||||
owner: techlog
|
||||
---
|
||||
apiVersion: postgresql.cnpg.io/v1
|
||||
kind: DatabaseRole
|
||||
metadata:
|
||||
name: platform-postgres-techlog
|
||||
namespace: platform-data
|
||||
spec:
|
||||
bypassrls: false
|
||||
cluster:
|
||||
name: platform-postgres
|
||||
connectionLimit: 30
|
||||
createdb: false
|
||||
createrole: false
|
||||
databaseRoleReclaimPolicy: retain
|
||||
login: true
|
||||
name: techlog
|
||||
passwordSecret:
|
||||
name: techlog-db-credentials
|
||||
replication: false
|
||||
superuser: false
|
||||
---
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: NetworkPolicy
|
||||
metadata:
|
||||
name: allow-techlog-backend
|
||||
namespace: platform-data
|
||||
spec:
|
||||
ingress:
|
||||
- from:
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
kubernetes.io/metadata.name: hyeonworks-prod
|
||||
podSelector:
|
||||
matchLabels:
|
||||
app: techlog-backend
|
||||
ports:
|
||||
- port: 5432
|
||||
protocol: TCP
|
||||
podSelector:
|
||||
matchLabels:
|
||||
cnpg.io/cluster: platform-postgres
|
||||
policyTypes:
|
||||
- Ingress
|
||||
Reference in New Issue
Block a user