# 단일 노드 k3s 홈 플랫폼 as-built SSOT — 디스크 세 장에서 Slack 알림까지
이 문서는 `desktop`(`donghyeon-System-Product-Name`, `192.168.0.107`) 한 대에서 돌고 있는
공용 플랫폼의 **현재 모습**을 한 곳에 모은 정본이다. 선언은
`/home/donghyeon/workspace/platform` 저장소가 갖고 있고, 설계와 운영 기록은
`/home/donghyeon/workspace/docs/platform` 에 흩어져 있으며, 실제로 돌고 있는 것은
클러스터와 호스트에 있다. **세 곳이 서로 다른 것을 말하기도 한다.** 이 문서는 셋을
대조해 어느 쪽이 사실인지 적는다.
기준 시각: **2026-09-20** (Asia/Seoul)
분석 대상 저장소: `/home/donghyeon/workspace/platform` @ `16c337bcc91b27ac0f074154b8337e4c8dc17ebb` (working tree clean)
설계·운영 문서: `/home/donghyeon/workspace/docs/platform` (git 없음, 파일 85개 · 28,708줄)
라이브 대상: 위 호스트의 k3s `v1.36.2+k3s1` 클러스터와 호스트 서비스
## 이 문서를 읽는 법
**증거 어휘를 섞지 않는다.** 아래 네 표기는 서로 바꿔 쓰지 않는다.
| 표기 | 뜻 |
|---|---|
| **관측** | 2026-09-20 에 이 호스트에서 명령을 돌려 직접 본 것. `final/evidence/raw/` 에 원문이 있다 |
| **선언** | 저장소의 manifest·values·스크립트에 그렇게 적혀 있는 것. 적용됐다는 뜻은 아니다 |
| **기록** | 중앙 문서가 과거 어느 날짜에 그렇게 확인했다고 적은 것. 지금도 그렇다는 뜻은 아니다 |
| **추론** | 위 셋에서 논리적으로 끌어낸 것. 근거를 함께 적는다 |
| **미확인** | 확인할 방법이 없었거나 확인하지 않은 것 |
**「1/1 Ready」는 가용성이 아니다.** 이 플랫폼은 노드 하나에 replica 하나씩이다. 모든
`1/1` 은 그 시점의 정상 관측이지 장애 허용의 증거가 아니다. 문서 전체에서 이 구분을
유지한다.
**`Retain` 은 백업이 아니다.** reclaim policy 는 PVC 를 지워도 볼륨을 자동으로 지우지
않겠다는 뜻이고, retention 은 각 제품이 자기 데이터를 언제 지우는지의 설정이다. 둘 다
사본이 다른 곳에 있다는 뜻이 아니다.
---
# 제1부 — 통합 분석
## 1. 범위와 기준
### 1.1 세 개의 원본과 그 사이의 시차
이 플랫폼에서는 셋이 각각 사실을 주장한다.
```text
코드·설정 문서 런타임
/workspace/platform ←→ /workspace/docs/platform ←→ k3s + 호스트
@16c337b (2026-08-28) 최신 2026-08-15 2026-09-20 관측
```
셋의 기준일이 다르다. 그래서 「문서에 그렇게 적혀 있다」와 「그렇게 돌고 있다」가 갈리는
자리가 생기고, 그 목록이 §17이다.
**중앙 문서 안에서도 기준일이 다르다.** `README.md` 와 `architecture/platform-overview.md`
는 2026-08-09 기준으로 "Phase 4 공용 관측성 플랫폼은 … 아직 클러스터에는 구현·적용하지
않았다" 고 적는다. 그런데 `observability/` 아래 9편은 2026-08-15 기준으로 같은 스택의
as-built 를 설명하고, 라이브에서는 그 스택이 40일째 돌고 있다. **`observability/` 쪽이
최신이고 상위 두 문서가 뒤처졌다.**(관측 — 파드 age 40d, evidence
`cluster-node-and-pods`)
### 1.2 무엇을 읽고 무엇을 실행했나
| 대상 | 방법 | 분량 |
|---|---|---|
| `platform` 저장소 | 전량 읽기 (vendored Helm chart 제외) | 파일 301개 · 83,003줄 |
| vendored Helm chart | 목록만 확인, 내용은 안 읽음 | 파일 713개 · 155,560줄 |
| 중앙 문서 | README·architecture 15편·ADR 10편·observability 9편 전량, runbook·plan 은 참조만 | 85편 중 35편 전량 |
| 라이브 클러스터 | read-only 명령 20벌 (19벌은 `desktop`, 1벌은 다른 호스트) | `final/evidence/raw/` |
**클러스터를 바꾸는 명령은 하나도 돌리지 않았다.** 관측에 쓴 것은 `kubectl get/describe/top`,
Prometheus·Alertmanager 읽기 API, `curl` 로 건강 확인, `openssl s_client` 로 인증서 확인,
`git remote -v`·`git ls-remote`·`git ls-files`, 그리고 파일 읽기다. `port-forward` 는
loopback 으로만 열고 즉시 닫았다. Gitea 에는 익명 읽기 API 만 불렀다.
**보지 못한 것이 있다.** `sudo` 비밀번호가 없어 `k3s secrets-encrypt status`,
`/etc/hyeonworks/` 아래 recovery evidence, `/srv/k3s/ssd/` 의 실제 사용량을 읽지 못했다.
이 셋은 §19에 한계로 적는다.
### 1.3 범위 밖
- Windows 가 쓰는 `/dev/sda1`·`/dev/sda2` 와 그 안의 데이터
- `/mnt/hdd-archive` 의 개인 자료 파일 목록
- 같은 workspace 의 다른 저장소 14개(`tech-log-backend`, `keycloak-pattern` 등)
- Secret·토큰·인증서 개인키의 값
---
## 2. 한 장으로 보는 전체 구조
### 2.1 요청이 지나는 다섯 홉
```text
[1] 클라이언트
공개 인터넷 · LAN 192.168.0.0/24 · Tailscale 100.64.0.0/10
│
│ 이름 해석이 출발지마다 다르다 (§5)
▼
[2] Host Nginx :80 / :443 ← 클러스터 밖, systemd
TLS 종료 · HTTP→HTTPS 301 · source allowlist · forwarded header 덮어쓰기
등록되지 않은 SNI 는 ssl_reject_handshake
│
│ http://127.0.0.1:30080 (loopback 전용)
▼
[3] Traefik NodePort 30080/30443 ← kube-system, k3s 기본 Ingress
kube-proxy nodeport-addresses=127.0.0.0/8
web entrypoint 만 10.42.0.1/32 를 forwarded-header 신뢰 프록시로 인정
│
│ Host 기반 Ingress 5건
▼
[4] 서비스 파드
git.learn… → gitea/gitea-http:3000
id.learn… → keycloak/keycloak-service:8080
storage-admin.learn…→ object-storage/minio-aistor-console:9090
db-admin.learn… → platform-admin/pgadmin:80
grafana.learn… → observability/grafana:80
│
▼
[5] 상태
platform-data/platform-postgres-rw:5432 (gitea DB · keycloak DB)
object-storage/minio:80 (S3 — loki · tempo 버킷)
정적 Local PV 10개 (SSD 9 · XFS HDD 1)
```
**이 그림의 핵심은 「TLS 를 한 번만 끊는다」와 「클러스터로 들어가는 문이 하나다」다.**
Host Nginx 가 인증서를 갖고, 그 뒤 loopback 한 포트로만 들어가며, 그 포트는 LAN 에서도
닿지 않는다.

Diagram description
클라이언트는 공개 인터넷, LAN 192.168.0.0/24, Tailscale 100.64.0.0/10 세 출발지를 가진다. 요청은 호스트 경계 안의 Host Nginx 443으로 들어가고 여기서만 TLS가 종료된다. Host Nginx는 관리 hostname에 source allowlist를 적용하고 forwarded header를 다시 쓴 뒤 loopback 127.0.0.1:30080 하나로만 넘긴다. k3s 클러스터 경계 안의 Traefik은 NodePort 30080을 kube-proxy nodeport-addresses=127.0.0.0/8로 loopback에 묶고, web entrypoint에서 10.42.0.1/32만 forwarded-header 신뢰 프록시로 인정한다. 거기서 Host 기반 Ingress 다섯 건이 Gitea, Keycloak, AIStor Console, pgAdmin, Grafana로 갈라진다. 상태 계층에서는 Gitea와 Keycloak만 공용 PostgreSQL의 read-write Service 5432로 이어지며, 이 Service에는 Ingress도 NodePort도 LoadBalancer도 없다.
[Editable source](assets/diagrams/platform-request-path/platform-request-path.drawio) · [Grounded VizSpec](.techviz/platform-request-path/spec.json)
### 2.2 공개 수준이 세 층이다
| hostname | 공개 DNS | Host Nginx source 제한 | 인증 | 관측 |
|---|---|---|---|---|
| `git.learn.hyeonworks.com` | 있음 | 없음 (공개) | Gitea 로컬 + Keycloak OIDC | HTTP 200 |
| `id.learn.hyeonworks.com` | 있음 | 없음 (공개) | Keycloak 자체 | issuer HTTPS 확인 |
| `grafana.learn.hyeonworks.com` | 없음 | LAN + Tailscale | Grafana 로컬 + Keycloak OIDC | HTTP 200 |
| `storage-admin.learn.hyeonworks.com` | 없음 | LAN + Tailscale | AIStor root + Keycloak OIDC | probe 대상 |
| `db-admin.learn.hyeonworks.com` | 없음 | LAN + Tailscale | pgAdmin internal + Keycloak OIDC | probe 대상 |
(관측 — evidence `host-nginx-active-config`, `edge-boundary-probe`)
**S3 API 와 PostgreSQL 에는 hostname 이 없다.** `object-storage/minio:80` 과
`platform-data/platform-postgres-rw:5432` 는 ClusterIP 뿐이고 Ingress·NodePort·LoadBalancer 가
없다.(관측 — evidence `cluster-services-and-ingress`)
### 2.3 namespace 13개의 역할
| namespace | 담는 것 | PSS enforce | 관측 대상 label | NetworkPolicy |
|---|---|---|---|---:|
| `kube-system` | Traefik · CoreDNS · local-path · metrics-server | (없음) | `true` | 1 |
| `cnpg-system` | CloudNativePG Operator | baseline | 없음 | **0** |
| `platform-data` | PostgreSQL Cluster · DB · Role | baseline | `true` | 3 |
| `gitea` | Gitea | baseline | `true` | 7 |
| `keycloak` | Keycloak Operator · Keycloak 1대 | baseline | `true` | 1 |
| `aistor` | AIStor Operator 3파드 | baseline | 없음 | 5 |
| `object-storage` | ObjectStore 1대 | baseline | `true` | 11 |
| `platform-admin` | pgAdmin | **restricted** | 없음 | 6 |
| `observability` | Prometheus·Alertmanager·Grafana·Loki·Tempo·KSM·Blackbox | **restricted** | `true` | 18 |
| `observability-agent` | Alloy · node-exporter | **privileged** | `true` | 6 |
| `default`·`kube-public`·`kube-node-lease` | 비어 있음 | 없음 | 없음 | 0 |
(관측 — evidence `cluster-node-and-pods`, `cluster-networkpolicy-and-storage`)
`observability.hyeonworks.com/enabled: "true"` 가 붙은 namespace 에서만 Prometheus 가
ServiceMonitor·PodMonitor·Probe·PrometheusRule 을 찾는다. **그래서 `aistor`·`cnpg-system`·
`platform-admin` 의 워크로드는 이 경로로는 수집되지 않는다.** pgAdmin 이 blackbox probe 로만
감시되는 이유가 여기 있다(§11.3).
---
## 3. 호스트 계층 — 물리 디스크 세 장이 역할을 나눈다
### 3.1 하드웨어와 OS
| 항목 | 값 | 출처 |
|---|---|---|
| OS | Ubuntu 24.04.4 LTS, 커널 `7.0.0-30-generic` | 관측 |
| CPU | 12 스레드 (6코어 12스레드) | 관측 · 기록 |
| 메모리 | 31Gi total, 관측 시점 10Gi 사용 | 관측 |
| swap | 8.0Gi | 관측 |
| LAN 주소 | `192.168.0.107/24` (`enp3s0`) | 관측 |
| Tailscale 주소 | `100.92.240.34/32` (`tailscale0`) | 관측 |
| 클러스터 CIDR | `10.42.0.0/24` (`cni0`), flannel | 관측 |
같은 호스트에 `docker0 172.17.0.1/16`, `br-8359faae6017 172.18.0.1/16`, 그리고 내려가 있는
`mpqemubr0 10.135.97.1/24`(multipass)가 있다. **k3s 와 무관한 컨테이너 런타임이 둘 더 떠
있다** — `docker.service` 와 `snap.multipass.multipassd.service` 가 running 이다.(관측)
이것들이 플랫폼 선언에 나오지 않는다는 점은 §17에 적는다.
### 3.2 디스크 세 장의 분담
```text
/dev/sdc CT250MX500SSD1 약 250GB ─── 시스템 SSD
└ sdc1 ext4 228G / k3s · PostgreSQL · Gitea · 관측성 로컬 PV
관측: 136G used / 80G avail (63%) — 내역은 §7.4
/dev/sdb WDC WD20EZAZ-00L9GB0 2,000,398,934,016 bytes ─── 데이터 HDD
├ sdb1 16MiB Microsoft Reserved (기존)
├ sdb2 ntfs3 932G /mnt/hdd-archive 개인 자료, 관측: 24G used (3%)
└ sdb3 xfs 932G /srv/k3s/aistor AIStor 오브젝트, 관측: 19G used (3%)
/dev/sda CT1000MX500SSD1 약 1TB ─── Windows SSD
└ sda3 NTFS (상시 마운트 안 함) K3s 제어면 recovery LUKS 컨테이너 32GiB
```
(관측 — evidence `k3s-config-dropins-and-storage`)
**`/srv/k3s/aistor` 는 마운트 포인트이면서 동시에 Local PV 의 host path 다.** 마운트가 빠진
채 ObjectStore 가 뜨면 그 경로는 루트 SSD 의 평범한 디렉터리가 되고 객체가 조용히 `/dev/sdc1`
에 쌓인다. 중앙 문서가 이것을 배포 원칙으로 못 박았다 — 「마운트 누락 시 루트 SSD에 데이터가
생성되지 않도록 사전 검증」. 같은 이유로 `/etc/fstab` 의 AIStor 항목에는 **일부러 `nofail` 을
쓰지 않았다** — 「로컬 디스크 장애를 조용히 무시하지 않도록」.(기록)
**AIStor 마운트 옵션이 `noquota` 다.**
```text
/srv/k3s/aistor /dev/sdb3 xfs rw,noatime,inode64,logbufs=8,logbsize=32k,noquota
```
그래서 PV 의 `900Gi` 와 PVC request `900Gi` 는 **바인딩 메타데이터일 뿐 파일시스템 quota 가
아니다.** 약 932Gi 파일시스템에서 900Gi 를 넘겨 쓰는 것을 커널이 막지 않는다. 실제 경계는
버킷 quota(§11.5)와 root SSD 사용률 경보(§11.4)다.
### 3.3 무엇이 죽으면 무엇을 같이 잃나
이 배치에서 함께 죽는 것들:
| 무엇이 죽으면 | 무엇을 같이 잃나 |
|---|---|
| 노드 | 전부 |
| `/dev/sdc` (시스템 SSD) | k3s 제어면과 정적 Local PV 아홉 개 전부 — PostgreSQL · Gitea · pgAdmin · Prometheus · Grafana · Alertmanager · Alloy · Loki WAL · Tempo WAL |
| `/dev/sdb` (데이터 HDD) | 개인 자료 **와** AIStor 오브젝트 (파티션만 다르고 같은 디스크다) |
| `/dev/sda` (Windows SSD) | K3s recovery LUKS 컨테이너 **와** KeePass vault |
**백업 목적지가 백업 대상과 같은 섀시 안에 있다.** AIStor 는 PostgreSQL·Gitea 의 백업
목적지로 설계됐지만 같은 서버다. K3s recovery 컨테이너는 `/dev/sdc` 단독 장애만 분리하고
`/dev/sda` 고장이나 장비 전체 사고는 막지 못한다. 중앙 문서가 이 한계를 반복해서 명시하고
있고, **이 문서도 오프사이트 백업이 없다는 사실을 바꾸지 않는다.**(기록 + 추론)
---
## 4. 엣지 — TLS 를 한 번 끊고 그 뒤로는 평문이다

