docs(reviews): add the k3s maturity review and set Traefik resources #3

Merged
donghyeon.kang merged 5 commits from donghyeon.kang/k3s-maturity-review AGit into main 2026-11-11 15:14:16 +00:00
Owner

무엇을, 왜

desktop 한 대의 k3s가 운영(hyeonworks.com)과 프로그램 전체 CI를 같이 돌린다. 이번 주 사고 셋이 그 구성의 약한 곳을 보여 줬다. 사고가 나기 전에 남은 약점을 찾으려고 구성 성숙도를 점검했다(template-program README 4절 W6).

이 PR은 두 가지를 넣고, 하나는 w1에 넘긴다.

  1. 점검 보고서 docs/reviews/2026-11-11-k3s-maturity-review.md: 16개 축의 성숙도(0~5), 위험 상위 10개, repo↔클러스터 drift 표, kube-bench·kube-linter·Polaris·kubescape 결과, 권하는 순서, 소유자 결정 6개. docs/README.md는 새 docs/reviews/ 폴더를 넣으면서 만든 문서 지도다.
  2. platform-postgres pg_hba drift — w1에 넘김: 라이브 Cluster에는 tech-log용 두 줄(host techlog techlog all scram-sha-256, host all techlog all reject)이 있는데 repo에는 없다. 지금 렌더를 그대로 적용하면 운영 backend가 DB에 못 붙는다. 고치는 변경(1c4ef9a: 두 줄 + 렌더 불변식)을 만들고 검증했지만, CNPG 백업(w1 범위)이 같은 cluster.yaml을 고치므로 이 PR에서는 되돌렸다(388eb74). w1이 1c4ef9a를 cherry-pick한다. 그 전까지 platform-postgres 렌더를 그대로 적용하지 않는다.
  3. Traefik requests·limits: k3s 기본 Traefik은 BestEffort다. 이 노드 kubelet에는 메모리 축출 문턱이 없어서 메모리가 모자라면 커널 OOM killer가 고르고, BestEffort는 oom_score_adj 1000이라 먼저 죽는다. 모든 공개 경로가 이 파드 하나를 지난다. requests cpu: 50m·memory: 64Mi, limit memory: 256Mi(CPU limit 없음)를 base와 overlay patch 둘에 넣었다.

위험 상위 5개(자세한 것은 보고서 0.3절):

  1. 백업이 하나도 없다. CNPG는 w1이 하고 있고, Gitea 저장소 PV·k3s datastore·AIStor는 w1 범위 밖이다.
  2. DB·Gitea·Prometheus PV가 OS·이미지·빌드 캐시와 같은 SSD 파티션에 있다.
  3. 메모리 압박 보호가 없다(메모리 축출 문턱 0, 예약 0, Postgres oom_score_adj 985).
  4. repo를 다시 적용하면 운영이 깨지는 drift가 있다(pg_hba, 고칠 변경은 w1에 넘김). tech-log 운영 객체 27개는 아직 repo 밖이다.
  5. 감사 로그가 없고, 일상 kubeconfig가 회수할 수 없는 system:masters 인증서다.

고른 방법과 버린 대안

  • pg_hba는 「repo를 라이브에 맞춘다」로 만들었다. 라이브에서 두 줄을 빼는 쪽은 운영 장애라 버렸다. tech-log의 DatabaseRole·Database·NetworkPolicy까지 옮기는 것은 둘 곳이 소유자 결정이라(보고서 8절 결정 2) 이 PR에 넣지 않았다.
  • Traefik은 Guaranteed로 올리지 않았다. 안 쓰는 CPU를 예약하게 되고, 메모리 압박의 진짜 해결은 kubelet 예약·축출 문턱(k3s 재시작 필요)이기 때문이다. 보고서 7.2절에 순서를 적었다.
  • PriorityClass는 붙이는 순간 Postgres·Gitea·Keycloak이 재시작되므로 넣지 않았다. PDB는 노드가 한 대라 drain만 막아서 더하지 않았다.
  • Keycloak 원격 ref·이미지 digest 고정은 apply-keycloak.sh의 방어 문자열까지 바꿔야 해서 따로 낸다.
  • 점검기 넷은 빌드급 부하가 아니고 heavy.lock 앞에 다른 작업이 4개 줄 서 있어서, lock 대신 nice -n 10으로 돌렸다.

