Author SHA1 Message Date
DongHyeonka 3eafb7e1d8 feat(validate): add a live drift check against the repository renders
The 2026-11-11 review found a pg_hba rule that existed only in the
cluster by rendering every root by hand and running kubectl diff.
Nothing does that regularly, so drift is found by accident.

live-drift-check.sh renders all live roots (Phase 1 and 2, admin
services, observability core, the Traefik trust overlay, the tenant,
PriorityClass and keycloak policy roots), strips Secrets and runs
kubectl diff, which is a server-side dry run. It prints one line per
drifted object, honours a dated accepted-drift list and can write
Prometheus textfile metrics for a later alert.

Risk: read-only. It consumes the render scripts' verified-output-dir
handoff and deletes those directories on exit; the README notes this
second consumer. Secret values are not compared.

Verification (desktop, before this series is applied): 17 drifted
objects, matching the review plus the new roots; exit 1; the textfile
holds platform_live_drift_objects 17.
2026-11-12 00:29:18 +09:00
DongHyeonka ebdf33f072 feat(tenants): declare the tech-log objects inside platform namespaces
The tech-log tenant needs objects inside platform namespaces: its
database and role, ingress to Postgres and AIStor, blackbox probes,
alert rules, a dashboard and two observability NetworkPolicies. They
were only ever applied with kubectl and no repository holds them, so a
deleted object cannot be recreated and a platform re-apply can drop
tech-log access without anyone noticing.

Declare them in services/tenants/techlog, copied from each object's
last-applied configuration. The dashboard follows the repository's
dashboard pattern (JSON file + configMapGenerator, same name, same
labels). The hyeonworks-prod Namespace moves here as the tenant
boundary and gets PSA enforce=baseline, warn/audit=restricted.

Rejected: enforce=restricted now. A server dry-run shows all three
tech-log pods would violate it; baseline has zero violations.

Risk: the render matches the live objects exactly except the added PSA
labels. The pg_hba rules and the Secret stay out of this root (Cluster
owner and Git policy).

Verification (desktop):
- render-tenants-and-policies.sh passes.
- kubectl diff of the render shows only the Namespace PSA labels.
- kubectl label --dry-run=server enforce=baseline: no warnings.
2026-11-12 00:29:18 +09:00
DongHyeonka c0749ec8a4 feat(keycloak): default-deny the keycloak namespace egress
The keycloak namespace only has the ingress policy the Keycloak
Operator creates. Neither the Keycloak pod nor the Operator pod has any
egress restriction, unlike every other platform namespace.

Add a namespace-wide default deny and allow only what is used: DNS,
platform-postgres 5432 (server and realm-import jobs), JGroups between
Keycloak pods, and for the Operator the API server and the Keycloak
management ports. Keycloak ingress stays owned by the Operator policy.

Rejected: allowing public 443 like Gitea does. Neither the repository
nor the Keycloak CR configures SMTP or an external identity provider,
and the only open TCP connections from keycloak-0 on 2026-11-12 were to
PostgreSQL. Adding SMTP or an IdP later needs a new egress rule; the
README says so.

Risk: a missed dependency would break logins for every service. The
README lists the post-apply checks (OIDC discovery, a new TCP
connection to Postgres from keycloak-0, Operator logs) and the one-line
rollback.

Verification: render and kubectl diff only add the five policies.
2026-11-12 00:29:18 +09:00
DongHyeonka c2a3f75bc3 feat(priority): add platform-critical and platform-low PriorityClasses
Every platform pod runs at priority 0. During the 2026-11-09 disk
eviction the tech-log production pods were ranked with Grafana and
kube-state-metrics. The kubelet ranks evictions by usage over requests
and then by priority, so without classes the database and the
production app have no head start.

Add two classes and attach nothing yet: platform-critical (1000000,
may preempt) for platform-postgres, Gitea, Keycloak and tech-log, and
platform-low (-1000, never preempts) for Grafana, pgAdmin, Loki and
Tempo. Neither is the global default, so no pod changes silently.

