diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2ff8975 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +# platform-core 문서 지도 + +이 폴더는 이 저장소 안에 두는 기록 문서만 담는다. 아키텍처·운영 절차·결정 기록의 +정본은 루트 [README](../README.md)가 가리키는 중앙 Platform 문서다. 구성요소의 사용법과 +적용 절차는 각 디렉터리의 `README.md`와 [`bootstrap/manual/`](../bootstrap/manual/)에 있다. + +| 폴더 | 담는 것 | 수명 | +|---|---|---| +| [`reviews/`](reviews/) | 점검·리뷰 결과 | 기록(쓴 날의 상태) | +| [`platform/plans/`](platform/plans/) | 설계 메모 | 기록 | +| [`superpowers/plans/`](superpowers/plans/) | 실행 계획 | 기록 | + +폴더 이름과 수명 구분은 design-docs `conventions/docs-system.md` 2절을 따른다. +새 폴더를 만들면 같은 변경에서 이 표에 더한다. + +## 기록 문서의 머리 블록 + +`reviews/`에 새로 쓰는 기록은 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다. +형식과 상태 어휘는 design-docs `conventions/docs-system.md` 4절이 정본이다. 리뷰의 +상태는 「진행 중」·「닫힘」 둘이다. 이 절을 만들기 전에 쓴 `platform/plans/`· +`superpowers/plans/` 문서에는 머리 블록이 없다. diff --git a/docs/reviews/2026-11-11-k3s-maturity-review.md b/docs/reviews/2026-11-11-k3s-maturity-review.md new file mode 100644 index 0000000..fa519d3 --- /dev/null +++ b/docs/reviews/2026-11-11-k3s-maturity-review.md @@ -0,0 +1,485 @@ + +> **기록 · 리뷰** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 진행 중 +- 작성일: 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는 **이 PR에서 고침**. 나머지는 둘 곳을 정한다(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 진행 중 | + +점검 중 본 사실 하나를 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에 못 붙음** | **이 PR에서 repo를 라이브에 맞춤** | +| `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에서 고친 것 + +위험이 낮고 되돌릴 수 있는 매니페스트·문서만 고쳤다. 클러스터에는 아무것도 적용하지 않았다. + +| 변경 | 파일 | 라이브에 적용하면 | 되돌리기 | +|---|---|---|---| +| platform-postgres `pg_hba`에 라이브와 같은 techlog 두 줄 + 렌더 불변식 둘 | `services/platform-postgres/base/cluster.yaml`, `scripts/validate/render-phase1.sh`, `services/platform-postgres/README.md` | 바뀌는 것 없음. `kubectl diff`에서 Cluster 차이가 사라졌다(남은 차이는 4.2의 DatabaseRole 기본값 필드뿐) | 커밋 되돌리기 | +| 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/` | 없음 | — | + +렌더 결과(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줄만 +) + +$ 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 | | Backup and Restore with SQLite — `db/`와 `token`을 함께 | +| A1·A15 | | 26장 — 복원이 되는지 정기적으로 증명, 성공 신호가 끊기면 경보 | +| A2 | , | stable 채널 권장, minor 건너뛰기 금지 | +| A3 | | 기본 문턱, 하나를 바꾸면 나머지가 0이 됨(`MergeDefaultEvictionSettings`), 축출 순위 | +| A3 | | kubeReserved·systemReserved | +| A3 | | 단일 인스턴스 stateful 앱의 PDB | +| A3 | | PriorityClass | +| A4 | | probe 종류별 쓰임 | +| A5 | | 태그는 움직이고 digest는 고정 | +| A5·A7·A8 | | Images, Authentication & Authorization, Network security | +| A6 | , | provider 선택, aescbc 「약함」·secretbox 「강함」 | +| A7 | | `system:masters`를 쓰지 말 것, 토큰 자동 마운트 끄기 | +| A9 | | Pod Security(`psa.yaml`), API Server audit configuration, `protect-kernel-defaults`, NetworkPolicies | +| A9·A10 | | 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 | | `shutdownGracePeriod` 둘 다 0이면 꺼짐 | +| A11 | | 유효 365일, 만료 120일 안이면 시작할 때 갱신(2025-05 릴리스 전에는 90일), `k3s certificate rotate` | +| A12 | , | local PV 제약, local-path 용량 제한 없음 | +| A13 | | Watchdog과 외부 dead man's switch | +| A14 | | 원칙 1~4(선언, 버전 관리, 자동 pull, 지속 조정) | +| 전체 | | 단일 기계는 단일 장애점 | +| 전체 | NSA/CISA Kubernetes Hardening Guide v1.2(2022-08), | 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: 새 불변식이 수정 전 파일에서 실패(RED)하고 수정 후 통과(GREEN). 수정 후 렌더로 `kubectl diff`하면 Cluster 차이가 없다. + - Traefik: `validate.sh` 통과, `kubectl diff`에 resources만 더해진다. + - 이 보고서: 반증할 수 있는 가정 — 「repo를 다시 적용해도 운영이 깨지지 않는다」는 이 PR 뒤에는 pg_hba에 대해 참이어야 한다. 남은 반례는 4.3의 객체들이 지워지는 경우다. + - 큰 일의 소유자 승인: 소유자 지시 「k3s 구성의 성숙도를 보고 문제 지점을 확인하라」(template-program README 4절 W6, 2026-11-11)를 이 점검의 승인으로 보았다. 구조를 바꾸는 항목은 만들지 않고 8절에 결정으로 올렸다.