위험과 영향

  • 이 PR은 클러스터에 아무것도 적용하지 않았다. 적용은 병합 뒤 총괄·소유자가 정한다.
  • Traefik: trust overlay를 적용하면 k3s helm-controller가 Traefik을 한 번 다시 배포한다(RollingUpdate, 몇 초). 적용은 기존 infrastructure/networking/traefik/scripts/apply-trust.sh로 한다.
  • 겹침: 이 PR의 최종 변경은 docs/와 infrastructure/networking/traefik/뿐이다. w1 브랜치 파일과도, w1 범위(CNPG 백업의 services/platform-postgres/)와도 겹치지 않는다. 커밋에는 pg_hba 변경과 그 되돌림이 같이 있어 순변경은 0이다(force push 금지라 되돌림 커밋으로 뺐다).
  • 보고서의 도구 결과는 항목마다 원인을 대조했다. kube-bench FAIL 25개 중 21개는 이미지에 journalctl이 없어 생긴 오탐이다. kubescape C-0012(설정 안의 자격 증명) 8건도 이름만 걸린 오탐이다(값은 보지 않고 형태만 확인).

검증

desktop, Helm 3.19.4, Kustomize 5.8.1(kubectl 내장), 2026-11-11.

# 최종 head 4fa02fb 기준(로그: 공유 노트 k3s-maturity-review-verify.log)
$ bash scripts/validate/render-phase1.sh                                    (exit 0)
$ bash scripts/validate/render-phase2.sh                                    (exit 0)

$ 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                (exit 0)
  • baseline·observe overlay 렌더에도 같은 resources가 들어간다(각 2줄 확인).
  • 점검기: kube-bench v0.16.0, kube-linter v0.8.3, Polaris 10.1.8, kubescape v4.0.16을 digest로 기록하고 돌린 뒤 이미지를 지웠다.
  • 돌리지 못한 것: scan-platform-sensitive-source.sh는 정본 경로(/home/donghyeon/workspace/platform)에 고정돼 임시 사본에 쓸 수 없다. test-scan-platform-sensitive-source.sh는 main 원본 사본에서도 같은 이유로 실패해(「canonical scanner test content leaf found a credential literal」) 이 PR과 무관하다.
  • 이 브랜치는 PR #2 병합(41b46f6) 뒤 main 위로 다시 올렸다.
  • w1에 넘긴 pg_hba 변경(1c4ef9a)의 증거: 수정 전 cluster.yaml + 새 불변식은 ERROR: the tech-log role must authenticate only to the tech-log database(exit 1), 수정 후 통과(exit 0), 수정 후 렌더의 kubectl diff에 Cluster 차이 없음. 보고서 6.1절.