Risk: creating the classes changes no pod. Attaching them restarts the
pods, so that is left for the k3s restart window.

Verification: render-tenants-and-policies.sh (added later in this
series) checks the values, the preemption policy and globalDefault.
2026-11-12 00:28:57 +09:00
donghyeon.kang 7580eb7f75 Merge pull request 'docs(reviews): add the k3s maturity review and set Traefik resources' (#3) from donghyeon.kang/k3s-maturity-review into main 2026-11-11 15:14:16 +00:00
DongHyeonka 4fa02fb43d docs(reviews): record the pg_hba fix as handed to W1
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.
2026-11-11 23:44:19 +09:00
DongHyeonka 388eb74d4c revert(platform-postgres): hand the tech-log pg_hba fix to W1
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.
2026-11-11 23:43:37 +09:00
DongHyeonka 18638f3782 docs(reviews): add the 2026-11-11 k3s maturity review
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.
2026-11-11 23:40:08 +09:00
DongHyeonka 497c37b44b fix(traefik): give the ingress controller requests and a memory limit
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.
2026-11-11 23:39:58 +09:00
DongHyeonka 1c4ef9affd fix(platform-postgres): keep the tech-log pg_hba rules the cluster uses
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.
2026-11-11 23:39:58 +09:00
donghyeon.kang 41b46f64ea Merge pull request 'fix(observability): let Prometheus accept samples after a clock jump' (#2) from fix/prometheus-ooo-window into main 2026-11-11 14:18:34 +00:00
DongHyeonka af5a90bef8 fix(observability): let Prometheus accept samples after a clock jump
On 2026-11-11 the desktop booted with the RTC read as UTC while it held
KST, so the clock ran 9 hours ahead until NTP pulled it back. Prometheus
had written one hour of samples stamped 18:36-19:36Z into its TSDB head
during that window. With outOfOrderTimeWindow at the chart default of
0s, every later scrape was older than the head's valid range and was
dropped as "out of bounds". From 11:21Z no metric was stored, no rule
could fire on real data, and KubeAPIDown (an absent() rule) fired
falsely. It would have stayed blind until the wall clock passed the
bogus head time, about 7 hours later.

Set prometheusSpec.tsdb.outOfOrderTimeWindow to 10h. Samples up to 10
hours behind the head are now accepted, which covers the +9h KST-as-UTC
misread. The README records why.

Rejected: deleting the head WAL from the Retain PV. It works at once
but removes persisted data and needs the pod stopped. Rejected: waiting
for the clock to catch up. It leaves monitoring blind for hours during
the period when the cause of the incident is still being found.

Risk: out-of-order samples use an extra in-memory head and vertical
compaction only while they arrive; in normal operation none arrive. A
genuinely late exporter could now backfill up to 10h, which is harmless
on this single-node Prometheus. Preventing the clock jump itself is the
host change in infrastructure/host, not this commit.

Verification: the values file parses and holds
prometheus.prometheusSpec.tsdb.outOfOrderTimeWindow=10h. The live
Prometheus CR already carried tsdb.outOfOrderTimeWindow=0s from this
chart key, so the key maps to spec.tsdb. The same value was patched
onto the live CR: the operator wrote out_of_order_time_window: 10h, the
config reloaded at 13:04:37Z, "too old" warnings dropped to 0, all 34
targets report up, and KubeAPIDown resolved. The pinned renderer
(scripts/validate/render-observability-core.sh) was not run: it requires
Helm v3.19.4 and kustomize v5.8.1, which are not installed on the
laptop or the desktop.
2026-11-11 22:09:23 +09:00
27 changed files with 1431 additions and 0 deletions
+21
View File
@@ -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/` 문서에는 머리 블록이 없다.
@@ -0,0 +1,496 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 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절에 결정으로 올렸다.
@@ -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
+37
View File
@@ -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 값의 차이는 보지 않는다.
+10
View File
@@ -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 위와 같은 이미지 문자열 차이.
+173
View File
@@ -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
+20
View File
@@ -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.
+44
View File
@@ -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
+12
View File
@@ -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