Files

2278 lines
135 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 단일 노드 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 에서도
닿지 않는다.
<!-- techviz:begin id=platform-request-path context-sha256=2831219e5510d6eff44e36eb652d6e63637490c23e193c9134510dad1d6bf226 -->
<!-- techviz:generate id=platform-request-path -->
![왼쪽의 클라이언트에서 출발한 화살표가 호스트 경계 안의 Host Nginx를 지나 k3s 클러스터 경계 안의 Traefik으로 들어가고, Traefik에서 다섯 서비스로 갈라진 뒤 그 가운데 Gitea와 Keycloak만 공용 PostgreSQL로 이어지는 구조도.](assets/diagrams/platform-request-path/platform-request-path.svg)
<details>
<summary>Diagram description</summary>
클라이언트는 공개 인터넷, 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도 없다.
</details>
[Editable source](assets/diagrams/platform-request-path/platform-request-path.drawio) · [Grounded VizSpec](.techviz/platform-request-path/spec.json)
<!-- techviz:end id=platform-request-path -->
### 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 를 한 번 끊고 그 뒤로는 평문이다
<!-- techviz:begin id=edge-trust-chain context-sha256=2831219e5510d6eff44e36eb652d6e63637490c23e193c9134510dad1d6bf226 -->
<!-- techviz:generate id=edge-trust-chain -->
![왼쪽부터 클라이언트, Host Nginx, Traefik, backend 네 참가자의 생명선이 있고, 클라이언트가 임의 헤더를 보내면 Host Nginx 가 상수로 덮어쓰고 loopback 으로 넘긴 뒤 Traefik 이 source 를 확인하고 backend 로 전달하는 순서를 번호가 붙은 화살표로 보여 주는 시퀀스 다이어그램.](assets/diagrams/edge-trust-chain/edge-trust-chain.svg)
<details>
<summary>Diagram description</summary>
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 만 본다.
</details>
[Editable source](assets/diagrams/edge-trust-chain/edge-trust-chain.drawio) · [Grounded VizSpec](.techviz/edge-trust-chain/spec.json)
<!-- techviz:end id=edge-trust-chain -->
### 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/<name>-<version>/` 아래에 **저장소에 풀어 놓았다**(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.(관측)
<!-- techviz:begin id=observability-signal-paths context-sha256=2831219e5510d6eff44e36eb652d6e63637490c23e193c9134510dad1d6bf226 -->
<!-- techviz:generate id=observability-signal-paths -->
![왼쪽의 호스트 커널·파일시스템, /var/log/pods, 애플리케이션 OTLP 세 출처에서 출발한 화살표가 node-exporter 와 Alloy 를 거쳐 Prometheus·Loki·Tempo 로 들어가고, Loki 와 Tempo 의 객체만 AIStor S3 로 내려가며, 세 저장소가 모두 Grafana 로 모이고 Prometheus 만 Alertmanager 를 통해 Slack 으로 나가는 데이터 흐름도.](assets/diagrams/observability-signal-paths/observability-signal-paths.svg)
<details>
<summary>Diagram description</summary>
수집 계층은 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 자신의 지표도 끌어가지만 이 그림에서는 세 신호의 경로를 흐리지 않도록 생략했다.
</details>
[Editable source](assets/diagrams/observability-signal-paths/observability-signal-paths.drawio) · [Grounded VizSpec](.techviz/observability-signal-paths/spec.json)
<!-- techviz:end id=observability-signal-paths -->
### 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 가 `<namespace>/<config>/<receiver>` 로 이름을 다시 짓는다.** 소스에
적은 `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/*<pod_uid>/<container>/*.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.
<!-- techviz:begin id=dashboard-authority-loop context-sha256=2831219e5510d6eff44e36eb652d6e63637490c23e193c9134510dad1d6bf226 -->
<!-- techviz:generate id=dashboard-authority-loop -->
![Git JSON 이 desired state 로, 사이드카가 controller 로, Grafana 가 actual state 로 놓이고 파일 provider 가 30초마다 되돌리는 고리를 이루는 구조도. UI 편집은 이 고리 바깥에서 actual state 에만 닿는다.](assets/diagrams/dashboard-authority-loop/dashboard-authority-loop.svg)
<details>
<summary>Diagram description</summary>
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 로 스스로 상태를 되돌릴 수도 없다.
</details>
[Editable source](assets/diagrams/dashboard-authority-loop/dashboard-authority-loop.drawio) · [Grounded VizSpec](.techviz/dashboard-authority-loop/spec.json)
<!-- techviz:end id=dashboard-authority-loop -->
---
## 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 <context> 두 정책 공통
RECOVERY <context> 두 정책 공통
ENCRYPTED <context> 두 정책 공통 — 문구만 다르다
off-host : "the mount is encrypted off-host media"
local : "the mounted local recovery volume is LUKS2 encrypted"
LOCAL_RISK_ACCEPTED <context> 로컬 정책에서만
```
**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 <context> GITEA-OIDC <manifest-sha256>
— 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>` 를 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/<id>.txt` 에 원문이, `final/evidence/meta/<id>.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)의 한계와 같은 종류의 제약이다.