리뷰어가 볼 곳

  • docs/reviews/2026-11-11-k3s-maturity-review.md 0절(성숙도 표·위험 상위 10개)과 8절(소유자 결정).
  • infrastructure/networking/traefik/overlays/*/…-patch.yaml: patch가 valuesContent를 통째로 바꾸므로 세 곳 값이 같아야 한다.

관련

  • design-docs template-program/README.md 4절 W6, 5절(w1 범위)
  • 공유 노트 desktop-pod-recovery-2026-11-11.md, w1-infra-hardening.md, k3s-maturity-review.md
  • PR #2(병합됨), w1 브랜치 claude/vigorous-booth-e9c7b9
## 무엇을, 왜 desktop 한 대의 k3s가 운영(hyeonworks.com)과 프로그램 전체 CI를 같이 돌린다. 이번 주 사고 셋이 그 구성의 약한 곳을 보여 줬다. 사고가 나기 전에 남은 약점을 찾으려고 구성 성숙도를 점검했다(template-program README 4절 W6). 이 PR은 두 가지를 넣고, 하나는 w1에 넘긴다. 1. **점검 보고서** `docs/reviews/2026-11-11-k3s-maturity-review.md`: 16개 축의 성숙도(0~5), 위험 상위 10개, repo↔클러스터 drift 표, kube-bench·kube-linter·Polaris·kubescape 결과, 권하는 순서, 소유자 결정 6개. `docs/README.md`는 새 `docs/reviews/` 폴더를 넣으면서 만든 문서 지도다. 2. **platform-postgres `pg_hba` drift — w1에 넘김**: 라이브 Cluster에는 tech-log용 두 줄(`host techlog techlog all scram-sha-256`, `host all techlog all reject`)이 있는데 repo에는 없다. 지금 렌더를 그대로 적용하면 운영 backend가 DB에 못 붙는다. 고치는 변경(`1c4ef9a`: 두 줄 + 렌더 불변식)을 만들고 검증했지만, CNPG 백업(w1 범위)이 같은 `cluster.yaml`을 고치므로 이 PR에서는 되돌렸다(`388eb74`). w1이 `1c4ef9a`를 cherry-pick한다. 그 전까지 platform-postgres 렌더를 그대로 적용하지 않는다. 3. **Traefik requests·limits**: k3s 기본 Traefik은 BestEffort다. 이 노드 kubelet에는 메모리 축출 문턱이 없어서 메모리가 모자라면 커널 OOM killer가 고르고, BestEffort는 `oom_score_adj` 1000이라 먼저 죽는다. 모든 공개 경로가 이 파드 하나를 지난다. requests `cpu: 50m`·`memory: 64Mi`, limit `memory: 256Mi`(CPU limit 없음)를 base와 overlay patch 둘에 넣었다. 위험 상위 5개(자세한 것은 보고서 0.3절): 1. 백업이 하나도 없다. CNPG는 w1이 하고 있고, Gitea 저장소 PV·k3s datastore·AIStor는 w1 범위 밖이다. 2. DB·Gitea·Prometheus PV가 OS·이미지·빌드 캐시와 같은 SSD 파티션에 있다. 3. 메모리 압박 보호가 없다(메모리 축출 문턱 0, 예약 0, Postgres `oom_score_adj` 985). 4. repo를 다시 적용하면 운영이 깨지는 drift가 있다(pg_hba, 고칠 변경은 w1에 넘김). tech-log 운영 객체 27개는 아직 repo 밖이다. 5. 감사 로그가 없고, 일상 kubeconfig가 회수할 수 없는 `system:masters` 인증서다. ## 고른 방법과 버린 대안 - pg_hba는 「repo를 라이브에 맞춘다」로 만들었다. 라이브에서 두 줄을 빼는 쪽은 운영 장애라 버렸다. tech-log의 DatabaseRole·Database·NetworkPolicy까지 옮기는 것은 둘 곳이 소유자 결정이라(보고서 8절 결정 2) 이 PR에 넣지 않았다. - Traefik은 Guaranteed로 올리지 않았다. 안 쓰는 CPU를 예약하게 되고, 메모리 압박의 진짜 해결은 kubelet 예약·축출 문턱(k3s 재시작 필요)이기 때문이다. 보고서 7.2절에 순서를 적었다. - PriorityClass는 붙이는 순간 Postgres·Gitea·Keycloak이 재시작되므로 넣지 않았다. PDB는 노드가 한 대라 drain만 막아서 더하지 않았다. - Keycloak 원격 ref·이미지 digest 고정은 `apply-keycloak.sh`의 방어 문자열까지 바꿔야 해서 따로 낸다. - 점검기 넷은 빌드급 부하가 아니고 heavy.lock 앞에 다른 작업이 4개 줄 서 있어서, lock 대신 `nice -n 10`으로 돌렸다. ## 위험과 영향 - 이 PR은 클러스터에 아무것도 적용하지 않았다. 적용은 병합 뒤 총괄·소유자가 정한다. - Traefik: trust overlay를 적용하면 k3s helm-controller가 Traefik을 한 번 다시 배포한다(RollingUpdate, 몇 초). 적용은 기존 `infrastructure/networking/traefik/scripts/apply-trust.sh`로 한다. - 겹침: 이 PR의 최종 변경은 `docs/`와 `infrastructure/networking/traefik/`뿐이다. w1 브랜치 파일과도, w1 범위(CNPG 백업의 `services/platform-postgres/`)와도 겹치지 않는다. 커밋에는 pg_hba 변경과 그 되돌림이 같이 있어 순변경은 0이다(force push 금지라 되돌림 커밋으로 뺐다). - 보고서의 도구 결과는 항목마다 원인을 대조했다. kube-bench FAIL 25개 중 21개는 이미지에 `journalctl`이 없어 생긴 오탐이다. kubescape C-0012(설정 안의 자격 증명) 8건도 이름만 걸린 오탐이다(값은 보지 않고 형태만 확인). ## 검증 desktop, Helm 3.19.4, Kustomize 5.8.1(kubectl 내장), 2026-11-11. ```text # 최종 head 4fa02fb 기준(로그: 공유 노트 k3s-maturity-review-verify.log) $ bash scripts/validate/render-phase1.sh (exit 0) $ bash scripts/validate/render-phase2.sh (exit 0) $ 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 (exit 0) ``` - baseline·observe overlay 렌더에도 같은 resources가 들어간다(각 2줄 확인). - 점검기: kube-bench v0.16.0, kube-linter v0.8.3, Polaris 10.1.8, kubescape v4.0.16을 digest로 기록하고 돌린 뒤 이미지를 지웠다. - 돌리지 못한 것: `scan-platform-sensitive-source.sh`는 정본 경로(`/home/donghyeon/workspace/platform`)에 고정돼 임시 사본에 쓸 수 없다. `test-scan-platform-sensitive-source.sh`는 main 원본 사본에서도 같은 이유로 실패해(「canonical scanner test content leaf found a credential literal」) 이 PR과 무관하다. - 이 브랜치는 PR #2 병합(`41b46f6`) 뒤 main 위로 다시 올렸다. - w1에 넘긴 pg_hba 변경(`1c4ef9a`)의 증거: 수정 전 cluster.yaml + 새 불변식은 `ERROR: the tech-log role must authenticate only to the tech-log database`(exit 1), 수정 후 통과(exit 0), 수정 후 렌더의 `kubectl diff`에 Cluster 차이 없음. 보고서 6.1절. ## 리뷰어가 볼 곳 - `docs/reviews/2026-11-11-k3s-maturity-review.md` 0절(성숙도 표·위험 상위 10개)과 8절(소유자 결정). - `infrastructure/networking/traefik/overlays/*/…-patch.yaml`: patch가 valuesContent를 통째로 바꾸므로 세 곳 값이 같아야 한다. ## 관련 - design-docs `template-program/README.md` 4절 W6, 5절(w1 범위) - 공유 노트 `desktop-pod-recovery-2026-11-11.md`, `w1-infra-hardening.md`, `k3s-maturity-review.md` - PR #2(병합됨), w1 브랜치 `claude/vigorous-booth-e9c7b9`
donghyeon.kang added 3 commits 2026-11-11 14:40:57 +00:00
The live platform-postgres Cluster has two pg_hba rules for the techlog
role that the repository does not declare. They were added outside the
repository for hyeonworks.com. Applying the current render would remove
them and the production backend could no longer reach its database.

Declare the same two rules, in the same position after the Keycloak
pair, and pin them with render invariants like the Gitea and Keycloak
pairs. The techlog DatabaseRole, Database, Secret and NetworkPolicies
stay outside this build root; where they belong is an owner decision
recorded in the 2026-11-11 maturity review.

Risk: none for the live cluster. The rendered Cluster now matches the
live object. A fresh install without the tech-log tenant gets two
rules for a role that does not exist, which PostgreSQL ignores.

Verification (desktop, Helm 3.19.4, Kustomize 5.8.1):
- render-phase1.sh with the old cluster.yaml and the new invariants
  fails: "the tech-log role must authenticate only to the tech-log
  database"; with the new cluster.yaml it passes.
- kubectl diff of the new render against the live cluster shows no
  Cluster change; only the pre-existing DatabaseRole default fields.
The k3s-bundled Traefik runs with no requests or limits, so it is a
BestEffort pod. The kubelet on this node has no memory eviction
threshold (the k3s default evictionHard only covers nodefs and
imagefs), so under memory pressure the kernel OOM killer chooses, and
BestEffort containers have oom_score_adj 1000. Every public route goes
through this one pod.

Set requests cpu 50m / memory 64Mi and a 256Mi memory limit in the base
and in both overlay patches, because the baseline and trust patches
replace valuesContent as a whole. No CPU limit, to avoid throttling.
Measured use on 2026-11-11 was about 5m CPU and 42Mi memory.

Rejected: raising Traefik to Guaranteed. It would reserve CPU the
ingress does not use, and the real fix for memory pressure is kubelet
reservation and eviction thresholds, which need a k3s restart.

Risk: applying the trust overlay makes the k3s helm-controller roll
Traefik once (RollingUpdate, a few seconds). Not applied here.

Verification (desktop):
- infrastructure/networking/traefik/scripts/validate.sh passes.
- kubectl diff of the trust overlay against the live HelmChartConfig
  adds only the resources block.
- baseline and observe renders both contain the same resources.
The desktop k3s runs production and all CI on one node, and three
incidents this week came from that. Record where the configuration is
weak before the next one.

The review scores 16 axes from 0 to 5 against the k3s hardening guide,
the k3s CIS self-assessment, the NSA/CISA hardening guide and the
Kubernetes security checklist, lists the top ten risks, compares the
rendered repository with the live cluster, and summarizes kube-bench,
kube-linter, Polaris and kubescape runs. Items W1 is already fixing are
marked and not repeated. docs/README.md is the new docs map that the
docs-system convention asks for when a docs folder is added.

Risk: documentation only. Tool results were checked finding by finding;
21 kube-bench FAILs and several Polaris and kubescape items are false
positives and are reported as such.

Verification: every count and value in the review comes from read-only
commands run on 2026-11-11 (kubectl get/diff, configz, journal, lsblk,
openssl). The scanners ran with pinned digests and their images were
removed afterwards.
donghyeon.kang added 2 commits 2026-11-11 14:45:45 +00:00
This reverts commit 1c4ef9a.

W1 owns the CNPG backup work, which changes the same Cluster manifest
(services/platform-postgres/base/cluster.yaml). The program rule is that
another session does not edit files in W1's scope; overlaps are recorded
as findings and handed over. The drift itself is unchanged: the live
Cluster still has two techlog pg_hba rules the repository does not
declare, so applying the current render would cut the production
backend off its database. The exact change, its render invariants and
the RED/GREEN evidence are in the maturity review, section 6.

Verification: git diff origin/main...HEAD no longer lists any
services/platform-postgres or scripts/validate/render-phase1.sh path.
The previous commit took the tech-log pg_hba change out of this PR
because W1's CNPG backup work owns the same Cluster manifest. Update the
review so it no longer says the fix is in this PR: section 6.1 now gives
W1 the exact change (commit 1c4ef9a to cherry-pick), its render
invariants and the RED/GREEN and kubectl diff evidence, and the W1
overlap table lists it.

Verification: grep finds no remaining "fixed in this PR" claim for
pg_hba; git diff origin/main...HEAD lists only docs/ and Traefik paths.
donghyeon.kang changed title from docs(reviews): add the k3s maturity review with two low-risk fixes to docs(reviews): add the k3s maturity review and set Traefik resources 2026-11-11 15:14:15 +00:00
donghyeon.kang merged commit 7580eb7f75 into main 2026-11-11 15:14:16 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/platform-core#3