Diagram description
1) 클라이언트가 HTTPS 443 으로 요청을 보낸다. 이 요청에는 임의의 Host 와 X-Forwarded-* 가 들어 있을 수 있다. 2) Host Nginx 는 등록되지 않은 SNI 를 ssl_reject_handshake 로 거부한다. 3) 관리 hostname 셋에서는 source allowlist 192.168.0.0/24 와 100.64.0.0/10 만 통과시키고 나머지는 거부한다. 4) Host 와 X-Forwarded-Host 를 상수 hostname 으로, X-Forwarded-Proto 를 https, X-Forwarded-Port 를 443 으로 덮어쓰고 X-Forwarded-For 와 X-Real-IP 를 접속 주소로 다시 쓴다. 5) 다섯 server block 이 모두 같은 loopback upstream 127.0.0.1:30080 으로 넘긴다. NodePort 는 kube-proxy nodeport-addresses=127.0.0.0/8 로 loopback 에만 묶여 있어 LAN 에서는 연결되지 않는다. 6) Traefik 의 web entrypoint 는 forwardedHeaders.trustedIPs 가 10.42.0.1/32 하나뿐이므로 그 source 에서 온 헤더만 신뢰한다. 7) Traefik 이 Host 기반 Ingress 로 backend 에 전달하고, backend 는 상수로 고정된 hostname 만 본다.
[Editable source](assets/diagrams/edge-trust-chain/edge-trust-chain.drawio) · [Grounded VizSpec](.techviz/edge-trust-chain/spec.json)
### 4.1 Host Nginx 가 지는 책임
활성 파일은 `/etc/nginx/sites-available/learn-services`(214줄, 2026-08-15 04:26 수정)이고
`sites-enabled/learn-services` 가 그것을 가리킨다. 저장소 원본은
`infrastructure/networking/host-nginx/learn-services-observability.conf` 계열이다.
이 파일이 하는 일 넷:
**(1) 등록되지 않은 SNI 를 거부한다.**
```nginx
server {
listen 443 ssl default_server;
listen [::]:443 ssl default_server ipv6only=on;
ssl_reject_handshake on;
}
```
**(2) 다섯 hostname 마다 TLS 를 끊고 같은 loopback upstream 으로 보낸다.** 다섯 server
block 이 모두 `proxy_pass http://127.0.0.1:30080;` 하나를 쓴다.
**(3) 외부가 보낸 forwarded header 를 믿지 않고 덮어쓴다.**
```nginx
proxy_set_header Host git.learn.hyeonworks.com;
proxy_set_header X-Forwarded-Host git.learn.hyeonworks.com;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Port 443;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
```
`Host` 와 `X-Forwarded-Host` 를 **변수가 아니라 상수로** 박아 둔다. 클라이언트가 무엇을
보내든 backend 가 보는 hostname 은 하나다. Keycloak 의 issuer 가 헤더 주입으로 바뀌지
않는 이유가 여기 있다.
**(4) 관리 hostname 셋에만 source allowlist 를 건다.**
```nginx
allow 192.168.0.0/24;
allow 100.64.0.0/10;
deny all;
```
`grafana`·`storage-admin`·`db-admin` 세 곳에 있고, `git`·`id` 두 곳에는 없다.
### 4.2 hostname 마다 다른 세 가지 값
같은 구조를 다섯 번 반복하지만 세 값은 서비스마다 다르다.
| hostname | `client_max_body_size` | read/send timeout | WebSocket upgrade | `/metrics` 차단 |
|---|---:|---:|---|---|
| `git.learn…` | 512m | 3600s | 있음 | `return 404` |
| `id.learn…` | 10m | 300s | 없음 | 없음 |
| `storage-admin.learn…` | 5g | 3600s | 있음 | 없음 |
| `db-admin.learn…` | 100m | 600s | 없음 | 없음 |
| `grafana.learn…` | 10m | 300s | 있음 | `return 404` |
(관측 — evidence `host-nginx-active-config`)
Git push 와 S3 콘솔 업로드가 큰 body 와 긴 타임아웃을 요구하고, ID·Grafana 는 그럴 이유가
없어 좁혀 뒀다. `/metrics` 를 404 로 막은 곳은 Gitea 와 Grafana 둘이다 — 둘 다 애플리케이션이
`/metrics` 를 열 수 있는 제품이라 공개 경로에서 미리 닫았다.(추론 — 근거: 그 둘만 막혀 있고,
Keycloak 은 관리 포트 9000 이 아예 Ingress 에 없어 막을 필요가 없다)
### 4.3 인증서 다섯 장이 아니라 세 장이다
| hostname | 실제 제시하는 인증서 CN | SAN | 만료 |
|---|---|---|---|
| `git.learn…` | `git.learn.hyeonworks.com` | `git`, `id` | 2026-12-15 |
| `id.learn…` | `git.learn.hyeonworks.com` | `git`, `id` | 2026-12-15 |
| `storage-admin.learn…` | `storage-admin.learn.hyeonworks.com` | `db-admin`, `storage-admin` | **2026-10-21** |
| `db-admin.learn…` | `storage-admin.learn.hyeonworks.com` | `db-admin`, `storage-admin` | **2026-10-21** |
| `grafana.learn…` | `grafana.learn.hyeonworks.com` | `grafana` | 2026-11-08 |
발급자는 Let's Encrypt — 서로 다른 인증서 셋 중 `YE2` 가 둘, `YE1` 이 하나다(hostname 으로 세면 YE2 넷·YE1 하나). (관측 — evidence `edge-tls-certificates`)
**인증서가 셋이고 hostname 이 다섯이다.** `git`+`id` 가 한 장, `storage-admin`+`db-admin` 이
한 장, `grafana` 가 한 장이다. nginx 설정에서도 `id` server block 이
`/etc/letsencrypt/live/git.learn.hyeonworks.com/` 을, `db-admin` server block 이
`/etc/letsencrypt/live/storage-admin.learn.hyeonworks.com/` 을 참조한다. **SAN 에 들어
있으므로 유효하지만, 한 장이 갱신에 실패하면 두 hostname 이 함께 끊긴다.**(추론)
**`storage-admin`/`db-admin` 인증서가 가장 먼저 만료된다 — 2026-10-21, 기준일로부터 31일
뒤다.** `PlatformCertificateExpiry` 경보가 30일 미만에서 warning 으로 뜨므로 **하루 뒤부터
warning 이 뜨기 시작한다.**(관측 + 추론) 이 경보는 blackbox probe 의
`probe_ssl_earliest_cert_expiry` 를 쓰는데, `private-edge` probe 대상에 두 hostname 이 모두
들어 있으므로 감지는 된다.
### 4.4 Traefik — 문 하나를 loopback 에 묶는다
```text
Service/kube-system/traefik NodePort 80:30080/TCP 443:30443/TCP
/etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml:
kube-proxy-arg:
- "nodeport-addresses=127.0.0.0/8"
```
관측 결과:
```text
NodePort via LAN IP 192.168.0.107:30080: 000 ← 연결 자체가 안 됨
NodePort via loopback 127.0.0.1:30080: 404 ← Traefik 도달, Host 없는 요청이라 라우트 없음
```
(관측 — evidence `edge-boundary-probe`, `k3s-config-dropins-and-storage`)
**`404` 는 성공 신호이고 `000` 이 차단 신호다.** Traefik 에 닿았으면 라우트가 없어도 `404` 가
돌아온다. 그래서 외부 차단을 판정할 때는 `404` 도 실패로 센다 — 중앙 문서가 같은 기준을
적고 있고 이 관측이 그 기준을 따른다.
**`30443` 은 열려 있지만 경로에서 안 쓴다.** Service 에 포트는 있고 `websecure` entrypoint 도
있지만 Host Nginx 가 `30080` 으로만 보낸다.
### 4.5 forwarded header 신뢰 경계 — 정확히 `/32` 하나
라이브 `HelmChartConfig/kube-system/traefik` 의 `web` entrypoint:
```yaml
ports:
web:
nodePort: 30080
forwardedHeaders:
trustedIPs:
# 2026-07-23 Host Nginx 경유 probe에서 관측한 Traefik ClientHost이다.
- "10.42.0.1/32"
```
(관측 — evidence `traefik-live-helmchartconfig`)
`10.42.0.1` 은 `cni0` 의 주소다. 호스트에서 loopback NodePort 로 들어온 패킷이 클러스터
네트워크로 SNAT 되면서 이 주소로 보인다. **추측한 CIDR 이 아니라 실제로 관측한 source
하나만 `/32` 로 신뢰한다.** `forwardedHeaders.insecure` 도 `websecure` trust 도 없다.
**루트 build root 는 라이브와 다르다. 그런데 그것이 의도다.**
`infrastructure/networking/traefik/kustomization.yaml` 은 `overlays/observe` 를 가리키고
`observe` 는 `base` 를 그대로 쓴다. `base` 에는 `trustedIPs` 가 없고 그것은 `overlays/trust`
에만 있다.
```text
infrastructure/networking/traefik/
├── kustomization.yaml → resources: [overlays/observe] ← 기본 build root
├── base/helm-chart-config.yaml trustedIPs 없음
└── overlays/
├── baseline/ Service 계약만 (access log·trust 없음)
├── observe/ base 그대로 ← 기본 build root 가 가리키는 곳
└── trust/ trustedIPs: 10.42.0.1/32 ← 라이브와 같은 것
```
저장소가 그 이유를 적어 두었다.(기록 — `infrastructure/networking/traefik/README.md`)
> 루트 `kustomization.yaml`은 의도적으로 안전한 `observe` overlay를 가리킨다. 현재 live 상태는
> `trust`이므로 루트에 단순히 `kubectl apply -k`를 실행하면 trust 제거를 요청하게 된다. 상태
> 전환은 아래 guarded script와 정확한 overlay를 사용한다.
**즉 「루트를 그대로 적용하면 trust 가 사라진다」는 사고가 아니라 설계다.** 신뢰 경계를 켜고
끄는 것은 `scripts/apply-trust.sh`·`rollback-to-observe.sh` 가 맡고, 루트는 아무것도 모르는
사람이 `apply -k` 를 쳤을 때 **덜 위험한 쪽**으로 떨어지게 두었다. 대신 라이브가 어느 overlay
상태인지는 저장소를 봐서는 알 수 없고 `HelmChartConfig` 를 읽어야 한다.
---
## 5. 이름 해석 — 같은 이름이 출발지마다 다른 주소를 준다
세 개의 resolver 가 같은 다섯 이름에 서로 다른 답을 준다.
```text
git / id / storage-admin / db-admin / grafana
.learn.hyeonworks.com
LAN 클라이언트 → dnsmasq @192.168.0.107:53 → 192.168.0.107
Tailscale 노드 → dnsmasq @100.92.240.34:53 → 100.92.240.34
클러스터 내 파드 → CoreDNS (coredns-custom) → 192.168.0.107
공개 인터넷 → 권威 DNS → git·id 만 A 레코드 있음
```
### 5.1 호스트 dnsmasq 두 인스턴스
systemd unit 두 개가 각각 하나의 주소에만 바인딩한다.(관측 — evidence `host-private-dns-config`)
```ini
# /etc/dnsmasq-hyeonworks/lan.conf
port=53
listen-address=192.168.0.107
bind-interfaces
no-hosts
no-resolv
server=1.1.1.1
server=1.0.0.1
cache-size=1000
domain-needed
bogus-priv
address=/git.learn.hyeonworks.com/192.168.0.107
...
```
`domain-needed` 와 `bogus-priv` 는 점 없는 이름과 사설 대역 역질의를 상류로 **안 보내는** 설정이다.
`tailscale.conf` 는 `listen-address` 와 `address=` 목표만 `100.92.240.34` 로 다르고 나머지는
같다. `bind-interfaces` 로 두 프로세스가 같은 53 포트를 주소별로 나눠 쓴다.
두 unit 의 systemd hardening 이 같다: `NoNewPrivileges`, `PrivateTmp`, `ProtectHome`,
`ProtectSystem=strict`, `ProtectKernelTunables/Modules/ControlGroups`,
`RestrictAddressFamilies`, `CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_SETGID CAP_SETUID`.
### 5.2 CoreDNS 확장
`coredns-custom` ConfigMap 이 `learn.hyeonworks.com:53` server block 을 더한다. 다섯 이름을
모두 `192.168.0.107` 로 답하고 그 밖은 `fallthrough` + `forward . /etc/resolv.conf`.
**이것이 왜 필요한가.** 클러스터 안의 파드가 `https://id.learn.hyeonworks.com/...` 로
Keycloak discovery 를 부를 때, 공개 DNS 로 나갔다가 다시 들어오면 경로가 길고
`storage-admin`·`db-admin`·`grafana` 는 공개 A 레코드가 아예 없어 실패한다. CoreDNS 가 노드
주소로 바로 답하면 파드 → 호스트 Nginx → Traefik → 파드 로 돌아온다. Gitea 가 쓰던 임시
`hostAliases` 를 이것이 대체했다.(선언 + 기록)
### 5.3 다른 호스트에서 본 결과
별도 호스트 `donghyeon-960XGK`(LAN `192.168.0.103`, Tailscale `100.123.124.30`)에서 같은
이름을 물어봤다.(관측 — evidence `tailscale-peer-vantage`)
```text
git / id / storage-admin / db-admin / grafana .learn.hyeonworks.com
→ 전부 100.92.240.34 (Tailscale 주소)
https://git.learn…/api/healthz 200
https://storage-admin.learn…/ 200
https://db-admin.learn…/ 302 (pgAdmin 로그인 redirect)
https://grafana.learn…/api/health 200
http://192.168.0.107:30080/ 000 (거부)
http://192.168.0.107:30443/ 000 (거부)
```
**Tailscale split DNS 가 실제로 등록돼 있고 동작한다.** 이 호스트는 LAN 에도 있지만
Tailscale 주소를 받았다 — Tailscale 의 DNS 설정이 우선한다. 그리고 그 주소로 들어온 요청이
Host Nginx 의 `allow 100.64.0.0/10` 을 통과해 관리 UI 세 곳이 다 열렸다.
**NodePort 차단도 두 번째 호스트에서 재확인됐다.** `30080` 과 `30443` 둘 다 거부다.
### 5.4 이 구조가 만드는 제약
- **공유기 DHCP 의 DNS 설정은 여전히 확인하지 못했다**(미확인). 위 관측은 Tailscale 경로가
동작한다는 것을 보여 주지만, Tailscale 이 없는 LAN 클라이언트가 `192.168.0.107:53` 을
resolver 로 받는지는 공유기 설정이라 이 문서 범위 밖이다.
- **파드가 관리 UI 를 부르면 Host Nginx 의 allowlist 에 막힌다.** 파드 → 노드는 로컬 배달이라
SNAT 이 걸리지 않고 **파드 IP 가 그대로** 도착한다 — nginx access log 에 blackbox 는
`10.42.0.144` 로 찍힌다(관측). 그 주소는 `192.168.0.0/24` 에도 `100.64.0.0/10` 에도 없다.
그래서 blackbox 의 `private-edge` probe 는 **403 을 기대값으로 삼는다**(§11.3).
`10.42.0.1` 은 반대 방향 — 호스트가 loopback NodePort 로 넣은 패킷이 Traefik 에 닿을 때의
`cni0` 주소다(§4.5). 두 주소를 섞지 않는다.
---
## 6. k3s 클러스터 — 기본값을 어디까지 남겼나
### 6.1 k3s 자체
| 항목 | 값 |
|---|---|
| 버전 | `v1.36.2+k3s1` |
| 노드 | 1 (control-plane), age 63d |
| 컨테이너 런타임 | `containerd://2.3.2-k3s2` |
| CNI | flannel (`10.42.0.0/24`) |
| Ingress | Traefik `3.7.4`, chart `40.1.3+up40.1.0` |
| DNS | CoreDNS `1.14.4` |
| 기본 StorageClass | `local-path` (rancher, `Delete`) — **플랫폼은 안 쓴다** |
| metrics-server | `v0.8.1` |
(관측 — evidence `cluster-node-and-pods`, `running-container-images`)
### 6.2 손댄 두 곳
`/etc/rancher/k3s/config.yaml.d/` 에 drop-in 이 둘이다.
```yaml
# 30-nodeport-loopback.yaml
kube-proxy-arg:
- "nodeport-addresses=127.0.0.0/8"
```
```yaml
# 40-secrets-encryption.yaml
secrets-encryption: true
secrets-encryption-provider: aescbc
```
(관측 — evidence `k3s-config-dropins-and-storage`)
**두 번째는 「설정이 켜져 있다」이지 「재암호화가 끝났다」가 아니다.** 실제 상태는
`k3s secrets-encrypt status` 가 말하고 그건 `sudo` 가 필요해 못 읽었다(미확인). 중앙 문서는
2026-08-09 에 `Enabled/reencrypt_finished` 를 확인했다고 기록한다(기록).
저장소에도 같은 파일이 `infrastructure/security/k3s/40-secrets-encryption.yaml` 로 있고 내용이
바이트 단위로 같다.(관측)
### 6.3 Helm 배포 방식 — chart 를 복사하지 않는다
k3s 가 관리하는 Traefik 은 `HelmChartConfig` 로 values 만 덮어쓴다. 나머지는 Kustomize 의
Helm inflator 로 공식 chart 를 **렌더 시점에 내려받아** 쓴다. 고정 대상은 chart 버전과
package SHA-256 둘 다다.
| build root | chart | 버전 | package SHA-256 |
|---|---|---|---|
| `infrastructure/controllers/cloudnative-pg` | `cloudnative-pg` | `0.29.0` (app `1.30.0`) | `668e065ff53508d58238788fd35b355a925060843629a951df0e6a9362e6d32f` |
| `services/gitea` · `services/gitea/profiles/oidc` | `gitea` | `12.7.0` (app `1.27.0`) | `5881ef9c59400bee2d5547e77c4cd0efb925143c2f5d93fb4f38446db76b0167` |
| `infrastructure/controllers/keycloak-operator` | (Kustomize remote) | release `26.7.0` | 공식 Git release ref |
| `infrastructure/controllers/aistor-operator` | `aistor-operator` | `5.10.0` | `e5534f5ae4f6f12a3528a8cda5954d73280cba1a8e979e1628fbf3aac76babd1` |
| `services/minio-aistor` | `aistor-objectstore` | `1.0.16` | `50ffa6a4e014cdc48566b237593baab41d039f103cdc50c1b1ac173b8d8bf71e` |
| `services/observability/kube-prometheus-stack` | `kube-prometheus-stack` | `88.0.1` | (vendored) |
| `services/observability/grafana` | `grafana` | `12.10.1` | (vendored) |
| `services/observability/alloy` | `alloy` | `1.11.0` | (vendored) |
| `services/observability/blackbox-exporter` | `prometheus-blackbox-exporter` | `11.16.0` | (vendored) |
**관측성 스택만 방식이 다르다.** Phase 1·2 의 chart 는 렌더할 때 내려받고 SHA-256 을 비교하지만,
관측성 chart 넷은 `.helm/charts/-/` 아래에 **저장소에 풀어 놓았다**(713파일
155,560줄). `.gitignore` 에 `.helm/` 이 있으므로 이 디렉터리는 **git 이 추적하지 않는다.**
즉 작업 트리에는 있고 커밋에는 없다.(관측)
이것이 뜻하는 것: **관측성 스택을 다른 기계에서 저장소만 가지고 재현할 수 없다.** 누군가
`.helm/charts/` 를 다시 채워야 한다. Phase 1·2 는 `render-phase1.sh`/`render-phase2.sh` 가
그 일을 하지만 관측성 쪽에 같은 역할을 하는 것이 `render-observability-core.sh` 인지는
확인했다(§14.2) — 그 스크립트가 chart 를 내려받는 경로를 갖고 있다.
렌더 도구도 고정이다: Kustomize `v5.8.1`, Helm `v3.19.4`. `--load-restrictor LoadRestrictionsNone`
은 쓰지 않고 기본 `RootOnly` 를 유지한다. 그래서 values 와 patch 가 항상 build root 아래에 있다.
---
## 7. 스토리지 — 정적 Local PV 열 개
### 7.1 StorageClass 를 워크로드마다 하나씩 나눴다
StorageClass 11개 중 `local-path`(k3s 기본)를 뺀 10개가 전부
`kubernetes.io/no-provisioner` · `Retain` · `WaitForFirstConsumer` ·
`allowVolumeExpansion: false` 로 같다.
**왜 하나로 안 하고 열 개인가.** provisioner 가 없으면 PVC 는 조건이 맞는 아무 PV 에나
바인딩된다. StorageClass 이름을 워크로드마다 다르게 하면 **Gitea 의 PVC 가 PostgreSQL 의
PV 를 선점하는 일이 구조적으로 불가능해진다.** 용량·접근모드만으로는 막을 수 없는 것을
이름으로 막았다.(추론 — 근거: 중앙 문서의 "PostgreSQL과 Gitea가 잘못 교차 바인딩되지
않도록 workload별 StorageClass를 분리한다")
### 7.2 PV 열 개의 배치
| PV | 용량 | host path | 소비자 | 디스크 |
|---|---:|---|---|---|
| `platform-postgres-local-pv` | 20Gi | `/srv/k3s/ssd/platform-postgres` | `platform-data/platform-postgres-1` | SSD |
| `gitea-local-pv` | 50Gi | `/srv/k3s/ssd/gitea` | `gitea/gitea-data` | SSD |
| `pgadmin-data-local-pv` | 2Gi | `/srv/k3s/ssd/pgadmin` | `platform-admin/pgadmin` | SSD |
| `observability-prometheus-local-pv` | 20Gi | `/srv/k3s/ssd/observability/prometheus` | Prometheus TSDB | SSD |
| `observability-grafana-local-pv` | 2Gi | `/srv/k3s/ssd/observability/grafana` | Grafana SQLite | SSD |
| `observability-alertmanager-local-pv` | 1Gi | `/srv/k3s/ssd/observability/alertmanager` | silence·notification 상태 | SSD |
| `observability-alloy-local-pv` | 2Gi | `/srv/k3s/ssd/observability/alloy` | position·전송 큐 | SSD |
| `observability-loki-local-pv` | 5Gi | `/srv/k3s/ssd/observability/loki` | Loki WAL | SSD |
| `observability-tempo-local-pv` | 5Gi | `/srv/k3s/ssd/observability/tempo` | Tempo WAL | SSD |
| `aistor-data-local-pv` | 900Gi | `/srv/k3s/aistor` | ObjectStore pool-0 | **XFS HDD** |
전부 `Bound`, 전부 `Retain`, 전부 `ReadWriteOnce`, 전부 노드 `donghyeon-system-product-name`
affinity.(관측 — evidence `cluster-networkpolicy-and-storage`)
**SSD 쪽 선언 합계는 107Gi 인데 root filesystem 은 228G 이고 이미 136G 가 차 있다**(같은 날 두 번째 측정에서는 138G — §7.4).
Local PV 의 `capacity` 는 quota 가 아니므로 이 합계가 지켜진다는 보장이 없다. 그래서
실질 경계는 root filesystem 사용률 경보 세 단계(75% info / 85% warning / 90% critical)다.
**관측 시점 경보 식 기준 사용률은 64.8% 로 첫 경계 아래에 있다**(§16.1).(관측)
### 7.3 Loki·Tempo 만 두 층이다
나머지는 로컬 PV 하나로 끝나지만 Loki 와 Tempo 는 로컬을 작업 공간으로만 쓰고 본 데이터를
S3 로 보낸다.
```text
Loki WAL/working → /srv/k3s/ssd/observability/loki (5Gi)
chunks·ruler·admin → AIStor loki 버킷 (보존 720h = 30일)
Tempo WAL/working → /srv/k3s/ssd/observability/tempo (5Gi)
trace block → AIStor tempo 버킷 (보존 168h = 7일)
```
둘 다 `minio.object-storage.svc.cluster.local` 로 간다 — Loki 는 `http://…`(기본 80),
Tempo 는 `…:80` 을 명시한다. `s3ForcePathStyle`/`forcepathstyle` 과 `insecure: true` 를 켠다.
**XFS 를 직접 마운트하지 않는다.** 두 파드는 `platform.hyeonworks.com/aistor-client: "true"`
label 을 달고, 그 label 이 `object-storage` 쪽 NetworkPolicy 의 통과 조건이다(§12.4).
관측 시점 `loki` 버킷 866,300,448 bytes, `tempo` 버킷 0 bytes. quota 대비 `loki` 0.403%.
**`tempo` 가 0 인 것은 고장이 아니라 trace 를 보내는 애플리케이션이 아직 없기 때문이다** —
Alloy 의 OTLP receiver 는 떠 있지만 보내는 쪽이 없다(§11.6).(관측 + 추론)
**XFS 쪽 19G 도 객체가 아니다.** `df` 가 `/srv/k3s/aistor` 를 19G used 로 보이고 ObjectStore
status 의 `rawUsage` 도 `20,085,288,960` bytes(약 18.7 GiB)를 낸다. 그런데 버킷 둘의 합은
866,300,448 bytes(약 826 MiB)뿐이다. 차이 약 17.9 GiB(`20,085,288,960 − 866,300,448 = 19,218,988,512`)는
객체가 아니라 **파일시스템이 미리 잡아 둔 공간**이다. 중앙 문서가 「빈 XFS 에서 약 18GiB 가
사용된 것으로 보이는 이유」로 이미 설명했고 그때 값과 지금 값이 맞는다.(관측 + 기록)
**그 덩어리는 한 가지가 아니다.** 원문은 셋으로 나눈다 — Allocation Group 별 reverse
mapping·refcount B-tree 확장 예약, 비상 메타데이터 갱신용 예약, 그리고 내부 로그
`119254 × 4096 = 488,464,384 bytes`(약 466MiB). 「18GiB 전체가 로그 영역인 것은 아니다」라고
원문이 못 박는다. **AG 예약분만 따로 실측한 적은 양쪽 어디에도 없다** — 그것을 재는
`xfs_db -r -c agresv` 는 `sudo` 가 필요하고 중앙 문서의 해당 체크리스트도 미체크다(미확인).
**그래서 AIStor 의 `usage`·`rawUsage` 도 파일시스템 값이지 객체 크기가 아니다.** §7.5 의
`kubelet_volume_stats_*` 와 같은 함정이고, 객체 용량을 보려면
`minio_cluster_usage_buckets_total_bytes` 를 써야 한다 — 플랫폼 경보의 quota 규칙이 실제로
그 metric 을 쓴다(§11.4).
### 7.4 루트 SSD 를 실제로 채운 것은 플랫폼이 아니다
§7.2 의 선언 합계 107Gi 와 루트 파일시스템 사용량을 나란히 읽으면 플랫폼이 그만큼 썼다고
오해하기 쉽다. **재 보면 아니다.**(관측 — evidence `disk-usage-attribution`. 이 증거는
`df` 가 138G / 64% 를 낼 때 잡았다. §7.2·§16 의 136G / 63% 는 한 시간 앞선 측정이다)
| 무엇 | 실사용 | 선언 용량 | 어떻게 쟀나 |
|---|---:|---:|---|
| Prometheus TSDB | **4.65 GiB** | 20Gi | 자체 metric: blocks `4,657,964,807` + WAL `291,393,543` + head chunks `39,312,192` bytes |
| PostgreSQL | 614 MiB | 20Gi | 파드 안 `du -sh /var/lib/postgresql/data` |
| Gitea | 174.7 MiB | 50Gi | 파드 안 `du -sh /data` |
| Grafana | 1.7 MiB | 2Gi | 파드 안 `du -sh /var/lib/grafana` |
| Loki WAL | 9.9 MiB | 5Gi | 자체 metric `prometheus_tsdb_wal_storage_size_bytes` `10,342,630` bytes |
| Alloy | 36 KiB | 2Gi | 파드 안 `du -sh /var/lib/alloy` |
| Alertmanager | 4 KiB | 1Gi | 파드 안 `du -sh /alertmanager` |
| pgAdmin | 228 KiB | 2Gi | 파드 안 `du -sh /var/lib/pgadmin` |
| Tempo WAL | **미확인** | 5Gi | distroless 라 `du`·`ls` 가 없고 크기 metric 도 없다 |
**정적 Local PV 아홉 개가 루트 SSD 에서 실제로 쓰는 것은 다 합쳐 약 5.4 GiB 다.** 그 중
**관측성 몫은 약 4.66 GiB 이고 거의 전부 Prometheus TSDB 다.** 선언 합계 107Gi 의 5%,
파일시스템 228G 의 2.4% 다.
그러면 138G 는 무엇인가. 루트 파일시스템만 세면(`du -shx`) 이렇게 나뉜다.
| 경로 | 크기 | 무엇 |
|---|---:|---|
| `/home/donghyeon` | **61G** | 그 중 `hdd-migration-backup-20260722` 가 **24G**, `workspace` 4.4G, `Documents` 1.2G |
| `/var` | 11.7G(읽힌 부분) | `lib/snapd` 5.7G · `log` 1.4G · `lib/rancher` 251.4M · `lib/apt` 210.5M |
| `/usr` | 9.3G | OS |
| `/opt` | 758.6M | |
| `/boot` | 396.1M | |
| 나머지 | 약 20M | `/etc` 13.1M · `/tmp` 7.1M · `/snap` 140.0K · `/srv`(루트 부분) 20.0K · `/mnt`(마운트 포인트만) 16.0K |
| **미귀속** | **약 54.8G** | `/var/lib/docker` · `/var/lib/containerd` · `/var/lib/rancher/k3s/agent/containerd` · `/root` |
귀속분 합이 `61 + 11.7 + 9.3 + 0.76 + 0.40 + 0.02 = 83.2G` 이고 그때 `df` 가 138G 였으므로
미귀속은 **54.8G** 다.
**미귀속 54.8G 는 컨테이너 이미지 저장소로 보인다**(추론 — 읽지 못한 디렉터리가 그 넷뿐이고,
이 호스트에는 k3s containerd 와 별개로 Docker 가 함께 떠 있다(§3.1, §17.6)). 확인하려면
`sudo du -shx /var/lib/docker /var/lib/containerd /var/lib/rancher` 한 줄이면 된다.
**눈에 띄는 것은 `/home/donghyeon/hdd-migration-backup-20260722` 24G 다.** ADR-0001 이
2026-07-22 HDD 분할 때 "시스템 SSD에 파일 안전본을 만들고 SHA-256으로 검증한 다음 파티션과
파일시스템을 새로 생성한다" 고 적은 그 안전본이다. 복원 뒤 SHA-256 재검증을 통과했고
`/mnt/hdd-archive` 에 24G 가 그대로 있으므로, 이 사본은 **두 달째 역할이 끝난 채 루트 SSD 228G 의
10.5%, 지금 쓰고 있는 138G 의 17.4% 를 차지하고 있다.**(관측 + 추론) 지우는 것은 사람이 정할 일이지만, root filesystem
경보가 관측성 증가가 아니라 이 사본 때문에 먼저 울릴 수 있다는 점은 적어 둔다.
### 7.5 PVC 사용량 지표를 믿으면 안 된다
`kubelet_volume_stats_capacity_bytes` 는 **정적 Local PV 아홉 개 전부에 똑같은
`243,885,932,544`** 를 낸다. `…_used_bytes` 도 `147,697,172,480` ~ `147,715,776,512` 사이에
몰려 있다(폭 18.6MB — 측정 시각 차이일 뿐 PVC 별 차이가 아니다). 그것은 PVC 가 아니라 **루트
파일시스템 전체**다. local PV 가 루트 fs 의 그냥 디렉터리라 kubelet 의 `statfs` 가 파일시스템
값을 돌려주기 때문이다. XFS 위에 있는 AIStor PVC 하나만 제 값(`20,094,828,544` /
`999,892,553,728`)을 낸다.(관측 — evidence `disk-usage-attribution`)
**그리고 그 값을 읽는 경보가 이미 돌고 있다.** kube-prometheus-stack 이 만드는
`kubernetes-storage` group 에 넷이 있다(§11.4 의 「생성 133」에 포함).
| alert | 조건 | `for` |
|---|---|---:|
| `KubePersistentVolumeFillingUp` | `available/capacity < 0.03` | 1m |
| `KubePersistentVolumeFillingUp` | `available/capacity < 0.15` | 1h |
| `KubePersistentVolumeInodesFillingUp` | `inodes_free/inodes < 0.03` | 1m |
| `KubePersistentVolumeInodesFillingUp` | `inodes_free/inodes < 0.15` | 1h |
관측 시점 `kubelet_volume_stats_available_bytes / …_capacity_bytes` 는 아홉 개가 전부
**`0.3419`** 다 — 루트 파일시스템의 여유율이다. AIStor 하나만 `0.9799` 로 제 값을 낸다.
넷 다 `inactive`.(관측)
**그래서 이 넷은 두 방향으로 다 틀린다.**
- **거짓 초록** — Gitea PVC 가 50Gi 를 다 채워도 이 식은 여전히 루트 여유율을 읽는다. 루트에
여유가 있는 한 **영원히 `inactive`** 다.
- **거짓 폭풍** — 반대로 루트가 85% 에 닿으면 `available/capacity` 가 `0.15` 밑으로 떨어져
**아홉 개가 한꺼번에 울린다.** 그 시점에 `PlatformRootFilesystemUsage` warning 도 같이
울리므로, 같은 사건 하나에 경보 열 건이 뜬다.
그러므로 §7.5 의 결론은 「PVC 사용률 경보를 만들 수 없다」가 아니라 **「이미 있는데 값을 잘못
읽고 있다」**다. 워크로드별 디스크 귀속을 metric 으로 얻을 방법이 지금은 없고 §7.4 처럼 파드마다
들어가 재야 한다. 플랫폼 경보가 **root filesystem 사용률 3단계**(§11.4)를 쓰는 것은 이 제약에
맞지만, 저장소·중앙 문서 어디에도 이 제약을 적은 문장이 없다(관측 — `grep` 0건). 그래서
생성 경보 넷이 걸러지지 않은 채 남았다(추론).
---
## 8. 데이터 계층 — 인스턴스 하나, 데이터베이스 둘
### 8.1 구성
| 항목 | 값 |
|---|---|
| Operator | CloudNativePG `1.30.0`, namespace `cnpg-system`, replica 1 |
| Cluster | `platform-data/platform-postgres`, instances 1 |
| 이미지 | `ghcr.io/cloudnative-pg/postgresql:17.9-standard-trixie` |
| Service | `platform-postgres-rw:5432` 하나. `ro`·`r` 은 명시적으로 비활성 |
| 자원 | request `250m/512Mi` → limit `2 CPU/4Gi` |
| 스토리지 | `platform-postgres-local-pv` 20Gi, Retain |
| 데이터 검사합 | `dataChecksums: true` (initdb 시점) |
(선언 + 관측)
### 8.2 두 서비스를 가르는 세 겹
Gitea 와 Keycloak 이 같은 PostgreSQL 인스턴스를 쓰지만 데이터베이스·역할·Secret 을
공유하지 않는다. 경계가 세 겹이다.
**(1) `pg_hba` — 역할이 자기 DB 에만 인증된다.**
```yaml
postgresql:
pg_hba:
- host gitea gitea all scram-sha-256
- host all gitea all reject
- host keycloak keycloak all scram-sha-256
- host all keycloak all reject
```
순서가 중요하다. 허용 규칙이 거부 규칙보다 앞에 있고, 거부 규칙이 CloudNativePG 의 기본
fallback 보다 앞에 온다. **database owner 분리만으로는 PostgreSQL 의 기본 `CONNECT` 권한을
회수하지 못한다.** 중앙 문서는 그래서 「실제 접속 차단 경계는 이 HBA 규칙과 **Secret 격리의
조합**」이라고 적는다 — HBA 혼자가 아니라 두 겹이다.(선언 + 기록)
**(2) Secret 격리 — 같은 값이 두 namespace 에 두 벌.**
Kubernetes Secret 은 namespace 를 넘지 못한다. 그래서 DB 자격 증명마다 객체가 둘이다.
| 서버 측 (`platform-data`) | 소비자 측 | type·key |
|---|---|---|
| `gitea-db-credentials` | `gitea/gitea-db-credentials` | `kubernetes.io/basic-auth`; `username`,`password` |
| `keycloak-db-credentials` | `keycloak/keycloak-db-credentials` | 같음 |
서버 측에는 `cnpg.io/reload=true` label 이 붙는다. (관측 — 두 namespace 에 같은 이름의
`kubernetes.io/basic-auth` Secret 이 실재. 값이 같은지는 payload 를 안 읽어 미확인)
**(3) NetworkPolicy — namespace 단위로 5432 도달을 가른다.**
`platform-data` 의 정책 셋:
| 정책 | 허용 |
|---|---|
| `platform-postgres-ingress` | `cnpg-system` operator(8000·5432), 같은 cluster operand(8000·5432), `gitea` namespace(5432), **`observability` 의 Prometheus(9187)** |
| `platform-postgres-keycloak-ingress` | `keycloak` namespace(5432)만 **추가** |
| `platform-postgres-allow-pgadmin` | `platform-admin` pgAdmin(5432)만 **추가** |
NetworkPolicy 의 허용은 additive 라서 Phase 2·3 의 증분 root 가 Phase 1 정책을 복사하거나
고치지 않는다. **그래서 Phase 2·3 은 Cluster 선언을 다시 렌더하지 않고 정책 한 줄씩만 더한다.**
**egress 는 제한하지 않는다.** operand 파드가 나가는 방향은 열려 있다. 중앙 문서가
"Operator 관리 경로와 향후 backup·Kubernetes API 경로를 섣불리 차단하지 않기 위한 선택"
이라고 적는다(기록). `platform-data` 에 default-deny 가 없는 것과 같은 이야기다.
### 8.3 Database·DatabaseRole 을 CR 로 관리한다
`Cluster` 의 `initdb` 가 `gitea` DB 와 owner 를 만들고(순환 의존을 줄이려고 Secret 에서
읽는다), 그 뒤 같은 이름의 `DatabaseRole`·`Database` CR 이 선언적 수명주기를 가져간다.
두 CR 의 reclaim policy 가 `retain` 이라 **CR 을 지워도 PostgreSQL 의 역할·DB 가 지워지지
않는다.** Keycloak 쪽은 `services/platform-postgres-keycloak` 이 같은 모양의 CR 둘과
NetworkPolicy 하나만 렌더한다.(선언)
### 8.4 확인하지 못한 것
중앙 문서의 체크리스트에서 **여섯 항목을 아직 아무도 체크하지 않았다**: 두 역할이 superuser
가 아닌지 SQL 로 확인, 상대 DB 에 HBA `reject` 가 실제로 걸리는지 확인, 두 역할이 상대 DB
객체를 못 읽는지 확인, **`gitea`·`keycloak` namespace 만 NetworkPolicy 경로로 TCP 5432 에
닿는지 확인**, PostgreSQL 재시작 뒤 데이터 유지 확인, AIStor 백업·복원 확인. 네 번째가 §8.2 가
세 겹 중 하나로 든 바로 그 경계다.
이 문서도 그 다섯을 확인하지 않았다(미확인). **선언과 집행은 다른 것이고, 여기서는 선언만
확인했다.**
---
## 9. ID 계층 — 프록시가 아니라 발급자다
### 9.1 무엇이 아닌가부터
Keycloak 은 **모든 요청 앞에 서는 인증 프록시가 아니다.** Traefik ForwardAuth 도, Nginx
auth_request 도 쓰지 않는다. 각 애플리케이션이 표준 OIDC client 로 직접 연결한다.
Keycloak 이 Host Nginx·Traefik 뒤에 있는 것은 **브라우저가 `id.learn.hyeonworks.com` 에
닿기 위한 네트워크 경로**일 뿐, 다른 서비스를 대신 인증하는 것이 아니다. 두 의미를
ADR-0005 가 이 둘을 갈라 놓는다.
### 9.2 Keycloak 인스턴스
```yaml
apiVersion: k8s.keycloak.org/v2beta1
kind: Keycloak
spec:
instances: 1
db: { vendor: postgres, host: platform-postgres-rw.platform-data.svc.cluster.local,
database: keycloak, poolInitialSize: 5, poolMinSize: 5, poolMaxSize: 20 }
hostname: { hostname: https://id.learn.hyeonworks.com, strict: true }
http: { httpEnabled: true, httpPort: 8080, serviceHttpPort: 8080 }
proxy: { headers: xforwarded }
ingress: { enabled: false } # Operator 가 만드는 Ingress 를 끄고 직접 쓴다
additionalOptions: [ { name: metrics-enabled, value: "true" } ]
```
`hostname.strict: true` 와 `proxy.headers: xforwarded` 의 조합이 §4.1의 nginx 상수 헤더와
맞물린다. **외부가 `X-Forwarded-Host` 를 주입해도 nginx 가 덮어쓰고, Traefik 은
`10.42.0.1/32` 에서 온 헤더만 믿고, Keycloak 은 `strict` hostname 을 쓴다.** 세 겹이 같은
방향을 본다.
관측: discovery 의 `issuer` 가 `https://id.learn.hyeonworks.com/realms/hyeonworks` 로 나온다
(evidence `edge-boundary-probe`).
**Service 는 `8080/9000` 두 포트를 갖지만 Ingress backend 는 `8080` 만 쓴다.** 관리 포트
`9000` 은 Ingress·NodePort·LoadBalancer·Host Nginx 어디에도 없다.(관측 — evidence
`cluster-services-and-ingress`)
CR 안에 NetworkPolicy 선언이 들어 있어서 Operator 가 `keycloak-network-policy` 하나를 만든다.
라이브의 ingress 규칙은 **셋**이다.(관측)
| 포트 | 출발지 |
|---|---|
| TCP 8080 | `kube-system` 의 Traefik 파드 |
| TCP 7800 · 57800 | **같은 Keycloak 파드 자신** — Infinispan 클러스터링 포트 |
| TCP 9000 | `keycloak` 의 Operator, `observability` 의 Prometheus |
CR 에는 `https` 목록도 있지만 TLS 를 껐기 때문에 **8443 규칙은 렌더되지 않았다.** 인스턴스가
하나라 7800·57800 규칙은 지금 아무 트래픽도 나르지 않지만 규칙 자체는 존재한다.
### 9.3 realm 하나와 client 넷
`hyeonworks` realm 하나에 confidential client 넷이 붙는다.
| client | 소비자 | Secret | 권한 게이트 |
|---|---|---|---|
| `gitea` | Gitea | `gitea/gitea-keycloak-oidc` (`key`,`secret`) | 없음 — 로그인하면 계정 생성 |
| `aistor-console` | AIStor Console | `object-storage/aistor-keycloak-oidc` (`client-id`,`client-secret`) | group `/platform-object-admins` → `policy=consoleAdmin` |
| `pgadmin` | pgAdmin | `platform-admin/pgadmin-keycloak-oidc` | group `/platform-db-admins` |
| `grafana` | Grafana | `observability/grafana-keycloak-oidc` | group `/platform-observability-admins` → Admin, `/platform-observability-viewers` → Viewer |
(관측 — 네 Secret 모두 실재. evidence `secret-inventory-names-only`. client 설정 자체는
Keycloak 관리 API 를 안 불러서 선언·기록 근거다)
**권한을 group 으로 나르는 방식이 제품마다 다르다.**
- **Grafana** — `groups` claim 의 full-path 를 JMESPath 로 읽어 role 로 바꾼다.
```text
role_attribute_path:
contains(groups[*], '/platform-observability-admins') && 'Admin'
|| contains(groups[*], '/platform-observability-viewers') && 'Viewer'
|| null
```
게이트는 두 겹이다. 그 앞에 `allowed_groups: /platform-observability-admins
/platform-observability-viewers` 가 먼저 걸리고, 뒤에서 `role_attribute_strict: true` 가
`null` 을 거부한다.
`allow_assign_grafana_admin: false` 이므로 여기서 주는 `Admin` 은 **organization Admin 이고
server-wide `GrafanaAdmin` 이 아니다.**
- **AIStor** — group 의 속성을 aggregate mapper 가 `policy` claim 으로 만들고,
`MINIO_IDENTITY_OPENID_CLAIM_NAME=policy` 로 읽는다. 즉 Keycloak 이 IAM policy 이름을
직접 발급한다.
- **pgAdmin** — `OAUTH2_ADDITIONAL_CLAIMS: {'groups': ['/platform-db-admins']}` 로 claim
일치를 요구한다. 통과해도 `OAUTH2_AUTO_CREATE_USER` 로 pgAdmin 사용자만 생기고
**PostgreSQL 권한은 자동으로 안 준다.**
- **Gitea** — group 게이트가 없다. 대신 `ALLOW_ONLY_EXTERNAL_REGISTRATION=true` 로 로컬
가입을 막고 OIDC 로만 계정이 생기게 한다.
### 9.4 break-glass 가 네 곳에 있다
OIDC 가 죽어도 들어갈 길을 제품마다 남겼다.
| 서비스 | 비상 경로 | 근거 |
|---|---|---|
| Gitea | `gitea-admin` Secret 의 로컬 관리자, `ENABLE_PASSWORD_SIGNIN_FORM: true` | 관측(Secret) + 선언 |
| Grafana | `grafana-admin` Secret, `auth.basic.enabled: true`, `oauth_auto_login: false` | 관측 + 선언 |
| pgAdmin | `pgadmin-bootstrap` Secret, `AUTHENTICATION_SOURCES = ['oauth2','internal']` | 관측 + 선언 |
| AIStor | `aistor-root-configuration` 의 root 계정, `disableRoot: false` | 관측 + 선언 |
**Keycloak 에는 설계된 break-glass 가 없다. 그런데 사실상의 경로가 공개면에 있다.**
`keycloak-initial-admin` Secret 은 실재한다(`kubernetes.io/basic-auth`, key `username`·
`password`). Operator 가 만든 bootstrap 임시 리소스이고 중앙 문서는 "named 관리자와 MFA로
교체해야 한다"고 적는데 **교체됐다는 기록이 없다.**(관측 — Secret 실재. 교체 여부 미확인)
그리고 그 계정이 로그인하는 화면이 열려 있다. `id.learn.hyeonworks.com` 의 server block 에는
`allow`/`deny` 가 **없다** — `grafana`·`storage-admin`·`db-admin` 셋과 다르다(§4.1(4)). 그래서
관리 콘솔이 같은 공개 경로로 응답한다.(관측 — desktop 이 아닌 별도 호스트에서)
```text
https://id.learn.hyeonworks.com/admin/ 302 → /admin/master/console/
https://id.learn.hyeonworks.com/admin/master/console/ 200
https://id.learn.hyeonworks.com/realms/master/.well-known/… 200
```
**이것은 OIDC 경로가 아니다.** `hyeonworks` realm 의 discovery 를 공개하는 것은 설계다 — 브라우저가
거기서 로그인해야 하니까. 그런데 같은 hostname 이 `master` realm 의 discovery 와 **관리 콘솔
로그인 화면**까지 함께 낸다. ADR-0008 은 「관리 화면 이름이 공개 DNS 에 나타나지 않는다」를
원칙으로 세우고 Console·pgAdmin 에 적용했는데, **Keycloak 자신의 관리 화면은 그 원칙 밖에
있다.**(관측 + 추론)
실제 위험은 자격 증명의 강도와 로그인 시도 제한에 달려 있고 이 문서는 둘 다 확인하지 않았다
(미확인 — 로그인을 시도하지 않았다). 다만 **경계가 설계 원칙과 다르다는 것은 사실이다.**
좁히는 방법은 두 가지다 — Host Nginx 의 `id` server block 에서 `/admin` 과 `/realms/master`
만 source allowlist 뒤로 보내거나, Keycloak 의 관리 인터페이스를 별도 hostname·포트로 떼는
것이다. 어느 쪽도 지금은 안 되어 있다.
### 9.5 Gitea 의 서버 측 discovery 경로
Gitea 파드가 `https://id.learn.hyeonworks.com/.../openid-configuration` 을 부를 때 나가는
경로가 좁혀져 있다.
```text
Gitea Pod
→ CoreDNS(coredns-custom) 가 id.learn… → 192.168.0.107 로 답
→ NetworkPolicy gitea-allow-host-nginx-keycloak 이 192.168.0.107/32:443 만 허용
→ Host Nginx :443 → Traefik :30080 → Keycloak :8080
```
**노드로 가는 길은 이 `/32` 하나로 못 박혀 있다.** 다만 「사설 대역으로는 못 나간다」는 정확하지
않다. `gitea-allow-public-git-https` 의 except 는 `10.0.0.0/8`·`172.16.0.0/12`·
`192.168.0.0/16`·`169.254.0.0/16` **넷뿐이고 `100.64.0.0/10` 이 없다.** 노드의 Tailscale 주소
`100.92.240.34` 가 그 대역에 있으므로 CGNAT 쪽 443 은 선언상 한 갈래 더 열려 있다.(관측)
같은 문서의 Alertmanager 정책(§12.3)은 그 대역을 뺐는데 Gitea 정책은 안 뺐다.
---
## 10. 서비스 세 편
### 10.1 Gitea — build root 가 둘이다
같은 chart 를 두 개의 build root 가 쓴다.
```text
services/gitea/ ← baseline. Keycloak 없이 최초 생성용
kustomization.yaml
base/{pvc,ingress,network-policies}.yaml
branding/… ← baseline 은 안 씀
profiles/oidc/
kustomization.yaml ← OIDC desired profile
values/baseline.yaml ← 둘이 공유
values/oidc.yaml ← OIDC profile 만
network-policy.yaml ← Keycloak egress
patches/delete-ssh-service.yaml
```
`render-phase1.sh` 가 baseline 을 `gitea.yaml`, profile 을 `gitea-oidc.yaml` 로 따로 렌더한다.
**Gitea 단계에 한정하면 `apply-phase1-gitea.sh` 는 baseline `gitea.yaml` 만 적용하고,
`apply-gitea-oidc.sh` 는 `gitea-oidc.yaml` 하나만 적용한다.** 스크립트 전체로 보면
`apply-phase1-gitea.sh` 는 Phase 1 을 통째로 세우는 것이라 다섯을 순서대로 적용한다 —
`namespaces.yaml` → `ssd-local-pv.yaml` → `cnpg-operator.yaml` → `platform-postgres.yaml` →
`gitea.yaml`. 그 사이에 `prepare-ssd-local-paths.sh` 와 `create-phase1-secrets.sh --execute`
도 부른다.(관측)
적용 책임을 나눈 이유는 OIDC 설정이 공개 discovery 가 살아 있어야만 의미가
있기 때문이다 — `apply-gitea-oidc.sh` 는 적용 전에 공개 discovery 의 exact issuer 와 OIDC
Secret 의 type·key 계약과 현재 Gitea health 를 먼저 확인한다.(선언)
| 항목 | 값 |
|---|---|
| 이미지 | `docker.gitea.com/gitea:1.27.0-rootless` (관측) |
| replica | 1, `RollingUpdate` with `maxSurge: 0`, `maxUnavailable: 1` |
| 자원 | request `250m/512Mi` → limit `2 CPU/2Gi` |
| Service | ClusterIP `3000` 하나. SSH Service 는 patch 로 삭제 |
| DB | `platform-postgres-rw.platform-data.svc.cluster.local:5432/gitea`, `SSL_MODE: disable` |
| 끈 것 | SSH · LFS · Actions · Package Registry · 내장 PostgreSQL · Valkey |
`maxSurge: 0` 은 취향이 아니라 제약이다. **Local RWO 볼륨은 기존 파드와 교체 파드가 동시에
잡을 수 없다.** 그래서 새 파드를 먼저 띄울 수 없고 옛 파드를 먼저 내려야 한다. 같은 이유로
pgAdmin·Grafana 는 아예 `Recreate` 전략이다.(선언 + 추론)
관측: 파드 age 39d(OIDC rollout 시점), 공개 `https://git.learn.hyeonworks.com/api/healthz`
가 HTTP 200.
### 10.2 MinIO AIStor — S3 는 안 열고 Console 만 연다
| 항목 | 값 |
|---|---|
| Operator | `aistor` namespace, 파드 3개 (object-store-operator · adminjob-operator · object-store-webhook) |
| ObjectStore | `object-storage/minio-aistor`, pool-0, `servers: 1`, `volumesPerServer: 1` |
| 상태 | `Initialized` / `green`, `drivesOnline: 1`, `drivesOffline: 0`, `writeQuorum: 1` |
| 용량 | capacity `999,892,553,728` bytes, usage `20,085,288,960` bytes |
| chart | Operator `aistor-operator 5.10.0`(SHA-256 `e5534f5a…babd1`), ObjectStore `aistor-objectstore 1.0.16`(SHA-256 `50ffa6a4…bf71e`) |
| Service | `minio:80`(S3), `minio-aistor-console:9090`, `minio-aistor-hl`(headless 9000·4444) — 전부 ClusterIP |
| PV·PVC request | `900Gi` — **XFS 가 `noquota` 라 강제되지 않는다**(§3.2). 아래 capacity 는 932GiB 파일시스템 쪽 값이다 |
| PVC 보호 | `pvcProtection: true` |
| 자원 | server request `500m/2Gi` → limit `3 CPU/8Gi`, sidecar `100m/128Mi` → `500m/512Mi` |
| 보안 | `runAsUser/Group/fsGroup: 1000`, `fsGroupChangePolicy: OnRootMismatch`, cap drop ALL |
(관측 — evidence `aistor-objectstore-and-bucket-usage`, `cluster-services-and-ingress`)
**`writeQuorum: 1` 은 쓰기 하나만 성공하면 끝난다는 뜻이다.** 서버 1대·볼륨 1개이므로 erasure coding 도 복제도
없다. 드라이브가 죽으면 모든 버킷이 같이 죽는다.
`profiles/admin-oidc` 오버레이가 baseline 위에 Console Ingress·OIDC 환경변수·NetworkPolicy 를
더한다. **baseline 과 OIDC profile 이 갈려 있어 OIDC 만 되돌릴 수 있다** — 데이터와 PVC 는
건드리지 않고.
`MINIO_PROMETHEUS_AUTH_TYPE: public` 이 붙어 있어서 metrics 를 인증 없이 긁는다. **그런데
MinIO 는 S3 와 metrics 를 같은 9000 에 올린다.** 그래서 「Prometheus 만 본다」가 아니다 —
TCP 9000 ingress 를 **네 정책**이 연다: `object-storage-allow-prometheus-metrics`(Prometheus),
`…-allow-observability-s3`(Loki·Tempo), `…-allow-internal-clients`(같은 namespace 의
`aistor-client=true` 와 ObjectStore 파드), `…-allow-aistor-operator`. **S3 를 쓰라고 연 길이
그대로 metrics 길이고, 그 위에 인증이 없다.**(관측)
### 10.3 pgAdmin — 비밀번호를 저장하지 못하게 한다
| 항목 | 값 |
|---|---|
| chart | OCI `docker.io/dpage/pgadmin4-helm:9.16.0`, 이미지 `9.16` digest 고정 |
| namespace | `platform-admin`, PSS enforce **restricted** |
| replica | 1, `Recreate` |
| 스토리지 | 2Gi `ssd-local-pgadmin-retain` |
| 자원 | request `250m/512Mi` → limit `1 CPU/1Gi` |
| 보안 | `runAsUser/Group: 1001`, `readOnlyRootFilesystem: true`, cap drop ALL, seccomp+AppArmor RuntimeDefault, SA token automount off |
`config_local.py` 를 Secret 이 아니라 **ConfigMap 으로 read-only 마운트**한다 — 비밀이 아니기
때문이다. OIDC client id/secret 만 환경변수로 주입한다.
세 줄이 이 설정의 성격을 정한다.
```python
ALLOW_SAVE_PASSWORD = False
ALLOWED_HOSTS = ['db-admin.learn.hyeonworks.com']
ENABLE_PSQL = False
ENABLE_SERVER_PASS_EXEC_CMD = False
```
공유 서버 정의 둘(`Hyeonworks Gitea`, `Hyeonworks Keycloak`)에 **비밀번호를 넣지 않고**
`sslmode: require` 만 건다. 즉 pgAdmin 에 로그인해도 DB 비밀번호를 따로 알아야 한다.
`PGADMIN_REPLACE_SERVERS_ON_STARTUP: "True"` 로 서버 정의는 매번 선언으로 덮어쓴다.
probe 셋이 전부 `Host: db-admin.learn.hyeonworks.com` 헤더를 붙여 `/misc/ping` 을 친다 —
`ALLOWED_HOSTS` 때문에 헤더 없이는 통과하지 못한다.(선언 + 추론)
---
## 11. 관측성 — 세 신호가 각각 다른 길로 들어온다
### 11.1 전체 배치
```text
┌──────────────── observability-agent (PSS privileged) ───────────────┐
│ Alloy DaemonSet node-exporter DaemonSet │
│ ├ /var/log/pods (hostPath, ro) 호스트 CPU·메모리·FS·inode │
│ └ OTLP/gRPC :4317 │
└───────┬──────────────────────┬──────────────────────────────────────┘
log │ trace │ metric ▲ (pull)
▼ ▼ │
┌──────────────────── observability (PSS restricted) ─────────────────────────┴────────┐
│ Loki :3100 ──┐ Tempo :4317/:3200 ─┐ Prometheus :9090 │
│ WAL 5Gi │ WAL 5Gi │ TSDB 20Gi · 15d/16GB │
│ │ │ │ │ │
│ └──── AIStor S3 ────────────────┘ │ ▼ │
│ loki 30일 · tempo 7일 │ Alertmanager :9093 │
│ │ 120h · 1Gi │
│ kube-state-metrics Blackbox :9115 │ │ │
│ ▼ ▼ │
│ Grafana :3000 ◀── 5 dashboard ◀──── Slack (public 443) │
└────────────────────────────────────────────────────────────────────────────────────┘
```
관측 시점 전부 Ready: Grafana·Prometheus·Alertmanager·Loki·Tempo·Alloy·node-exporter·
kube-state-metrics·blackbox-exporter·prometheus-operator.(관측)

Diagram description
수집 계층은 observability-agent namespace 다. Alloy DaemonSet 이 노드의 /var/log/pods 를 read-only hostPath 로 읽어 Loki 의 3100 으로 밀고, 애플리케이션의 OTLP/gRPC 4317 을 받아 Tempo 의 4317 로 민다. node-exporter 는 호스트 지표를 노출만 하고, Prometheus 가 그것을 끌어간다. Prometheus 는 kube-state-metrics 와 Blackbox Exporter 도 끌어간다. 저장 계층은 observability namespace 다. Prometheus 는 로컬 TSDB 20Gi 에 15일 또는 16GB 까지 담고, Loki 와 Tempo 는 로컬 PV 를 WAL 로만 쓰고 본 객체를 AIStor S3 의 loki 버킷과 tempo 버킷에 보낸다. 조회는 Grafana 한 곳에서 한다. 경보는 Prometheus 가 평가해 Alertmanager 로 보내고 Alertmanager 만 공개 HTTPS 443 으로 나가 Slack 에 전달한다. 이 그림의 화살표는 TCP 연결을 거는 쪽이 아니라 데이터가 흐르는 쪽을 가리킨다. Prometheus 와 Grafana 는 스스로 연결을 걸지만 데이터는 target 과 backend 에서 그쪽으로 온다. Prometheus 는 Alloy 와 Loki 자신의 지표도 끌어가지만 이 그림에서는 세 신호의 경로를 흐리지 않도록 생략했다.
[Editable source](assets/diagrams/observability-signal-paths/observability-signal-paths.drawio) · [Grounded VizSpec](.techviz/observability-signal-paths/spec.json)
### 11.2 Prometheus — 두 겹 selector 로 소유권을 가른다
```yaml
serviceMonitorNamespaceSelector: { matchLabels: { observability.hyeonworks.com/enabled: "true" } }
serviceMonitorSelector: { matchLabels: { observability.hyeonworks.com/instance: home } }
```
`podMonitor`·`probe`·`rule` 도 같은 모양이고, 네 `…SelectorNilUsesHelmValues` 가 전부 `false`
다. **namespace 에 label 이 있고 객체에도 label 이 있어야 선택된다.**
이것이 만드는 실용적 효과: **미래의 애플리케이션 저장소가 자기 ServiceMonitor 를 만들어도
플랫폼이 namespace 에 label 을 붙이기 전에는 수집되지 않는다.** 소유권 경계를 label 로
표현했다.
label 이 붙은 namespace 다섯: `kube-system`, `gitea`, `keycloak`, `platform-data`,
`object-storage` (+ `observability`, `observability-agent` 자신). 저장소의
`infrastructure/namespaces/observability/discovery-namespaces.txt` 가 그 다섯을 적는다.
**이 파일은 kustomization 에 들어 있지 않다** — 목록만 있다. README 는 그 label 을
「later apply workflow」가 소유한다고 적는데 **저장소에서 그 label 을 붙이는 스크립트를 찾지
못했다**(관측 — `grep` 결과 렌더 검증 스크립트 하나만 걸린다). 라이브 namespace 에 label 이
붙어 있는 것은 사실이고, 무엇이 붙였는지는 미확인이다.
수집 기준: `scrapeInterval: 30s`, `evaluationInterval: 30s`, 보존 `15d` / `16GB` 중 먼저 닿는
쪽. **Prometheus 는 `16GB` 를 16 GiB 로 읽는다** — `prometheus_tsdb_retention_limit_bytes` 가
`17,179,869,184` 다. 관측 시점 block 크기 `4,657,964,807` bytes 로 그 한도의 **약 27%**.(관측)
**관측: active target 30, healthy 30 (30/30).** job 별 분포:
```text
kubelet 3 · apiserver 1 · coredns 1 · kube-state-metrics 1 · prometheus-node-exporter 1
observability-core-kube-pr-prometheus 2 · …-alertmanager 2 · …-operator 1
traefik 1 · gitea 1 · keycloak-service 1 · platform-postgres 1 · minio-aistor 1
alloy 1 · observability/loki 1 · tempo 1 · grafana 1 · blackbox-exporter 1
blackbox-public-edge 2 · blackbox-private-edge 3 · blackbox-private-internal 3
```
끈 것: `kubeControllerManager`, `kubeScheduler`, `kubeEtcd`, `kubeProxy`. **단일 노드 k3s 에서는
이 넷이 별도 엔드포인트로 노출되지 않아 항상 down 으로 보인다.** 켜 두면 영구 false alarm 이
된다.(선언 + 추론)
### 11.3 Blackbox — 경계마다 기대하는 응답이 다르다
Probe 셋이 세 그룹으로 나뉘고, **그룹마다 성공의 정의가 다르다.**
| Probe | module | 대상 | 성공 조건 |
|---|---|---|---|
| `platform-public-edge` | `http_2xx` | `https://git.learn.hyeonworks.com/api/healthz`, `https://id.learn.hyeonworks.com/realms/hyeonworks/.well-known/openid-configuration` | 2xx |
| `platform-private-edge` | `http_private_edge_403` | `https://grafana…/`, `https://storage-admin…/`, `https://db-admin…/` | **403** |
| `platform-private-internal` | `http_private_internal_200` | `http://grafana.observability…/api/health`, `http://pgadmin.platform-admin…/misc/ping`, `http://minio-aistor-console.object-storage…:9090/` | 200 |
**`private-edge` 는 403 을 성공으로 센다.** blackbox 파드는 클러스터
안에 있으므로 Host Nginx 에서 볼 때 source 가 `10.42.0.1` 이고 LAN·Tailscale allowlist 밖이다.
그래서 **allowlist 가 살아 있으면 403 이 온다.** 만약 200 이 오면 allowlist 가 사라진 것이고,
그것이 `probe_success=0` 으로 잡힌다. **경계가 열린 것을 장애로 감지하는 probe 다.**
`private-internal` 은 클러스터 내부 Service 를 직접 치되 `__param_hostname` relabeling 으로
각 애플리케이션이 기대하는 `Host` 헤더를 만들어 준다 — pgAdmin 의 `ALLOWED_HOSTS` 와
Grafana 의 `enforce_domain: true` 를 통과하기 위해서다.
### 11.4 규칙 — 플랫폼 22 + 생성 133 = 155
관측: **alert rule 155개, recording rule 86개, group 36개, firing 0, pending 0, unhealthy 0.**
(evidence `prometheus-targets-and-rules`)
문서는 "155 = generated 133 + platform 22" 와 "platform recording rule 1" 을 적는다. 라이브의
recording rule 86 은 그 1 + kube-prometheus-stack 이 만드는 85 다.(관측 + 추론)
플랫폼 규칙 22개는 `PrometheusRule` 넷에 나뉜다.
| 파일 | group | 내용 |
|---|---|---|
| `core-rules.yaml` | `platform.storage` · `platform.workloads` | PVC 미바인딩, root FS 사용률 3단계, inode 2단계, 재시작 burst, OOMKilled |
| `certificate-rules.yaml` | `platform.blackbox` · `platform.certificates` | probe 실패 3그룹, 만료 30일 warning / 14일 critical |
| `storage-quota-rules.yaml` | `platform.aistor-storage-quota` | recording rule 1 + quota 사용률 70/85/95 |
| `verified-service-rules.yaml` | `platform.verified-services` | CNPG collector down, Alloy config load 실패·재시도·drop, Loki reload 실패·WAL 80% |
**임계값을 셋으로 쪼갠 이유.** root filesystem 은 `>75% for 30m` = info, `>85% for 15m` =
warning, `>90% for 5m` = critical 이다. **한계에 가까울수록 관측 창을 짧게 잡는다.** 여유가
있을 때는 30분을 기다려 순간 튐을 걸러내고, 임박하면 5분 만에 깨운다.
**그런데 `PlatformLokiWALDiskUsageHigh` 는 Loki 를 보지 않는다.** 관측 시점
`loki_ingester_wal_disk_usage_percent` 가 약 `0.606` 인데 Loki 의 WAL 은 9.9 MiB 뿐이다(§7.4).
이 metric 은 Loki 자신의 사용량이 아니라 **WAL 이 놓인 파일시스템의 사용률**이다. 근거 셋:
metric 의 HELP 가 `Current disk usage percentage (0.0 to 1.0) for the WAL directory` 이고,
24시간 48표본에서 이 값과 루트 파일시스템의 `1 - free/total` 이 **소수점 5~6자리까지 함께
움직이며**(예: `0.604119` ↔ `0.604118`), Loki 가 9.9 MiB 를 쓰는데 값이 60% 대인 것은 그것으로만
설명된다.(관측)
그래서 이 경보는 `>= 0.8` 에서 **루트 파일시스템이 80% 에 닿을 때** 울린다. 즉
`PlatformRootFilesystemUsage` 와 같은 것을 다른 이름으로 한 번 더 세는 셈이고, **Loki 의
WAL 이 혼자 불어나는 상황은 잡지 못한다**(§18.6).
**임계값에 가장 가까운 것은 이 경보가 아니다.** 루트 파일시스템 사용률이 `65.8` 로 첫 임계
`75` 까지 9.2pp 인데, 이 WAL 경보는 `0.607` 로 임계 `0.8` 까지 19.3pp 다. 두 값이 같은 것을
보고 있으므로 **먼저 울리는 쪽은 언제나 `PlatformRootFilesystemUsage` 다.**
`verified-service-rules` 라는 이름이 말하는 것: **실제로 존재하는 metric 만 쓴 규칙이다.**
`cnpg_collector_up`, `alloy_config_last_load_successful`, `loki_write_batch_retries_total`,
`loki_write_dropped_entries_total`, `loki_runtime_config_last_reload_successful`,
`loki_ingester_wal_disk_usage_percent` 여섯을 inventory 로 확인한 뒤 규칙을 만들었다 — 중앙 문서가 "inventory 를 먼저 수집한 뒤에만
만들도록 분리했다" 고 기록한다.
AIStor quota recording rule:
```promql
platform:aistor_bucket_quota_usage_percent =
100 * max by (bucket) (minio_cluster_usage_buckets_total_bytes{bucket=~"loki|tempo"})
/ max by (bucket) (minio_cluster_usage_buckets_quota_total_bytes{bucket=~"loki|tempo"} > 0)
```
분모에 `> 0` 이 붙어 있다. **quota 를 안 건 버킷은 분모가 0 이 되어 규칙이 무한대를 내는
대신 결과에서 빠진다.** 관측 시점 `loki` 0.403%, `tempo` 0% 로 둘 다 값이 나오므로 두 버킷에
quota 가 실제로 걸려 있다.(관측 + 추론 — `loki` 866,300,448 bytes ÷ 0.40340% ≈ 214,748,364,800
bytes = 200Gi, 문서의 승인값과 일치)
### 11.5 Alertmanager — 묶는 키에 severity 를 넣었다
```text
groupBy: cluster, namespace, alertname, severity
groupWait: 30s
groupInterval: 5m
repeatInterval: 4h
receiver: platform-slack (sendResolved: true)
child route: alertname=InfoInhibitor → platform-null
inhibitRule: InfoInhibitor → 같은 namespace 의 severity=info 억제
```
**`severity` 를 group key 에 넣으면 무엇이 달라지나.** 같은 alertname 의 warning 과
critical 이 한 메시지로 섞이면 색과 제목이 둘 중 하나로 정해져 버린다. 갈라 놓으면 각각
제 색으로 온다.
`InfoInhibitor` 는 kube-prometheus-stack 이 info 억제를 구현하려고 만든 **제어용 alert**
이지 장애 통지가 아니다. 그런데 Alertmanager 입장에서는 그냥 alert 라서 Slack 에 firing /
resolved 가 찍혔다. child route 로 integration 이 없는 `platform-null` 로 보내서 **Slack 에는
안 보내되 inhibit source 로서의 의미는 유지한다.**
관측 런타임 receiver 는 정확히 둘이다.
```text
observability/platform-alertmanager/platform-null
observability/platform-alertmanager/platform-slack
```
**Prometheus Operator 가 `//` 로 이름을 다시 짓는다.** 소스에
적은 `platform-slack` 과 런타임 이름이 다르고, 이것을 몰라서 postcheck 가 정상 상태를
실패로 판정하고 rollback 한 사건이 있다(§17.4).
Slack 메시지 구조: 제목에 `[FIRING:n]`/`[RESOLVED]` + severity + alertname, color 는 resolved
green / critical·emergency red / warning yellow / 나머지 blue, short field 넷(Status,
Severity, Location=`cluster / namespace`, Alert count), alert 마다 group label 을 뺀 target
label 전체 + summary + description + 시작·종료 시각 + runbook 링크, 끝에 Grafana·Explore
링크와 footer.
관측: active alert 0, silence 0, Alertmanager `0.33.1`, cluster mode `disabled`(단일 노드).
### 11.6 로그와 trace — 수집 범위가 좁다
**Alloy 가 읽는 것은 이 노드에 뜬 파드의 stdout/stderr 뿐이다.**
```text
discovery.kubernetes "pods" { selectors { field = "spec.nodeName=" + sys.env("HOSTNAME") } }
→ /var/log/pods/*//*.log (hostPath ro)
→ CRI 또는 Docker parser
→ 마스킹 4단계
→ level 추출 (허용 목록 밖이면 label 버림)
→ label_keep: cluster, namespace, app, pod, container, level
→ loki.write http://loki.observability.svc.cluster.local:3100
```
**안 읽는 것**: Host Nginx access/error 로그, k3s·systemd journald, SSH/auth, kernel/audit,
파일로만 쓰는 애플리케이션 로그. ELK 계열은 아예 없다.
마스킹은 Loki 로 보내기 **전에** Alloy 에서 한다. 정규식 넷이 JSON 필드형·헤더형·bearer·
key=value 형을 각각 잡아 `[REDACTED]` 로 바꾼다. 중앙 문서는 이것을 "심층 방어"로 규정하고
**애플리케이션의 선제 마스킹이 권위**라고 적는다 — 즉 Alloy 마스킹을 믿고 로그에 비밀을
써도 된다는 뜻이 아니다.
label 을 여섯으로 못 박은 것은 **cardinality 통제**다. `trace_id`·`request_id`·원시 URL·
사용자 식별자를 label 로 만들지 않는다. 그것들은 로그 본문에 남고 검색은 문자열 filter 로
한다.
trace 경로:
```text
application OTLP/gRPC :4317
→ Alloy k8sattributes (namespace·deployment·node·pod·uid·start_time·container 부착)
→ batch 1s / 512 · max 1024
→ otlp exporter → tempo:4317 (retry 1s~15s, 최대 5m · queue 256, block_on_overflow)
→ Tempo → AIStor tempo 버킷
```
**보내는 쪽이 아직 없다.** `tempo` 버킷 0 bytes 가 그 증거다. Tempo 의
`metricsGenerator.enabled: false` 이므로 service map·node graph 데이터도 생기지 않는다.
Loki ↔ Tempo 상관은 양방향으로 설정돼 있다. Loki datasource 의 derived field 가
`"trace_id": "<32 hex>"` 를 찾아 Tempo 로 링크하고, Tempo 의 `tracesToLogsV2` 가
`k8s.namespace.name → namespace`, `k8s.pod.name → pod` 태그와 ±1분 창으로 Loki 로 돌아온다.
**설정만으로는 연결이 안 생긴다** — 애플리케이션이 같은 32자리 trace ID 를 구조화 로그에
써야 한다.
### 11.7 Grafana — Git 이 권위다
```text
Git JSON → 안정 이름 ConfigMap(grafana_dashboard=1) → grafana-sc-dashboard WATCH
→ /tmp/dashboards → Grafana file provider (30s)
```
`disableNameSuffixHash` 로 ConfigMap 이름이 해시로 안 바뀌고, `allowUiUpdates: false` 이며
각 dashboard JSON 도 `editable: false` 다. **UI 에서 고친 것은 다음 동기화에서 남는다고
가정하지 않는다.**
권한이 갈려 있다: **main Grafana 컨테이너는 ServiceAccount token 을 automount 하지 않는다.**
3600초 projected token 은 `grafana-sc-dashboard` 사이드카에만 붙고, 그 Role 은 `observability`
namespace 의 ConfigMap `list`/`watch` 만 갖는다. Secret 권한이 없다.
dashboard 다섯(전부 Prometheus datasource, `now-6h`, refresh 30s):
`platform-kubernetes-node`(5패널) · `platform-workload-health`(4) · `platform-services`(8) ·
`platform-observability-backends`(7) · `platform-https-endpoints`(4).
**로그 전용 dashboard 가 없다.** 로그와 trace 는 Explore 에서만 본다. 중앙 문서가 이것을
후속 우선순위 1번으로 적는다.
관측: Grafana `13.1.1`, sidecar `2.10.0`, `https://grafana.learn.hyeonworks.com/api/health`
HTTP 200.

Diagram description
Git 저장소의 dashboard JSON 이 desired state 다. Kustomize 가 disableNameSuffixHash 로 안정 이름 ConfigMap 을 만들고 grafana_dashboard=1 label 을 붙인다. grafana-sc-dashboard 사이드카는 observability namespace 의 ConfigMap 을 list 와 watch 만 할 수 있는 Role 로 WATCH 하고, 변경을 /tmp/dashboards 에 반영한다. Grafana file provider 가 30초마다 그 디렉터리를 읽어 actual state 를 맞춘다. allowUiUpdates 는 false 이고 각 dashboard JSON 도 editable 이 false 라, 브라우저에서 고친 것은 이 고리에 들어가지 못하고 다음 동기화에서 덮인다. main Grafana 컨테이너는 ServiceAccount token 을 automount 하지 않으므로 Kubernetes API 로 스스로 상태를 되돌릴 수도 없다.
[Editable source](assets/diagrams/dashboard-authority-loop/dashboard-authority-loop.drawio) · [Grounded VizSpec](.techviz/dashboard-authority-loop/spec.json)
---
## 12. 네트워크 정책 — default-deny 는 네 namespace뿐이다
### 12.1 전체 분포
관측: NetworkPolicy 58개.(evidence `cluster-networkpolicy-and-storage`)
| namespace | 개수 | default-deny | 범위 |
|---|---:|---|---|
| `observability` | 18 | 있음 | namespace 전체 |
| `object-storage` | 11 | 있음 | namespace 전체 |
| `gitea` | 7 | 있음 | **Gitea 파드만** |
| `platform-admin` | 6 | 있음 | **pgAdmin 파드만** |
| `observability-agent` | 6 | 있음 | namespace 전체 |
| `aistor` | 5 | 있음 | namespace 전체 |
| `platform-data` | 3 | **없음** | ingress 만 제한 |
| `kube-system` | 1 | 없음 | Traefik ingress 보존 + Prometheus 허용 |
| `keycloak` | 1 | 없음 | CR 이 만든 정책 |
| `cnpg-system` | **0** | 없음 | 정책 없음 |
**namespace 전체를 막는 default-deny 는 넷이다** — `observability`, `observability-agent`,
`object-storage`, `aistor`. `gitea` 와 `platform-admin` 의 default-deny 는 podSelector 가
붙어 있어서 **그 namespace 에 다른 파드가 생기면 정책 밖이다.**(관측 — POD-SELECTOR 칸)
`cnpg-system` 에는 정책이 하나도 없다. **PostgreSQL Operator 는 자유롭게 통신한다.**
### 12.2 Gitea 의 일곱
| 정책 | 방향 | 허용 |
|---|---|---|
| `gitea-default-deny` | 양방향 | 전부 차단 |
| `gitea-allow-traefik-http` | in | `kube-system` Traefik → 3000 |
| `gitea-allow-prometheus-metrics` | in | Prometheus → metrics |
| `gitea-allow-dns` | out | kube-dns 53 |
| `gitea-allow-platform-postgres` | out | `platform-data` PostgreSQL 5432 |
| `gitea-allow-public-git-https` | out | 사설·link-local 뺀 외부 IPv4 443 |
| `gitea-allow-host-nginx-keycloak` | out | `192.168.0.107/32` 443 |
마지막 둘의 관계가 이 정책 집합의 설계 의도를 보여 준다. **외부 Git remote 는 열되 사설
대역을 빼고, 그 예외로 노드 주소 하나를 뚫었다.**
다만 「못 나가는 것」을 정확히 적으면 좁다. except 는 `10.0.0.0/8`·`172.16.0.0/12`·
`192.168.0.0/16`·`169.254.0.0/16` 넷이고 **`100.64.0.0/10` 이 빠져 있다** — 노드의 Tailscale
주소가 그 대역이다. 그리고 공개 IPv4 의 443 이 열려 있으므로 **공개 HTTPS 로 가는 webhook 은
나간다.** 실제로 막히는 것은 사설 IPv4 대역의 HTTPS 와, 443 이 아닌 포트(SMTP·SSH 등)다.(관측)
### 12.3 관측성의 열여덟
수집·질의·전송이 각각 정책이 된다.
```text
in : Prometheus ← KSM · operator · blackbox · self
Grafana ← Traefik(ingress)
Alertmanager← Prometheus · peer
out : Prometheus → platform target 들
Grafana → datasource(Prometheus·Loki·Tempo) · Kubernetes API(sidecar)
· 192.168.0.107/32:443 (Host Nginx 를 거쳐 Keycloak — OIDC 로그인)
Blackbox → probe 대상 · 192.168.0.107/32:443
Loki·Tempo → AIStor
Alertmanager→ public HTTPS
전부 → DNS
```
**Grafana 와 Blackbox 의 `192.168.0.107/32:443` 이 이 목록에서 가장 덜 보이는 줄이다.**
Grafana 쪽은 §11.7 의 OIDC 로그인이 성립하는 길이고 — 파드가 노드 주소로 나가 Host Nginx 를
거쳐 Keycloak 으로 돌아온다(§5.2) — Blackbox 쪽은 `private-edge` probe 가 403 을 받아 오는
길이다(§11.3). 둘 다 없으면 그 기능이 죽는다.
`observability-allow-alertmanager-public-https`(파일 이름은 `alertmanager-public-https-egress.yaml`)
가 유일하게 공개 인터넷으로 나간다.
```text
to: 0.0.0.0/0
except: 10.0.0.0/8, 100.64.0.0/10, 172.16.0.0/12, 192.168.0.0/16
ports: TCP 443
```
**Slack webhook 하나 때문에 열어야 하는 구멍을 「공개 IPv4 의 443」까지 좁힌 것이다.**
vanilla NetworkPolicy 는 hostname 단위 egress 를 못 하므로 여기가 한계다. 사설·CGNAT 을
빼서 내부로 돌아오는 것은 막았다.
### 12.4 오브젝트 스토리지의 열하나
`object-storage-allow-observability-s3` 하나가 두 조건을 동시에 건다.
```text
from: namespace observability 의 파드 중
label platform.hyeonworks.com/aistor-client: "true" 이고
이름이 loki 또는 tempo 인 것
port: TCP 9000
```
**label 만으로는 부족하다고 보고 이름까지 건다.** 그래서 `observability` 에 label 만 붙인
다른 파드를 넣어도 S3 에 못 닿는다.
`object-storage-allow-labeled-clients` 는 이름과 달리 **다른 namespace 의 클라이언트를
들여보내는 정책이 아니다.** `policyTypes: [Egress]` 이고, NetworkPolicy 의 `podSelector` 는
정책이 놓인 namespace 안에서만 파드를 고른다. 즉 **`object-storage` 안의 `aistor-client=true`
파드가 ObjectStore 로 나가는 것**을 여는 규칙이다.(관측)
밖에서 들어오는 길은 각자 자기 namespace 쪽에서 열린다 — Loki·Tempo 는
`observability-allow-aistor-egress`(§12.3)로 나가고, 받는 쪽은 위의
`object-storage-allow-observability-s3` 가 연다. **한 흐름에 정책 두 개가 양쪽에서 필요하다**는
것이 이 저장소가 `targets/counterpart-network-policies.yaml` 이라는 파일을 따로 둔 이유다.
### 12.5 이 정책들이 증명하는 것과 안 하는 것
**증명하는 것**: 선언이 클러스터에 있다. 58개가 실재한다(관측).
**컨트롤러는 켜져 있다.** flannel 자체는 NetworkPolicy 를 집행하지 않지만 k3s 는 자체
netpol controller 를 함께 넣는다. 마지막 k3s 기동 로그에 그것이 있다.(관측)
```text
Aug 27 12:28:20 … level=info msg="Starting network policy controller version v2.6.3-k3s1, …"
Aug 27 12:28:20 … network_policy_controller.go:164] Starting network policy controller
Aug 27 12:28:20 … network_policy_controller.go:179] Starting network policy controller full sync goroutine
```
**증명하지 않는 것**: 그 컨트롤러가 실제로 만든 iptables·ipset 규칙과, 허용·거부가 양방향으로
맞는지. `iptables -S` 는 root 가 필요해 못 읽었다(미확인). 중앙 문서도 "k3s CNI에서 정책이
실제 강제되는지는 양방향 allow/deny Pod 시험으로 별도 확인한다" 고 적고 **그 시험 기록이
없다.**
즉 남은 간격은 「컨트롤러가 있는가」가 아니라 **「규칙이 의도대로 걸렸는가」**다. 좁히는
방법은 §18.1 에 적는다.
---
## 13. 시크릿·암호화·복구
### 13.1 저장소에는 자격 증명이 없다
`.gitignore` 가 막는 것:
```text
.env / .env.* *.key *.pem *.p12 *.pfx *.jks *.crt
*.kubeconfig / kubeconfig
**/secrets/*.yaml **/secrets/*.yml
infrastructure/security/k3s/local-recovery.env ← 하드웨어 식별자
.helm/ charts/ *.tgz rendered/ dist/
```
**이름 기반 ignore 는 보조일 뿐이다.** `scripts/validate/scan-platform-sensitive-source.sh`
(1,725줄)가 이름과 무관하게 소스 YAML 의 `kind: Secret` 을 거부하고, 그 스크립트의 테스트가
`test-scan-platform-sensitive-source.sh`(1,485줄)다.
`local-recovery.env` 가 ignore 되는 이유는 비밀번호가 아니라 **하드웨어 식별자**다 — WWN,
serial, FS UUID, PARTUUID. 파괴적 작업의 대상을 `/dev/sdX` 이름이 아니라 이 식별자 조합으로
고정하는 계약 파일이다. 작업 트리에는 있고 커밋에는 없다.(관측)
### 13.2 Secret 계약과 라이브 대조
문서가 선언한 계약 11개가 라이브에 전부 있다.(관측 — evidence `secret-inventory-names-only`)
| 단계 | 객체 | type | 라이브 |
|---|---|---|---|
| Phase 1 | `platform-data/gitea-db-credentials` | basic-auth | ✅ |
| Phase 1 | `gitea/gitea-db-credentials` | basic-auth | ✅ |
| Phase 1 | `gitea/gitea-admin` | basic-auth | ✅ |
| Keycloak | `platform-data/keycloak-db-credentials` | basic-auth | ✅ |
| Keycloak | `keycloak/keycloak-db-credentials` | basic-auth | ✅ |
| Keycloak | `gitea/gitea-keycloak-oidc` | Opaque | ✅ |
| AIStor | `aistor/minio-license` | Opaque | ✅ |
| AIStor | `object-storage/aistor-root-configuration` | Opaque | ✅ |
| Phase 3 | `object-storage/aistor-keycloak-oidc` | Opaque | ✅ |
| Phase 3 | `platform-admin/pgadmin-keycloak-oidc` | Opaque | ✅ |
| Phase 3 | `platform-admin/pgadmin-bootstrap` | Opaque | ✅ |
관측성 계약 5개도 전부 있다: `observability/` 의 `grafana-keycloak-oidc`, `grafana-admin`,
`loki-object-storage`, `tempo-object-storage`, `alertmanager-slack-webhook`.
**중앙 문서(2026-08-09)는 이 다섯을 "아직 생성하지 않았다" 고 적는다 — 그 뒤에 만들어졌다.**
계약에 없는데 라이브에 있는 것: `object-storage/minio-license`(chart 가 복사), 각 chart 가
만드는 TLS·generated Secret 들, `keycloak/keycloak-initial-admin`.
### 13.3 two-or-none 계약
bootstrap 스크립트들이 공통으로 지키는 규칙이 하나 있다.
```text
계약의 객체가 전부 없다 → 대화형 입력 후 최초 생성
계약의 객체가 전부 있다 → type·key·교차 namespace 값 일치를 검증한다. Secret data 는 안 건드린다
일부만 있다 → 아무것도 쓰지 않고 중단
```
「전부 있다」 가지도 완전한 읽기 전용은 아니다. 서버 측 Secret 에 `cnpg.io/reload=true` label 이
없으면 `--overwrite` 로 **label 만 수리한다** — `Repaired cnpg.io/reload=true without changing
Secret data.` 를 찍는다. data 는 그대로 두지만 「검증만 한다」는 아니다.(관측)
**부분 상태를 「고쳐 주는」 동작이 없다.** Kubernetes API 호출은 트랜잭션이 아니라서 중간에
실패하면 일부 객체가 남는다.
**다만 실패 처리는 셋이 같지 않다.** `create-phase1-secrets.sh` 와 `create-keycloak-secrets.sh`
는 아무것도 지우지 않고 `SAFE STOP: no Secret or database data was deleted or rolled back.`
을 찍는다. `create-aistor-secrets.sh` 는 `trap ERR → on_error → rollback_new_secrets` 로
**이번 실행이 만든 Secret 두 개를 지운다.** 「어느 쪽도 자동으로 안 지운다」가 아니라
「이미 있던 것은 안 지우고, 방금 만든 것은 되돌린다」다.(관측)
같은 이유로 **회전 기능이 없다.** `create-phase1-secrets.sh`·`create-keycloak-secrets.sh`·
`create-aistor-secrets.sh` 어느 것도 rotation 을 지원하지 않는다. 회전은 「새 자격 증명 생성
→ 소비자 전환 → 동작 검증 → 옛 값 폐기」의 별도 작업이다.
`gitea-admin` 에는 제품 쪽 제약이 하나 더 있다. `passwordMode: initialOnlyRequireReset` 이라
**Secret 의 data 만 바꿔도 이미 만들어진 Gitea 계정 비밀번호는 안 바뀐다.**
### 13.4 k3s Secret 저장 암호화가 막는 것과 못 막는 것
**막는 것**: datastore 파일이나 snapshot 만 단독으로 새어 나갔을 때 payload 가 바로 읽히는 것.
**못 막는 것**: 같은 호스트의 root 침해, full-disk 탈취. **암호화 key 와 상태 파일이 같은
호스트에 있고, server token 과 backup 을 함께 얻으면 복구 과정에서 복호화할 수 있다.**
그래서 token·config·datastore·검증 자료를 묶은 recovery bundle **전체를 하나의 Secret 으로
취급한다.**
### 13.5 로컬 LUKS 복구 매체 — 승인된 예외
원칙은 암호화된 off-host 매체다. 그런데 외장 매체가 없어서 **K3s 제어면 bundle 에 한해**
같은 섀시의 다른 물리 SSD 를 쓰기로 했다(ADR-0010).
```text
/dev/sda3 NTFS (수동 mount, 평소 unmount)
└ HyeonworksRecovery/
├ vault/hyeonworks-recovery.kdbx ← LUKS 밖. 마스터 암호는 외우거나 밀봉 종이
└ containers/k3s-recovery.luks ← 32GiB 완전 할당 regular file, mode 0600
└ loop → dm-crypt LUKS2 → ext4 (label K3S_RECOVERY, root:root 0700)
└ pre / post bundle
```
**장치를 이름으로 고르지 않는다.** `local-recovery.env` 의 WWN·serial·FS UUID·PARTUUID 가
전부 일치해야 하고, recovery 디스크의 parent 가 K3s root 의 parent 와 **달라야** 진행한다.
`/dev/sda` 같은 커널 이름은 판정 입력으로 쓰지 않는다.
용량도 상수가 아니라 식이다.
```text
P = 한 phase bundle 의 예상 bytes
U = 이미 쓴 bytes
컨테이너 크기를 정할 때 (총 용량 기준):
required = U + 2 × ceil(P × 1.25) + 10GiB ≤ ext4 usable capacity
매 실행 직전 (가용 공간 기준):
pre 직전: 2 × ceil(P × 1.25) + 10GiB
post 직전: ceil(P × 1.25) + 10GiB
```
**위와 아래는 좌변이 다른 양이다** — 위는 컨테이너를 32GiB 로 정할 때 한 번 쓰는 총 용량 식,
아래는 실행할 때마다 다시 재는 가용 공간 식이다. 32GiB 는 목표값이고 매 실행마다 아래 두 식을
다시 계산해 만족할 때만 진행한다.
바깥 NTFS 쪽에도 조건이 하나 더 있다. `local-recovery.env` 의 `OUTER_MIN_REMAINING_PERCENT=20`
— 운영 컨테이너와 header 복구 시험용 전체 사본이 동시에 있어도 **파일시스템의 20% 가 남아야**
한다.(관측) 이 파일은 키 29개짜리 계약이고 위에 든 네 identity 는 그 일부다.
**암호가 프로세스 경계를 넘는 방식**: KeePass 의 protected Password attribute 를 foreground
anonymous pipe 로 `cryptsetup` 에만 넘긴다. argv·환경변수·명령 치환·임시 파일·stdout 어디에도
안 남긴다. LUKS header backup 은 root 전용 tmpfs `/run/hyeonworks-k3s-recovery.*` 안에서만
만들고 KeePass 첨부로 import 한 뒤 평문 파일을 지운다.
`apply-k3s-secret-encryption.sh` 의 정책 계약:
```text
--recovery-policy encrypted-off-host | local-separate-disk-luks (필수, 기본값 없음)
확인 문구 (순서대로):
APPLY 두 정책 공통
RECOVERY 두 정책 공통
ENCRYPTED 두 정책 공통 — 문구만 다르다
off-host : "the mount is encrypted off-host media"
local : "the mounted local recovery volume is LUKS2 encrypted"
LOCAL_RISK_ACCEPTED 로컬 정책에서만
```
**enum 에 기본값이 없어서 정책을 반드시 밝혀야 한다.** 로컬 정책을 고르면 마지막 문구가
「같은 섀시라는 것을 안다」는 서명 역할을 한다.
**그런데 반대 방향은 막혀 있지 않다.** validator 의 off-host 가지는 한 줄이다.
```bash
case "$policy" in
encrypted-off-host) return 0 ;;
local-separate-disk-luks)
… # contract root · LUKS lineage · pinned inode · 용량 gate
```
**`encrypted-off-host` 를 고르면 아무 검사도 하지 않는다.** 로컬 디스크를 `--backup-root` 로
주고 off-host 라고 선언하면 스크립트는 막지 못한다. 장치 lineage·LUKS·contract 검사는 전부
로컬 가지에만 있다. 즉 이 계약이 방지하는 것은 **모르고 로컬을 쓰는 것**이지 **알고 거짓말하는
것**이 아니다.(관측)
### 13.6 완료된 것과 안 된 것
| 항목 | 상태 | 근거 |
|---|---|---|
| 32GiB LUKS2/ext4 매체 생성, close/reopen 검증 | 완료 (2026-08-08) | 기록 |
| `pre` 체크포인트 — 대상 80개 `22,857,763 bytes`, SQLite quick_check | 완료 | 기록 |
| LUKS header erase→restore proof (16,777,216 bytes) | 완료 (2026-08-09) | 기록 |
| Secret 암호화 live 전환 `Enabled/reencrypt_finished` + post bundle | 완료 (2026-08-09) | 기록 |
| 격리 restore drill | **미완료** | 기록 |
| off-host 복제 | **미완료** | 기록 |
| lifecycle 자동화 | **미완료** — KeePass CLI 대화형 입력과 충돌 | 기록 |
| Slack webhook off-host recovery | **미완료**, `RISK_ACCEPTED` 로 진행 | 기록 |
**「관측성 Phase 4 gate 가 열리지 않았다」고 문서가 적는데 관측성은 돌고 있다.** 두
gate(`--expect-reencrypted` 와 restore evidence `--check`) 중 두 번째가 성립하지 않는 상태에서
Slack Secret 을 `SLACK_DEPLOYMENT_GATE=RISK_ACCEPTED` 로 만들고 진행했다. **gate 를 통과한
것이 아니라 위험을 명시적으로 수용하고 넘어간 것이다.** 이 구분이 §17.5다.
---
## 14. 저장소 구조 — 선언보다 자동화가 여섯 배다
### 14.1 줄 수가 말하는 것
(관측 — evidence `platform-repo-loc`)
| 영역 | 파일 | 줄 | 비중 |
|---|---:|---:|---:|
| `scripts/` | 77 | **67,631** | **81.5%** |
| `services/` | 118 | 7,468 | 9.0% |
| `infrastructure/` | 91 | 4,426 | 5.3% |
| `docs/` (저장소 안) | 4 | 2,112 | 2.5% |
| `bootstrap/` (수동 절차) | 7 | 1,349 | 1.6% |
| `components/` | 2 | 17 | 0.0% |
| `clusters/` | 2 | 0 | 0.0% |
| 합계 | 301 | 83,003 | |
| (별도) vendored `.helm/charts` | 713 | 155,560 | git 미추적 |
**선언 11,894줄 대 자동화 67,631줄 — 5.7배다.** 그리고 자동화 안에서도:
| | 파일 | 줄 |
|---|---:|---:|
| `scripts/validate/` | 42 | 45,889 |
| └ 그 중 `test-*` (스크립트 자신의 테스트) | 26 | **33,937** |
| `scripts/bootstrap/` | 27 | 14,132 |
| `scripts/lib/` | 5 | 5,325 |
| `scripts/libexec/` | 3 | 2,285 |
**테스트 33,937줄이 전체의 41%다.** git 이 추적하는 파일 중 가장 큰 것도 manifest 가 아니라
`scripts/validate/test-k3s-local-recovery.sh` (8,668줄)다. 다만 디스크 전체로 보면 그 위에
vendored CRD 가 있다 — `crd-prometheuses.yaml` 13,928줄, `crd-scrapeconfigs.yaml` 12,938줄
…(전부 `.helm/charts` 라 git 미추적).(관측)
**그리고 이 6.8만 줄의 4분의 3은 §14.2 가 예로 드는 bootstrap 트랜잭션이 아니다.**
| 계열 | 파일 | 줄 | `scripts/` 대비 |
|---|---:|---:|---:|
| `*observability*` | 21 | 20,850 | 30.8% |
| `*k3s-local-recovery*` | 15 | 17,722 | 26.2% |
| `*slack-webhook-recovery*` | 7 | 8,069 | 11.9% |
| `*k3s-secret-encryption*` | — | 6,238 | 9.2% |
| **넷 합계** | | **52,879** | **78.2%** |
**이 문서는 그 셋의 이름을 거의 부르지 않는다.** 개별로 큰 것만 봐도
`configure-keycloak-grafana-oidc.sh` 1,928 · `create-observability-secrets.sh` 1,826 ·
`observability-smoke.sh` 1,808 · `apply-observability-access.sh` 1,419 ·
`libexec/slack-webhook-recovery-dirfd.py` 1,095 가 본문에 없다. 아래 §14.2 가 대표로 드는
`apply-gitea-oidc.sh` 673줄은 모집단의 **1%** 이고, 「왜 이렇게 커졌나」의 실제 답은
**관측성 Phase 4 하나와 암호화 복구 하나**다.(관측)
### 14.2 왜 이렇게 됐나
`apply-*.sh` 하나가 하는 일을 보면 이해된다. `apply-gitea-oidc.sh`(673줄)의 순서:
```text
[1/8] 현재 context · 대상 node Ready 와 InternalIP 192.168.0.107 대조 · Gitea health
[2/8] Host Nginx 로컬 SNI 경로로 공개 Keycloak discovery 의 exact issuer 확인
[3/8] gitea-keycloak-oidc Secret 의 type 과 key 이름만 확인 (payload 안 읽음)
[4/8] 고정 chart package SHA-256 재검증 · 렌더 · handoff SHA-256 을 메모리에 저장
[5/8] 운영자 확인: Type APPLY GITEA-OIDC
— context 뿐 아니라 렌더 결과의 SHA-256 64자를 그대로 쳐야 한다
[6/8] 승인 직후 context · API server · node 재검사, handoff SHA-256 재비교
[7/8] gitea-oidc.yaml 하나만 적용하고 rollout 대기
[8/8] 사후 검증 — 출처가 넷이다
OAuth source : gitea admin auth list (파드 exec)
가입 정책·scope : /data/gitea/conf/app.ini (파드 exec)
OIDC redirect : HTTPS 요청의 302 Location 파싱
브랜딩 hash : 공개 URL 다운로드 → 저장소 원본과 sha256 대조
성공·실패·INT·TERM 어느 경로로 끝나도 handoff 디렉터리 제거
```
**「적용」이 아니라 「트랜잭션」이다.** 사전 조건, 사람 확인, 확인 직후 재검사, 바이트 단위
handoff 대조, 사후 검증, 모든 종료 경로의 cleanup 이 한 스크립트에 들어 있다. 확인 문구에
manifest 의 SHA-256 을 넣은 것이 이 구조의 핵심이다 — **운영자가 무엇을 적용하는지 손으로
옮겨 적지 않으면 통과할 수 없다.**
그래서 이런 성질이 생긴다.
- **fail-closed 가 기본이다.** 조건이 불명확하면 진행하지 않는다. `--execute` 없이는
아무것도 바꾸지 않고, 확인 문구는 정확히 일치해야 한다.
- **create-only 와 lifecycle 이 갈려 있다.** `apply-phase1-gitea.sh` 는 `gitea/gitea`
Deployment 나 `gitea-keycloak-oidc` Secret 이 이미 있으면 **시작 전에 거부한다.**
재적용용 스크립트가 아니다.
- **rollback 이 삭제가 아니다.** Traefik 실패 rollback 은 HCC 삭제가 아니라 NodePort-only
baseline 적용이다. 자동 rollback 은 CRD·Retain PV/PVC·버킷·Secret payload 를 지우지 않는다.
- **실패 기록이 재시도 입력이 아니다.** 실패한 rollback ID·ledger·handoff 는 보존하되
같은 ID 로 재시도하지 못하게 한다.
### 14.3 이 접근의 값
**얻은 것**: 사람이 손으로 하면 반드시 빠뜨릴 단계를 코드가 붙든다. 「계획이 맞아도 손으로
옮기다 깨진다」를 막는 구조다.
**치른 값**: 스크립트를 테스트해야 하고, 그 테스트가 33,937줄이 됐다. 그리고 **스크립트의
predicate 가 틀리면 정상 상태를 실패로 판정한다** — 실제로 그런 일이 네 번 있었다(§17.4).
**아직 없는 것**: 이 스크립트들을 자동으로 돌리는 CI 가 없다. `.github/` 도 `.gitea/` 도
없다(관측). 사람이 부를 때만 돈다.
### 14.4 GitOps 는 아직 자리만 있다
```text
clusters/home/applications/.gitkeep ← 비어 있음
clusters/home/projects/.gitkeep ← 비어 있음
components/policies/.gitkeep ← 비어 있음
components/mesh-ready/README.md ← 17줄, "설치하지 않는다"
bootstrap/argocd/README.md ← 인계 기준만
```
Argo CD 도 Istio 도 배포되지 않았고, **디렉터리와 README 만 예약돼 있다.** ADR-0002 가 Argo CD
인계 순서를, ADR-0007 이 Istio 보류 조건을 각각 정해 뒀다.
Argo CD 인계의 전제는 "Gitea OIDC live 적용과 실제 login/logout, HTTPS clone/push 가 검증되고
플랫폼 저장소가 push 된 뒤"였다. **그 중 「플랫폼 저장소 push」는 이미 끝났다.**
```text
origin https://git.learn.hyeonworks.com/donghyeon.kang/platform-core (fetch/push)
main 16c337b [origin/main] Add platform infrastructure configuration
git ls-remote origin → refs/heads/main 16c337bcc91b27ac0f074154b8337e4c8dc17ebb
```
(관측 — evidence `git-remote-and-gitea-repos`. 로컬 HEAD 와 원격 `main` 이 같은 커밋이다)
**그리고 Gitea 는 이미 일상적으로 쓰이고 있다.** 익명 API 로 본 저장소가 20개 이상이고 가장
최근 갱신이 이 문서의 기준일인 2026-09-20 이다(`clean-architecture-frontend-template`
`2026-09-20T04:47:36Z`, `memento-frontend` `2026-09-20T04:54:16Z`). 중앙 문서가 미완으로
남긴 "HTTPS clone/push 수용 시험"은 **형식적으로 기록되지 않았을 뿐 실제로는 매일 일어나고
있다.**(관측 + 추론)
즉 Argo CD 가 없는 이유는 전제 미충족이 아니라 **아직 안 한 것이다.** 이 구분은 §18.2 에서
다시 적는다.
---
## 15. 의사결정 원장
ADR 10건. 각각의 **제약 → 선택 → 감수한 값**만 줄인다.
| ADR | 제약 | 선택 | 감수한 값 |
|---|---|---|---|
| 0001 HDD 분할 | 2TB HDD 에 지울 수 없는 개인 자료 약 24.5GB, AIStor 는 XFS 필요, SSH 만 가능 | SSD 에 검증된 안전본 → 파티션 재생성 → 복원 후 SHA-256 재검증 | 개인 자료와 AIStor 가 같은 디스크 장애 공유, 회전식 I/O 가 상한 |
| 0002 수동 bootstrap → Argo CD | Gitea 를 Argo CD 로 깔려면 Argo CD 가, Argo CD 의 Git 원본을 만들려면 Gitea 가 먼저 필요 | 수동으로 Gitea 까지 만들고, push 뒤 App-of-Apps 로 인계 | 인계 전까지 drift 가능, Gitea 와 GitOps 제어면이 같은 서버 |
| 0003 Nginx edge TLS | 외부는 80/443 만, Host Nginx 가 이미 인증서를 가짐 | Nginx 에서 TLS 종료 → loopback `30080` 하나로 전달, Traefik 이 라우팅 소유 | 내부 구간 평문, Nginx 단일 실패점, NodePort 차단이 풀리면 우회 가능 |
| 0004 공용 PostgreSQL | 6코어·32GB 에서 인스턴스 둘은 비쌈, 하나로 합치면 격리 상실 | 인스턴스 1 + DB·Role·Secret·HBA 로 논리 분리 | 물리 장애·자원 경합 공유, HA 없음 |
| 0005 Keycloak direct OIDC | 공통 인증 프록시는 모든 요청에 의존성 추가 | 각 앱이 OIDC client 로 직접 연결, ForwardAuth 없음 | 앱마다 OIDC 를 제대로 구현해야, Keycloak 장애 시 신규 로그인 실패 |
| 0006 AIStor Free | 구 MinIO Operator 유지보수 불명확, S3 가 반드시 필요 | AIStor Free `servers:1 volumesPerServer:1`, license 는 Secret 으로 | 복제·erasure coding 없음, HDD 장애 시 전 버킷 동시 손실 |
| 0007 Istio 보류 | 단일 노드에서 mesh 가 주는 가용성이 없음 | 설치하지 않고 `components/mesh-ready` 자리만 예약 | 자동 mTLS·workload identity 없음, L7 telemetry 는 앱 계측 의존 |
| 0008 비공개 관리 UI + split DNS | 관리 화면 권한이 큼, 공개 DNS 에 이름을 두고 싶지 않음 | 공개 A/AAAA 없음 + dnsmasq 두 벌 + CoreDNS + source allowlist + exact-SAN 인증서 | 공유기·Tailscale DNS 를 따로 관리, DNS-01 토큰과 갱신 hook 필요 |
| 0009 공용 관측성 | 앱이 아직 없는데 관측 계층이 필요 | 플랫폼이 수집·저장·조회·알림을 소유, 앱은 ServiceMonitor·SLO 만 | 약 2.1 CPU·4.5Gi request 와 35Gi SSD 추가, HA 없음, hostname 단위 egress 제한 불가 |
| 0010 로컬 암호화 복구 | off-host 매체가 없는데 Secret 암호화 전환에 복구본이 필요 | `/dev/sda3` NTFS 안 32GiB LUKS2 컨테이너, K3s 제어면 bundle 만 | 같은 섀시 — 화재·도난·전원 사고 미보호, `/dev/sda` 고장 시 vault 와 함께 손실 |
**열 건을 관통하는 것이 하나 있다: 단일 노드라는 사실을 숨기지 않는다.** ADR 마다 "HA 를
제공하지 않는다", "재해 복구본이 아니다", "독립 백업이 아니다" 를 반복해서 적는다. 이것은
문체가 아니라 **나중에 이 문서를 읽고 잘못 믿는 것을 막는 장치다.**
---
## 16. 2026-09-20 라이브 확인
명령 20벌을 돌렸다. 원문과 메타데이터는 `final/evidence/` 에 있다. 19벌은 `desktop` 에서,
한 벌(`tailscale-peer-vantage`)은 **다른 호스트에서** 돌렸다.
| 확인한 것 | 결과 | evidence |
|---|---|---|
| 노드·파드 | 노드 1 Ready, 파드 26개 전부 Running/Completed | `cluster-node-and-pods` |
| 외부 노출 | Ingress 5건, NodePort 1건(traefik), LoadBalancer 0건 | `cluster-services-and-ingress` |
| NetworkPolicy | 58건, default-deny 6건(namespace 전체는 4건) | `cluster-networkpolicy-and-storage` |
| PV/PVC | 10/10 Bound, 전부 Retain·RWO·노드 affinity | 같음 |
| Prometheus | active target 30 / healthy 30, alert rule 155, recording rule 86, firing 0, unhealthy 0 | `prometheus-targets-and-rules` |
| Alertmanager | receiver 정확히 2(qualified), active alert 0, silence 0 | `alertmanager-receivers-and-alerts` |
| AIStor | `Initialized`/`green`, drive 1/1, usage 20,085,288,960 bytes | `aistor-objectstore-and-bucket-usage` |
| 버킷 quota | `loki` 0.403%, `tempo` 0% | 같음 |
| Secret 계약 | 문서가 선언한 16개 전부 존재 (payload 미확인) | `secret-inventory-names-only` |
| Host Nginx | 5 hostname, 관리 3곳에 source allowlist, `ssl_reject_handshake` | `host-nginx-active-config` |
| 사설 DNS | dnsmasq 2 인스턴스 active, 5 이름 × 2 주소 | `host-private-dns-config` |
| 인증서 | 5 hostname 을 3장이 덮음, 최단 만료 2026-10-21 | `edge-tls-certificates` |
| 엣지 경계 | public 200, private 200(LAN), NodePort LAN 거부·loopback 404 | `edge-boundary-probe` |
| k3s drop-in | `nodeport-addresses=127.0.0.0/8`, `secrets-encryption: true` | `k3s-config-dropins-and-storage` |
| 노드 자원 | request CPU 40% / mem 32%, limit CPU 176% / mem **89%** | `node-resource-allocation` |
| 이미지 | 전부 고정 tag 또는 digest | `running-container-images` |
| Git 원격 | `platform-core` `main` = 로컬 HEAD, Gitea 저장소 20+ 전부 public, CI 없음 | `git-remote-and-gitea-repos` |
| 백업 | CronJob 0 · ScheduledBackup/Backup 0 · `Cluster` 에 backup 섹션 없음 | `backup-absence` |
| 다른 호스트에서 | 5 이름 → Tailscale 주소, 관리 UI 200/302, NodePort 2개 거부 | `tailscale-peer-vantage` |
| 디스크 귀속 | 관측성 실사용 약 4.66 GiB · Local PV 아홉 개 합계 약 5.4 GiB · 루트 138G 중 `/home` 61G | `disk-usage-attribution` |
### 16.1 눈에 띄는 숫자 셋
**(1) 메모리 limit 합계가 allocatable 의 89%다.** allocatable 이 `32,776,484Ki`(약
32,008Mi)인데 limit 합계가 `28,652Mi` 다. request 는 `10,450Mi`(32%)로 여유가 있다.
**단일 노드에서 모든 워크로드가 동시에 limit 까지 쓰면 OOM 영역이다.** 실제 사용은
`9,272Mi`(28%)로 멀고, 실제로 그렇게 되면 `PlatformPodOOMKilled` 경보가 잡는다.
CPU limit 합계 176% 는 throttle 로 끝나므로 성격이 다르다.
**(2) root filesystem 이 경보 식 기준 64.8%다.** `node_filesystem_avail_bytes` /
`node_filesystem_size_bytes` 로 계산하면 `1 - 85,786,652,672 / 243,885,932,544 = 64.83%`
다(`df` 의 63% 와 조금 다른 것은 예약 블록 처리 차이다). **첫 경보 임계 75% 까지 약
24.8GB 남았다.** Prometheus TSDB 가 지금 4.6GB 이고 `retentionSize: 16GB` 까지 자랄 수
있으므로 **그것만으로 +11GB 가 잠재해 있다.** Loki·Tempo·Alloy WAL 에는 byte 상한이 없다.
같은 날 조금 뒤의 두 번째 측정에서는 `df` 가 138G / 64% 였다 — **한 시간 안에 2G 가
늘었다.** 무엇이 늘었는지는 §7.4 의 귀속표를 보면 플랫폼 쪽이 아니다. 그리고 그 표가
보여 주듯 **첫 경보를 먼저 당길 후보는 관측성 증가가 아니라 `/home/donghyeon` 의 24G
이전 안전본이다.**
**(3) `tempo` 버킷 0 bytes.** 고장이 아니라 trace 를 보내는 애플리케이션이 없어서다.
---
## 17. 문서와 라이브가 어긋난 곳
열 곳을 찾았다. **고쳐야 할 것과, 사실이므로 그대로 둘 것을 구분한다.**
### 17.1 상위 문서가 관측성을 「미적용」이라고 말한다 — 문서가 뒤처졌다
`docs/platform/README.md`(2026-08-09)와 `architecture/platform-overview.md`(2026-08-08),
`architecture/repository-layout.md`(2026-07-31), `architecture/namespace-and-resource-policy.md`
(2026-07-31)가 모두 관측성을 "설계 승인, 구현 전" 으로 적는다. 라이브에서는 40일째 돌고
있고 `observability/` 9편(2026-08-15)이 as-built 를 설명한다.
**같은 저장소 안에서 최신 문서가 상위 문서를 반박하는 상태다.** `observability/` 쪽을 믿어야
한다. 고칠 곳: 위 네 문서의 상태 줄과 Phase 4 관련 문장.
### 17.2 Traefik 루트 build root 와 라이브가 다르다 — 그런데 그것이 설계다
§4.5 에서 본 것. 루트 `kustomization.yaml` 은 `overlays/observe` 를, 라이브는 `trust` 를 쓴다.
**처음에 이것을 drift 로 적었는데 틀렸다.** 저장소가 이유까지 적어 두었다 —
`traefik/README.md` 가 「루트 `kustomization.yaml`은 의도적으로 안전한 `observe` overlay를
가리킨다 … 상태 전환은 아래 guarded script와 정확한 overlay를 사용한다」.
**고칠 코드는 없다.** 남는 것은 관측 가능성 하나다 — 라이브가 세 overlay 중 어느 상태인지
저장소만 보고는 알 수 없고 `HelmChartConfig` 를 읽어야 한다. 저장소는 그것을 기록하지 않는다.
### 17.3 관측성 chart 가 저장소에 풀려 있고 git 이 추적하지 않는다
`services/observability/{alloy,blackbox-exporter,grafana}/.helm/charts/…` 아래 713파일
155,560줄이 작업 트리에 있는데 `.gitignore` 의 `.helm/` 때문에 커밋에 없다.
**「재현 가능한 선언만 버전 관리한다」는 저장소 규칙 자체는 맞다.** Phase 1·2 는 렌더할 때
내려받고 SHA-256 을 대조하므로 문제가 없다. 그런데 관측성 쪽은 **이 디렉터리가 이미 있다는
전제로 `chartHome: .helm/charts` 를 가리킨다.** 다른 기계에서 clone 하면 렌더가 안 된다.
고칠 곳: 관측성 chart 도 Phase 1·2 처럼 pinned package SHA-256 을 저장소에 적고 렌더 시
내려받게 하거나, 최소한 「이 디렉터리를 어떻게 다시 만드는가」를 README 에 적는다.
### 17.4 스크립트 predicate 가 정상을 실패로 판정한 사건 넷 — 기록이므로 그대로 둔다
중앙 문서 `observability/07-build-history-and-decisions.md` 에 보존된 것.
| 사건 | 무엇을 잘못 봤나 | 결과 |
|---|---|---|
| Task 6 첫 apply | `AlertmanagerConfig` 의 런타임 receiver 이름이 `platform-slack` 일 거라고 봤는데 Operator 가 `observability/platform-alertmanager/platform-slack` 으로 만든다 | reconcile RC 1, rollback PASS, acceptance 없음 |
| Task 6 parse-only | `--verified-output-dir` 가 줄바꿈으로 쪼개져 usage RC 2, shell RC 127 | mutation 0, Blackbox proof 만 남음 |
| 구조화 Slack 첫 apply | Alertmanager v0.33.1 API 가 `name` 과 같은 값의 `labels.name` 을 함께 주는데 postcheck 가 key 를 하나로 제한 | reconcile RC 1, rollback PASS |
| OIDC wrapper | 대화형 확인을 기다리는 동안 short-lived admin token 이 만료 | prestate 재검사 HTTP 401, mutation 전 실패 |
**네 건 모두 「대상이 틀린 게 아니라 검사기가 틀렸다」.** 그리고 네 건 모두 **검사를 느슨하게
푸는 대신 predicate 를 정확하게 고쳤다** — 예를 들어 receiver 는 raw 이름이 아니라 exact
qualified singleton 만 통과시키도록 좁혔다.
**이 기록을 고쳐 쓰지 않는다.** rollback PASS 가 acceptance 가 아니고, 나중에 성공했다고
해서 그때 wrapper 가 성공한 것이 되지 않는다. 사후에 성공 서사로 바꾸면 다음에 같은 실패를
알아보지 못한다.
### 17.5 Phase 4 gate 가 안 열렸는데 Phase 4 가 돌고 있다 — 사실이고, 수용된 위험이다
`security-and-secrets.md` 는 Phase 4 Secret 생성 전에 두 gate 를 독립 호출하라고 적는다.
```text
k3s-secret-encryption.sh --expect-reencrypted → 통과 (2026-08-09)
k3s-secret-encryption-restore-evidence.sh --check → 격리 restore drill 이 없어 불가
```
두 번째가 성립하지 않는 상태에서 Slack Secret 을 `SLACK_DEPLOYMENT_GATE=RISK_ACCEPTED` 로
만들고 관측성을 적용했다. strict recovery checker 는 **expected RC `1`** 로 실패하는 것이
정상 경로였다.
**이것은 gate 를 우회한 것이 아니라 위험을 명시적으로 기록하고 진행한 것이다.** 문서가
"active risk acceptance 는 operational delivery 를 대체하지 않는 gap 이다" 라고 적는다.
고칠 것은 문서가 아니라 격리 restore drill 을 실제로 도는 일이다.
### 17.6 선언에 없는 것이 호스트에 돌고 있다
`docker.service`, `snap.multipass.multipassd.service`, `cups`·`cups-browsed`,
`avahi-daemon` 이 running 이다. `docker0 172.17.0.1/16`, `br-8359faae6017 172.18.0.1/16`,
`mpqemubr0 10.135.97.1/24`(down) 인터페이스가 있다.(관측)
**플랫폼 선언은 이것들을 모른다.** 개발 편의로 남아 있는 것으로 보이지만(추론), Docker 는
iptables 규칙을 만들고 기본 정책을 바꾸는 소프트웨어다. **NodePort loopback 제한과 같은
호스트 방화벽 가정이 Docker 의 iptables 조작과 어떻게 상호작용하는지는 확인하지 않았다**
(미확인). §18.3 에 적는다.
### 17.7 중앙 문서 네 곳이 라이브와 다르다
§17.1 이 관측성 「미적용」 넷을 세었는데, 그 밖에도 넷이 더 있다.(관측)
| 문서 | 적힌 것 | 라이브·저장소 |
|---|---|---|
| `host-nginx/README.md:5-7` | 활성 설정은 `learn-services-keycloak.conf`, SHA-256 `5c5cd74b…` | 실제 활성 파일은 `learn-services-observability.conf` 와 바이트 동일 |
| `minio-aistor/README.md` | admin-oidc profile 은 「선언형 구현·dry-run 완료, live 적용 대기」 | Console Ingress·OIDC env 가 적용돼 있다 |
| `gitea-service.md:82` | base 의 NetworkPolicy 「다섯」 | 파일에는 여섯, 라이브 Gitea 파드에는 일곱(§12.2) |
| `observability/09-…md:14,24` | receiver 「정확히 하나」, groupBy 세 항목 | 둘이고 네 항목이다 — 저장소 선언과 라이브가 §11.5 쪽이다 |
앞의 셋은 문서가 뒤처진 것이고, 마지막은 **가장 최신인 관측성 문서가 자기 저장소 선언과
어긋나 있는** 경우다.
### 17.8 저장소 안에 죽은 사본이 있다
`services/minio-aistor/values/home.yaml` 은 `base/deployment/values/home.yaml` 과 바이트
동일한데 **어느 kustomization 도 참조하지 않는다** — `helmCharts` 는 `base/deployment` 에만
있다. 그리고 중앙 문서 `minio-aistor-service.md:36` 이 하필 그 미참조 사본을 설정 위치로
가리킨다. 중앙 문서 쪽에는 `architecture/platform-overview.md.orig` 도 남아 있다.(관측)
### 17.9 CNPG Cluster 의 `resizeInUseVolumes` 와 StorageClass 가 반대를 말한다
라이브 `Cluster` 의 storage 에 `resizeInUseVolumes: true`(CNPG 기본값)가 있는데, 그것이 쓰는
`ssd-local-postgres-retain` 은 `allowVolumeExpansion: false` 다(§7.1 — 열 개 전부 그렇다).
지금은 확장을 시도하지 않아 증상이 없다.(관측)
### 17.10 인프라 저장소가 공개 인터넷에서 익명으로 읽힌다
`git.learn.hyeonworks.com` 은 공개 A 레코드가 있고 Host Nginx 에 source allowlist 가 없다
(§2.2). 그리고 Gitea 의 저장소가 **전부 `public`** 이다.(관측 — evidence
`git-remote-and-gitea-repos`. 익명 API `repos/search` 가 **22건**을 반환하고 전부 `public`)
```text
donghyeon.kang/platform-core/raw/branch/main/README.md → 200 (익명)
```
**자격 증명은 없다.** `.gitignore` 와 `scan-platform-sensitive-source.sh` 가 소스 YAML 의
`kind: Secret` 을 거부하고, `local-recovery.env`(하드웨어 식별자)와 `.helm/` 은 추적되지
않는다. 실제로 추적 파일이 302개이고 그 안에 `.helm/` 은 0개다.(관측)
**그런데 내부 구조 전체가 공개다.** 공개된 것: 노드 LAN 주소 `192.168.0.107`, Tailscale
주소 `100.92.240.34`, 다섯 hostname 과 각각의 backend·포트, Host Nginx 의 source allowlist
CIDR, NetworkPolicy 58건의 정확한 selector 와 포트, 디스크 마운트 경로와 host path, 경보
임계값, Keycloak realm·client·group 이름, Secret 의 이름과 key 이름.
**이게 문제인지 아닌지는 이 문서가 정할 일이 아니다.** 다만 두 가지는 사실로 적어 둔다.
1. **저장소를 public 으로 둔 것이 의도인지 기본값인지 문서 어디에도 없다.** ADR 에도
`security-and-secrets.md` 에도 저장소 공개 수준을 정한 문장이 없다. 「Secret 을 Git 에
두지 않는다」는 있지만 「Git 자체를 누가 읽을 수 있는가」는 없다.
2. **경보의 `runbook_url` 이 공개 저장소를 가리킨다.** 22개 플랫폼 alert 가 전부
`https://git.learn.hyeonworks.com/donghyeon.kang/project-infra/src/branch/main/docs/runbooks/2026-07-31-observability-access-cutover.md`
를 가리키고 익명으로 200 이다(관측). 링크가 살아 있는 것은 좋지만, **대응 절차가 공개돼
있다는 뜻이기도 하다.**
고칠 곳이 있다면 코드가 아니라 결정이다 — 저장소 공개 수준을 ADR 로 한 번 정하는 것.
---
## 18. 열린 질문
### 18.1 NetworkPolicy 58개가 실제로 집행되는가
**왜 열려 있나.** k3s 의 netpol controller 는 켜져 있다(§12.5 — 기동 로그로 확인). 남은 것은
그것이 만든 규칙이 의도대로 걸렸는가다. 중앙 문서가 "k3s CNI에서 정책이 실제 강제되는지는
양방향 allow/deny Pod 시험으로 별도 확인한다" 고 적고 그 시험 기록이 없다. 이 문서도
하지 않았고 `iptables -S` 는 root 가 필요해 못 읽었다.
**답하는 방법.** 일회용 파드 둘로 양방향을 친다. (a) `default` namespace 의 파드에서
`platform-postgres-rw:5432` 로 TCP 연결 — 차단돼야 한다. (b) `observability` 에 label 만 붙인
파드에서 `minio:9000` 으로 연결 — `object-storage-allow-observability-s3` 가 이름까지 보므로
차단돼야 한다. (c) `gitea` namespace 에 Gitea label 없는 파드를 띄우고 밖으로 나가기 —
`gitea-default-deny` 가 podSelector 로 좁혀져 있으므로 **통과할 것으로 예상**되고, 그것이
확인되면 §12.1 의 지적이 사실이 된다.
**왜 중요한가.** §12 전체와 §9·§10 의 경계 주장이 여기에 얹혀 있다. 컨트롤러가 도는 것은
확인했으니 「선언뿐」은 아니지만 **어느 규칙이 실제로 걸렸는지는 아직 모른다.**
### 18.2 Argo CD 인계를 막는 것이 무엇인가
**전제는 이미 충족됐다.** §14.4 에서 본 대로 `platform` 저장소는
`git.learn.hyeonworks.com/donghyeon.kang/platform-core` 의 `main` 에 같은 커밋으로 올라가
있고, Gitea 에는 저장소 20개 이상이 오늘까지 갱신되고 있다. 중앙 문서가 미완으로 남긴
"HTTPS clone/push 수용 시험"은 **기록되지 않았을 뿐 실제로는 돌고 있다.**
**그래서 질문이 바뀐다.** "push 할 수 있는가"가 아니라 **"인계를 시작하면 무엇이 깨지는가"**다.
ADR-0002 가 미리 적어 둔 위험 네 가지를 아직 아무도 해소하지 않았다.
- 수동으로 만든 리소스와 Git 선언의 **immutable field 가 다르면 인계 때 재생성된다.**
특히 `Retain` Local PV/PVC 와 CNPG `Cluster` 가 그렇다.
- **라이브에만 있고 저장소 기본 build root 에는 없는 것이 최소 하나 확인됐다**(§17.2 의
Traefik `trustedIPs`). 인계 전에 이런 diff 를 전부 찾아야 한다.
- **관측성 chart 가 저장소에서 재현되지 않는다**(§17.3). Argo CD 가 `.helm/charts` 를 못
만들면 그 Application 은 렌더에 실패한다.
- 수동으로 만든 Secret 16개를 Argo CD 관리로 가져오려면 Secret 관리 제품을 먼저 정해야
한다(§13.2). ADR 이 아직 없다.
**답하는 방법.** `kubectl diff -k ` 를 build root 마다 돌려 라이브와 선언의 차이를
전부 목록으로 만든다. `prune` 없이, `automated sync` 없이. 차이가 0 이 되기 전에는 인계하지
않는다.
### 18.3 외부망에서 고포트 `30080/30443` 이 정말 닫혔는가
**왜 열려 있나.** LAN 에서의 거부는 확인됐다(관측: `000`). **공개 IP 에서의 확인은 이 호스트
안에서 할 수 없다.** 중앙 문서도 이것을 반복해서 미완으로 남긴다. 게다가 §17.6 의 Docker 가
iptables 를 만지는 변수다.
**답하는 방법.** LAN 밖의 다른 네트워크(모바일 테더링, Tailscale 이 아닌 외부 호스트)에서
공개 IP 의 두 포트로 접속해 reject 또는 timeout 인지 본다. **`404` 가 오면 실패다.**
### 18.4 네 identity 의 OIDC 동작
**왜 열려 있나.** Grafana 는 `donghyeon.kang` 한 사람의 로그인만 확인됐다(기록). admin /
viewer / group 없음 / membership 제거 네 경우를 다 돌리지 않았다. Gitea·AIStor·pgAdmin 은
실제 사용자 로그인 확인 자체가 없다.
**무엇을 확인해야 하나.** `role_attribute_strict: true` 가 group 없는 사용자를 정말 막는지,
pgAdmin 의 `OAUTH2_ADDITIONAL_CLAIMS` 가 정말 게이트로 동작하는지, AIStor 의 `policy` claim
이 `consoleAdmin` 을 제대로 나르는지.
### 18.5 인증서 갱신이 자동으로 도는가
**왜 열려 있나.** `storage-admin`/`db-admin` 인증서가 2026-10-21 만료로 31일 남았다(관측).
중앙 문서는 Cloudflare DNS-01 과 certbot deploy hook(「`nginx -t` 가 성공한 경우에만
reload」)을 적지만 **갱신이 실제로 성공한 적이 있는지는 기록이 없다.** `git`+`id` 인증서는
2026-09-16 발급이므로 최근에 갱신된 것으로 보이고(추론), `grafana` 는 2026-08-10, 나머지
둘은 2026-07-23 발급이다.
**답하는 방법.** `certbot renew --dry-run` 을 세 lineage 에 돌리고 deploy hook 이 붙어 있는지
확인한다. 그리고 `PlatformCertificateExpiry` 경보가 실제로 Slack 까지 오는지 본다 — **하루
뒤면 자연히 warning 조건에 들어간다.**
### 18.6 Loki 의 WAL 이 혼자 불어나면 무엇이 잡는가
**왜 열려 있나.** `PlatformLokiWALDiskUsageHigh` 는 이름과 달리 Loki 를 보지 않고 WAL 이
놓인 파일시스템의 사용률을 본다(§11.4). 관측값 `0.6057` 은 Loki 가 쓴 9.9 MiB 가 아니라
루트 파일시스템의 사용률이다. 그래서 **루트가 한가한데 Loki WAL 만 5Gi 를 다 채우는
상황에는 아무 경보도 없다.** Local PV 의 `capacity` 는 quota 가 아니고(§7.2),
`kubelet_volume_stats_*` 도 파일시스템 값을 되풀이한다(§7.5).
**잴 수단이 없는 것은 아니다.** Loki 는 자기 WAL 바이트를 이미 노출한다 —
`prometheus_tsdb_wal_storage_size_bytes{job="observability/loki"}`. §7.4 가 「9.9 MiB」로 쓴
`10,342,630` 이 바로 이 값이다.(관측) 그러니 정확히는 **「그 metric 으로 된 경보가 없다」**다.
이름만 보면 맞을 것 같은 `loki_ingester_wal_bytes_in_use` 는 `0` 을 내므로 쓸 수 없다.
**무엇이 걸려 있나.** Loki 의 `disk_full_threshold: 0.90` 과 `replay_memory_ceiling: 512MB`
는 Loki 가 스스로 쓰기를 멈추는 값이지 사람에게 알리는 값이 아니다. Alloy 쪽
`PlatformAlloyLogEntriesDropped` 는 **결과**를 잡지만 원인이 WAL 포화인지는 가르지 않는다.
§7.5 의 `KubePersistentVolumeFillingUp` 넷은 루트 여유율을 읽으므로 여기서도 도움이 안 된다.
**답하는 방법.** 셋이다. (a) 가장 싼 것 — `prometheus_tsdb_wal_storage_size_bytes` 에 절대
바이트 임계로 경보 하나를 건다. (b) Loki·Tempo·Alloy 의 로컬 PV 를 크기가 강제되는
볼륨(전용 파티션·LVM·loop 파일)으로 옮기면 `kubelet_volume_stats_*` 가 제 값을 내고 §7.5 의
생성 경보 넷도 살아난다. (c) 어느 쪽도 안 하면 최소한 이 경보의 이름이 뜻하는 바를 적는다.
### 18.7 백업이 하나도 돌고 있지 않다
**관측한 것.**(evidence `backup-absence`)
```text
kubectl get cronjob -A → No resources found
kubectl get scheduledbackup,backup -A → No resources found
kubectl get job -A → helm-install-traefik 둘뿐 (40d·63d, Complete)
cluster.yaml 의 backup / barmanObjectStore / plugin → 없음
```
버킷도 둘밖에 없다. `minio_cluster_usage_buckets_total_bytes` 가 `loki` 와 `tempo` 만 낸다 —
`platform-postgres-backup`·`gitea-backup`·`learning-postgres-backup` 은 만들어진 흔적이 없다.
(관측 — evidence `aistor-objectstore-and-bucket-usage`)
**설계와의 거리.** `backup-and-recovery.md` 는 PostgreSQL 일 1회 base backup + 연속 WAL,
Gitea 일 1회, 보존 14일을 적는다. **선언도 스케줄도 버킷도 없다.**
**무엇이 걸려 있나.** 지금 `/dev/sdc` 가 죽으면 **Gitea 저장소와 두 DB 의 논리 복구본이
어디에도 없다.** K3s recovery bundle 은 제어면(SQLite·token·host config)만 담고 애플리케이션
데이터는 명시적으로 제외한다(ADR-0010). Gitea 는 `platform-core` 를 포함해 20개 저장소의
유일한 원본이고(§17.7), 그 중 일부는 다른 기계의 clone 이 사본 노릇을 하겠지만 **issue·PR·
사용자·attachment 는 clone 에 안 담긴다.**
**이것이 이 플랫폼에서 가장 큰 단일 공백이다.** 단일 노드·non-HA 는 문서가 반복해서
경고하고 수용한 위험이다. 백업 부재는 다르다 — 문서가 「할 것」으로 적어 둔 뒤 아직 안 했다.
다른 미완들(격리 restore drill, off-host 복제, OIDC matrix)은 **있는 것을 검증하는** 일인데
이것만 **없는 것을 만드는** 일이다.
**답하는 방법.** 순서가 이미 문서에 있다 — AIStor 에 `platform-postgres-backup` 버킷과
전용 최소권한 access key 를 만들고, CNPG `Cluster` 에 backup 설정을 더하고,
`ScheduledBackup` 을 걸고, **별도 임시 namespace 에 복원해 두 DB 의 격리까지 확인**한다.
버킷을 만드는 것과 복원이 되는 것은 다른 일이다.
---
## 19. 이 문서로 말할 수 없는 것
앞의 열여덟 절은 각자의 자리에서 무엇을 못 봤는지 이미 밝혔다. 여기서는 그 조각들이
합쳐졌을 때 **읽는 사람이 넘어서면 안 되는 선 하나**만 다시 못 박는다.
**이 문서의 「경계」는 전부 선언과 관측된 상태이지 시험 결과가 아니다.** 로그인도, push 도,
S3 put/get 도, 백업도, 복구도, NetworkPolicy 의 allow/deny 도 한 번 돌려 보지 않았다.
그래서 세 쌍을 아직 아무도 잇지 못했다 — 「NetworkPolicy 58건이 있다」와 「그 58건이
경계로 동작한다」(§18.1), 「Secret 계약 16개가 다 있다」와 「그 값이 맞다」(§13.2),
「`secrets-encryption: true` 가 켜져 있다」와 「재암호화가 끝났다」(§6.2).
그 선을 만든 것이 넷이다. `sudo` 가 없어 `k3s secrets-encrypt status` 와 `/etc/hyeonworks/`
아래를 못 읽었고(§1.2), 같은 이유로 루트 SSD 의 약 53G — 컨테이너 이미지 저장소로 보이는 —
를 귀속하지 못했으며 Tempo 의 로컬 작업공간도 재지 못했다(§7.4). Keycloak 관리 API 를
부르지 않아 realm 내용은 discovery endpoint 까지만 봤고(§9.3), 중앙 문서의 runbook 20편·plan
27편 약 21,900줄과 vendored chart 155,560줄은 인용을 확인할 때만 열었다(§1.2, §21.2).
**그리고 「관측」이라고 적었는데 증거 파일에 원문이 없는 것이 여덟 가지 있다.** CPU·메모리·
swap, 노드 allocatable, §16.1 의 root filesystem 계산에 쓴 `85,786,652,672`, Host Nginx 파일의
줄 수와 mtime, PV 열 개의 nodeAffinity, k3s drop-in 의 바이트 동일성, 호스트의 systemd 서비스
다섯, 스크립트 네 개의 줄 수. **여덟 다 라이브에서는 참이지만 §1.2 가 정의한 「관측 = 증거
원문이 있다」를 어긴다.** 다시 주장하려면 그 명령을 돌려 증거로 남겨야 한다.
마지막으로 **이것은 2026-09-20 한 번의 스냅숏이다.** 파드의 재시작 횟수가 대부분 24일 전
1~4회로 찍혀 있다 — 이 시스템은 움직인다. 숫자를 인용하기 전에 §16 의 명령을 다시 돌린다.
---
# 제2부 — 근거
## 20. 증거 색인
전부 `final/evidence/raw/.txt` 에 원문이, `final/evidence/meta/.json` 에
command·cwd·executedAt·exitCode·revision·sha256 이 있다. 모두 2026-09-20 에 실행했다.
19벌은 `ssh desktop` 으로 종료 코드 `0`, 한 벌(`tailscale-peer-vantage`)은 별도 호스트에서
종료 코드 `7` 이다 — **마지막 명령인 NodePort `curl` 의 연결 거부가 그 증거의 결론이라
비정상이 아니다.** meta 의 `exitCodeNote` 에 그 사실을 적었다.
| id | 무엇을 증명하나 | 증명하지 않는 것 |
|---|---|---|
| `cluster-node-and-pods` | 노드 사양과 전 namespace 파드 Ready | Ready 가 기능 정상은 아니다 |
| `cluster-services-and-ingress` | Service type 과 Ingress host, 외부 노출이 NodePort 하나 | Host Nginx allowlist 는 안 보인다 |
| `cluster-networkpolicy-and-storage` | NetworkPolicy 58건, PV 10개 Bound | CNI 집행 여부는 모른다 |
| `prometheus-targets-and-rules` | 30/30 healthy, alert 155·recording 86, firing 0 | 155개 조건을 주입 시험한 것이 아니다 |
| `alertmanager-receivers-and-alerts` | receiver 2개 qualified, active·silence 0 | Slack 전달 성공 여부는 모른다 |
| `aistor-objectstore-and-bucket-usage` | `Initialized/green`, drive 1/1, 버킷 사용량·quota율 | S3 기능·복구 가능성은 모른다 |
| `secret-inventory-names-only` | Secret 이름과 type | 값의 정확성·회전 여부는 모른다 |
| `host-nginx-active-config` | 활성 nginx 설정 전문 | 저장소 어느 후보와 같은지는 별도 대조 |
| `host-private-dns-config` | dnsmasq 2 인스턴스와 정적 응답 | 공유기·Tailscale 등록은 호스트 밖 |
| `edge-tls-certificates` | 각 hostname 이 제시하는 인증서 | 갱신 자동화 동작은 모른다 |
| `edge-boundary-probe` | public 200, NodePort LAN 거부·loopback 404 | 외부망에서의 차단은 모른다 |
| `k3s-config-dropins-and-storage` | drop-in 2개, XFS `noquota`, 디스크 사용량 | `secrets-encrypt status` 는 못 읽었다 |
| `node-resource-allocation` | request/limit 합계와 실사용 | 부하 시험이 아니다 |
| `running-container-images` | 실제 이미지 tag·digest | 저장소 고정값과의 대조는 별도 |
| `traefik-live-helmchartconfig` | 라이브에 `trustedIPs: 10.42.0.1/32` 존재 | 저장소 기본 root 가 이를 렌더하는지는 별도 |
| `platform-repo-loc` | 영역별 파일·줄 수 | 줄 수가 품질이 아니다 |
| `git-remote-and-gitea-repos` | 원격 `main` = 로컬 HEAD, Gitea 저장소 20+ 전부 public, CI 디렉터리 없음, `.helm/`·`local-recovery.env` 미추적 | 이 기계에서 push 했다는 직접 증거는 아니다 |
| `backup-absence` | CronJob·ScheduledBackup·Backup 0건, `Cluster` 에 backup 섹션 없음 | 수동 `pg_dump` 같은 다른 방식의 백업 이력은 모른다 |
| `tailscale-peer-vantage` | 다른 호스트에서 Tailscale split DNS 동작, 관리 UI 접근, NodePort 거부 | LAN·Tailscale 밖에서의 동작은 여전히 모른다 |
| `disk-usage-attribution` | 워크로드별 실사용량, 루트 파일시스템 내역, local PV 의 `kubelet_volume_stats_*` 가 파일시스템 전체를 되풀이한다는 것 | `sudo` 가 없어 컨테이너 이미지 저장소 약 53G 를 귀속하지 못했다. Tempo 로컬도 못 쟀다 |
## 21. 원본 색인
### 21.1 분석 대상 저장소
`/home/donghyeon/workspace/platform` @ `16c337bcc91b27ac0f074154b8337e4c8dc17ebb`
(commit 2개: `fa76531` Initial commit, `16c337b` Add platform infrastructure configuration.
원격 없음, working tree clean)
| 경로 | 이 문서에서 근거로 쓴 절 |
|---|---|
| `README.md` | §1.1, §6.3, §14 |
| `infrastructure/networking/traefik/**` | §4.4, §4.5, §17.2 |
| `infrastructure/networking/host-nginx/**` | §4.1~§4.3 |
| `infrastructure/networking/private-dns/**` | §5 |
| `infrastructure/namespaces/**` | §2.3, §11.2 |
| `infrastructure/storage/**` | §7 |
| `infrastructure/security/k3s/**` | §6.2, §13.1, §13.5 |
| `services/platform-postgres{,-keycloak}/**` | §8 |
| `services/keycloak/**` | §9.2 |
| `services/gitea/**` | §10.1, §9.5 |
| `services/minio-aistor/**` | §10.2, §9.3 |
| `services/pgadmin/**` | §10.3 |
| `services/observability/**` | §11 전체 |
| `scripts/**` | §13.3, §14 |
| `.gitignore` | §13.1, §17.3 |
### 21.2 중앙 설계·운영 문서
`/home/donghyeon/workspace/docs/platform` (git 없음, 85파일 28,708줄)
| 묶음 | 편수 | 기준일 | 전량 읽음 |
|---|---:|---|---|
| `architecture/` | 16 (`.md` 15 + `platform-overview.md.orig`) | 2026-07-23 ~ 2026-08-09 | ✅ (`.orig` 제외) |
| `adr/` | 10 | 2026-07-22 ~ 2026-08-01 | ✅ |
| `observability/` | 10 | 2026-08-15 | ✅ (08 제외 9편) |
| `runbooks/` | 20 | 2026-07-22 ~ 2026-08-13 | 참조만 |
| `plans/` | 27 | 2026-07-31 ~ 2026-08-15 | 참조만 |
| `README.md` | 1 | 2026-08-09 | ✅ |
**중앙 문서를 이 저장소로 복사하지 않았다.** 이 SSOT 가 인용한 문장은 본문에 「기록」으로
표시했고, 원문은 위 경로에 있다. 그 경로가 사라지면 이 문서의 「기록」 항목은 재확인할 수
없게 된다 — 그것이 §19(4)의 한계와 같은 종류의 제약이다.