# 단일 노드 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 에서도 닿지 않는다. ![왼쪽의 클라이언트에서 출발한 화살표가 호스트 경계 안의 Host Nginx를 지나 k3s 클러스터 경계 안의 Traefik으로 들어가고, Traefik에서 다섯 서비스로 갈라진 뒤 그 가운데 Gitea와 Keycloak만 공용 PostgreSQL로 이어지는 구조도.](assets/diagrams/platform-request-path/platform-request-path.svg)
Diagram description 클라이언트는 공개 인터넷, LAN 192.168.0.0/24, Tailscale 100.64.0.0/10 세 출발지를 가진다. 요청은 호스트 경계 안의 Host Nginx 443으로 들어가고 여기서만 TLS가 종료된다. Host Nginx는 관리 hostname에 source allowlist를 적용하고 forwarded header를 다시 쓴 뒤 loopback 127.0.0.1:30080 하나로만 넘긴다. k3s 클러스터 경계 안의 Traefik은 NodePort 30080을 kube-proxy nodeport-addresses=127.0.0.0/8로 loopback에 묶고, web entrypoint에서 10.42.0.1/32만 forwarded-header 신뢰 프록시로 인정한다. 거기서 Host 기반 Ingress 다섯 건이 Gitea, Keycloak, AIStor Console, pgAdmin, Grafana로 갈라진다. 상태 계층에서는 Gitea와 Keycloak만 공용 PostgreSQL의 read-write Service 5432로 이어지며, 이 Service에는 Ingress도 NodePort도 LoadBalancer도 없다.
[Editable source](assets/diagrams/platform-request-path/platform-request-path.drawio) · [Grounded VizSpec](.techviz/platform-request-path/spec.json) ### 2.2 공개 수준이 세 층이다 | hostname | 공개 DNS | Host Nginx source 제한 | 인증 | 관측 | |---|---|---|---|---| | `git.learn.hyeonworks.com` | 있음 | 없음 (공개) | Gitea 로컬 + Keycloak OIDC | HTTP 200 | | `id.learn.hyeonworks.com` | 있음 | 없음 (공개) | Keycloak 자체 | issuer HTTPS 확인 | | `grafana.learn.hyeonworks.com` | 없음 | LAN + Tailscale | Grafana 로컬 + Keycloak OIDC | HTTP 200 | | `storage-admin.learn.hyeonworks.com` | 없음 | LAN + Tailscale | AIStor root + Keycloak OIDC | probe 대상 | | `db-admin.learn.hyeonworks.com` | 없음 | LAN + Tailscale | pgAdmin internal + Keycloak OIDC | probe 대상 | (관측 — evidence `host-nginx-active-config`, `edge-boundary-probe`) **S3 API 와 PostgreSQL 에는 hostname 이 없다.** `object-storage/minio:80` 과 `platform-data/platform-postgres-rw:5432` 는 ClusterIP 뿐이고 Ingress·NodePort·LoadBalancer 가 없다.(관측 — evidence `cluster-services-and-ingress`) ### 2.3 namespace 13개의 역할 | namespace | 담는 것 | PSS enforce | 관측 대상 label | NetworkPolicy | |---|---|---|---|---:| | `kube-system` | Traefik · CoreDNS · local-path · metrics-server | (없음) | `true` | 1 | | `cnpg-system` | CloudNativePG Operator | baseline | 없음 | **0** | | `platform-data` | PostgreSQL Cluster · DB · Role | baseline | `true` | 3 | | `gitea` | Gitea | baseline | `true` | 7 | | `keycloak` | Keycloak Operator · Keycloak 1대 | baseline | `true` | 1 | | `aistor` | AIStor Operator 3파드 | baseline | 없음 | 5 | | `object-storage` | ObjectStore 1대 | baseline | `true` | 11 | | `platform-admin` | pgAdmin | **restricted** | 없음 | 6 | | `observability` | Prometheus·Alertmanager·Grafana·Loki·Tempo·KSM·Blackbox | **restricted** | `true` | 18 | | `observability-agent` | Alloy · node-exporter | **privileged** | `true` | 6 | | `default`·`kube-public`·`kube-node-lease` | 비어 있음 | 없음 | 없음 | 0 | (관측 — evidence `cluster-node-and-pods`, `cluster-networkpolicy-and-storage`) `observability.hyeonworks.com/enabled: "true"` 가 붙은 namespace 에서만 Prometheus 가 ServiceMonitor·PodMonitor·Probe·PrometheusRule 을 찾는다. **그래서 `aistor`·`cnpg-system`· `platform-admin` 의 워크로드는 이 경로로는 수집되지 않는다.** pgAdmin 이 blackbox probe 로만 감시되는 이유가 여기 있다(§11.3). --- ## 3. 호스트 계층 — 물리 디스크 세 장이 역할을 나눈다 ### 3.1 하드웨어와 OS | 항목 | 값 | 출처 | |---|---|---| | OS | Ubuntu 24.04.4 LTS, 커널 `7.0.0-30-generic` | 관측 | | CPU | 12 스레드 (6코어 12스레드) | 관측 · 기록 | | 메모리 | 31Gi total, 관측 시점 10Gi 사용 | 관측 | | swap | 8.0Gi | 관측 | | LAN 주소 | `192.168.0.107/24` (`enp3s0`) | 관측 | | Tailscale 주소 | `100.92.240.34/32` (`tailscale0`) | 관측 | | 클러스터 CIDR | `10.42.0.0/24` (`cni0`), flannel | 관측 | 같은 호스트에 `docker0 172.17.0.1/16`, `br-8359faae6017 172.18.0.1/16`, 그리고 내려가 있는 `mpqemubr0 10.135.97.1/24`(multipass)가 있다. **k3s 와 무관한 컨테이너 런타임이 둘 더 떠 있다** — `docker.service` 와 `snap.multipass.multipassd.service` 가 running 이다.(관측) 이것들이 플랫폼 선언에 나오지 않는다는 점은 §17에 적는다. ### 3.2 디스크 세 장의 분담 ```text /dev/sdc CT250MX500SSD1 약 250GB ─── 시스템 SSD └ sdc1 ext4 228G / k3s · PostgreSQL · Gitea · 관측성 로컬 PV 관측: 136G used / 80G avail (63%) — 내역은 §7.4 /dev/sdb WDC WD20EZAZ-00L9GB0 2,000,398,934,016 bytes ─── 데이터 HDD ├ sdb1 16MiB Microsoft Reserved (기존) ├ sdb2 ntfs3 932G /mnt/hdd-archive 개인 자료, 관측: 24G used (3%) └ sdb3 xfs 932G /srv/k3s/aistor AIStor 오브젝트, 관측: 19G used (3%) /dev/sda CT1000MX500SSD1 약 1TB ─── Windows SSD └ sda3 NTFS (상시 마운트 안 함) K3s 제어면 recovery LUKS 컨테이너 32GiB ``` (관측 — evidence `k3s-config-dropins-and-storage`) **`/srv/k3s/aistor` 는 마운트 포인트이면서 동시에 Local PV 의 host path 다.** 마운트가 빠진 채 ObjectStore 가 뜨면 그 경로는 루트 SSD 의 평범한 디렉터리가 되고 객체가 조용히 `/dev/sdc1` 에 쌓인다. 중앙 문서가 이것을 배포 원칙으로 못 박았다 — 「마운트 누락 시 루트 SSD에 데이터가 생성되지 않도록 사전 검증」. 같은 이유로 `/etc/fstab` 의 AIStor 항목에는 **일부러 `nofail` 을 쓰지 않았다** — 「로컬 디스크 장애를 조용히 무시하지 않도록」.(기록) **AIStor 마운트 옵션이 `noquota` 다.** ```text /srv/k3s/aistor /dev/sdb3 xfs rw,noatime,inode64,logbufs=8,logbsize=32k,noquota ``` 그래서 PV 의 `900Gi` 와 PVC request `900Gi` 는 **바인딩 메타데이터일 뿐 파일시스템 quota 가 아니다.** 약 932Gi 파일시스템에서 900Gi 를 넘겨 쓰는 것을 커널이 막지 않는다. 실제 경계는 버킷 quota(§11.5)와 root SSD 사용률 경보(§11.4)다. ### 3.3 무엇이 죽으면 무엇을 같이 잃나 이 배치에서 함께 죽는 것들: | 무엇이 죽으면 | 무엇을 같이 잃나 | |---|---| | 노드 | 전부 | | `/dev/sdc` (시스템 SSD) | k3s 제어면과 정적 Local PV 아홉 개 전부 — PostgreSQL · Gitea · pgAdmin · Prometheus · Grafana · Alertmanager · Alloy · Loki WAL · Tempo WAL | | `/dev/sdb` (데이터 HDD) | 개인 자료 **와** AIStor 오브젝트 (파티션만 다르고 같은 디스크다) | | `/dev/sda` (Windows SSD) | K3s recovery LUKS 컨테이너 **와** KeePass vault | **백업 목적지가 백업 대상과 같은 섀시 안에 있다.** AIStor 는 PostgreSQL·Gitea 의 백업 목적지로 설계됐지만 같은 서버다. K3s recovery 컨테이너는 `/dev/sdc` 단독 장애만 분리하고 `/dev/sda` 고장이나 장비 전체 사고는 막지 못한다. 중앙 문서가 이 한계를 반복해서 명시하고 있고, **이 문서도 오프사이트 백업이 없다는 사실을 바꾸지 않는다.**(기록 + 추론) --- ## 4. 엣지 — TLS 를 한 번 끊고 그 뒤로는 평문이다 ![왼쪽부터 클라이언트, Host Nginx, Traefik, backend 네 참가자의 생명선이 있고, 클라이언트가 임의 헤더를 보내면 Host Nginx 가 상수로 덮어쓰고 loopback 으로 넘긴 뒤 Traefik 이 source 를 확인하고 backend 로 전달하는 순서를 번호가 붙은 화살표로 보여 주는 시퀀스 다이어그램.](assets/diagrams/edge-trust-chain/edge-trust-chain.svg)
Diagram description 1) 클라이언트가 HTTPS 443 으로 요청을 보낸다. 이 요청에는 임의의 Host 와 X-Forwarded-* 가 들어 있을 수 있다. 2) Host Nginx 는 등록되지 않은 SNI 를 ssl_reject_handshake 로 거부한다. 3) 관리 hostname 셋에서는 source allowlist 192.168.0.0/24 와 100.64.0.0/10 만 통과시키고 나머지는 거부한다. 4) Host 와 X-Forwarded-Host 를 상수 hostname 으로, X-Forwarded-Proto 를 https, X-Forwarded-Port 를 443 으로 덮어쓰고 X-Forwarded-For 와 X-Real-IP 를 접속 주소로 다시 쓴다. 5) 다섯 server block 이 모두 같은 loopback upstream 127.0.0.1:30080 으로 넘긴다. NodePort 는 kube-proxy nodeport-addresses=127.0.0.0/8 로 loopback 에만 묶여 있어 LAN 에서는 연결되지 않는다. 6) Traefik 의 web entrypoint 는 forwardedHeaders.trustedIPs 가 10.42.0.1/32 하나뿐이므로 그 source 에서 온 헤더만 신뢰한다. 7) Traefik 이 Host 기반 Ingress 로 backend 에 전달하고, backend 는 상수로 고정된 hostname 만 본다.
[Editable source](assets/diagrams/edge-trust-chain/edge-trust-chain.drawio) · [Grounded VizSpec](.techviz/edge-trust-chain/spec.json) ### 4.1 Host Nginx 가 지는 책임 활성 파일은 `/etc/nginx/sites-available/learn-services`(214줄, 2026-08-15 04:26 수정)이고 `sites-enabled/learn-services` 가 그것을 가리킨다. 저장소 원본은 `infrastructure/networking/host-nginx/learn-services-observability.conf` 계열이다. 이 파일이 하는 일 넷: **(1) 등록되지 않은 SNI 를 거부한다.** ```nginx server { listen 443 ssl default_server; listen [::]:443 ssl default_server ipv6only=on; ssl_reject_handshake on; } ``` **(2) 다섯 hostname 마다 TLS 를 끊고 같은 loopback upstream 으로 보낸다.** 다섯 server block 이 모두 `proxy_pass http://127.0.0.1:30080;` 하나를 쓴다. **(3) 외부가 보낸 forwarded header 를 믿지 않고 덮어쓴다.** ```nginx proxy_set_header Host git.learn.hyeonworks.com; proxy_set_header X-Forwarded-Host git.learn.hyeonworks.com; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-Port 443; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` `Host` 와 `X-Forwarded-Host` 를 **변수가 아니라 상수로** 박아 둔다. 클라이언트가 무엇을 보내든 backend 가 보는 hostname 은 하나다. Keycloak 의 issuer 가 헤더 주입으로 바뀌지 않는 이유가 여기 있다. **(4) 관리 hostname 셋에만 source allowlist 를 건다.** ```nginx allow 192.168.0.0/24; allow 100.64.0.0/10; deny all; ``` `grafana`·`storage-admin`·`db-admin` 세 곳에 있고, `git`·`id` 두 곳에는 없다. ### 4.2 hostname 마다 다른 세 가지 값 같은 구조를 다섯 번 반복하지만 세 값은 서비스마다 다르다. | hostname | `client_max_body_size` | read/send timeout | WebSocket upgrade | `/metrics` 차단 | |---|---:|---:|---|---| | `git.learn…` | 512m | 3600s | 있음 | `return 404` | | `id.learn…` | 10m | 300s | 없음 | 없음 | | `storage-admin.learn…` | 5g | 3600s | 있음 | 없음 | | `db-admin.learn…` | 100m | 600s | 없음 | 없음 | | `grafana.learn…` | 10m | 300s | 있음 | `return 404` | (관측 — evidence `host-nginx-active-config`) Git push 와 S3 콘솔 업로드가 큰 body 와 긴 타임아웃을 요구하고, ID·Grafana 는 그럴 이유가 없어 좁혀 뒀다. `/metrics` 를 404 로 막은 곳은 Gitea 와 Grafana 둘이다 — 둘 다 애플리케이션이 `/metrics` 를 열 수 있는 제품이라 공개 경로에서 미리 닫았다.(추론 — 근거: 그 둘만 막혀 있고, Keycloak 은 관리 포트 9000 이 아예 Ingress 에 없어 막을 필요가 없다) ### 4.3 인증서 다섯 장이 아니라 세 장이다 | hostname | 실제 제시하는 인증서 CN | SAN | 만료 | |---|---|---|---| | `git.learn…` | `git.learn.hyeonworks.com` | `git`, `id` | 2026-12-15 | | `id.learn…` | `git.learn.hyeonworks.com` | `git`, `id` | 2026-12-15 | | `storage-admin.learn…` | `storage-admin.learn.hyeonworks.com` | `db-admin`, `storage-admin` | **2026-10-21** | | `db-admin.learn…` | `storage-admin.learn.hyeonworks.com` | `db-admin`, `storage-admin` | **2026-10-21** | | `grafana.learn…` | `grafana.learn.hyeonworks.com` | `grafana` | 2026-11-08 | 발급자는 Let's Encrypt — 서로 다른 인증서 셋 중 `YE2` 가 둘, `YE1` 이 하나다(hostname 으로 세면 YE2 넷·YE1 하나). (관측 — evidence `edge-tls-certificates`) **인증서가 셋이고 hostname 이 다섯이다.** `git`+`id` 가 한 장, `storage-admin`+`db-admin` 이 한 장, `grafana` 가 한 장이다. nginx 설정에서도 `id` server block 이 `/etc/letsencrypt/live/git.learn.hyeonworks.com/` 을, `db-admin` server block 이 `/etc/letsencrypt/live/storage-admin.learn.hyeonworks.com/` 을 참조한다. **SAN 에 들어 있으므로 유효하지만, 한 장이 갱신에 실패하면 두 hostname 이 함께 끊긴다.**(추론) **`storage-admin`/`db-admin` 인증서가 가장 먼저 만료된다 — 2026-10-21, 기준일로부터 31일 뒤다.** `PlatformCertificateExpiry` 경보가 30일 미만에서 warning 으로 뜨므로 **하루 뒤부터 warning 이 뜨기 시작한다.**(관측 + 추론) 이 경보는 blackbox probe 의 `probe_ssl_earliest_cert_expiry` 를 쓰는데, `private-edge` probe 대상에 두 hostname 이 모두 들어 있으므로 감지는 된다. ### 4.4 Traefik — 문 하나를 loopback 에 묶는다 ```text Service/kube-system/traefik NodePort 80:30080/TCP 443:30443/TCP /etc/rancher/k3s/config.yaml.d/30-nodeport-loopback.yaml: kube-proxy-arg: - "nodeport-addresses=127.0.0.0/8" ``` 관측 결과: ```text NodePort via LAN IP 192.168.0.107:30080: 000 ← 연결 자체가 안 됨 NodePort via loopback 127.0.0.1:30080: 404 ← Traefik 도달, Host 없는 요청이라 라우트 없음 ``` (관측 — evidence `edge-boundary-probe`, `k3s-config-dropins-and-storage`) **`404` 는 성공 신호이고 `000` 이 차단 신호다.** Traefik 에 닿았으면 라우트가 없어도 `404` 가 돌아온다. 그래서 외부 차단을 판정할 때는 `404` 도 실패로 센다 — 중앙 문서가 같은 기준을 적고 있고 이 관측이 그 기준을 따른다. **`30443` 은 열려 있지만 경로에서 안 쓴다.** Service 에 포트는 있고 `websecure` entrypoint 도 있지만 Host Nginx 가 `30080` 으로만 보낸다. ### 4.5 forwarded header 신뢰 경계 — 정확히 `/32` 하나 라이브 `HelmChartConfig/kube-system/traefik` 의 `web` entrypoint: ```yaml ports: web: nodePort: 30080 forwardedHeaders: trustedIPs: # 2026-07-23 Host Nginx 경유 probe에서 관측한 Traefik ClientHost이다. - "10.42.0.1/32" ``` (관측 — evidence `traefik-live-helmchartconfig`) `10.42.0.1` 은 `cni0` 의 주소다. 호스트에서 loopback NodePort 로 들어온 패킷이 클러스터 네트워크로 SNAT 되면서 이 주소로 보인다. **추측한 CIDR 이 아니라 실제로 관측한 source 하나만 `/32` 로 신뢰한다.** `forwardedHeaders.insecure` 도 `websecure` trust 도 없다. **루트 build root 는 라이브와 다르다. 그런데 그것이 의도다.** `infrastructure/networking/traefik/kustomization.yaml` 은 `overlays/observe` 를 가리키고 `observe` 는 `base` 를 그대로 쓴다. `base` 에는 `trustedIPs` 가 없고 그것은 `overlays/trust` 에만 있다. ```text infrastructure/networking/traefik/ ├── kustomization.yaml → resources: [overlays/observe] ← 기본 build root ├── base/helm-chart-config.yaml trustedIPs 없음 └── overlays/ ├── baseline/ Service 계약만 (access log·trust 없음) ├── observe/ base 그대로 ← 기본 build root 가 가리키는 곳 └── trust/ trustedIPs: 10.42.0.1/32 ← 라이브와 같은 것 ``` 저장소가 그 이유를 적어 두었다.(기록 — `infrastructure/networking/traefik/README.md`) > 루트 `kustomization.yaml`은 의도적으로 안전한 `observe` overlay를 가리킨다. 현재 live 상태는 > `trust`이므로 루트에 단순히 `kubectl apply -k`를 실행하면 trust 제거를 요청하게 된다. 상태 > 전환은 아래 guarded script와 정확한 overlay를 사용한다. **즉 「루트를 그대로 적용하면 trust 가 사라진다」는 사고가 아니라 설계다.** 신뢰 경계를 켜고 끄는 것은 `scripts/apply-trust.sh`·`rollback-to-observe.sh` 가 맡고, 루트는 아무것도 모르는 사람이 `apply -k` 를 쳤을 때 **덜 위험한 쪽**으로 떨어지게 두었다. 대신 라이브가 어느 overlay 상태인지는 저장소를 봐서는 알 수 없고 `HelmChartConfig` 를 읽어야 한다. --- ## 5. 이름 해석 — 같은 이름이 출발지마다 다른 주소를 준다 세 개의 resolver 가 같은 다섯 이름에 서로 다른 답을 준다. ```text git / id / storage-admin / db-admin / grafana .learn.hyeonworks.com LAN 클라이언트 → dnsmasq @192.168.0.107:53 → 192.168.0.107 Tailscale 노드 → dnsmasq @100.92.240.34:53 → 100.92.240.34 클러스터 내 파드 → CoreDNS (coredns-custom) → 192.168.0.107 공개 인터넷 → 권威 DNS → git·id 만 A 레코드 있음 ``` ### 5.1 호스트 dnsmasq 두 인스턴스 systemd unit 두 개가 각각 하나의 주소에만 바인딩한다.(관측 — evidence `host-private-dns-config`) ```ini # /etc/dnsmasq-hyeonworks/lan.conf port=53 listen-address=192.168.0.107 bind-interfaces no-hosts no-resolv server=1.1.1.1 server=1.0.0.1 cache-size=1000 domain-needed bogus-priv address=/git.learn.hyeonworks.com/192.168.0.107 ... ``` `domain-needed` 와 `bogus-priv` 는 점 없는 이름과 사설 대역 역질의를 상류로 **안 보내는** 설정이다. `tailscale.conf` 는 `listen-address` 와 `address=` 목표만 `100.92.240.34` 로 다르고 나머지는 같다. `bind-interfaces` 로 두 프로세스가 같은 53 포트를 주소별로 나눠 쓴다. 두 unit 의 systemd hardening 이 같다: `NoNewPrivileges`, `PrivateTmp`, `ProtectHome`, `ProtectSystem=strict`, `ProtectKernelTunables/Modules/ControlGroups`, `RestrictAddressFamilies`, `CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_SETGID CAP_SETUID`. ### 5.2 CoreDNS 확장 `coredns-custom` ConfigMap 이 `learn.hyeonworks.com:53` server block 을 더한다. 다섯 이름을 모두 `192.168.0.107` 로 답하고 그 밖은 `fallthrough` + `forward . /etc/resolv.conf`. **이것이 왜 필요한가.** 클러스터 안의 파드가 `https://id.learn.hyeonworks.com/...` 로 Keycloak discovery 를 부를 때, 공개 DNS 로 나갔다가 다시 들어오면 경로가 길고 `storage-admin`·`db-admin`·`grafana` 는 공개 A 레코드가 아예 없어 실패한다. CoreDNS 가 노드 주소로 바로 답하면 파드 → 호스트 Nginx → Traefik → 파드 로 돌아온다. Gitea 가 쓰던 임시 `hostAliases` 를 이것이 대체했다.(선언 + 기록) ### 5.3 다른 호스트에서 본 결과 별도 호스트 `donghyeon-960XGK`(LAN `192.168.0.103`, Tailscale `100.123.124.30`)에서 같은 이름을 물어봤다.(관측 — evidence `tailscale-peer-vantage`) ```text git / id / storage-admin / db-admin / grafana .learn.hyeonworks.com → 전부 100.92.240.34 (Tailscale 주소) https://git.learn…/api/healthz 200 https://storage-admin.learn…/ 200 https://db-admin.learn…/ 302 (pgAdmin 로그인 redirect) https://grafana.learn…/api/health 200 http://192.168.0.107:30080/ 000 (거부) http://192.168.0.107:30443/ 000 (거부) ``` **Tailscale split DNS 가 실제로 등록돼 있고 동작한다.** 이 호스트는 LAN 에도 있지만 Tailscale 주소를 받았다 — Tailscale 의 DNS 설정이 우선한다. 그리고 그 주소로 들어온 요청이 Host Nginx 의 `allow 100.64.0.0/10` 을 통과해 관리 UI 세 곳이 다 열렸다. **NodePort 차단도 두 번째 호스트에서 재확인됐다.** `30080` 과 `30443` 둘 다 거부다. ### 5.4 이 구조가 만드는 제약 - **공유기 DHCP 의 DNS 설정은 여전히 확인하지 못했다**(미확인). 위 관측은 Tailscale 경로가 동작한다는 것을 보여 주지만, Tailscale 이 없는 LAN 클라이언트가 `192.168.0.107:53` 을 resolver 로 받는지는 공유기 설정이라 이 문서 범위 밖이다. - **파드가 관리 UI 를 부르면 Host Nginx 의 allowlist 에 막힌다.** 파드 → 노드는 로컬 배달이라 SNAT 이 걸리지 않고 **파드 IP 가 그대로** 도착한다 — nginx access log 에 blackbox 는 `10.42.0.144` 로 찍힌다(관측). 그 주소는 `192.168.0.0/24` 에도 `100.64.0.0/10` 에도 없다. 그래서 blackbox 의 `private-edge` probe 는 **403 을 기대값으로 삼는다**(§11.3). `10.42.0.1` 은 반대 방향 — 호스트가 loopback NodePort 로 넣은 패킷이 Traefik 에 닿을 때의 `cni0` 주소다(§4.5). 두 주소를 섞지 않는다. --- ## 6. k3s 클러스터 — 기본값을 어디까지 남겼나 ### 6.1 k3s 자체 | 항목 | 값 | |---|---| | 버전 | `v1.36.2+k3s1` | | 노드 | 1 (control-plane), age 63d | | 컨테이너 런타임 | `containerd://2.3.2-k3s2` | | CNI | flannel (`10.42.0.0/24`) | | Ingress | Traefik `3.7.4`, chart `40.1.3+up40.1.0` | | DNS | CoreDNS `1.14.4` | | 기본 StorageClass | `local-path` (rancher, `Delete`) — **플랫폼은 안 쓴다** | | metrics-server | `v0.8.1` | (관측 — evidence `cluster-node-and-pods`, `running-container-images`) ### 6.2 손댄 두 곳 `/etc/rancher/k3s/config.yaml.d/` 에 drop-in 이 둘이다. ```yaml # 30-nodeport-loopback.yaml kube-proxy-arg: - "nodeport-addresses=127.0.0.0/8" ``` ```yaml # 40-secrets-encryption.yaml secrets-encryption: true secrets-encryption-provider: aescbc ``` (관측 — evidence `k3s-config-dropins-and-storage`) **두 번째는 「설정이 켜져 있다」이지 「재암호화가 끝났다」가 아니다.** 실제 상태는 `k3s secrets-encrypt status` 가 말하고 그건 `sudo` 가 필요해 못 읽었다(미확인). 중앙 문서는 2026-08-09 에 `Enabled/reencrypt_finished` 를 확인했다고 기록한다(기록). 저장소에도 같은 파일이 `infrastructure/security/k3s/40-secrets-encryption.yaml` 로 있고 내용이 바이트 단위로 같다.(관측) ### 6.3 Helm 배포 방식 — chart 를 복사하지 않는다 k3s 가 관리하는 Traefik 은 `HelmChartConfig` 로 values 만 덮어쓴다. 나머지는 Kustomize 의 Helm inflator 로 공식 chart 를 **렌더 시점에 내려받아** 쓴다. 고정 대상은 chart 버전과 package SHA-256 둘 다다. | build root | chart | 버전 | package SHA-256 | |---|---|---|---| | `infrastructure/controllers/cloudnative-pg` | `cloudnative-pg` | `0.29.0` (app `1.30.0`) | `668e065ff53508d58238788fd35b355a925060843629a951df0e6a9362e6d32f` | | `services/gitea` · `services/gitea/profiles/oidc` | `gitea` | `12.7.0` (app `1.27.0`) | `5881ef9c59400bee2d5547e77c4cd0efb925143c2f5d93fb4f38446db76b0167` | | `infrastructure/controllers/keycloak-operator` | (Kustomize remote) | release `26.7.0` | 공식 Git release ref | | `infrastructure/controllers/aistor-operator` | `aistor-operator` | `5.10.0` | `e5534f5ae4f6f12a3528a8cda5954d73280cba1a8e979e1628fbf3aac76babd1` | | `services/minio-aistor` | `aistor-objectstore` | `1.0.16` | `50ffa6a4e014cdc48566b237593baab41d039f103cdc50c1b1ac173b8d8bf71e` | | `services/observability/kube-prometheus-stack` | `kube-prometheus-stack` | `88.0.1` | (vendored) | | `services/observability/grafana` | `grafana` | `12.10.1` | (vendored) | | `services/observability/alloy` | `alloy` | `1.11.0` | (vendored) | | `services/observability/blackbox-exporter` | `prometheus-blackbox-exporter` | `11.16.0` | (vendored) | **관측성 스택만 방식이 다르다.** Phase 1·2 의 chart 는 렌더할 때 내려받고 SHA-256 을 비교하지만, 관측성 chart 넷은 `.helm/charts/-/` 아래에 **저장소에 풀어 놓았다**(713파일 155,560줄). `.gitignore` 에 `.helm/` 이 있으므로 이 디렉터리는 **git 이 추적하지 않는다.** 즉 작업 트리에는 있고 커밋에는 없다.(관측) 이것이 뜻하는 것: **관측성 스택을 다른 기계에서 저장소만 가지고 재현할 수 없다.** 누군가 `.helm/charts/` 를 다시 채워야 한다. Phase 1·2 는 `render-phase1.sh`/`render-phase2.sh` 가 그 일을 하지만 관측성 쪽에 같은 역할을 하는 것이 `render-observability-core.sh` 인지는 확인했다(§14.2) — 그 스크립트가 chart 를 내려받는 경로를 갖고 있다. 렌더 도구도 고정이다: Kustomize `v5.8.1`, Helm `v3.19.4`. `--load-restrictor LoadRestrictionsNone` 은 쓰지 않고 기본 `RootOnly` 를 유지한다. 그래서 values 와 patch 가 항상 build root 아래에 있다. --- ## 7. 스토리지 — 정적 Local PV 열 개 ### 7.1 StorageClass 를 워크로드마다 하나씩 나눴다 StorageClass 11개 중 `local-path`(k3s 기본)를 뺀 10개가 전부 `kubernetes.io/no-provisioner` · `Retain` · `WaitForFirstConsumer` · `allowVolumeExpansion: false` 로 같다. **왜 하나로 안 하고 열 개인가.** provisioner 가 없으면 PVC 는 조건이 맞는 아무 PV 에나 바인딩된다. StorageClass 이름을 워크로드마다 다르게 하면 **Gitea 의 PVC 가 PostgreSQL 의 PV 를 선점하는 일이 구조적으로 불가능해진다.** 용량·접근모드만으로는 막을 수 없는 것을 이름으로 막았다.(추론 — 근거: 중앙 문서의 "PostgreSQL과 Gitea가 잘못 교차 바인딩되지 않도록 workload별 StorageClass를 분리한다") ### 7.2 PV 열 개의 배치 | PV | 용량 | host path | 소비자 | 디스크 | |---|---:|---|---|---| | `platform-postgres-local-pv` | 20Gi | `/srv/k3s/ssd/platform-postgres` | `platform-data/platform-postgres-1` | SSD | | `gitea-local-pv` | 50Gi | `/srv/k3s/ssd/gitea` | `gitea/gitea-data` | SSD | | `pgadmin-data-local-pv` | 2Gi | `/srv/k3s/ssd/pgadmin` | `platform-admin/pgadmin` | SSD | | `observability-prometheus-local-pv` | 20Gi | `/srv/k3s/ssd/observability/prometheus` | Prometheus TSDB | SSD | | `observability-grafana-local-pv` | 2Gi | `/srv/k3s/ssd/observability/grafana` | Grafana SQLite | SSD | | `observability-alertmanager-local-pv` | 1Gi | `/srv/k3s/ssd/observability/alertmanager` | silence·notification 상태 | SSD | | `observability-alloy-local-pv` | 2Gi | `/srv/k3s/ssd/observability/alloy` | position·전송 큐 | SSD | | `observability-loki-local-pv` | 5Gi | `/srv/k3s/ssd/observability/loki` | Loki WAL | SSD | | `observability-tempo-local-pv` | 5Gi | `/srv/k3s/ssd/observability/tempo` | Tempo WAL | SSD | | `aistor-data-local-pv` | 900Gi | `/srv/k3s/aistor` | ObjectStore pool-0 | **XFS HDD** | 전부 `Bound`, 전부 `Retain`, 전부 `ReadWriteOnce`, 전부 노드 `donghyeon-system-product-name` affinity.(관측 — evidence `cluster-networkpolicy-and-storage`) **SSD 쪽 선언 합계는 107Gi 인데 root filesystem 은 228G 이고 이미 136G 가 차 있다**(같은 날 두 번째 측정에서는 138G — §7.4). Local PV 의 `capacity` 는 quota 가 아니므로 이 합계가 지켜진다는 보장이 없다. 그래서 실질 경계는 root filesystem 사용률 경보 세 단계(75% info / 85% warning / 90% critical)다. **관측 시점 경보 식 기준 사용률은 64.8% 로 첫 경계 아래에 있다**(§16.1).(관측) ### 7.3 Loki·Tempo 만 두 층이다 나머지는 로컬 PV 하나로 끝나지만 Loki 와 Tempo 는 로컬을 작업 공간으로만 쓰고 본 데이터를 S3 로 보낸다. ```text Loki WAL/working → /srv/k3s/ssd/observability/loki (5Gi) chunks·ruler·admin → AIStor loki 버킷 (보존 720h = 30일) Tempo WAL/working → /srv/k3s/ssd/observability/tempo (5Gi) trace block → AIStor tempo 버킷 (보존 168h = 7일) ``` 둘 다 `minio.object-storage.svc.cluster.local` 로 간다 — Loki 는 `http://…`(기본 80), Tempo 는 `…:80` 을 명시한다. `s3ForcePathStyle`/`forcepathstyle` 과 `insecure: true` 를 켠다. **XFS 를 직접 마운트하지 않는다.** 두 파드는 `platform.hyeonworks.com/aistor-client: "true"` label 을 달고, 그 label 이 `object-storage` 쪽 NetworkPolicy 의 통과 조건이다(§12.4). 관측 시점 `loki` 버킷 866,300,448 bytes, `tempo` 버킷 0 bytes. quota 대비 `loki` 0.403%. **`tempo` 가 0 인 것은 고장이 아니라 trace 를 보내는 애플리케이션이 아직 없기 때문이다** — Alloy 의 OTLP receiver 는 떠 있지만 보내는 쪽이 없다(§11.6).(관측 + 추론) **XFS 쪽 19G 도 객체가 아니다.** `df` 가 `/srv/k3s/aistor` 를 19G used 로 보이고 ObjectStore status 의 `rawUsage` 도 `20,085,288,960` bytes(약 18.7 GiB)를 낸다. 그런데 버킷 둘의 합은 866,300,448 bytes(약 826 MiB)뿐이다. 차이 약 17.9 GiB(`20,085,288,960 − 866,300,448 = 19,218,988,512`)는 객체가 아니라 **파일시스템이 미리 잡아 둔 공간**이다. 중앙 문서가 「빈 XFS 에서 약 18GiB 가 사용된 것으로 보이는 이유」로 이미 설명했고 그때 값과 지금 값이 맞는다.(관측 + 기록) **그 덩어리는 한 가지가 아니다.** 원문은 셋으로 나눈다 — Allocation Group 별 reverse mapping·refcount B-tree 확장 예약, 비상 메타데이터 갱신용 예약, 그리고 내부 로그 `119254 × 4096 = 488,464,384 bytes`(약 466MiB). 「18GiB 전체가 로그 영역인 것은 아니다」라고 원문이 못 박는다. **AG 예약분만 따로 실측한 적은 양쪽 어디에도 없다** — 그것을 재는 `xfs_db -r -c agresv` 는 `sudo` 가 필요하고 중앙 문서의 해당 체크리스트도 미체크다(미확인). **그래서 AIStor 의 `usage`·`rawUsage` 도 파일시스템 값이지 객체 크기가 아니다.** §7.5 의 `kubelet_volume_stats_*` 와 같은 함정이고, 객체 용량을 보려면 `minio_cluster_usage_buckets_total_bytes` 를 써야 한다 — 플랫폼 경보의 quota 규칙이 실제로 그 metric 을 쓴다(§11.4). ### 7.4 루트 SSD 를 실제로 채운 것은 플랫폼이 아니다 §7.2 의 선언 합계 107Gi 와 루트 파일시스템 사용량을 나란히 읽으면 플랫폼이 그만큼 썼다고 오해하기 쉽다. **재 보면 아니다.**(관측 — evidence `disk-usage-attribution`. 이 증거는 `df` 가 138G / 64% 를 낼 때 잡았다. §7.2·§16 의 136G / 63% 는 한 시간 앞선 측정이다) | 무엇 | 실사용 | 선언 용량 | 어떻게 쟀나 | |---|---:|---:|---| | Prometheus TSDB | **4.65 GiB** | 20Gi | 자체 metric: blocks `4,657,964,807` + WAL `291,393,543` + head chunks `39,312,192` bytes | | PostgreSQL | 614 MiB | 20Gi | 파드 안 `du -sh /var/lib/postgresql/data` | | Gitea | 174.7 MiB | 50Gi | 파드 안 `du -sh /data` | | Grafana | 1.7 MiB | 2Gi | 파드 안 `du -sh /var/lib/grafana` | | Loki WAL | 9.9 MiB | 5Gi | 자체 metric `prometheus_tsdb_wal_storage_size_bytes` `10,342,630` bytes | | Alloy | 36 KiB | 2Gi | 파드 안 `du -sh /var/lib/alloy` | | Alertmanager | 4 KiB | 1Gi | 파드 안 `du -sh /alertmanager` | | pgAdmin | 228 KiB | 2Gi | 파드 안 `du -sh /var/lib/pgadmin` | | Tempo WAL | **미확인** | 5Gi | distroless 라 `du`·`ls` 가 없고 크기 metric 도 없다 | **정적 Local PV 아홉 개가 루트 SSD 에서 실제로 쓰는 것은 다 합쳐 약 5.4 GiB 다.** 그 중 **관측성 몫은 약 4.66 GiB 이고 거의 전부 Prometheus TSDB 다.** 선언 합계 107Gi 의 5%, 파일시스템 228G 의 2.4% 다. 그러면 138G 는 무엇인가. 루트 파일시스템만 세면(`du -shx`) 이렇게 나뉜다. | 경로 | 크기 | 무엇 | |---|---:|---| | `/home/donghyeon` | **61G** | 그 중 `hdd-migration-backup-20260722` 가 **24G**, `workspace` 4.4G, `Documents` 1.2G | | `/var` | 11.7G(읽힌 부분) | `lib/snapd` 5.7G · `log` 1.4G · `lib/rancher` 251.4M · `lib/apt` 210.5M | | `/usr` | 9.3G | OS | | `/opt` | 758.6M | | | `/boot` | 396.1M | | | 나머지 | 약 20M | `/etc` 13.1M · `/tmp` 7.1M · `/snap` 140.0K · `/srv`(루트 부분) 20.0K · `/mnt`(마운트 포인트만) 16.0K | | **미귀속** | **약 54.8G** | `/var/lib/docker` · `/var/lib/containerd` · `/var/lib/rancher/k3s/agent/containerd` · `/root` | 귀속분 합이 `61 + 11.7 + 9.3 + 0.76 + 0.40 + 0.02 = 83.2G` 이고 그때 `df` 가 138G 였으므로 미귀속은 **54.8G** 다. **미귀속 54.8G 는 컨테이너 이미지 저장소로 보인다**(추론 — 읽지 못한 디렉터리가 그 넷뿐이고, 이 호스트에는 k3s containerd 와 별개로 Docker 가 함께 떠 있다(§3.1, §17.6)). 확인하려면 `sudo du -shx /var/lib/docker /var/lib/containerd /var/lib/rancher` 한 줄이면 된다. **눈에 띄는 것은 `/home/donghyeon/hdd-migration-backup-20260722` 24G 다.** ADR-0001 이 2026-07-22 HDD 분할 때 "시스템 SSD에 파일 안전본을 만들고 SHA-256으로 검증한 다음 파티션과 파일시스템을 새로 생성한다" 고 적은 그 안전본이다. 복원 뒤 SHA-256 재검증을 통과했고 `/mnt/hdd-archive` 에 24G 가 그대로 있으므로, 이 사본은 **두 달째 역할이 끝난 채 루트 SSD 228G 의 10.5%, 지금 쓰고 있는 138G 의 17.4% 를 차지하고 있다.**(관측 + 추론) 지우는 것은 사람이 정할 일이지만, root filesystem 경보가 관측성 증가가 아니라 이 사본 때문에 먼저 울릴 수 있다는 점은 적어 둔다. ### 7.5 PVC 사용량 지표를 믿으면 안 된다 `kubelet_volume_stats_capacity_bytes` 는 **정적 Local PV 아홉 개 전부에 똑같은 `243,885,932,544`** 를 낸다. `…_used_bytes` 도 `147,697,172,480` ~ `147,715,776,512` 사이에 몰려 있다(폭 18.6MB — 측정 시각 차이일 뿐 PVC 별 차이가 아니다). 그것은 PVC 가 아니라 **루트 파일시스템 전체**다. local PV 가 루트 fs 의 그냥 디렉터리라 kubelet 의 `statfs` 가 파일시스템 값을 돌려주기 때문이다. XFS 위에 있는 AIStor PVC 하나만 제 값(`20,094,828,544` / `999,892,553,728`)을 낸다.(관측 — evidence `disk-usage-attribution`) **그리고 그 값을 읽는 경보가 이미 돌고 있다.** kube-prometheus-stack 이 만드는 `kubernetes-storage` group 에 넷이 있다(§11.4 의 「생성 133」에 포함). | alert | 조건 | `for` | |---|---|---:| | `KubePersistentVolumeFillingUp` | `available/capacity < 0.03` | 1m | | `KubePersistentVolumeFillingUp` | `available/capacity < 0.15` | 1h | | `KubePersistentVolumeInodesFillingUp` | `inodes_free/inodes < 0.03` | 1m | | `KubePersistentVolumeInodesFillingUp` | `inodes_free/inodes < 0.15` | 1h | 관측 시점 `kubelet_volume_stats_available_bytes / …_capacity_bytes` 는 아홉 개가 전부 **`0.3419`** 다 — 루트 파일시스템의 여유율이다. AIStor 하나만 `0.9799` 로 제 값을 낸다. 넷 다 `inactive`.(관측) **그래서 이 넷은 두 방향으로 다 틀린다.** - **거짓 초록** — Gitea PVC 가 50Gi 를 다 채워도 이 식은 여전히 루트 여유율을 읽는다. 루트에 여유가 있는 한 **영원히 `inactive`** 다. - **거짓 폭풍** — 반대로 루트가 85% 에 닿으면 `available/capacity` 가 `0.15` 밑으로 떨어져 **아홉 개가 한꺼번에 울린다.** 그 시점에 `PlatformRootFilesystemUsage` warning 도 같이 울리므로, 같은 사건 하나에 경보 열 건이 뜬다. 그러므로 §7.5 의 결론은 「PVC 사용률 경보를 만들 수 없다」가 아니라 **「이미 있는데 값을 잘못 읽고 있다」**다. 워크로드별 디스크 귀속을 metric 으로 얻을 방법이 지금은 없고 §7.4 처럼 파드마다 들어가 재야 한다. 플랫폼 경보가 **root filesystem 사용률 3단계**(§11.4)를 쓰는 것은 이 제약에 맞지만, 저장소·중앙 문서 어디에도 이 제약을 적은 문장이 없다(관측 — `grep` 0건). 그래서 생성 경보 넷이 걸러지지 않은 채 남았다(추론). --- ## 8. 데이터 계층 — 인스턴스 하나, 데이터베이스 둘 ### 8.1 구성 | 항목 | 값 | |---|---| | Operator | CloudNativePG `1.30.0`, namespace `cnpg-system`, replica 1 | | Cluster | `platform-data/platform-postgres`, instances 1 | | 이미지 | `ghcr.io/cloudnative-pg/postgresql:17.9-standard-trixie` | | Service | `platform-postgres-rw:5432` 하나. `ro`·`r` 은 명시적으로 비활성 | | 자원 | request `250m/512Mi` → limit `2 CPU/4Gi` | | 스토리지 | `platform-postgres-local-pv` 20Gi, Retain | | 데이터 검사합 | `dataChecksums: true` (initdb 시점) | (선언 + 관측) ### 8.2 두 서비스를 가르는 세 겹 Gitea 와 Keycloak 이 같은 PostgreSQL 인스턴스를 쓰지만 데이터베이스·역할·Secret 을 공유하지 않는다. 경계가 세 겹이다. **(1) `pg_hba` — 역할이 자기 DB 에만 인증된다.** ```yaml postgresql: pg_hba: - host gitea gitea all scram-sha-256 - host all gitea all reject - host keycloak keycloak all scram-sha-256 - host all keycloak all reject ``` 순서가 중요하다. 허용 규칙이 거부 규칙보다 앞에 있고, 거부 규칙이 CloudNativePG 의 기본 fallback 보다 앞에 온다. **database owner 분리만으로는 PostgreSQL 의 기본 `CONNECT` 권한을 회수하지 못한다.** 중앙 문서는 그래서 「실제 접속 차단 경계는 이 HBA 규칙과 **Secret 격리의 조합**」이라고 적는다 — HBA 혼자가 아니라 두 겹이다.(선언 + 기록) **(2) Secret 격리 — 같은 값이 두 namespace 에 두 벌.** Kubernetes Secret 은 namespace 를 넘지 못한다. 그래서 DB 자격 증명마다 객체가 둘이다. | 서버 측 (`platform-data`) | 소비자 측 | type·key | |---|---|---| | `gitea-db-credentials` | `gitea/gitea-db-credentials` | `kubernetes.io/basic-auth`; `username`,`password` | | `keycloak-db-credentials` | `keycloak/keycloak-db-credentials` | 같음 | 서버 측에는 `cnpg.io/reload=true` label 이 붙는다. (관측 — 두 namespace 에 같은 이름의 `kubernetes.io/basic-auth` Secret 이 실재. 값이 같은지는 payload 를 안 읽어 미확인) **(3) NetworkPolicy — namespace 단위로 5432 도달을 가른다.** `platform-data` 의 정책 셋: | 정책 | 허용 | |---|---| | `platform-postgres-ingress` | `cnpg-system` operator(8000·5432), 같은 cluster operand(8000·5432), `gitea` namespace(5432), **`observability` 의 Prometheus(9187)** | | `platform-postgres-keycloak-ingress` | `keycloak` namespace(5432)만 **추가** | | `platform-postgres-allow-pgadmin` | `platform-admin` pgAdmin(5432)만 **추가** | NetworkPolicy 의 허용은 additive 라서 Phase 2·3 의 증분 root 가 Phase 1 정책을 복사하거나 고치지 않는다. **그래서 Phase 2·3 은 Cluster 선언을 다시 렌더하지 않고 정책 한 줄씩만 더한다.** **egress 는 제한하지 않는다.** operand 파드가 나가는 방향은 열려 있다. 중앙 문서가 "Operator 관리 경로와 향후 backup·Kubernetes API 경로를 섣불리 차단하지 않기 위한 선택" 이라고 적는다(기록). `platform-data` 에 default-deny 가 없는 것과 같은 이야기다. ### 8.3 Database·DatabaseRole 을 CR 로 관리한다 `Cluster` 의 `initdb` 가 `gitea` DB 와 owner 를 만들고(순환 의존을 줄이려고 Secret 에서 읽는다), 그 뒤 같은 이름의 `DatabaseRole`·`Database` CR 이 선언적 수명주기를 가져간다. 두 CR 의 reclaim policy 가 `retain` 이라 **CR 을 지워도 PostgreSQL 의 역할·DB 가 지워지지 않는다.** Keycloak 쪽은 `services/platform-postgres-keycloak` 이 같은 모양의 CR 둘과 NetworkPolicy 하나만 렌더한다.(선언) ### 8.4 확인하지 못한 것 중앙 문서의 체크리스트에서 **여섯 항목을 아직 아무도 체크하지 않았다**: 두 역할이 superuser 가 아닌지 SQL 로 확인, 상대 DB 에 HBA `reject` 가 실제로 걸리는지 확인, 두 역할이 상대 DB 객체를 못 읽는지 확인, **`gitea`·`keycloak` namespace 만 NetworkPolicy 경로로 TCP 5432 에 닿는지 확인**, PostgreSQL 재시작 뒤 데이터 유지 확인, AIStor 백업·복원 확인. 네 번째가 §8.2 가 세 겹 중 하나로 든 바로 그 경계다. 이 문서도 그 다섯을 확인하지 않았다(미확인). **선언과 집행은 다른 것이고, 여기서는 선언만 확인했다.** --- ## 9. ID 계층 — 프록시가 아니라 발급자다 ### 9.1 무엇이 아닌가부터 Keycloak 은 **모든 요청 앞에 서는 인증 프록시가 아니다.** Traefik ForwardAuth 도, Nginx auth_request 도 쓰지 않는다. 각 애플리케이션이 표준 OIDC client 로 직접 연결한다. Keycloak 이 Host Nginx·Traefik 뒤에 있는 것은 **브라우저가 `id.learn.hyeonworks.com` 에 닿기 위한 네트워크 경로**일 뿐, 다른 서비스를 대신 인증하는 것이 아니다. 두 의미를 ADR-0005 가 이 둘을 갈라 놓는다. ### 9.2 Keycloak 인스턴스 ```yaml apiVersion: k8s.keycloak.org/v2beta1 kind: Keycloak spec: instances: 1 db: { vendor: postgres, host: platform-postgres-rw.platform-data.svc.cluster.local, database: keycloak, poolInitialSize: 5, poolMinSize: 5, poolMaxSize: 20 } hostname: { hostname: https://id.learn.hyeonworks.com, strict: true } http: { httpEnabled: true, httpPort: 8080, serviceHttpPort: 8080 } proxy: { headers: xforwarded } ingress: { enabled: false } # Operator 가 만드는 Ingress 를 끄고 직접 쓴다 additionalOptions: [ { name: metrics-enabled, value: "true" } ] ``` `hostname.strict: true` 와 `proxy.headers: xforwarded` 의 조합이 §4.1의 nginx 상수 헤더와 맞물린다. **외부가 `X-Forwarded-Host` 를 주입해도 nginx 가 덮어쓰고, Traefik 은 `10.42.0.1/32` 에서 온 헤더만 믿고, Keycloak 은 `strict` hostname 을 쓴다.** 세 겹이 같은 방향을 본다. 관측: discovery 의 `issuer` 가 `https://id.learn.hyeonworks.com/realms/hyeonworks` 로 나온다 (evidence `edge-boundary-probe`). **Service 는 `8080/9000` 두 포트를 갖지만 Ingress backend 는 `8080` 만 쓴다.** 관리 포트 `9000` 은 Ingress·NodePort·LoadBalancer·Host Nginx 어디에도 없다.(관측 — evidence `cluster-services-and-ingress`) CR 안에 NetworkPolicy 선언이 들어 있어서 Operator 가 `keycloak-network-policy` 하나를 만든다. 라이브의 ingress 규칙은 **셋**이다.(관측) | 포트 | 출발지 | |---|---| | TCP 8080 | `kube-system` 의 Traefik 파드 | | TCP 7800 · 57800 | **같은 Keycloak 파드 자신** — Infinispan 클러스터링 포트 | | TCP 9000 | `keycloak` 의 Operator, `observability` 의 Prometheus | CR 에는 `https` 목록도 있지만 TLS 를 껐기 때문에 **8443 규칙은 렌더되지 않았다.** 인스턴스가 하나라 7800·57800 규칙은 지금 아무 트래픽도 나르지 않지만 규칙 자체는 존재한다. ### 9.3 realm 하나와 client 넷 `hyeonworks` realm 하나에 confidential client 넷이 붙는다. | client | 소비자 | Secret | 권한 게이트 | |---|---|---|---| | `gitea` | Gitea | `gitea/gitea-keycloak-oidc` (`key`,`secret`) | 없음 — 로그인하면 계정 생성 | | `aistor-console` | AIStor Console | `object-storage/aistor-keycloak-oidc` (`client-id`,`client-secret`) | group `/platform-object-admins` → `policy=consoleAdmin` | | `pgadmin` | pgAdmin | `platform-admin/pgadmin-keycloak-oidc` | group `/platform-db-admins` | | `grafana` | Grafana | `observability/grafana-keycloak-oidc` | group `/platform-observability-admins` → Admin, `/platform-observability-viewers` → Viewer | (관측 — 네 Secret 모두 실재. evidence `secret-inventory-names-only`. client 설정 자체는 Keycloak 관리 API 를 안 불러서 선언·기록 근거다) **권한을 group 으로 나르는 방식이 제품마다 다르다.** - **Grafana** — `groups` claim 의 full-path 를 JMESPath 로 읽어 role 로 바꾼다. ```text role_attribute_path: contains(groups[*], '/platform-observability-admins') && 'Admin' || contains(groups[*], '/platform-observability-viewers') && 'Viewer' || null ``` 게이트는 두 겹이다. 그 앞에 `allowed_groups: /platform-observability-admins /platform-observability-viewers` 가 먼저 걸리고, 뒤에서 `role_attribute_strict: true` 가 `null` 을 거부한다. `allow_assign_grafana_admin: false` 이므로 여기서 주는 `Admin` 은 **organization Admin 이고 server-wide `GrafanaAdmin` 이 아니다.** - **AIStor** — group 의 속성을 aggregate mapper 가 `policy` claim 으로 만들고, `MINIO_IDENTITY_OPENID_CLAIM_NAME=policy` 로 읽는다. 즉 Keycloak 이 IAM policy 이름을 직접 발급한다. - **pgAdmin** — `OAUTH2_ADDITIONAL_CLAIMS: {'groups': ['/platform-db-admins']}` 로 claim 일치를 요구한다. 통과해도 `OAUTH2_AUTO_CREATE_USER` 로 pgAdmin 사용자만 생기고 **PostgreSQL 권한은 자동으로 안 준다.** - **Gitea** — group 게이트가 없다. 대신 `ALLOW_ONLY_EXTERNAL_REGISTRATION=true` 로 로컬 가입을 막고 OIDC 로만 계정이 생기게 한다. ### 9.4 break-glass 가 네 곳에 있다 OIDC 가 죽어도 들어갈 길을 제품마다 남겼다. | 서비스 | 비상 경로 | 근거 | |---|---|---| | Gitea | `gitea-admin` Secret 의 로컬 관리자, `ENABLE_PASSWORD_SIGNIN_FORM: true` | 관측(Secret) + 선언 | | Grafana | `grafana-admin` Secret, `auth.basic.enabled: true`, `oauth_auto_login: false` | 관측 + 선언 | | pgAdmin | `pgadmin-bootstrap` Secret, `AUTHENTICATION_SOURCES = ['oauth2','internal']` | 관측 + 선언 | | AIStor | `aistor-root-configuration` 의 root 계정, `disableRoot: false` | 관측 + 선언 | **Keycloak 에는 설계된 break-glass 가 없다. 그런데 사실상의 경로가 공개면에 있다.** `keycloak-initial-admin` Secret 은 실재한다(`kubernetes.io/basic-auth`, key `username`· `password`). Operator 가 만든 bootstrap 임시 리소스이고 중앙 문서는 "named 관리자와 MFA로 교체해야 한다"고 적는데 **교체됐다는 기록이 없다.**(관측 — Secret 실재. 교체 여부 미확인) 그리고 그 계정이 로그인하는 화면이 열려 있다. `id.learn.hyeonworks.com` 의 server block 에는 `allow`/`deny` 가 **없다** — `grafana`·`storage-admin`·`db-admin` 셋과 다르다(§4.1(4)). 그래서 관리 콘솔이 같은 공개 경로로 응답한다.(관측 — desktop 이 아닌 별도 호스트에서) ```text https://id.learn.hyeonworks.com/admin/ 302 → /admin/master/console/ https://id.learn.hyeonworks.com/admin/master/console/ 200 https://id.learn.hyeonworks.com/realms/master/.well-known/… 200 ``` **이것은 OIDC 경로가 아니다.** `hyeonworks` realm 의 discovery 를 공개하는 것은 설계다 — 브라우저가 거기서 로그인해야 하니까. 그런데 같은 hostname 이 `master` realm 의 discovery 와 **관리 콘솔 로그인 화면**까지 함께 낸다. ADR-0008 은 「관리 화면 이름이 공개 DNS 에 나타나지 않는다」를 원칙으로 세우고 Console·pgAdmin 에 적용했는데, **Keycloak 자신의 관리 화면은 그 원칙 밖에 있다.**(관측 + 추론) 실제 위험은 자격 증명의 강도와 로그인 시도 제한에 달려 있고 이 문서는 둘 다 확인하지 않았다 (미확인 — 로그인을 시도하지 않았다). 다만 **경계가 설계 원칙과 다르다는 것은 사실이다.** 좁히는 방법은 두 가지다 — Host Nginx 의 `id` server block 에서 `/admin` 과 `/realms/master` 만 source allowlist 뒤로 보내거나, Keycloak 의 관리 인터페이스를 별도 hostname·포트로 떼는 것이다. 어느 쪽도 지금은 안 되어 있다. ### 9.5 Gitea 의 서버 측 discovery 경로 Gitea 파드가 `https://id.learn.hyeonworks.com/.../openid-configuration` 을 부를 때 나가는 경로가 좁혀져 있다. ```text Gitea Pod → CoreDNS(coredns-custom) 가 id.learn… → 192.168.0.107 로 답 → NetworkPolicy gitea-allow-host-nginx-keycloak 이 192.168.0.107/32:443 만 허용 → Host Nginx :443 → Traefik :30080 → Keycloak :8080 ``` **노드로 가는 길은 이 `/32` 하나로 못 박혀 있다.** 다만 「사설 대역으로는 못 나간다」는 정확하지 않다. `gitea-allow-public-git-https` 의 except 는 `10.0.0.0/8`·`172.16.0.0/12`· `192.168.0.0/16`·`169.254.0.0/16` **넷뿐이고 `100.64.0.0/10` 이 없다.** 노드의 Tailscale 주소 `100.92.240.34` 가 그 대역에 있으므로 CGNAT 쪽 443 은 선언상 한 갈래 더 열려 있다.(관측) 같은 문서의 Alertmanager 정책(§12.3)은 그 대역을 뺐는데 Gitea 정책은 안 뺐다. --- ## 10. 서비스 세 편 ### 10.1 Gitea — build root 가 둘이다 같은 chart 를 두 개의 build root 가 쓴다. ```text services/gitea/ ← baseline. Keycloak 없이 최초 생성용 kustomization.yaml base/{pvc,ingress,network-policies}.yaml branding/… ← baseline 은 안 씀 profiles/oidc/ kustomization.yaml ← OIDC desired profile values/baseline.yaml ← 둘이 공유 values/oidc.yaml ← OIDC profile 만 network-policy.yaml ← Keycloak egress patches/delete-ssh-service.yaml ``` `render-phase1.sh` 가 baseline 을 `gitea.yaml`, profile 을 `gitea-oidc.yaml` 로 따로 렌더한다. **Gitea 단계에 한정하면 `apply-phase1-gitea.sh` 는 baseline `gitea.yaml` 만 적용하고, `apply-gitea-oidc.sh` 는 `gitea-oidc.yaml` 하나만 적용한다.** 스크립트 전체로 보면 `apply-phase1-gitea.sh` 는 Phase 1 을 통째로 세우는 것이라 다섯을 순서대로 적용한다 — `namespaces.yaml` → `ssd-local-pv.yaml` → `cnpg-operator.yaml` → `platform-postgres.yaml` → `gitea.yaml`. 그 사이에 `prepare-ssd-local-paths.sh` 와 `create-phase1-secrets.sh --execute` 도 부른다.(관측) 적용 책임을 나눈 이유는 OIDC 설정이 공개 discovery 가 살아 있어야만 의미가 있기 때문이다 — `apply-gitea-oidc.sh` 는 적용 전에 공개 discovery 의 exact issuer 와 OIDC Secret 의 type·key 계약과 현재 Gitea health 를 먼저 확인한다.(선언) | 항목 | 값 | |---|---| | 이미지 | `docker.gitea.com/gitea:1.27.0-rootless` (관측) | | replica | 1, `RollingUpdate` with `maxSurge: 0`, `maxUnavailable: 1` | | 자원 | request `250m/512Mi` → limit `2 CPU/2Gi` | | Service | ClusterIP `3000` 하나. SSH Service 는 patch 로 삭제 | | DB | `platform-postgres-rw.platform-data.svc.cluster.local:5432/gitea`, `SSL_MODE: disable` | | 끈 것 | SSH · LFS · Actions · Package Registry · 내장 PostgreSQL · Valkey | `maxSurge: 0` 은 취향이 아니라 제약이다. **Local RWO 볼륨은 기존 파드와 교체 파드가 동시에 잡을 수 없다.** 그래서 새 파드를 먼저 띄울 수 없고 옛 파드를 먼저 내려야 한다. 같은 이유로 pgAdmin·Grafana 는 아예 `Recreate` 전략이다.(선언 + 추론) 관측: 파드 age 39d(OIDC rollout 시점), 공개 `https://git.learn.hyeonworks.com/api/healthz` 가 HTTP 200. ### 10.2 MinIO AIStor — S3 는 안 열고 Console 만 연다 | 항목 | 값 | |---|---| | Operator | `aistor` namespace, 파드 3개 (object-store-operator · adminjob-operator · object-store-webhook) | | ObjectStore | `object-storage/minio-aistor`, pool-0, `servers: 1`, `volumesPerServer: 1` | | 상태 | `Initialized` / `green`, `drivesOnline: 1`, `drivesOffline: 0`, `writeQuorum: 1` | | 용량 | capacity `999,892,553,728` bytes, usage `20,085,288,960` bytes | | chart | Operator `aistor-operator 5.10.0`(SHA-256 `e5534f5a…babd1`), ObjectStore `aistor-objectstore 1.0.16`(SHA-256 `50ffa6a4…bf71e`) | | Service | `minio:80`(S3), `minio-aistor-console:9090`, `minio-aistor-hl`(headless 9000·4444) — 전부 ClusterIP | | PV·PVC request | `900Gi` — **XFS 가 `noquota` 라 강제되지 않는다**(§3.2). 아래 capacity 는 932GiB 파일시스템 쪽 값이다 | | PVC 보호 | `pvcProtection: true` | | 자원 | server request `500m/2Gi` → limit `3 CPU/8Gi`, sidecar `100m/128Mi` → `500m/512Mi` | | 보안 | `runAsUser/Group/fsGroup: 1000`, `fsGroupChangePolicy: OnRootMismatch`, cap drop ALL | (관측 — evidence `aistor-objectstore-and-bucket-usage`, `cluster-services-and-ingress`) **`writeQuorum: 1` 은 쓰기 하나만 성공하면 끝난다는 뜻이다.** 서버 1대·볼륨 1개이므로 erasure coding 도 복제도 없다. 드라이브가 죽으면 모든 버킷이 같이 죽는다. `profiles/admin-oidc` 오버레이가 baseline 위에 Console Ingress·OIDC 환경변수·NetworkPolicy 를 더한다. **baseline 과 OIDC profile 이 갈려 있어 OIDC 만 되돌릴 수 있다** — 데이터와 PVC 는 건드리지 않고. `MINIO_PROMETHEUS_AUTH_TYPE: public` 이 붙어 있어서 metrics 를 인증 없이 긁는다. **그런데 MinIO 는 S3 와 metrics 를 같은 9000 에 올린다.** 그래서 「Prometheus 만 본다」가 아니다 — TCP 9000 ingress 를 **네 정책**이 연다: `object-storage-allow-prometheus-metrics`(Prometheus), `…-allow-observability-s3`(Loki·Tempo), `…-allow-internal-clients`(같은 namespace 의 `aistor-client=true` 와 ObjectStore 파드), `…-allow-aistor-operator`. **S3 를 쓰라고 연 길이 그대로 metrics 길이고, 그 위에 인증이 없다.**(관측) ### 10.3 pgAdmin — 비밀번호를 저장하지 못하게 한다 | 항목 | 값 | |---|---| | chart | OCI `docker.io/dpage/pgadmin4-helm:9.16.0`, 이미지 `9.16` digest 고정 | | namespace | `platform-admin`, PSS enforce **restricted** | | replica | 1, `Recreate` | | 스토리지 | 2Gi `ssd-local-pgadmin-retain` | | 자원 | request `250m/512Mi` → limit `1 CPU/1Gi` | | 보안 | `runAsUser/Group: 1001`, `readOnlyRootFilesystem: true`, cap drop ALL, seccomp+AppArmor RuntimeDefault, SA token automount off | `config_local.py` 를 Secret 이 아니라 **ConfigMap 으로 read-only 마운트**한다 — 비밀이 아니기 때문이다. OIDC client id/secret 만 환경변수로 주입한다. 세 줄이 이 설정의 성격을 정한다. ```python ALLOW_SAVE_PASSWORD = False ALLOWED_HOSTS = ['db-admin.learn.hyeonworks.com'] ENABLE_PSQL = False ENABLE_SERVER_PASS_EXEC_CMD = False ``` 공유 서버 정의 둘(`Hyeonworks Gitea`, `Hyeonworks Keycloak`)에 **비밀번호를 넣지 않고** `sslmode: require` 만 건다. 즉 pgAdmin 에 로그인해도 DB 비밀번호를 따로 알아야 한다. `PGADMIN_REPLACE_SERVERS_ON_STARTUP: "True"` 로 서버 정의는 매번 선언으로 덮어쓴다. probe 셋이 전부 `Host: db-admin.learn.hyeonworks.com` 헤더를 붙여 `/misc/ping` 을 친다 — `ALLOWED_HOSTS` 때문에 헤더 없이는 통과하지 못한다.(선언 + 추론) --- ## 11. 관측성 — 세 신호가 각각 다른 길로 들어온다 ### 11.1 전체 배치 ```text ┌──────────────── observability-agent (PSS privileged) ───────────────┐ │ Alloy DaemonSet node-exporter DaemonSet │ │ ├ /var/log/pods (hostPath, ro) 호스트 CPU·메모리·FS·inode │ │ └ OTLP/gRPC :4317 │ └───────┬──────────────────────┬──────────────────────────────────────┘ log │ trace │ metric ▲ (pull) ▼ ▼ │ ┌──────────────────── observability (PSS restricted) ─────────────────────────┴────────┐ │ Loki :3100 ──┐ Tempo :4317/:3200 ─┐ Prometheus :9090 │ │ WAL 5Gi │ WAL 5Gi │ TSDB 20Gi · 15d/16GB │ │ │ │ │ │ │ │ └──── AIStor S3 ────────────────┘ │ ▼ │ │ loki 30일 · tempo 7일 │ Alertmanager :9093 │ │ │ 120h · 1Gi │ │ kube-state-metrics Blackbox :9115 │ │ │ │ ▼ ▼ │ │ Grafana :3000 ◀── 5 dashboard ◀──── Slack (public 443) │ └────────────────────────────────────────────────────────────────────────────────────┘ ``` 관측 시점 전부 Ready: Grafana·Prometheus·Alertmanager·Loki·Tempo·Alloy·node-exporter· kube-state-metrics·blackbox-exporter·prometheus-operator.(관측) ![왼쪽의 호스트 커널·파일시스템, /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)
Diagram description 수집 계층은 observability-agent namespace 다. Alloy DaemonSet 이 노드의 /var/log/pods 를 read-only hostPath 로 읽어 Loki 의 3100 으로 밀고, 애플리케이션의 OTLP/gRPC 4317 을 받아 Tempo 의 4317 로 민다. node-exporter 는 호스트 지표를 노출만 하고, Prometheus 가 그것을 끌어간다. Prometheus 는 kube-state-metrics 와 Blackbox Exporter 도 끌어간다. 저장 계층은 observability namespace 다. Prometheus 는 로컬 TSDB 20Gi 에 15일 또는 16GB 까지 담고, Loki 와 Tempo 는 로컬 PV 를 WAL 로만 쓰고 본 객체를 AIStor S3 의 loki 버킷과 tempo 버킷에 보낸다. 조회는 Grafana 한 곳에서 한다. 경보는 Prometheus 가 평가해 Alertmanager 로 보내고 Alertmanager 만 공개 HTTPS 443 으로 나가 Slack 에 전달한다. 이 그림의 화살표는 TCP 연결을 거는 쪽이 아니라 데이터가 흐르는 쪽을 가리킨다. Prometheus 와 Grafana 는 스스로 연결을 걸지만 데이터는 target 과 backend 에서 그쪽으로 온다. Prometheus 는 Alloy 와 Loki 자신의 지표도 끌어가지만 이 그림에서는 세 신호의 경로를 흐리지 않도록 생략했다.
[Editable source](assets/diagrams/observability-signal-paths/observability-signal-paths.drawio) · [Grounded VizSpec](.techviz/observability-signal-paths/spec.json) ### 11.2 Prometheus — 두 겹 selector 로 소유권을 가른다 ```yaml serviceMonitorNamespaceSelector: { matchLabels: { observability.hyeonworks.com/enabled: "true" } } serviceMonitorSelector: { matchLabels: { observability.hyeonworks.com/instance: home } } ``` `podMonitor`·`probe`·`rule` 도 같은 모양이고, 네 `…SelectorNilUsesHelmValues` 가 전부 `false` 다. **namespace 에 label 이 있고 객체에도 label 이 있어야 선택된다.** 이것이 만드는 실용적 효과: **미래의 애플리케이션 저장소가 자기 ServiceMonitor 를 만들어도 플랫폼이 namespace 에 label 을 붙이기 전에는 수집되지 않는다.** 소유권 경계를 label 로 표현했다. label 이 붙은 namespace 다섯: `kube-system`, `gitea`, `keycloak`, `platform-data`, `object-storage` (+ `observability`, `observability-agent` 자신). 저장소의 `infrastructure/namespaces/observability/discovery-namespaces.txt` 가 그 다섯을 적는다. **이 파일은 kustomization 에 들어 있지 않다** — 목록만 있다. README 는 그 label 을 「later apply workflow」가 소유한다고 적는데 **저장소에서 그 label 을 붙이는 스크립트를 찾지 못했다**(관측 — `grep` 결과 렌더 검증 스크립트 하나만 걸린다). 라이브 namespace 에 label 이 붙어 있는 것은 사실이고, 무엇이 붙였는지는 미확인이다. 수집 기준: `scrapeInterval: 30s`, `evaluationInterval: 30s`, 보존 `15d` / `16GB` 중 먼저 닿는 쪽. **Prometheus 는 `16GB` 를 16 GiB 로 읽는다** — `prometheus_tsdb_retention_limit_bytes` 가 `17,179,869,184` 다. 관측 시점 block 크기 `4,657,964,807` bytes 로 그 한도의 **약 27%**.(관측) **관측: active target 30, healthy 30 (30/30).** job 별 분포: ```text kubelet 3 · apiserver 1 · coredns 1 · kube-state-metrics 1 · prometheus-node-exporter 1 observability-core-kube-pr-prometheus 2 · …-alertmanager 2 · …-operator 1 traefik 1 · gitea 1 · keycloak-service 1 · platform-postgres 1 · minio-aistor 1 alloy 1 · observability/loki 1 · tempo 1 · grafana 1 · blackbox-exporter 1 blackbox-public-edge 2 · blackbox-private-edge 3 · blackbox-private-internal 3 ``` 끈 것: `kubeControllerManager`, `kubeScheduler`, `kubeEtcd`, `kubeProxy`. **단일 노드 k3s 에서는 이 넷이 별도 엔드포인트로 노출되지 않아 항상 down 으로 보인다.** 켜 두면 영구 false alarm 이 된다.(선언 + 추론) ### 11.3 Blackbox — 경계마다 기대하는 응답이 다르다 Probe 셋이 세 그룹으로 나뉘고, **그룹마다 성공의 정의가 다르다.** | Probe | module | 대상 | 성공 조건 | |---|---|---|---| | `platform-public-edge` | `http_2xx` | `https://git.learn.hyeonworks.com/api/healthz`, `https://id.learn.hyeonworks.com/realms/hyeonworks/.well-known/openid-configuration` | 2xx | | `platform-private-edge` | `http_private_edge_403` | `https://grafana…/`, `https://storage-admin…/`, `https://db-admin…/` | **403** | | `platform-private-internal` | `http_private_internal_200` | `http://grafana.observability…/api/health`, `http://pgadmin.platform-admin…/misc/ping`, `http://minio-aistor-console.object-storage…:9090/` | 200 | **`private-edge` 는 403 을 성공으로 센다.** blackbox 파드는 클러스터 안에 있으므로 Host Nginx 에서 볼 때 source 가 `10.42.0.1` 이고 LAN·Tailscale allowlist 밖이다. 그래서 **allowlist 가 살아 있으면 403 이 온다.** 만약 200 이 오면 allowlist 가 사라진 것이고, 그것이 `probe_success=0` 으로 잡힌다. **경계가 열린 것을 장애로 감지하는 probe 다.** `private-internal` 은 클러스터 내부 Service 를 직접 치되 `__param_hostname` relabeling 으로 각 애플리케이션이 기대하는 `Host` 헤더를 만들어 준다 — pgAdmin 의 `ALLOWED_HOSTS` 와 Grafana 의 `enforce_domain: true` 를 통과하기 위해서다. ### 11.4 규칙 — 플랫폼 22 + 생성 133 = 155 관측: **alert rule 155개, recording rule 86개, group 36개, firing 0, pending 0, unhealthy 0.** (evidence `prometheus-targets-and-rules`) 문서는 "155 = generated 133 + platform 22" 와 "platform recording rule 1" 을 적는다. 라이브의 recording rule 86 은 그 1 + kube-prometheus-stack 이 만드는 85 다.(관측 + 추론) 플랫폼 규칙 22개는 `PrometheusRule` 넷에 나뉜다. | 파일 | group | 내용 | |---|---|---| | `core-rules.yaml` | `platform.storage` · `platform.workloads` | PVC 미바인딩, root FS 사용률 3단계, inode 2단계, 재시작 burst, OOMKilled | | `certificate-rules.yaml` | `platform.blackbox` · `platform.certificates` | probe 실패 3그룹, 만료 30일 warning / 14일 critical | | `storage-quota-rules.yaml` | `platform.aistor-storage-quota` | recording rule 1 + quota 사용률 70/85/95 | | `verified-service-rules.yaml` | `platform.verified-services` | CNPG collector down, Alloy config load 실패·재시도·drop, Loki reload 실패·WAL 80% | **임계값을 셋으로 쪼갠 이유.** root filesystem 은 `>75% for 30m` = info, `>85% for 15m` = warning, `>90% for 5m` = critical 이다. **한계에 가까울수록 관측 창을 짧게 잡는다.** 여유가 있을 때는 30분을 기다려 순간 튐을 걸러내고, 임박하면 5분 만에 깨운다. **그런데 `PlatformLokiWALDiskUsageHigh` 는 Loki 를 보지 않는다.** 관측 시점 `loki_ingester_wal_disk_usage_percent` 가 약 `0.606` 인데 Loki 의 WAL 은 9.9 MiB 뿐이다(§7.4). 이 metric 은 Loki 자신의 사용량이 아니라 **WAL 이 놓인 파일시스템의 사용률**이다. 근거 셋: metric 의 HELP 가 `Current disk usage percentage (0.0 to 1.0) for the WAL directory` 이고, 24시간 48표본에서 이 값과 루트 파일시스템의 `1 - free/total` 이 **소수점 5~6자리까지 함께 움직이며**(예: `0.604119` ↔ `0.604118`), Loki 가 9.9 MiB 를 쓰는데 값이 60% 대인 것은 그것으로만 설명된다.(관측) 그래서 이 경보는 `>= 0.8` 에서 **루트 파일시스템이 80% 에 닿을 때** 울린다. 즉 `PlatformRootFilesystemUsage` 와 같은 것을 다른 이름으로 한 번 더 세는 셈이고, **Loki 의 WAL 이 혼자 불어나는 상황은 잡지 못한다**(§18.6). **임계값에 가장 가까운 것은 이 경보가 아니다.** 루트 파일시스템 사용률이 `65.8` 로 첫 임계 `75` 까지 9.2pp 인데, 이 WAL 경보는 `0.607` 로 임계 `0.8` 까지 19.3pp 다. 두 값이 같은 것을 보고 있으므로 **먼저 울리는 쪽은 언제나 `PlatformRootFilesystemUsage` 다.** `verified-service-rules` 라는 이름이 말하는 것: **실제로 존재하는 metric 만 쓴 규칙이다.** `cnpg_collector_up`, `alloy_config_last_load_successful`, `loki_write_batch_retries_total`, `loki_write_dropped_entries_total`, `loki_runtime_config_last_reload_successful`, `loki_ingester_wal_disk_usage_percent` 여섯을 inventory 로 확인한 뒤 규칙을 만들었다 — 중앙 문서가 "inventory 를 먼저 수집한 뒤에만 만들도록 분리했다" 고 기록한다. AIStor quota recording rule: ```promql platform:aistor_bucket_quota_usage_percent = 100 * max by (bucket) (minio_cluster_usage_buckets_total_bytes{bucket=~"loki|tempo"}) / max by (bucket) (minio_cluster_usage_buckets_quota_total_bytes{bucket=~"loki|tempo"} > 0) ``` 분모에 `> 0` 이 붙어 있다. **quota 를 안 건 버킷은 분모가 0 이 되어 규칙이 무한대를 내는 대신 결과에서 빠진다.** 관측 시점 `loki` 0.403%, `tempo` 0% 로 둘 다 값이 나오므로 두 버킷에 quota 가 실제로 걸려 있다.(관측 + 추론 — `loki` 866,300,448 bytes ÷ 0.40340% ≈ 214,748,364,800 bytes = 200Gi, 문서의 승인값과 일치) ### 11.5 Alertmanager — 묶는 키에 severity 를 넣었다 ```text groupBy: cluster, namespace, alertname, severity groupWait: 30s groupInterval: 5m repeatInterval: 4h receiver: platform-slack (sendResolved: true) child route: alertname=InfoInhibitor → platform-null inhibitRule: InfoInhibitor → 같은 namespace 의 severity=info 억제 ``` **`severity` 를 group key 에 넣으면 무엇이 달라지나.** 같은 alertname 의 warning 과 critical 이 한 메시지로 섞이면 색과 제목이 둘 중 하나로 정해져 버린다. 갈라 놓으면 각각 제 색으로 온다. `InfoInhibitor` 는 kube-prometheus-stack 이 info 억제를 구현하려고 만든 **제어용 alert** 이지 장애 통지가 아니다. 그런데 Alertmanager 입장에서는 그냥 alert 라서 Slack 에 firing / resolved 가 찍혔다. child route 로 integration 이 없는 `platform-null` 로 보내서 **Slack 에는 안 보내되 inhibit source 로서의 의미는 유지한다.** 관측 런타임 receiver 는 정확히 둘이다. ```text observability/platform-alertmanager/platform-null observability/platform-alertmanager/platform-slack ``` **Prometheus Operator 가 `//` 로 이름을 다시 짓는다.** 소스에 적은 `platform-slack` 과 런타임 이름이 다르고, 이것을 몰라서 postcheck 가 정상 상태를 실패로 판정하고 rollback 한 사건이 있다(§17.4). Slack 메시지 구조: 제목에 `[FIRING:n]`/`[RESOLVED]` + severity + alertname, color 는 resolved green / critical·emergency red / warning yellow / 나머지 blue, short field 넷(Status, Severity, Location=`cluster / namespace`, Alert count), alert 마다 group label 을 뺀 target label 전체 + summary + description + 시작·종료 시각 + runbook 링크, 끝에 Grafana·Explore 링크와 footer. 관측: active alert 0, silence 0, Alertmanager `0.33.1`, cluster mode `disabled`(단일 노드). ### 11.6 로그와 trace — 수집 범위가 좁다 **Alloy 가 읽는 것은 이 노드에 뜬 파드의 stdout/stderr 뿐이다.** ```text discovery.kubernetes "pods" { selectors { field = "spec.nodeName=" + sys.env("HOSTNAME") } } → /var/log/pods/*//*.log (hostPath ro) → CRI 또는 Docker parser → 마스킹 4단계 → level 추출 (허용 목록 밖이면 label 버림) → label_keep: cluster, namespace, app, pod, container, level → loki.write http://loki.observability.svc.cluster.local:3100 ``` **안 읽는 것**: Host Nginx access/error 로그, k3s·systemd journald, SSH/auth, kernel/audit, 파일로만 쓰는 애플리케이션 로그. ELK 계열은 아예 없다. 마스킹은 Loki 로 보내기 **전에** Alloy 에서 한다. 정규식 넷이 JSON 필드형·헤더형·bearer· key=value 형을 각각 잡아 `[REDACTED]` 로 바꾼다. 중앙 문서는 이것을 "심층 방어"로 규정하고 **애플리케이션의 선제 마스킹이 권위**라고 적는다 — 즉 Alloy 마스킹을 믿고 로그에 비밀을 써도 된다는 뜻이 아니다. label 을 여섯으로 못 박은 것은 **cardinality 통제**다. `trace_id`·`request_id`·원시 URL· 사용자 식별자를 label 로 만들지 않는다. 그것들은 로그 본문에 남고 검색은 문자열 filter 로 한다. trace 경로: ```text application OTLP/gRPC :4317 → Alloy k8sattributes (namespace·deployment·node·pod·uid·start_time·container 부착) → batch 1s / 512 · max 1024 → otlp exporter → tempo:4317 (retry 1s~15s, 최대 5m · queue 256, block_on_overflow) → Tempo → AIStor tempo 버킷 ``` **보내는 쪽이 아직 없다.** `tempo` 버킷 0 bytes 가 그 증거다. Tempo 의 `metricsGenerator.enabled: false` 이므로 service map·node graph 데이터도 생기지 않는다. Loki ↔ Tempo 상관은 양방향으로 설정돼 있다. Loki datasource 의 derived field 가 `"trace_id": "<32 hex>"` 를 찾아 Tempo 로 링크하고, Tempo 의 `tracesToLogsV2` 가 `k8s.namespace.name → namespace`, `k8s.pod.name → pod` 태그와 ±1분 창으로 Loki 로 돌아온다. **설정만으로는 연결이 안 생긴다** — 애플리케이션이 같은 32자리 trace ID 를 구조화 로그에 써야 한다. ### 11.7 Grafana — Git 이 권위다 ```text Git JSON → 안정 이름 ConfigMap(grafana_dashboard=1) → grafana-sc-dashboard WATCH → /tmp/dashboards → Grafana file provider (30s) ``` `disableNameSuffixHash` 로 ConfigMap 이름이 해시로 안 바뀌고, `allowUiUpdates: false` 이며 각 dashboard JSON 도 `editable: false` 다. **UI 에서 고친 것은 다음 동기화에서 남는다고 가정하지 않는다.** 권한이 갈려 있다: **main Grafana 컨테이너는 ServiceAccount token 을 automount 하지 않는다.** 3600초 projected token 은 `grafana-sc-dashboard` 사이드카에만 붙고, 그 Role 은 `observability` namespace 의 ConfigMap `list`/`watch` 만 갖는다. Secret 권한이 없다. dashboard 다섯(전부 Prometheus datasource, `now-6h`, refresh 30s): `platform-kubernetes-node`(5패널) · `platform-workload-health`(4) · `platform-services`(8) · `platform-observability-backends`(7) · `platform-https-endpoints`(4). **로그 전용 dashboard 가 없다.** 로그와 trace 는 Explore 에서만 본다. 중앙 문서가 이것을 후속 우선순위 1번으로 적는다. 관측: Grafana `13.1.1`, sidecar `2.10.0`, `https://grafana.learn.hyeonworks.com/api/health` HTTP 200. ![Git JSON 이 desired state 로, 사이드카가 controller 로, Grafana 가 actual state 로 놓이고 파일 provider 가 30초마다 되돌리는 고리를 이루는 구조도. UI 편집은 이 고리 바깥에서 actual state 에만 닿는다.](assets/diagrams/dashboard-authority-loop/dashboard-authority-loop.svg)
Diagram description Git 저장소의 dashboard JSON 이 desired state 다. Kustomize 가 disableNameSuffixHash 로 안정 이름 ConfigMap 을 만들고 grafana_dashboard=1 label 을 붙인다. grafana-sc-dashboard 사이드카는 observability namespace 의 ConfigMap 을 list 와 watch 만 할 수 있는 Role 로 WATCH 하고, 변경을 /tmp/dashboards 에 반영한다. Grafana file provider 가 30초마다 그 디렉터리를 읽어 actual state 를 맞춘다. allowUiUpdates 는 false 이고 각 dashboard JSON 도 editable 이 false 라, 브라우저에서 고친 것은 이 고리에 들어가지 못하고 다음 동기화에서 덮인다. main Grafana 컨테이너는 ServiceAccount token 을 automount 하지 않으므로 Kubernetes API 로 스스로 상태를 되돌릴 수도 없다.
[Editable source](assets/diagrams/dashboard-authority-loop/dashboard-authority-loop.drawio) · [Grounded VizSpec](.techviz/dashboard-authority-loop/spec.json) --- ## 12. 네트워크 정책 — default-deny 는 네 namespace뿐이다 ### 12.1 전체 분포 관측: NetworkPolicy 58개.(evidence `cluster-networkpolicy-and-storage`) | namespace | 개수 | default-deny | 범위 | |---|---:|---|---| | `observability` | 18 | 있음 | namespace 전체 | | `object-storage` | 11 | 있음 | namespace 전체 | | `gitea` | 7 | 있음 | **Gitea 파드만** | | `platform-admin` | 6 | 있음 | **pgAdmin 파드만** | | `observability-agent` | 6 | 있음 | namespace 전체 | | `aistor` | 5 | 있음 | namespace 전체 | | `platform-data` | 3 | **없음** | ingress 만 제한 | | `kube-system` | 1 | 없음 | Traefik ingress 보존 + Prometheus 허용 | | `keycloak` | 1 | 없음 | CR 이 만든 정책 | | `cnpg-system` | **0** | 없음 | 정책 없음 | **namespace 전체를 막는 default-deny 는 넷이다** — `observability`, `observability-agent`, `object-storage`, `aistor`. `gitea` 와 `platform-admin` 의 default-deny 는 podSelector 가 붙어 있어서 **그 namespace 에 다른 파드가 생기면 정책 밖이다.**(관측 — POD-SELECTOR 칸) `cnpg-system` 에는 정책이 하나도 없다. **PostgreSQL Operator 는 자유롭게 통신한다.** ### 12.2 Gitea 의 일곱 | 정책 | 방향 | 허용 | |---|---|---| | `gitea-default-deny` | 양방향 | 전부 차단 | | `gitea-allow-traefik-http` | in | `kube-system` Traefik → 3000 | | `gitea-allow-prometheus-metrics` | in | Prometheus → metrics | | `gitea-allow-dns` | out | kube-dns 53 | | `gitea-allow-platform-postgres` | out | `platform-data` PostgreSQL 5432 | | `gitea-allow-public-git-https` | out | 사설·link-local 뺀 외부 IPv4 443 | | `gitea-allow-host-nginx-keycloak` | out | `192.168.0.107/32` 443 | 마지막 둘의 관계가 이 정책 집합의 설계 의도를 보여 준다. **외부 Git remote 는 열되 사설 대역을 빼고, 그 예외로 노드 주소 하나를 뚫었다.** 다만 「못 나가는 것」을 정확히 적으면 좁다. except 는 `10.0.0.0/8`·`172.16.0.0/12`· `192.168.0.0/16`·`169.254.0.0/16` 넷이고 **`100.64.0.0/10` 이 빠져 있다** — 노드의 Tailscale 주소가 그 대역이다. 그리고 공개 IPv4 의 443 이 열려 있으므로 **공개 HTTPS 로 가는 webhook 은 나간다.** 실제로 막히는 것은 사설 IPv4 대역의 HTTPS 와, 443 이 아닌 포트(SMTP·SSH 등)다.(관측) ### 12.3 관측성의 열여덟 수집·질의·전송이 각각 정책이 된다. ```text in : Prometheus ← KSM · operator · blackbox · self Grafana ← Traefik(ingress) Alertmanager← Prometheus · peer out : Prometheus → platform target 들 Grafana → datasource(Prometheus·Loki·Tempo) · Kubernetes API(sidecar) · 192.168.0.107/32:443 (Host Nginx 를 거쳐 Keycloak — OIDC 로그인) Blackbox → probe 대상 · 192.168.0.107/32:443 Loki·Tempo → AIStor Alertmanager→ public HTTPS 전부 → DNS ``` **Grafana 와 Blackbox 의 `192.168.0.107/32:443` 이 이 목록에서 가장 덜 보이는 줄이다.** Grafana 쪽은 §11.7 의 OIDC 로그인이 성립하는 길이고 — 파드가 노드 주소로 나가 Host Nginx 를 거쳐 Keycloak 으로 돌아온다(§5.2) — Blackbox 쪽은 `private-edge` probe 가 403 을 받아 오는 길이다(§11.3). 둘 다 없으면 그 기능이 죽는다. `observability-allow-alertmanager-public-https`(파일 이름은 `alertmanager-public-https-egress.yaml`) 가 유일하게 공개 인터넷으로 나간다. ```text to: 0.0.0.0/0 except: 10.0.0.0/8, 100.64.0.0/10, 172.16.0.0/12, 192.168.0.0/16 ports: TCP 443 ``` **Slack webhook 하나 때문에 열어야 하는 구멍을 「공개 IPv4 의 443」까지 좁힌 것이다.** vanilla NetworkPolicy 는 hostname 단위 egress 를 못 하므로 여기가 한계다. 사설·CGNAT 을 빼서 내부로 돌아오는 것은 막았다. ### 12.4 오브젝트 스토리지의 열하나 `object-storage-allow-observability-s3` 하나가 두 조건을 동시에 건다. ```text from: namespace observability 의 파드 중 label platform.hyeonworks.com/aistor-client: "true" 이고 이름이 loki 또는 tempo 인 것 port: TCP 9000 ``` **label 만으로는 부족하다고 보고 이름까지 건다.** 그래서 `observability` 에 label 만 붙인 다른 파드를 넣어도 S3 에 못 닿는다. `object-storage-allow-labeled-clients` 는 이름과 달리 **다른 namespace 의 클라이언트를 들여보내는 정책이 아니다.** `policyTypes: [Egress]` 이고, NetworkPolicy 의 `podSelector` 는 정책이 놓인 namespace 안에서만 파드를 고른다. 즉 **`object-storage` 안의 `aistor-client=true` 파드가 ObjectStore 로 나가는 것**을 여는 규칙이다.(관측) 밖에서 들어오는 길은 각자 자기 namespace 쪽에서 열린다 — Loki·Tempo 는 `observability-allow-aistor-egress`(§12.3)로 나가고, 받는 쪽은 위의 `object-storage-allow-observability-s3` 가 연다. **한 흐름에 정책 두 개가 양쪽에서 필요하다**는 것이 이 저장소가 `targets/counterpart-network-policies.yaml` 이라는 파일을 따로 둔 이유다. ### 12.5 이 정책들이 증명하는 것과 안 하는 것 **증명하는 것**: 선언이 클러스터에 있다. 58개가 실재한다(관측). **컨트롤러는 켜져 있다.** flannel 자체는 NetworkPolicy 를 집행하지 않지만 k3s 는 자체 netpol controller 를 함께 넣는다. 마지막 k3s 기동 로그에 그것이 있다.(관측) ```text Aug 27 12:28:20 … level=info msg="Starting network policy controller version v2.6.3-k3s1, …" Aug 27 12:28:20 … network_policy_controller.go:164] Starting network policy controller Aug 27 12:28:20 … network_policy_controller.go:179] Starting network policy controller full sync goroutine ``` **증명하지 않는 것**: 그 컨트롤러가 실제로 만든 iptables·ipset 규칙과, 허용·거부가 양방향으로 맞는지. `iptables -S` 는 root 가 필요해 못 읽었다(미확인). 중앙 문서도 "k3s CNI에서 정책이 실제 강제되는지는 양방향 allow/deny Pod 시험으로 별도 확인한다" 고 적고 **그 시험 기록이 없다.** 즉 남은 간격은 「컨트롤러가 있는가」가 아니라 **「규칙이 의도대로 걸렸는가」**다. 좁히는 방법은 §18.1 에 적는다. --- ## 13. 시크릿·암호화·복구 ### 13.1 저장소에는 자격 증명이 없다 `.gitignore` 가 막는 것: ```text .env / .env.* *.key *.pem *.p12 *.pfx *.jks *.crt *.kubeconfig / kubeconfig **/secrets/*.yaml **/secrets/*.yml infrastructure/security/k3s/local-recovery.env ← 하드웨어 식별자 .helm/ charts/ *.tgz rendered/ dist/ ``` **이름 기반 ignore 는 보조일 뿐이다.** `scripts/validate/scan-platform-sensitive-source.sh` (1,725줄)가 이름과 무관하게 소스 YAML 의 `kind: Secret` 을 거부하고, 그 스크립트의 테스트가 `test-scan-platform-sensitive-source.sh`(1,485줄)다. `local-recovery.env` 가 ignore 되는 이유는 비밀번호가 아니라 **하드웨어 식별자**다 — WWN, serial, FS UUID, PARTUUID. 파괴적 작업의 대상을 `/dev/sdX` 이름이 아니라 이 식별자 조합으로 고정하는 계약 파일이다. 작업 트리에는 있고 커밋에는 없다.(관측) ### 13.2 Secret 계약과 라이브 대조 문서가 선언한 계약 11개가 라이브에 전부 있다.(관측 — evidence `secret-inventory-names-only`) | 단계 | 객체 | type | 라이브 | |---|---|---|---| | Phase 1 | `platform-data/gitea-db-credentials` | basic-auth | ✅ | | Phase 1 | `gitea/gitea-db-credentials` | basic-auth | ✅ | | Phase 1 | `gitea/gitea-admin` | basic-auth | ✅ | | Keycloak | `platform-data/keycloak-db-credentials` | basic-auth | ✅ | | Keycloak | `keycloak/keycloak-db-credentials` | basic-auth | ✅ | | Keycloak | `gitea/gitea-keycloak-oidc` | Opaque | ✅ | | AIStor | `aistor/minio-license` | Opaque | ✅ | | AIStor | `object-storage/aistor-root-configuration` | Opaque | ✅ | | Phase 3 | `object-storage/aistor-keycloak-oidc` | Opaque | ✅ | | Phase 3 | `platform-admin/pgadmin-keycloak-oidc` | Opaque | ✅ | | Phase 3 | `platform-admin/pgadmin-bootstrap` | Opaque | ✅ | 관측성 계약 5개도 전부 있다: `observability/` 의 `grafana-keycloak-oidc`, `grafana-admin`, `loki-object-storage`, `tempo-object-storage`, `alertmanager-slack-webhook`. **중앙 문서(2026-08-09)는 이 다섯을 "아직 생성하지 않았다" 고 적는다 — 그 뒤에 만들어졌다.** 계약에 없는데 라이브에 있는 것: `object-storage/minio-license`(chart 가 복사), 각 chart 가 만드는 TLS·generated Secret 들, `keycloak/keycloak-initial-admin`. ### 13.3 two-or-none 계약 bootstrap 스크립트들이 공통으로 지키는 규칙이 하나 있다. ```text 계약의 객체가 전부 없다 → 대화형 입력 후 최초 생성 계약의 객체가 전부 있다 → type·key·교차 namespace 값 일치를 검증한다. Secret data 는 안 건드린다 일부만 있다 → 아무것도 쓰지 않고 중단 ``` 「전부 있다」 가지도 완전한 읽기 전용은 아니다. 서버 측 Secret 에 `cnpg.io/reload=true` label 이 없으면 `--overwrite` 로 **label 만 수리한다** — `Repaired cnpg.io/reload=true without changing Secret data.` 를 찍는다. data 는 그대로 두지만 「검증만 한다」는 아니다.(관측) **부분 상태를 「고쳐 주는」 동작이 없다.** Kubernetes API 호출은 트랜잭션이 아니라서 중간에 실패하면 일부 객체가 남는다. **다만 실패 처리는 셋이 같지 않다.** `create-phase1-secrets.sh` 와 `create-keycloak-secrets.sh` 는 아무것도 지우지 않고 `SAFE STOP: no Secret or database data was deleted or rolled back.` 을 찍는다. `create-aistor-secrets.sh` 는 `trap ERR → on_error → rollback_new_secrets` 로 **이번 실행이 만든 Secret 두 개를 지운다.** 「어느 쪽도 자동으로 안 지운다」가 아니라 「이미 있던 것은 안 지우고, 방금 만든 것은 되돌린다」다.(관측) 같은 이유로 **회전 기능이 없다.** `create-phase1-secrets.sh`·`create-keycloak-secrets.sh`· `create-aistor-secrets.sh` 어느 것도 rotation 을 지원하지 않는다. 회전은 「새 자격 증명 생성 → 소비자 전환 → 동작 검증 → 옛 값 폐기」의 별도 작업이다. `gitea-admin` 에는 제품 쪽 제약이 하나 더 있다. `passwordMode: initialOnlyRequireReset` 이라 **Secret 의 data 만 바꿔도 이미 만들어진 Gitea 계정 비밀번호는 안 바뀐다.** ### 13.4 k3s Secret 저장 암호화가 막는 것과 못 막는 것 **막는 것**: datastore 파일이나 snapshot 만 단독으로 새어 나갔을 때 payload 가 바로 읽히는 것. **못 막는 것**: 같은 호스트의 root 침해, full-disk 탈취. **암호화 key 와 상태 파일이 같은 호스트에 있고, server token 과 backup 을 함께 얻으면 복구 과정에서 복호화할 수 있다.** 그래서 token·config·datastore·검증 자료를 묶은 recovery bundle **전체를 하나의 Secret 으로 취급한다.** ### 13.5 로컬 LUKS 복구 매체 — 승인된 예외 원칙은 암호화된 off-host 매체다. 그런데 외장 매체가 없어서 **K3s 제어면 bundle 에 한해** 같은 섀시의 다른 물리 SSD 를 쓰기로 했다(ADR-0010). ```text /dev/sda3 NTFS (수동 mount, 평소 unmount) └ HyeonworksRecovery/ ├ vault/hyeonworks-recovery.kdbx ← LUKS 밖. 마스터 암호는 외우거나 밀봉 종이 └ containers/k3s-recovery.luks ← 32GiB 완전 할당 regular file, mode 0600 └ loop → dm-crypt LUKS2 → ext4 (label K3S_RECOVERY, root:root 0700) └ pre / post bundle ``` **장치를 이름으로 고르지 않는다.** `local-recovery.env` 의 WWN·serial·FS UUID·PARTUUID 가 전부 일치해야 하고, recovery 디스크의 parent 가 K3s root 의 parent 와 **달라야** 진행한다. `/dev/sda` 같은 커널 이름은 판정 입력으로 쓰지 않는다. 용량도 상수가 아니라 식이다. ```text P = 한 phase bundle 의 예상 bytes U = 이미 쓴 bytes 컨테이너 크기를 정할 때 (총 용량 기준): required = U + 2 × ceil(P × 1.25) + 10GiB ≤ ext4 usable capacity 매 실행 직전 (가용 공간 기준): pre 직전: 2 × ceil(P × 1.25) + 10GiB post 직전: ceil(P × 1.25) + 10GiB ``` **위와 아래는 좌변이 다른 양이다** — 위는 컨테이너를 32GiB 로 정할 때 한 번 쓰는 총 용량 식, 아래는 실행할 때마다 다시 재는 가용 공간 식이다. 32GiB 는 목표값이고 매 실행마다 아래 두 식을 다시 계산해 만족할 때만 진행한다. 바깥 NTFS 쪽에도 조건이 하나 더 있다. `local-recovery.env` 의 `OUTER_MIN_REMAINING_PERCENT=20` — 운영 컨테이너와 header 복구 시험용 전체 사본이 동시에 있어도 **파일시스템의 20% 가 남아야** 한다.(관측) 이 파일은 키 29개짜리 계약이고 위에 든 네 identity 는 그 일부다. **암호가 프로세스 경계를 넘는 방식**: KeePass 의 protected Password attribute 를 foreground anonymous pipe 로 `cryptsetup` 에만 넘긴다. argv·환경변수·명령 치환·임시 파일·stdout 어디에도 안 남긴다. LUKS header backup 은 root 전용 tmpfs `/run/hyeonworks-k3s-recovery.*` 안에서만 만들고 KeePass 첨부로 import 한 뒤 평문 파일을 지운다. `apply-k3s-secret-encryption.sh` 의 정책 계약: ```text --recovery-policy encrypted-off-host | local-separate-disk-luks (필수, 기본값 없음) 확인 문구 (순서대로): APPLY 두 정책 공통 RECOVERY 두 정책 공통 ENCRYPTED 두 정책 공통 — 문구만 다르다 off-host : "the mount is encrypted off-host media" local : "the mounted local recovery volume is LUKS2 encrypted" LOCAL_RISK_ACCEPTED 로컬 정책에서만 ``` **enum 에 기본값이 없어서 정책을 반드시 밝혀야 한다.** 로컬 정책을 고르면 마지막 문구가 「같은 섀시라는 것을 안다」는 서명 역할을 한다. **그런데 반대 방향은 막혀 있지 않다.** validator 의 off-host 가지는 한 줄이다. ```bash case "$policy" in encrypted-off-host) return 0 ;; local-separate-disk-luks) … # contract root · LUKS lineage · pinned inode · 용량 gate ``` **`encrypted-off-host` 를 고르면 아무 검사도 하지 않는다.** 로컬 디스크를 `--backup-root` 로 주고 off-host 라고 선언하면 스크립트는 막지 못한다. 장치 lineage·LUKS·contract 검사는 전부 로컬 가지에만 있다. 즉 이 계약이 방지하는 것은 **모르고 로컬을 쓰는 것**이지 **알고 거짓말하는 것**이 아니다.(관측) ### 13.6 완료된 것과 안 된 것 | 항목 | 상태 | 근거 | |---|---|---| | 32GiB LUKS2/ext4 매체 생성, close/reopen 검증 | 완료 (2026-08-08) | 기록 | | `pre` 체크포인트 — 대상 80개 `22,857,763 bytes`, SQLite quick_check | 완료 | 기록 | | LUKS header erase→restore proof (16,777,216 bytes) | 완료 (2026-08-09) | 기록 | | Secret 암호화 live 전환 `Enabled/reencrypt_finished` + post bundle | 완료 (2026-08-09) | 기록 | | 격리 restore drill | **미완료** | 기록 | | off-host 복제 | **미완료** | 기록 | | lifecycle 자동화 | **미완료** — KeePass CLI 대화형 입력과 충돌 | 기록 | | Slack webhook off-host recovery | **미완료**, `RISK_ACCEPTED` 로 진행 | 기록 | **「관측성 Phase 4 gate 가 열리지 않았다」고 문서가 적는데 관측성은 돌고 있다.** 두 gate(`--expect-reencrypted` 와 restore evidence `--check`) 중 두 번째가 성립하지 않는 상태에서 Slack Secret 을 `SLACK_DEPLOYMENT_GATE=RISK_ACCEPTED` 로 만들고 진행했다. **gate 를 통과한 것이 아니라 위험을 명시적으로 수용하고 넘어간 것이다.** 이 구분이 §17.5다. --- ## 14. 저장소 구조 — 선언보다 자동화가 여섯 배다 ### 14.1 줄 수가 말하는 것 (관측 — evidence `platform-repo-loc`) | 영역 | 파일 | 줄 | 비중 | |---|---:|---:|---:| | `scripts/` | 77 | **67,631** | **81.5%** | | `services/` | 118 | 7,468 | 9.0% | | `infrastructure/` | 91 | 4,426 | 5.3% | | `docs/` (저장소 안) | 4 | 2,112 | 2.5% | | `bootstrap/` (수동 절차) | 7 | 1,349 | 1.6% | | `components/` | 2 | 17 | 0.0% | | `clusters/` | 2 | 0 | 0.0% | | 합계 | 301 | 83,003 | | | (별도) vendored `.helm/charts` | 713 | 155,560 | git 미추적 | **선언 11,894줄 대 자동화 67,631줄 — 5.7배다.** 그리고 자동화 안에서도: | | 파일 | 줄 | |---|---:|---:| | `scripts/validate/` | 42 | 45,889 | | └ 그 중 `test-*` (스크립트 자신의 테스트) | 26 | **33,937** | | `scripts/bootstrap/` | 27 | 14,132 | | `scripts/lib/` | 5 | 5,325 | | `scripts/libexec/` | 3 | 2,285 | **테스트 33,937줄이 전체의 41%다.** git 이 추적하는 파일 중 가장 큰 것도 manifest 가 아니라 `scripts/validate/test-k3s-local-recovery.sh` (8,668줄)다. 다만 디스크 전체로 보면 그 위에 vendored CRD 가 있다 — `crd-prometheuses.yaml` 13,928줄, `crd-scrapeconfigs.yaml` 12,938줄 …(전부 `.helm/charts` 라 git 미추적).(관측) **그리고 이 6.8만 줄의 4분의 3은 §14.2 가 예로 드는 bootstrap 트랜잭션이 아니다.** | 계열 | 파일 | 줄 | `scripts/` 대비 | |---|---:|---:|---:| | `*observability*` | 21 | 20,850 | 30.8% | | `*k3s-local-recovery*` | 15 | 17,722 | 26.2% | | `*slack-webhook-recovery*` | 7 | 8,069 | 11.9% | | `*k3s-secret-encryption*` | — | 6,238 | 9.2% | | **넷 합계** | | **52,879** | **78.2%** | **이 문서는 그 셋의 이름을 거의 부르지 않는다.** 개별로 큰 것만 봐도 `configure-keycloak-grafana-oidc.sh` 1,928 · `create-observability-secrets.sh` 1,826 · `observability-smoke.sh` 1,808 · `apply-observability-access.sh` 1,419 · `libexec/slack-webhook-recovery-dirfd.py` 1,095 가 본문에 없다. 아래 §14.2 가 대표로 드는 `apply-gitea-oidc.sh` 673줄은 모집단의 **1%** 이고, 「왜 이렇게 커졌나」의 실제 답은 **관측성 Phase 4 하나와 암호화 복구 하나**다.(관측) ### 14.2 왜 이렇게 됐나 `apply-*.sh` 하나가 하는 일을 보면 이해된다. `apply-gitea-oidc.sh`(673줄)의 순서: ```text [1/8] 현재 context · 대상 node Ready 와 InternalIP 192.168.0.107 대조 · Gitea health [2/8] Host Nginx 로컬 SNI 경로로 공개 Keycloak discovery 의 exact issuer 확인 [3/8] gitea-keycloak-oidc Secret 의 type 과 key 이름만 확인 (payload 안 읽음) [4/8] 고정 chart package SHA-256 재검증 · 렌더 · handoff SHA-256 을 메모리에 저장 [5/8] 운영자 확인: Type APPLY GITEA-OIDC — context 뿐 아니라 렌더 결과의 SHA-256 64자를 그대로 쳐야 한다 [6/8] 승인 직후 context · API server · node 재검사, handoff SHA-256 재비교 [7/8] gitea-oidc.yaml 하나만 적용하고 rollout 대기 [8/8] 사후 검증 — 출처가 넷이다 OAuth source : gitea admin auth list (파드 exec) 가입 정책·scope : /data/gitea/conf/app.ini (파드 exec) OIDC redirect : HTTPS 요청의 302 Location 파싱 브랜딩 hash : 공개 URL 다운로드 → 저장소 원본과 sha256 대조 성공·실패·INT·TERM 어느 경로로 끝나도 handoff 디렉터리 제거 ``` **「적용」이 아니라 「트랜잭션」이다.** 사전 조건, 사람 확인, 확인 직후 재검사, 바이트 단위 handoff 대조, 사후 검증, 모든 종료 경로의 cleanup 이 한 스크립트에 들어 있다. 확인 문구에 manifest 의 SHA-256 을 넣은 것이 이 구조의 핵심이다 — **운영자가 무엇을 적용하는지 손으로 옮겨 적지 않으면 통과할 수 없다.** 그래서 이런 성질이 생긴다. - **fail-closed 가 기본이다.** 조건이 불명확하면 진행하지 않는다. `--execute` 없이는 아무것도 바꾸지 않고, 확인 문구는 정확히 일치해야 한다. - **create-only 와 lifecycle 이 갈려 있다.** `apply-phase1-gitea.sh` 는 `gitea/gitea` Deployment 나 `gitea-keycloak-oidc` Secret 이 이미 있으면 **시작 전에 거부한다.** 재적용용 스크립트가 아니다. - **rollback 이 삭제가 아니다.** Traefik 실패 rollback 은 HCC 삭제가 아니라 NodePort-only baseline 적용이다. 자동 rollback 은 CRD·Retain PV/PVC·버킷·Secret payload 를 지우지 않는다. - **실패 기록이 재시도 입력이 아니다.** 실패한 rollback ID·ledger·handoff 는 보존하되 같은 ID 로 재시도하지 못하게 한다. ### 14.3 이 접근의 값 **얻은 것**: 사람이 손으로 하면 반드시 빠뜨릴 단계를 코드가 붙든다. 「계획이 맞아도 손으로 옮기다 깨진다」를 막는 구조다. **치른 값**: 스크립트를 테스트해야 하고, 그 테스트가 33,937줄이 됐다. 그리고 **스크립트의 predicate 가 틀리면 정상 상태를 실패로 판정한다** — 실제로 그런 일이 네 번 있었다(§17.4). **아직 없는 것**: 이 스크립트들을 자동으로 돌리는 CI 가 없다. `.github/` 도 `.gitea/` 도 없다(관측). 사람이 부를 때만 돈다. ### 14.4 GitOps 는 아직 자리만 있다 ```text clusters/home/applications/.gitkeep ← 비어 있음 clusters/home/projects/.gitkeep ← 비어 있음 components/policies/.gitkeep ← 비어 있음 components/mesh-ready/README.md ← 17줄, "설치하지 않는다" bootstrap/argocd/README.md ← 인계 기준만 ``` Argo CD 도 Istio 도 배포되지 않았고, **디렉터리와 README 만 예약돼 있다.** ADR-0002 가 Argo CD 인계 순서를, ADR-0007 이 Istio 보류 조건을 각각 정해 뒀다. Argo CD 인계의 전제는 "Gitea OIDC live 적용과 실제 login/logout, HTTPS clone/push 가 검증되고 플랫폼 저장소가 push 된 뒤"였다. **그 중 「플랫폼 저장소 push」는 이미 끝났다.** ```text origin https://git.learn.hyeonworks.com/donghyeon.kang/platform-core (fetch/push) main 16c337b [origin/main] Add platform infrastructure configuration git ls-remote origin → refs/heads/main 16c337bcc91b27ac0f074154b8337e4c8dc17ebb ``` (관측 — evidence `git-remote-and-gitea-repos`. 로컬 HEAD 와 원격 `main` 이 같은 커밋이다) **그리고 Gitea 는 이미 일상적으로 쓰이고 있다.** 익명 API 로 본 저장소가 20개 이상이고 가장 최근 갱신이 이 문서의 기준일인 2026-09-20 이다(`clean-architecture-frontend-template` `2026-09-20T04:47:36Z`, `memento-frontend` `2026-09-20T04:54:16Z`). 중앙 문서가 미완으로 남긴 "HTTPS clone/push 수용 시험"은 **형식적으로 기록되지 않았을 뿐 실제로는 매일 일어나고 있다.**(관측 + 추론) 즉 Argo CD 가 없는 이유는 전제 미충족이 아니라 **아직 안 한 것이다.** 이 구분은 §18.2 에서 다시 적는다. --- ## 15. 의사결정 원장 ADR 10건. 각각의 **제약 → 선택 → 감수한 값**만 줄인다. | ADR | 제약 | 선택 | 감수한 값 | |---|---|---|---| | 0001 HDD 분할 | 2TB HDD 에 지울 수 없는 개인 자료 약 24.5GB, AIStor 는 XFS 필요, SSH 만 가능 | SSD 에 검증된 안전본 → 파티션 재생성 → 복원 후 SHA-256 재검증 | 개인 자료와 AIStor 가 같은 디스크 장애 공유, 회전식 I/O 가 상한 | | 0002 수동 bootstrap → Argo CD | Gitea 를 Argo CD 로 깔려면 Argo CD 가, Argo CD 의 Git 원본을 만들려면 Gitea 가 먼저 필요 | 수동으로 Gitea 까지 만들고, push 뒤 App-of-Apps 로 인계 | 인계 전까지 drift 가능, Gitea 와 GitOps 제어면이 같은 서버 | | 0003 Nginx edge TLS | 외부는 80/443 만, Host Nginx 가 이미 인증서를 가짐 | Nginx 에서 TLS 종료 → loopback `30080` 하나로 전달, Traefik 이 라우팅 소유 | 내부 구간 평문, Nginx 단일 실패점, NodePort 차단이 풀리면 우회 가능 | | 0004 공용 PostgreSQL | 6코어·32GB 에서 인스턴스 둘은 비쌈, 하나로 합치면 격리 상실 | 인스턴스 1 + DB·Role·Secret·HBA 로 논리 분리 | 물리 장애·자원 경합 공유, HA 없음 | | 0005 Keycloak direct OIDC | 공통 인증 프록시는 모든 요청에 의존성 추가 | 각 앱이 OIDC client 로 직접 연결, ForwardAuth 없음 | 앱마다 OIDC 를 제대로 구현해야, Keycloak 장애 시 신규 로그인 실패 | | 0006 AIStor Free | 구 MinIO Operator 유지보수 불명확, S3 가 반드시 필요 | AIStor Free `servers:1 volumesPerServer:1`, license 는 Secret 으로 | 복제·erasure coding 없음, HDD 장애 시 전 버킷 동시 손실 | | 0007 Istio 보류 | 단일 노드에서 mesh 가 주는 가용성이 없음 | 설치하지 않고 `components/mesh-ready` 자리만 예약 | 자동 mTLS·workload identity 없음, L7 telemetry 는 앱 계측 의존 | | 0008 비공개 관리 UI + split DNS | 관리 화면 권한이 큼, 공개 DNS 에 이름을 두고 싶지 않음 | 공개 A/AAAA 없음 + dnsmasq 두 벌 + CoreDNS + source allowlist + exact-SAN 인증서 | 공유기·Tailscale DNS 를 따로 관리, DNS-01 토큰과 갱신 hook 필요 | | 0009 공용 관측성 | 앱이 아직 없는데 관측 계층이 필요 | 플랫폼이 수집·저장·조회·알림을 소유, 앱은 ServiceMonitor·SLO 만 | 약 2.1 CPU·4.5Gi request 와 35Gi SSD 추가, HA 없음, hostname 단위 egress 제한 불가 | | 0010 로컬 암호화 복구 | off-host 매체가 없는데 Secret 암호화 전환에 복구본이 필요 | `/dev/sda3` NTFS 안 32GiB LUKS2 컨테이너, K3s 제어면 bundle 만 | 같은 섀시 — 화재·도난·전원 사고 미보호, `/dev/sda` 고장 시 vault 와 함께 손실 | **열 건을 관통하는 것이 하나 있다: 단일 노드라는 사실을 숨기지 않는다.** ADR 마다 "HA 를 제공하지 않는다", "재해 복구본이 아니다", "독립 백업이 아니다" 를 반복해서 적는다. 이것은 문체가 아니라 **나중에 이 문서를 읽고 잘못 믿는 것을 막는 장치다.** --- ## 16. 2026-09-20 라이브 확인 명령 20벌을 돌렸다. 원문과 메타데이터는 `final/evidence/` 에 있다. 19벌은 `desktop` 에서, 한 벌(`tailscale-peer-vantage`)은 **다른 호스트에서** 돌렸다. | 확인한 것 | 결과 | evidence | |---|---|---| | 노드·파드 | 노드 1 Ready, 파드 26개 전부 Running/Completed | `cluster-node-and-pods` | | 외부 노출 | Ingress 5건, NodePort 1건(traefik), LoadBalancer 0건 | `cluster-services-and-ingress` | | NetworkPolicy | 58건, default-deny 6건(namespace 전체는 4건) | `cluster-networkpolicy-and-storage` | | PV/PVC | 10/10 Bound, 전부 Retain·RWO·노드 affinity | 같음 | | Prometheus | active target 30 / healthy 30, alert rule 155, recording rule 86, firing 0, unhealthy 0 | `prometheus-targets-and-rules` | | Alertmanager | receiver 정확히 2(qualified), active alert 0, silence 0 | `alertmanager-receivers-and-alerts` | | AIStor | `Initialized`/`green`, drive 1/1, usage 20,085,288,960 bytes | `aistor-objectstore-and-bucket-usage` | | 버킷 quota | `loki` 0.403%, `tempo` 0% | 같음 | | Secret 계약 | 문서가 선언한 16개 전부 존재 (payload 미확인) | `secret-inventory-names-only` | | Host Nginx | 5 hostname, 관리 3곳에 source allowlist, `ssl_reject_handshake` | `host-nginx-active-config` | | 사설 DNS | dnsmasq 2 인스턴스 active, 5 이름 × 2 주소 | `host-private-dns-config` | | 인증서 | 5 hostname 을 3장이 덮음, 최단 만료 2026-10-21 | `edge-tls-certificates` | | 엣지 경계 | public 200, private 200(LAN), NodePort LAN 거부·loopback 404 | `edge-boundary-probe` | | k3s drop-in | `nodeport-addresses=127.0.0.0/8`, `secrets-encryption: true` | `k3s-config-dropins-and-storage` | | 노드 자원 | request CPU 40% / mem 32%, limit CPU 176% / mem **89%** | `node-resource-allocation` | | 이미지 | 전부 고정 tag 또는 digest | `running-container-images` | | Git 원격 | `platform-core` `main` = 로컬 HEAD, Gitea 저장소 20+ 전부 public, CI 없음 | `git-remote-and-gitea-repos` | | 백업 | CronJob 0 · ScheduledBackup/Backup 0 · `Cluster` 에 backup 섹션 없음 | `backup-absence` | | 다른 호스트에서 | 5 이름 → Tailscale 주소, 관리 UI 200/302, NodePort 2개 거부 | `tailscale-peer-vantage` | | 디스크 귀속 | 관측성 실사용 약 4.66 GiB · Local PV 아홉 개 합계 약 5.4 GiB · 루트 138G 중 `/home` 61G | `disk-usage-attribution` | ### 16.1 눈에 띄는 숫자 셋 **(1) 메모리 limit 합계가 allocatable 의 89%다.** allocatable 이 `32,776,484Ki`(약 32,008Mi)인데 limit 합계가 `28,652Mi` 다. request 는 `10,450Mi`(32%)로 여유가 있다. **단일 노드에서 모든 워크로드가 동시에 limit 까지 쓰면 OOM 영역이다.** 실제 사용은 `9,272Mi`(28%)로 멀고, 실제로 그렇게 되면 `PlatformPodOOMKilled` 경보가 잡는다. CPU limit 합계 176% 는 throttle 로 끝나므로 성격이 다르다. **(2) root filesystem 이 경보 식 기준 64.8%다.** `node_filesystem_avail_bytes` / `node_filesystem_size_bytes` 로 계산하면 `1 - 85,786,652,672 / 243,885,932,544 = 64.83%` 다(`df` 의 63% 와 조금 다른 것은 예약 블록 처리 차이다). **첫 경보 임계 75% 까지 약 24.8GB 남았다.** Prometheus TSDB 가 지금 4.6GB 이고 `retentionSize: 16GB` 까지 자랄 수 있으므로 **그것만으로 +11GB 가 잠재해 있다.** Loki·Tempo·Alloy WAL 에는 byte 상한이 없다. 같은 날 조금 뒤의 두 번째 측정에서는 `df` 가 138G / 64% 였다 — **한 시간 안에 2G 가 늘었다.** 무엇이 늘었는지는 §7.4 의 귀속표를 보면 플랫폼 쪽이 아니다. 그리고 그 표가 보여 주듯 **첫 경보를 먼저 당길 후보는 관측성 증가가 아니라 `/home/donghyeon` 의 24G 이전 안전본이다.** **(3) `tempo` 버킷 0 bytes.** 고장이 아니라 trace 를 보내는 애플리케이션이 없어서다. --- ## 17. 문서와 라이브가 어긋난 곳 열 곳을 찾았다. **고쳐야 할 것과, 사실이므로 그대로 둘 것을 구분한다.** ### 17.1 상위 문서가 관측성을 「미적용」이라고 말한다 — 문서가 뒤처졌다 `docs/platform/README.md`(2026-08-09)와 `architecture/platform-overview.md`(2026-08-08), `architecture/repository-layout.md`(2026-07-31), `architecture/namespace-and-resource-policy.md` (2026-07-31)가 모두 관측성을 "설계 승인, 구현 전" 으로 적는다. 라이브에서는 40일째 돌고 있고 `observability/` 9편(2026-08-15)이 as-built 를 설명한다. **같은 저장소 안에서 최신 문서가 상위 문서를 반박하는 상태다.** `observability/` 쪽을 믿어야 한다. 고칠 곳: 위 네 문서의 상태 줄과 Phase 4 관련 문장. ### 17.2 Traefik 루트 build root 와 라이브가 다르다 — 그런데 그것이 설계다 §4.5 에서 본 것. 루트 `kustomization.yaml` 은 `overlays/observe` 를, 라이브는 `trust` 를 쓴다. **처음에 이것을 drift 로 적었는데 틀렸다.** 저장소가 이유까지 적어 두었다 — `traefik/README.md` 가 「루트 `kustomization.yaml`은 의도적으로 안전한 `observe` overlay를 가리킨다 … 상태 전환은 아래 guarded script와 정확한 overlay를 사용한다」. **고칠 코드는 없다.** 남는 것은 관측 가능성 하나다 — 라이브가 세 overlay 중 어느 상태인지 저장소만 보고는 알 수 없고 `HelmChartConfig` 를 읽어야 한다. 저장소는 그것을 기록하지 않는다. ### 17.3 관측성 chart 가 저장소에 풀려 있고 git 이 추적하지 않는다 `services/observability/{alloy,blackbox-exporter,grafana}/.helm/charts/…` 아래 713파일 155,560줄이 작업 트리에 있는데 `.gitignore` 의 `.helm/` 때문에 커밋에 없다. **「재현 가능한 선언만 버전 관리한다」는 저장소 규칙 자체는 맞다.** Phase 1·2 는 렌더할 때 내려받고 SHA-256 을 대조하므로 문제가 없다. 그런데 관측성 쪽은 **이 디렉터리가 이미 있다는 전제로 `chartHome: .helm/charts` 를 가리킨다.** 다른 기계에서 clone 하면 렌더가 안 된다. 고칠 곳: 관측성 chart 도 Phase 1·2 처럼 pinned package SHA-256 을 저장소에 적고 렌더 시 내려받게 하거나, 최소한 「이 디렉터리를 어떻게 다시 만드는가」를 README 에 적는다. ### 17.4 스크립트 predicate 가 정상을 실패로 판정한 사건 넷 — 기록이므로 그대로 둔다 중앙 문서 `observability/07-build-history-and-decisions.md` 에 보존된 것. | 사건 | 무엇을 잘못 봤나 | 결과 | |---|---|---| | Task 6 첫 apply | `AlertmanagerConfig` 의 런타임 receiver 이름이 `platform-slack` 일 거라고 봤는데 Operator 가 `observability/platform-alertmanager/platform-slack` 으로 만든다 | reconcile RC 1, rollback PASS, acceptance 없음 | | Task 6 parse-only | `--verified-output-dir` 가 줄바꿈으로 쪼개져 usage RC 2, shell RC 127 | mutation 0, Blackbox proof 만 남음 | | 구조화 Slack 첫 apply | Alertmanager v0.33.1 API 가 `name` 과 같은 값의 `labels.name` 을 함께 주는데 postcheck 가 key 를 하나로 제한 | reconcile RC 1, rollback PASS | | OIDC wrapper | 대화형 확인을 기다리는 동안 short-lived admin token 이 만료 | prestate 재검사 HTTP 401, mutation 전 실패 | **네 건 모두 「대상이 틀린 게 아니라 검사기가 틀렸다」.** 그리고 네 건 모두 **검사를 느슨하게 푸는 대신 predicate 를 정확하게 고쳤다** — 예를 들어 receiver 는 raw 이름이 아니라 exact qualified singleton 만 통과시키도록 좁혔다. **이 기록을 고쳐 쓰지 않는다.** rollback PASS 가 acceptance 가 아니고, 나중에 성공했다고 해서 그때 wrapper 가 성공한 것이 되지 않는다. 사후에 성공 서사로 바꾸면 다음에 같은 실패를 알아보지 못한다. ### 17.5 Phase 4 gate 가 안 열렸는데 Phase 4 가 돌고 있다 — 사실이고, 수용된 위험이다 `security-and-secrets.md` 는 Phase 4 Secret 생성 전에 두 gate 를 독립 호출하라고 적는다. ```text k3s-secret-encryption.sh --expect-reencrypted → 통과 (2026-08-09) k3s-secret-encryption-restore-evidence.sh --check → 격리 restore drill 이 없어 불가 ``` 두 번째가 성립하지 않는 상태에서 Slack Secret 을 `SLACK_DEPLOYMENT_GATE=RISK_ACCEPTED` 로 만들고 관측성을 적용했다. strict recovery checker 는 **expected RC `1`** 로 실패하는 것이 정상 경로였다. **이것은 gate 를 우회한 것이 아니라 위험을 명시적으로 기록하고 진행한 것이다.** 문서가 "active risk acceptance 는 operational delivery 를 대체하지 않는 gap 이다" 라고 적는다. 고칠 것은 문서가 아니라 격리 restore drill 을 실제로 도는 일이다. ### 17.6 선언에 없는 것이 호스트에 돌고 있다 `docker.service`, `snap.multipass.multipassd.service`, `cups`·`cups-browsed`, `avahi-daemon` 이 running 이다. `docker0 172.17.0.1/16`, `br-8359faae6017 172.18.0.1/16`, `mpqemubr0 10.135.97.1/24`(down) 인터페이스가 있다.(관측) **플랫폼 선언은 이것들을 모른다.** 개발 편의로 남아 있는 것으로 보이지만(추론), Docker 는 iptables 규칙을 만들고 기본 정책을 바꾸는 소프트웨어다. **NodePort loopback 제한과 같은 호스트 방화벽 가정이 Docker 의 iptables 조작과 어떻게 상호작용하는지는 확인하지 않았다** (미확인). §18.3 에 적는다. ### 17.7 중앙 문서 네 곳이 라이브와 다르다 §17.1 이 관측성 「미적용」 넷을 세었는데, 그 밖에도 넷이 더 있다.(관측) | 문서 | 적힌 것 | 라이브·저장소 | |---|---|---| | `host-nginx/README.md:5-7` | 활성 설정은 `learn-services-keycloak.conf`, SHA-256 `5c5cd74b…` | 실제 활성 파일은 `learn-services-observability.conf` 와 바이트 동일 | | `minio-aistor/README.md` | admin-oidc profile 은 「선언형 구현·dry-run 완료, live 적용 대기」 | Console Ingress·OIDC env 가 적용돼 있다 | | `gitea-service.md:82` | base 의 NetworkPolicy 「다섯」 | 파일에는 여섯, 라이브 Gitea 파드에는 일곱(§12.2) | | `observability/09-…md:14,24` | receiver 「정확히 하나」, groupBy 세 항목 | 둘이고 네 항목이다 — 저장소 선언과 라이브가 §11.5 쪽이다 | 앞의 셋은 문서가 뒤처진 것이고, 마지막은 **가장 최신인 관측성 문서가 자기 저장소 선언과 어긋나 있는** 경우다. ### 17.8 저장소 안에 죽은 사본이 있다 `services/minio-aistor/values/home.yaml` 은 `base/deployment/values/home.yaml` 과 바이트 동일한데 **어느 kustomization 도 참조하지 않는다** — `helmCharts` 는 `base/deployment` 에만 있다. 그리고 중앙 문서 `minio-aistor-service.md:36` 이 하필 그 미참조 사본을 설정 위치로 가리킨다. 중앙 문서 쪽에는 `architecture/platform-overview.md.orig` 도 남아 있다.(관측) ### 17.9 CNPG Cluster 의 `resizeInUseVolumes` 와 StorageClass 가 반대를 말한다 라이브 `Cluster` 의 storage 에 `resizeInUseVolumes: true`(CNPG 기본값)가 있는데, 그것이 쓰는 `ssd-local-postgres-retain` 은 `allowVolumeExpansion: false` 다(§7.1 — 열 개 전부 그렇다). 지금은 확장을 시도하지 않아 증상이 없다.(관측) ### 17.10 인프라 저장소가 공개 인터넷에서 익명으로 읽힌다 `git.learn.hyeonworks.com` 은 공개 A 레코드가 있고 Host Nginx 에 source allowlist 가 없다 (§2.2). 그리고 Gitea 의 저장소가 **전부 `public`** 이다.(관측 — evidence `git-remote-and-gitea-repos`. 익명 API `repos/search` 가 **22건**을 반환하고 전부 `public`) ```text donghyeon.kang/platform-core/raw/branch/main/README.md → 200 (익명) ``` **자격 증명은 없다.** `.gitignore` 와 `scan-platform-sensitive-source.sh` 가 소스 YAML 의 `kind: Secret` 을 거부하고, `local-recovery.env`(하드웨어 식별자)와 `.helm/` 은 추적되지 않는다. 실제로 추적 파일이 302개이고 그 안에 `.helm/` 은 0개다.(관측) **그런데 내부 구조 전체가 공개다.** 공개된 것: 노드 LAN 주소 `192.168.0.107`, Tailscale 주소 `100.92.240.34`, 다섯 hostname 과 각각의 backend·포트, Host Nginx 의 source allowlist CIDR, NetworkPolicy 58건의 정확한 selector 와 포트, 디스크 마운트 경로와 host path, 경보 임계값, Keycloak realm·client·group 이름, Secret 의 이름과 key 이름. **이게 문제인지 아닌지는 이 문서가 정할 일이 아니다.** 다만 두 가지는 사실로 적어 둔다. 1. **저장소를 public 으로 둔 것이 의도인지 기본값인지 문서 어디에도 없다.** ADR 에도 `security-and-secrets.md` 에도 저장소 공개 수준을 정한 문장이 없다. 「Secret 을 Git 에 두지 않는다」는 있지만 「Git 자체를 누가 읽을 수 있는가」는 없다. 2. **경보의 `runbook_url` 이 공개 저장소를 가리킨다.** 22개 플랫폼 alert 가 전부 `https://git.learn.hyeonworks.com/donghyeon.kang/project-infra/src/branch/main/docs/runbooks/2026-07-31-observability-access-cutover.md` 를 가리키고 익명으로 200 이다(관측). 링크가 살아 있는 것은 좋지만, **대응 절차가 공개돼 있다는 뜻이기도 하다.** 고칠 곳이 있다면 코드가 아니라 결정이다 — 저장소 공개 수준을 ADR 로 한 번 정하는 것. --- ## 18. 열린 질문 ### 18.1 NetworkPolicy 58개가 실제로 집행되는가 **왜 열려 있나.** k3s 의 netpol controller 는 켜져 있다(§12.5 — 기동 로그로 확인). 남은 것은 그것이 만든 규칙이 의도대로 걸렸는가다. 중앙 문서가 "k3s CNI에서 정책이 실제 강제되는지는 양방향 allow/deny Pod 시험으로 별도 확인한다" 고 적고 그 시험 기록이 없다. 이 문서도 하지 않았고 `iptables -S` 는 root 가 필요해 못 읽었다. **답하는 방법.** 일회용 파드 둘로 양방향을 친다. (a) `default` namespace 의 파드에서 `platform-postgres-rw:5432` 로 TCP 연결 — 차단돼야 한다. (b) `observability` 에 label 만 붙인 파드에서 `minio:9000` 으로 연결 — `object-storage-allow-observability-s3` 가 이름까지 보므로 차단돼야 한다. (c) `gitea` namespace 에 Gitea label 없는 파드를 띄우고 밖으로 나가기 — `gitea-default-deny` 가 podSelector 로 좁혀져 있으므로 **통과할 것으로 예상**되고, 그것이 확인되면 §12.1 의 지적이 사실이 된다. **왜 중요한가.** §12 전체와 §9·§10 의 경계 주장이 여기에 얹혀 있다. 컨트롤러가 도는 것은 확인했으니 「선언뿐」은 아니지만 **어느 규칙이 실제로 걸렸는지는 아직 모른다.** ### 18.2 Argo CD 인계를 막는 것이 무엇인가 **전제는 이미 충족됐다.** §14.4 에서 본 대로 `platform` 저장소는 `git.learn.hyeonworks.com/donghyeon.kang/platform-core` 의 `main` 에 같은 커밋으로 올라가 있고, Gitea 에는 저장소 20개 이상이 오늘까지 갱신되고 있다. 중앙 문서가 미완으로 남긴 "HTTPS clone/push 수용 시험"은 **기록되지 않았을 뿐 실제로는 돌고 있다.** **그래서 질문이 바뀐다.** "push 할 수 있는가"가 아니라 **"인계를 시작하면 무엇이 깨지는가"**다. ADR-0002 가 미리 적어 둔 위험 네 가지를 아직 아무도 해소하지 않았다. - 수동으로 만든 리소스와 Git 선언의 **immutable field 가 다르면 인계 때 재생성된다.** 특히 `Retain` Local PV/PVC 와 CNPG `Cluster` 가 그렇다. - **라이브에만 있고 저장소 기본 build root 에는 없는 것이 최소 하나 확인됐다**(§17.2 의 Traefik `trustedIPs`). 인계 전에 이런 diff 를 전부 찾아야 한다. - **관측성 chart 가 저장소에서 재현되지 않는다**(§17.3). Argo CD 가 `.helm/charts` 를 못 만들면 그 Application 은 렌더에 실패한다. - 수동으로 만든 Secret 16개를 Argo CD 관리로 가져오려면 Secret 관리 제품을 먼저 정해야 한다(§13.2). ADR 이 아직 없다. **답하는 방법.** `kubectl diff -k ` 를 build root 마다 돌려 라이브와 선언의 차이를 전부 목록으로 만든다. `prune` 없이, `automated sync` 없이. 차이가 0 이 되기 전에는 인계하지 않는다. ### 18.3 외부망에서 고포트 `30080/30443` 이 정말 닫혔는가 **왜 열려 있나.** LAN 에서의 거부는 확인됐다(관측: `000`). **공개 IP 에서의 확인은 이 호스트 안에서 할 수 없다.** 중앙 문서도 이것을 반복해서 미완으로 남긴다. 게다가 §17.6 의 Docker 가 iptables 를 만지는 변수다. **답하는 방법.** LAN 밖의 다른 네트워크(모바일 테더링, Tailscale 이 아닌 외부 호스트)에서 공개 IP 의 두 포트로 접속해 reject 또는 timeout 인지 본다. **`404` 가 오면 실패다.** ### 18.4 네 identity 의 OIDC 동작 **왜 열려 있나.** Grafana 는 `donghyeon.kang` 한 사람의 로그인만 확인됐다(기록). admin / viewer / group 없음 / membership 제거 네 경우를 다 돌리지 않았다. Gitea·AIStor·pgAdmin 은 실제 사용자 로그인 확인 자체가 없다. **무엇을 확인해야 하나.** `role_attribute_strict: true` 가 group 없는 사용자를 정말 막는지, pgAdmin 의 `OAUTH2_ADDITIONAL_CLAIMS` 가 정말 게이트로 동작하는지, AIStor 의 `policy` claim 이 `consoleAdmin` 을 제대로 나르는지. ### 18.5 인증서 갱신이 자동으로 도는가 **왜 열려 있나.** `storage-admin`/`db-admin` 인증서가 2026-10-21 만료로 31일 남았다(관측). 중앙 문서는 Cloudflare DNS-01 과 certbot deploy hook(「`nginx -t` 가 성공한 경우에만 reload」)을 적지만 **갱신이 실제로 성공한 적이 있는지는 기록이 없다.** `git`+`id` 인증서는 2026-09-16 발급이므로 최근에 갱신된 것으로 보이고(추론), `grafana` 는 2026-08-10, 나머지 둘은 2026-07-23 발급이다. **답하는 방법.** `certbot renew --dry-run` 을 세 lineage 에 돌리고 deploy hook 이 붙어 있는지 확인한다. 그리고 `PlatformCertificateExpiry` 경보가 실제로 Slack 까지 오는지 본다 — **하루 뒤면 자연히 warning 조건에 들어간다.** ### 18.6 Loki 의 WAL 이 혼자 불어나면 무엇이 잡는가 **왜 열려 있나.** `PlatformLokiWALDiskUsageHigh` 는 이름과 달리 Loki 를 보지 않고 WAL 이 놓인 파일시스템의 사용률을 본다(§11.4). 관측값 `0.6057` 은 Loki 가 쓴 9.9 MiB 가 아니라 루트 파일시스템의 사용률이다. 그래서 **루트가 한가한데 Loki WAL 만 5Gi 를 다 채우는 상황에는 아무 경보도 없다.** Local PV 의 `capacity` 는 quota 가 아니고(§7.2), `kubelet_volume_stats_*` 도 파일시스템 값을 되풀이한다(§7.5). **잴 수단이 없는 것은 아니다.** Loki 는 자기 WAL 바이트를 이미 노출한다 — `prometheus_tsdb_wal_storage_size_bytes{job="observability/loki"}`. §7.4 가 「9.9 MiB」로 쓴 `10,342,630` 이 바로 이 값이다.(관측) 그러니 정확히는 **「그 metric 으로 된 경보가 없다」**다. 이름만 보면 맞을 것 같은 `loki_ingester_wal_bytes_in_use` 는 `0` 을 내므로 쓸 수 없다. **무엇이 걸려 있나.** Loki 의 `disk_full_threshold: 0.90` 과 `replay_memory_ceiling: 512MB` 는 Loki 가 스스로 쓰기를 멈추는 값이지 사람에게 알리는 값이 아니다. Alloy 쪽 `PlatformAlloyLogEntriesDropped` 는 **결과**를 잡지만 원인이 WAL 포화인지는 가르지 않는다. §7.5 의 `KubePersistentVolumeFillingUp` 넷은 루트 여유율을 읽으므로 여기서도 도움이 안 된다. **답하는 방법.** 셋이다. (a) 가장 싼 것 — `prometheus_tsdb_wal_storage_size_bytes` 에 절대 바이트 임계로 경보 하나를 건다. (b) Loki·Tempo·Alloy 의 로컬 PV 를 크기가 강제되는 볼륨(전용 파티션·LVM·loop 파일)으로 옮기면 `kubelet_volume_stats_*` 가 제 값을 내고 §7.5 의 생성 경보 넷도 살아난다. (c) 어느 쪽도 안 하면 최소한 이 경보의 이름이 뜻하는 바를 적는다. ### 18.7 백업이 하나도 돌고 있지 않다 **관측한 것.**(evidence `backup-absence`) ```text kubectl get cronjob -A → No resources found kubectl get scheduledbackup,backup -A → No resources found kubectl get job -A → helm-install-traefik 둘뿐 (40d·63d, Complete) cluster.yaml 의 backup / barmanObjectStore / plugin → 없음 ``` 버킷도 둘밖에 없다. `minio_cluster_usage_buckets_total_bytes` 가 `loki` 와 `tempo` 만 낸다 — `platform-postgres-backup`·`gitea-backup`·`learning-postgres-backup` 은 만들어진 흔적이 없다. (관측 — evidence `aistor-objectstore-and-bucket-usage`) **설계와의 거리.** `backup-and-recovery.md` 는 PostgreSQL 일 1회 base backup + 연속 WAL, Gitea 일 1회, 보존 14일을 적는다. **선언도 스케줄도 버킷도 없다.** **무엇이 걸려 있나.** 지금 `/dev/sdc` 가 죽으면 **Gitea 저장소와 두 DB 의 논리 복구본이 어디에도 없다.** K3s recovery bundle 은 제어면(SQLite·token·host config)만 담고 애플리케이션 데이터는 명시적으로 제외한다(ADR-0010). Gitea 는 `platform-core` 를 포함해 20개 저장소의 유일한 원본이고(§17.7), 그 중 일부는 다른 기계의 clone 이 사본 노릇을 하겠지만 **issue·PR· 사용자·attachment 는 clone 에 안 담긴다.** **이것이 이 플랫폼에서 가장 큰 단일 공백이다.** 단일 노드·non-HA 는 문서가 반복해서 경고하고 수용한 위험이다. 백업 부재는 다르다 — 문서가 「할 것」으로 적어 둔 뒤 아직 안 했다. 다른 미완들(격리 restore drill, off-host 복제, OIDC matrix)은 **있는 것을 검증하는** 일인데 이것만 **없는 것을 만드는** 일이다. **답하는 방법.** 순서가 이미 문서에 있다 — AIStor 에 `platform-postgres-backup` 버킷과 전용 최소권한 access key 를 만들고, CNPG `Cluster` 에 backup 설정을 더하고, `ScheduledBackup` 을 걸고, **별도 임시 namespace 에 복원해 두 DB 의 격리까지 확인**한다. 버킷을 만드는 것과 복원이 되는 것은 다른 일이다. --- ## 19. 이 문서로 말할 수 없는 것 앞의 열여덟 절은 각자의 자리에서 무엇을 못 봤는지 이미 밝혔다. 여기서는 그 조각들이 합쳐졌을 때 **읽는 사람이 넘어서면 안 되는 선 하나**만 다시 못 박는다. **이 문서의 「경계」는 전부 선언과 관측된 상태이지 시험 결과가 아니다.** 로그인도, push 도, S3 put/get 도, 백업도, 복구도, NetworkPolicy 의 allow/deny 도 한 번 돌려 보지 않았다. 그래서 세 쌍을 아직 아무도 잇지 못했다 — 「NetworkPolicy 58건이 있다」와 「그 58건이 경계로 동작한다」(§18.1), 「Secret 계약 16개가 다 있다」와 「그 값이 맞다」(§13.2), 「`secrets-encryption: true` 가 켜져 있다」와 「재암호화가 끝났다」(§6.2). 그 선을 만든 것이 넷이다. `sudo` 가 없어 `k3s secrets-encrypt status` 와 `/etc/hyeonworks/` 아래를 못 읽었고(§1.2), 같은 이유로 루트 SSD 의 약 53G — 컨테이너 이미지 저장소로 보이는 — 를 귀속하지 못했으며 Tempo 의 로컬 작업공간도 재지 못했다(§7.4). Keycloak 관리 API 를 부르지 않아 realm 내용은 discovery endpoint 까지만 봤고(§9.3), 중앙 문서의 runbook 20편·plan 27편 약 21,900줄과 vendored chart 155,560줄은 인용을 확인할 때만 열었다(§1.2, §21.2). **그리고 「관측」이라고 적었는데 증거 파일에 원문이 없는 것이 여덟 가지 있다.** CPU·메모리· swap, 노드 allocatable, §16.1 의 root filesystem 계산에 쓴 `85,786,652,672`, Host Nginx 파일의 줄 수와 mtime, PV 열 개의 nodeAffinity, k3s drop-in 의 바이트 동일성, 호스트의 systemd 서비스 다섯, 스크립트 네 개의 줄 수. **여덟 다 라이브에서는 참이지만 §1.2 가 정의한 「관측 = 증거 원문이 있다」를 어긴다.** 다시 주장하려면 그 명령을 돌려 증거로 남겨야 한다. 마지막으로 **이것은 2026-09-20 한 번의 스냅숏이다.** 파드의 재시작 횟수가 대부분 24일 전 1~4회로 찍혀 있다 — 이 시스템은 움직인다. 숫자를 인용하기 전에 §16 의 명령을 다시 돌린다. --- # 제2부 — 근거 ## 20. 증거 색인 전부 `final/evidence/raw/.txt` 에 원문이, `final/evidence/meta/.json` 에 command·cwd·executedAt·exitCode·revision·sha256 이 있다. 모두 2026-09-20 에 실행했다. 19벌은 `ssh desktop` 으로 종료 코드 `0`, 한 벌(`tailscale-peer-vantage`)은 별도 호스트에서 종료 코드 `7` 이다 — **마지막 명령인 NodePort `curl` 의 연결 거부가 그 증거의 결론이라 비정상이 아니다.** meta 의 `exitCodeNote` 에 그 사실을 적었다. | id | 무엇을 증명하나 | 증명하지 않는 것 | |---|---|---| | `cluster-node-and-pods` | 노드 사양과 전 namespace 파드 Ready | Ready 가 기능 정상은 아니다 | | `cluster-services-and-ingress` | Service type 과 Ingress host, 외부 노출이 NodePort 하나 | Host Nginx allowlist 는 안 보인다 | | `cluster-networkpolicy-and-storage` | NetworkPolicy 58건, PV 10개 Bound | CNI 집행 여부는 모른다 | | `prometheus-targets-and-rules` | 30/30 healthy, alert 155·recording 86, firing 0 | 155개 조건을 주입 시험한 것이 아니다 | | `alertmanager-receivers-and-alerts` | receiver 2개 qualified, active·silence 0 | Slack 전달 성공 여부는 모른다 | | `aistor-objectstore-and-bucket-usage` | `Initialized/green`, drive 1/1, 버킷 사용량·quota율 | S3 기능·복구 가능성은 모른다 | | `secret-inventory-names-only` | Secret 이름과 type | 값의 정확성·회전 여부는 모른다 | | `host-nginx-active-config` | 활성 nginx 설정 전문 | 저장소 어느 후보와 같은지는 별도 대조 | | `host-private-dns-config` | dnsmasq 2 인스턴스와 정적 응답 | 공유기·Tailscale 등록은 호스트 밖 | | `edge-tls-certificates` | 각 hostname 이 제시하는 인증서 | 갱신 자동화 동작은 모른다 | | `edge-boundary-probe` | public 200, NodePort LAN 거부·loopback 404 | 외부망에서의 차단은 모른다 | | `k3s-config-dropins-and-storage` | drop-in 2개, XFS `noquota`, 디스크 사용량 | `secrets-encrypt status` 는 못 읽었다 | | `node-resource-allocation` | request/limit 합계와 실사용 | 부하 시험이 아니다 | | `running-container-images` | 실제 이미지 tag·digest | 저장소 고정값과의 대조는 별도 | | `traefik-live-helmchartconfig` | 라이브에 `trustedIPs: 10.42.0.1/32` 존재 | 저장소 기본 root 가 이를 렌더하는지는 별도 | | `platform-repo-loc` | 영역별 파일·줄 수 | 줄 수가 품질이 아니다 | | `git-remote-and-gitea-repos` | 원격 `main` = 로컬 HEAD, Gitea 저장소 20+ 전부 public, CI 디렉터리 없음, `.helm/`·`local-recovery.env` 미추적 | 이 기계에서 push 했다는 직접 증거는 아니다 | | `backup-absence` | CronJob·ScheduledBackup·Backup 0건, `Cluster` 에 backup 섹션 없음 | 수동 `pg_dump` 같은 다른 방식의 백업 이력은 모른다 | | `tailscale-peer-vantage` | 다른 호스트에서 Tailscale split DNS 동작, 관리 UI 접근, NodePort 거부 | LAN·Tailscale 밖에서의 동작은 여전히 모른다 | | `disk-usage-attribution` | 워크로드별 실사용량, 루트 파일시스템 내역, local PV 의 `kubelet_volume_stats_*` 가 파일시스템 전체를 되풀이한다는 것 | `sudo` 가 없어 컨테이너 이미지 저장소 약 53G 를 귀속하지 못했다. Tempo 로컬도 못 쟀다 | ## 21. 원본 색인 ### 21.1 분석 대상 저장소 `/home/donghyeon/workspace/platform` @ `16c337bcc91b27ac0f074154b8337e4c8dc17ebb` (commit 2개: `fa76531` Initial commit, `16c337b` Add platform infrastructure configuration. 원격 없음, working tree clean) | 경로 | 이 문서에서 근거로 쓴 절 | |---|---| | `README.md` | §1.1, §6.3, §14 | | `infrastructure/networking/traefik/**` | §4.4, §4.5, §17.2 | | `infrastructure/networking/host-nginx/**` | §4.1~§4.3 | | `infrastructure/networking/private-dns/**` | §5 | | `infrastructure/namespaces/**` | §2.3, §11.2 | | `infrastructure/storage/**` | §7 | | `infrastructure/security/k3s/**` | §6.2, §13.1, §13.5 | | `services/platform-postgres{,-keycloak}/**` | §8 | | `services/keycloak/**` | §9.2 | | `services/gitea/**` | §10.1, §9.5 | | `services/minio-aistor/**` | §10.2, §9.3 | | `services/pgadmin/**` | §10.3 | | `services/observability/**` | §11 전체 | | `scripts/**` | §13.3, §14 | | `.gitignore` | §13.1, §17.3 | ### 21.2 중앙 설계·운영 문서 `/home/donghyeon/workspace/docs/platform` (git 없음, 85파일 28,708줄) | 묶음 | 편수 | 기준일 | 전량 읽음 | |---|---:|---|---| | `architecture/` | 16 (`.md` 15 + `platform-overview.md.orig`) | 2026-07-23 ~ 2026-08-09 | ✅ (`.orig` 제외) | | `adr/` | 10 | 2026-07-22 ~ 2026-08-01 | ✅ | | `observability/` | 10 | 2026-08-15 | ✅ (08 제외 9편) | | `runbooks/` | 20 | 2026-07-22 ~ 2026-08-13 | 참조만 | | `plans/` | 27 | 2026-07-31 ~ 2026-08-15 | 참조만 | | `README.md` | 1 | 2026-08-09 | ✅ | **중앙 문서를 이 저장소로 복사하지 않았다.** 이 SSOT 가 인용한 문장은 본문에 「기록」으로 표시했고, 원문은 위 경로에 있다. 그 경로가 사라지면 이 문서의 「기록」 항목은 재확인할 수 없게 된다 — 그것이 §19(4)의 한계와 같은 종류의 제약이다.