Files

135 KiB
Raw Permalink Blame History

단일 노드 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 세 개의 원본과 그 사이의 시차

이 플랫폼에서는 셋이 각각 사실을 주장한다.

코드·설정                 문서                      런타임
/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 요청이 지나는 다섯 홉

[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로 이어지는 구조도.

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 · Grounded VizSpec

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 디스크 세 장의 분담

/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 다.

/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 로 전달하는 순서를 번호가 붙은 화살표로 보여 주는 시퀀스 다이어그램.

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 · Grounded VizSpec

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 를 거부한다.

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 를 믿지 않고 덮어쓴다.

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 를 건다.

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 에 묶는다

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"

관측 결과:

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:

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 에만 있다.

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 가 같은 다섯 이름에 서로 다른 답을 준다.

                           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)

# /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)

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 이 둘이다.

# 30-nodeport-loopback.yaml
kube-proxy-arg:
  - "nodeport-addresses=127.0.0.0/8"
# 40-secrets-encryption.yaml
secrets-encryption: true
secrets-encryption-provider: aescbc

(관측 — evidence k3s-config-dropins-and-storage)

두 번째는 「설정이 켜져 있다」이지 「재암호화가 끝났다」가 아니다. 실제 상태는 k3s secrets-encrypt status 가 말하고 그건 sudo 가 필요해 못 읽었다(미확인). 중앙 문서는 2026-08-09 에 Enabled/reencrypt_finished 를 확인했다고 기록한다(기록).

저장소에도 같은 파일이 infrastructure/security/k3s/40-secrets-encryption.yaml 로 있고 내용이 바이트 단위로 같다.(관측)

6.3 Helm 배포 방식 — chart 를 복사하지 않는다

k3s 가 관리하는 Traefik 은 HelmChartConfig 로 values 만 덮어쓴다. 나머지는 Kustomize 의 Helm inflator 로 공식 chart 를 렌더 시점에 내려받아 쓴다. 고정 대상은 chart 버전과 package SHA-256 둘 다다.

build root chart 버전 package SHA-256
infrastructure/controllers/cloudnative-pg cloudnative-pg 0.29.0 (app 1.30.0) 668e065ff53508d58238788fd35b355a925060843629a951df0e6a9362e6d32f
services/gitea · services/gitea/profiles/oidc gitea 12.7.0 (app 1.27.0) 5881ef9c59400bee2d5547e77c4cd0efb925143c2f5d93fb4f38446db76b0167
infrastructure/controllers/keycloak-operator (Kustomize remote) release 26.7.0 공식 Git release ref
infrastructure/controllers/aistor-operator aistor-operator 5.10.0 e5534f5ae4f6f12a3528a8cda5954d73280cba1a8e979e1628fbf3aac76babd1
services/minio-aistor aistor-objectstore 1.0.16 50ffa6a4e014cdc48566b237593baab41d039f103cdc50c1b1ac173b8d8bf71e
services/observability/kube-prometheus-stack kube-prometheus-stack 88.0.1 (vendored)
services/observability/grafana grafana 12.10.1 (vendored)
services/observability/alloy alloy 1.11.0 (vendored)
services/observability/blackbox-exporter prometheus-blackbox-exporter 11.16.0 (vendored)

관측성 스택만 방식이 다르다. Phase 1·2 의 chart 는 렌더할 때 내려받고 SHA-256 을 비교하지만, 관측성 chart 넷은 .helm/charts/<name>-<version>/ 아래에 저장소에 풀어 놓았다(713파일 155,560줄). .gitignore 에 .helm/ 이 있으므로 이 디렉터리는 git 이 추적하지 않는다. 즉 작업 트리에는 있고 커밋에는 없다.(관측)

이것이 뜻하는 것: 관측성 스택을 다른 기계에서 저장소만 가지고 재현할 수 없다. 누군가 .helm/charts/ 를 다시 채워야 한다. Phase 1·2 는 render-phase1.sh/render-phase2.sh 가 그 일을 하지만 관측성 쪽에 같은 역할을 하는 것이 render-observability-core.sh 인지는 확인했다(§14.2) — 그 스크립트가 chart 를 내려받는 경로를 갖고 있다.

렌더 도구도 고정이다: Kustomize v5.8.1, Helm v3.19.4. --load-restrictor LoadRestrictionsNone 은 쓰지 않고 기본 RootOnly 를 유지한다. 그래서 values 와 patch 가 항상 build root 아래에 있다.


7. 스토리지 — 정적 Local PV 열 개

7.1 StorageClass 를 워크로드마다 하나씩 나눴다

StorageClass 11개 중 local-path(k3s 기본)를 뺀 10개가 전부 kubernetes.io/no-provisioner · Retain · WaitForFirstConsumer · allowVolumeExpansion: false 로 같다.

왜 하나로 안 하고 열 개인가. provisioner 가 없으면 PVC 는 조건이 맞는 아무 PV 에나 바인딩된다. StorageClass 이름을 워크로드마다 다르게 하면 Gitea 의 PVC 가 PostgreSQL 의 PV 를 선점하는 일이 구조적으로 불가능해진다. 용량·접근모드만으로는 막을 수 없는 것을 이름으로 막았다.(추론 — 근거: 중앙 문서의 "PostgreSQL과 Gitea가 잘못 교차 바인딩되지 않도록 workload별 StorageClass를 분리한다")

7.2 PV 열 개의 배치

PV 용량 host path 소비자 디스크
platform-postgres-local-pv 20Gi /srv/k3s/ssd/platform-postgres platform-data/platform-postgres-1 SSD
gitea-local-pv 50Gi /srv/k3s/ssd/gitea gitea/gitea-data SSD
pgadmin-data-local-pv 2Gi /srv/k3s/ssd/pgadmin platform-admin/pgadmin SSD
observability-prometheus-local-pv 20Gi /srv/k3s/ssd/observability/prometheus Prometheus TSDB SSD
observability-grafana-local-pv 2Gi /srv/k3s/ssd/observability/grafana Grafana SQLite SSD
observability-alertmanager-local-pv 1Gi /srv/k3s/ssd/observability/alertmanager silence·notification 상태 SSD
observability-alloy-local-pv 2Gi /srv/k3s/ssd/observability/alloy position·전송 큐 SSD
observability-loki-local-pv 5Gi /srv/k3s/ssd/observability/loki Loki WAL SSD
observability-tempo-local-pv 5Gi /srv/k3s/ssd/observability/tempo Tempo WAL SSD
aistor-data-local-pv 900Gi /srv/k3s/aistor ObjectStore pool-0 XFS HDD

전부 Bound, 전부 Retain, 전부 ReadWriteOnce, 전부 노드 donghyeon-system-product-name affinity.(관측 — evidence cluster-networkpolicy-and-storage)

SSD 쪽 선언 합계는 107Gi 인데 root filesystem 은 228G 이고 이미 136G 가 차 있다(같은 날 두 번째 측정에서는 138G — §7.4). Local PV 의 capacity 는 quota 가 아니므로 이 합계가 지켜진다는 보장이 없다. 그래서 실질 경계는 root filesystem 사용률 경보 세 단계(75% info / 85% warning / 90% critical)다. 관측 시점 경보 식 기준 사용률은 64.8% 로 첫 경계 아래에 있다(§16.1).(관측)

7.3 Loki·Tempo 만 두 층이다

나머지는 로컬 PV 하나로 끝나지만 Loki 와 Tempo 는 로컬을 작업 공간으로만 쓰고 본 데이터를 S3 로 보낸다.

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 에만 인증된다.

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 인스턴스

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 로 바꾼다.
    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 이 아닌 별도 호스트에서)

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 을 부를 때 나가는 경로가 좁혀져 있다.

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 가 쓴다.

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 만 환경변수로 주입한다.

세 줄이 이 설정의 성격을 정한다.

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 전체 배치

                 ┌──────────────── 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 으로 나가는 데이터 흐름도.

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 · Grounded VizSpec

11.2 Prometheus — 두 겹 selector 로 소유권을 가른다

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 별 분포:

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:

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 를 넣었다

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 는 정확히 둘이다.

observability/platform-alertmanager/platform-null
observability/platform-alertmanager/platform-slack

Prometheus Operator 가 <namespace>/<config>/<receiver> 로 이름을 다시 짓는다. 소스에 적은 platform-slack 과 런타임 이름이 다르고, 이것을 몰라서 postcheck 가 정상 상태를 실패로 판정하고 rollback 한 사건이 있다(§17.4).

Slack 메시지 구조: 제목에 [FIRING:n]/[RESOLVED] + severity + alertname, color 는 resolved green / critical·emergency red / warning yellow / 나머지 blue, short field 넷(Status, Severity, Location=cluster / namespace, Alert count), alert 마다 group label 을 뺀 target label 전체 + summary + description + 시작·종료 시각 + runbook 링크, 끝에 Grafana·Explore 링크와 footer.

관측: active alert 0, silence 0, Alertmanager 0.33.1, cluster mode disabled(단일 노드).

11.6 로그와 trace — 수집 범위가 좁다

Alloy 가 읽는 것은 이 노드에 뜬 파드의 stdout/stderr 뿐이다.

discovery.kubernetes "pods" { selectors { field = "spec.nodeName=" + sys.env("HOSTNAME") } }
  → /var/log/pods/*<pod_uid>/<container>/*.log  (hostPath ro)
  → CRI 또는 Docker parser
  → 마스킹 4단계
  → level 추출 (허용 목록 밖이면 label 버림)
  → label_keep: cluster, namespace, app, pod, container, level
  → loki.write http://loki.observability.svc.cluster.local:3100

안 읽는 것: Host Nginx access/error 로그, k3s·systemd journald, SSH/auth, kernel/audit, 파일로만 쓰는 애플리케이션 로그. ELK 계열은 아예 없다.

마스킹은 Loki 로 보내기 전에 Alloy 에서 한다. 정규식 넷이 JSON 필드형·헤더형·bearer· key=value 형을 각각 잡아 [REDACTED] 로 바꾼다. 중앙 문서는 이것을 "심층 방어"로 규정하고 애플리케이션의 선제 마스킹이 권위라고 적는다 — 즉 Alloy 마스킹을 믿고 로그에 비밀을 써도 된다는 뜻이 아니다.

label 을 여섯으로 못 박은 것은 cardinality 통제다. trace_id·request_id·원시 URL· 사용자 식별자를 label 로 만들지 않는다. 그것들은 로그 본문에 남고 검색은 문자열 filter 로 한다.

trace 경로:

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 이 권위다

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 에만 닿는다.

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 · Grounded VizSpec


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 관측성의 열여덟

수집·질의·전송이 각각 정책이 된다.

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) 가 유일하게 공개 인터넷으로 나간다.

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 하나가 두 조건을 동시에 건다.

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 기동 로그에 그것이 있다.(관측)

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 가 막는 것:

.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 스크립트들이 공통으로 지키는 규칙이 하나 있다.

계약의 객체가 전부 없다  → 대화형 입력 후 최초 생성
계약의 객체가 전부 있다  → 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).

/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 같은 커널 이름은 판정 입력으로 쓰지 않는다.

용량도 상수가 아니라 식이다.

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 의 정책 계약:

--recovery-policy encrypted-off-host | local-separate-disk-luks   (필수, 기본값 없음)

확인 문구 (순서대로):
  APPLY <context>                두 정책 공통
  RECOVERY <context>             두 정책 공통
  ENCRYPTED <context>            두 정책 공통 — 문구만 다르다
                                   off-host : "the mount is encrypted off-host media"
                                   local    : "the mounted local recovery volume is LUKS2 encrypted"
  LOCAL_RISK_ACCEPTED <context>  로컬 정책에서만

enum 에 기본값이 없어서 정책을 반드시 밝혀야 한다. 로컬 정책을 고르면 마지막 문구가 「같은 섀시라는 것을 안다」는 서명 역할을 한다.

그런데 반대 방향은 막혀 있지 않다. validator 의 off-host 가지는 한 줄이다.

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줄)의 순서:

[1/8] 현재 context · 대상 node Ready 와 InternalIP 192.168.0.107 대조 · Gitea health
[2/8] Host Nginx 로컬 SNI 경로로 공개 Keycloak discovery 의 exact issuer 확인
[3/8] gitea-keycloak-oidc Secret 의 type 과 key 이름만 확인 (payload 안 읽음)
[4/8] 고정 chart package SHA-256 재검증 · 렌더 · handoff SHA-256 을 메모리에 저장
[5/8] 운영자 확인:  Type APPLY <context> GITEA-OIDC <manifest-sha256>
      — context 뿐 아니라 렌더 결과의 SHA-256 64자를 그대로 쳐야 한다
[6/8] 승인 직후 context · API server · node 재검사, handoff SHA-256 재비교
[7/8] gitea-oidc.yaml 하나만 적용하고 rollout 대기
[8/8] 사후 검증 — 출처가 넷이다
        OAuth source   : gitea admin auth list       (파드 exec)
        가입 정책·scope : /data/gitea/conf/app.ini    (파드 exec)
        OIDC redirect  : HTTPS 요청의 302 Location 파싱
        브랜딩 hash     : 공개 URL 다운로드 → 저장소 원본과 sha256 대조
      성공·실패·INT·TERM 어느 경로로 끝나도 handoff 디렉터리 제거

「적용」이 아니라 「트랜잭션」이다. 사전 조건, 사람 확인, 확인 직후 재검사, 바이트 단위 handoff 대조, 사후 검증, 모든 종료 경로의 cleanup 이 한 스크립트에 들어 있다. 확인 문구에 manifest 의 SHA-256 을 넣은 것이 이 구조의 핵심이다 — 운영자가 무엇을 적용하는지 손으로 옮겨 적지 않으면 통과할 수 없다.

그래서 이런 성질이 생긴다.

  • fail-closed 가 기본이다. 조건이 불명확하면 진행하지 않는다. --execute 없이는 아무것도 바꾸지 않고, 확인 문구는 정확히 일치해야 한다.
  • create-only 와 lifecycle 이 갈려 있다. apply-phase1-gitea.sh 는 gitea/gitea Deployment 나 gitea-keycloak-oidc Secret 이 이미 있으면 시작 전에 거부한다. 재적용용 스크립트가 아니다.
  • rollback 이 삭제가 아니다. Traefik 실패 rollback 은 HCC 삭제가 아니라 NodePort-only baseline 적용이다. 자동 rollback 은 CRD·Retain PV/PVC·버킷·Secret payload 를 지우지 않는다.
  • 실패 기록이 재시도 입력이 아니다. 실패한 rollback ID·ledger·handoff 는 보존하되 같은 ID 로 재시도하지 못하게 한다.

14.3 이 접근의 값

얻은 것: 사람이 손으로 하면 반드시 빠뜨릴 단계를 코드가 붙든다. 「계획이 맞아도 손으로 옮기다 깨진다」를 막는 구조다.

치른 값: 스크립트를 테스트해야 하고, 그 테스트가 33,937줄이 됐다. 그리고 스크립트의 predicate 가 틀리면 정상 상태를 실패로 판정한다 — 실제로 그런 일이 네 번 있었다(§17.4).

아직 없는 것: 이 스크립트들을 자동으로 돌리는 CI 가 없다. .github/ 도 .gitea/ 도 없다(관측). 사람이 부를 때만 돈다.

14.4 GitOps 는 아직 자리만 있다

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」는 이미 끝났다.

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 를 독립 호출하라고 적는다.

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)

donghyeon.kang/platform-core/raw/branch/main/README.md   → 200 (익명)

자격 증명은 없다. .gitignore 와 scan-platform-sensitive-source.sh 가 소스 YAML 의 kind: Secret 을 거부하고, local-recovery.env(하드웨어 식별자)와 .helm/ 은 추적되지 않는다. 실제로 추적 파일이 302개이고 그 안에 .helm/ 은 0개다.(관측)

그런데 내부 구조 전체가 공개다. 공개된 것: 노드 LAN 주소 192.168.0.107, Tailscale 주소 100.92.240.34, 다섯 hostname 과 각각의 backend·포트, Host Nginx 의 source allowlist CIDR, NetworkPolicy 58건의 정확한 selector 와 포트, 디스크 마운트 경로와 host path, 경보 임계값, Keycloak realm·client·group 이름, Secret 의 이름과 key 이름.

이게 문제인지 아닌지는 이 문서가 정할 일이 아니다. 다만 두 가지는 사실로 적어 둔다.

  1. 저장소를 public 으로 둔 것이 의도인지 기본값인지 문서 어디에도 없다. ADR 에도 security-and-secrets.md 에도 저장소 공개 수준을 정한 문장이 없다. 「Secret 을 Git 에 두지 않는다」는 있지만 「Git 자체를 누가 읽을 수 있는가」는 없다.
  2. 경보의 runbook_url 이 공개 저장소를 가리킨다. 22개 플랫폼 alert 가 전부 https://git.learn.hyeonworks.com/donghyeon.kang/project-infra/src/branch/main/docs/runbooks/2026-07-31-observability-access-cutover.md 를 가리키고 익명으로 200 이다(관측). 링크가 살아 있는 것은 좋지만, 대응 절차가 공개돼 있다는 뜻이기도 하다.

고칠 곳이 있다면 코드가 아니라 결정이다 — 저장소 공개 수준을 ADR 로 한 번 정하는 것.


18. 열린 질문

18.1 NetworkPolicy 58개가 실제로 집행되는가

왜 열려 있나. k3s 의 netpol controller 는 켜져 있다(§12.5 — 기동 로그로 확인). 남은 것은 그것이 만든 규칙이 의도대로 걸렸는가다. 중앙 문서가 "k3s CNI에서 정책이 실제 강제되는지는 양방향 allow/deny Pod 시험으로 별도 확인한다" 고 적고 그 시험 기록이 없다. 이 문서도 하지 않았고 iptables -S 는 root 가 필요해 못 읽었다.

답하는 방법. 일회용 파드 둘로 양방향을 친다. (a) default namespace 의 파드에서 platform-postgres-rw:5432 로 TCP 연결 — 차단돼야 한다. (b) observability 에 label 만 붙인 파드에서 minio:9000 으로 연결 — object-storage-allow-observability-s3 가 이름까지 보므로 차단돼야 한다. (c) gitea namespace 에 Gitea label 없는 파드를 띄우고 밖으로 나가기 — gitea-default-deny 가 podSelector 로 좁혀져 있으므로 통과할 것으로 예상되고, 그것이 확인되면 §12.1 의 지적이 사실이 된다.

왜 중요한가. §12 전체와 §9·§10 의 경계 주장이 여기에 얹혀 있다. 컨트롤러가 도는 것은 확인했으니 「선언뿐」은 아니지만 어느 규칙이 실제로 걸렸는지는 아직 모른다.

18.2 Argo CD 인계를 막는 것이 무엇인가

전제는 이미 충족됐다. §14.4 에서 본 대로 platform 저장소는 git.learn.hyeonworks.com/donghyeon.kang/platform-core 의 main 에 같은 커밋으로 올라가 있고, Gitea 에는 저장소 20개 이상이 오늘까지 갱신되고 있다. 중앙 문서가 미완으로 남긴 "HTTPS clone/push 수용 시험"은 기록되지 않았을 뿐 실제로는 돌고 있다.

그래서 질문이 바뀐다. "push 할 수 있는가"가 아니라 **"인계를 시작하면 무엇이 깨지는가"**다. ADR-0002 가 미리 적어 둔 위험 네 가지를 아직 아무도 해소하지 않았다.

  • 수동으로 만든 리소스와 Git 선언의 immutable field 가 다르면 인계 때 재생성된다. 특히 Retain Local PV/PVC 와 CNPG Cluster 가 그렇다.
  • 라이브에만 있고 저장소 기본 build root 에는 없는 것이 최소 하나 확인됐다(§17.2 의 Traefik trustedIPs). 인계 전에 이런 diff 를 전부 찾아야 한다.
  • 관측성 chart 가 저장소에서 재현되지 않는다(§17.3). Argo CD 가 .helm/charts 를 못 만들면 그 Application 은 렌더에 실패한다.
  • 수동으로 만든 Secret 16개를 Argo CD 관리로 가져오려면 Secret 관리 제품을 먼저 정해야 한다(§13.2). ADR 이 아직 없다.

답하는 방법. kubectl diff -k <build root> 를 build root 마다 돌려 라이브와 선언의 차이를 전부 목록으로 만든다. prune 없이, automated sync 없이. 차이가 0 이 되기 전에는 인계하지 않는다.

18.3 외부망에서 고포트 30080/30443 이 정말 닫혔는가

왜 열려 있나. LAN 에서의 거부는 확인됐다(관측: 000). 공개 IP 에서의 확인은 이 호스트 안에서 할 수 없다. 중앙 문서도 이것을 반복해서 미완으로 남긴다. 게다가 §17.6 의 Docker 가 iptables 를 만지는 변수다.

답하는 방법. LAN 밖의 다른 네트워크(모바일 테더링, Tailscale 이 아닌 외부 호스트)에서 공개 IP 의 두 포트로 접속해 reject 또는 timeout 인지 본다. 404 가 오면 실패다.

18.4 네 identity 의 OIDC 동작

왜 열려 있나. Grafana 는 donghyeon.kang 한 사람의 로그인만 확인됐다(기록). admin / viewer / group 없음 / membership 제거 네 경우를 다 돌리지 않았다. Gitea·AIStor·pgAdmin 은 실제 사용자 로그인 확인 자체가 없다.

무엇을 확인해야 하나. role_attribute_strict: true 가 group 없는 사용자를 정말 막는지, pgAdmin 의 OAUTH2_ADDITIONAL_CLAIMS 가 정말 게이트로 동작하는지, AIStor 의 policy claim 이 consoleAdmin 을 제대로 나르는지.

18.5 인증서 갱신이 자동으로 도는가

왜 열려 있나. storage-admin/db-admin 인증서가 2026-10-21 만료로 31일 남았다(관측). 중앙 문서는 Cloudflare DNS-01 과 certbot deploy hook(「nginx -t 가 성공한 경우에만 reload」)을 적지만 갱신이 실제로 성공한 적이 있는지는 기록이 없다. git+id 인증서는 2026-09-16 발급이므로 최근에 갱신된 것으로 보이고(추론), grafana 는 2026-08-10, 나머지 둘은 2026-07-23 발급이다.

답하는 방법. certbot renew --dry-run 을 세 lineage 에 돌리고 deploy hook 이 붙어 있는지 확인한다. 그리고 PlatformCertificateExpiry 경보가 실제로 Slack 까지 오는지 본다 — 하루 뒤면 자연히 warning 조건에 들어간다.

18.6 Loki 의 WAL 이 혼자 불어나면 무엇이 잡는가

왜 열려 있나. PlatformLokiWALDiskUsageHigh 는 이름과 달리 Loki 를 보지 않고 WAL 이 놓인 파일시스템의 사용률을 본다(§11.4). 관측값 0.6057 은 Loki 가 쓴 9.9 MiB 가 아니라 루트 파일시스템의 사용률이다. 그래서 루트가 한가한데 Loki WAL 만 5Gi 를 다 채우는 상황에는 아무 경보도 없다. Local PV 의 capacity 는 quota 가 아니고(§7.2), kubelet_volume_stats_* 도 파일시스템 값을 되풀이한다(§7.5).

잴 수단이 없는 것은 아니다. Loki 는 자기 WAL 바이트를 이미 노출한다 — prometheus_tsdb_wal_storage_size_bytes{job="observability/loki"}. §7.4 가 「9.9 MiB」로 쓴 10,342,630 이 바로 이 값이다.(관측) 그러니 정확히는 **「그 metric 으로 된 경보가 없다」**다. 이름만 보면 맞을 것 같은 loki_ingester_wal_bytes_in_use 는 0 을 내므로 쓸 수 없다.

무엇이 걸려 있나. Loki 의 disk_full_threshold: 0.90 과 replay_memory_ceiling: 512MB 는 Loki 가 스스로 쓰기를 멈추는 값이지 사람에게 알리는 값이 아니다. Alloy 쪽 PlatformAlloyLogEntriesDropped 는 결과를 잡지만 원인이 WAL 포화인지는 가르지 않는다. §7.5 의 KubePersistentVolumeFillingUp 넷은 루트 여유율을 읽으므로 여기서도 도움이 안 된다.

답하는 방법. 셋이다. (a) 가장 싼 것 — prometheus_tsdb_wal_storage_size_bytes 에 절대 바이트 임계로 경보 하나를 건다. (b) Loki·Tempo·Alloy 의 로컬 PV 를 크기가 강제되는 볼륨(전용 파티션·LVM·loop 파일)으로 옮기면 kubelet_volume_stats_* 가 제 값을 내고 §7.5 의 생성 경보 넷도 살아난다. (c) 어느 쪽도 안 하면 최소한 이 경보의 이름이 뜻하는 바를 적는다.

18.7 백업이 하나도 돌고 있지 않다

관측한 것.(evidence backup-absence)

kubectl get cronjob -A                    → No resources found
kubectl get scheduledbackup,backup -A     → No resources found
kubectl get job -A                        → helm-install-traefik 둘뿐 (40d·63d, Complete)
cluster.yaml 의 backup / barmanObjectStore / plugin  → 없음

버킷도 둘밖에 없다. minio_cluster_usage_buckets_total_bytes 가 loki 와 tempo 만 낸다 — platform-postgres-backup·gitea-backup·learning-postgres-backup 은 만들어진 흔적이 없다. (관측 — evidence aistor-objectstore-and-bucket-usage)

설계와의 거리. backup-and-recovery.md 는 PostgreSQL 일 1회 base backup + 연속 WAL, Gitea 일 1회, 보존 14일을 적는다. 선언도 스케줄도 버킷도 없다.

무엇이 걸려 있나. 지금 /dev/sdc 가 죽으면 Gitea 저장소와 두 DB 의 논리 복구본이 어디에도 없다. K3s recovery bundle 은 제어면(SQLite·token·host config)만 담고 애플리케이션 데이터는 명시적으로 제외한다(ADR-0010). Gitea 는 platform-core 를 포함해 20개 저장소의 유일한 원본이고(§17.7), 그 중 일부는 다른 기계의 clone 이 사본 노릇을 하겠지만 issue·PR· 사용자·attachment 는 clone 에 안 담긴다.

이것이 이 플랫폼에서 가장 큰 단일 공백이다. 단일 노드·non-HA 는 문서가 반복해서 경고하고 수용한 위험이다. 백업 부재는 다르다 — 문서가 「할 것」으로 적어 둔 뒤 아직 안 했다. 다른 미완들(격리 restore drill, off-host 복제, OIDC matrix)은 있는 것을 검증하는 일인데 이것만 없는 것을 만드는 일이다.

답하는 방법. 순서가 이미 문서에 있다 — AIStor 에 platform-postgres-backup 버킷과 전용 최소권한 access key 를 만들고, CNPG Cluster 에 backup 설정을 더하고, ScheduledBackup 을 걸고, 별도 임시 namespace 에 복원해 두 DB 의 격리까지 확인한다. 버킷을 만드는 것과 복원이 되는 것은 다른 일이다.


19. 이 문서로 말할 수 없는 것

앞의 열여덟 절은 각자의 자리에서 무엇을 못 봤는지 이미 밝혔다. 여기서는 그 조각들이 합쳐졌을 때 읽는 사람이 넘어서면 안 되는 선 하나만 다시 못 박는다.

이 문서의 「경계」는 전부 선언과 관측된 상태이지 시험 결과가 아니다. 로그인도, push 도, S3 put/get 도, 백업도, 복구도, NetworkPolicy 의 allow/deny 도 한 번 돌려 보지 않았다. 그래서 세 쌍을 아직 아무도 잇지 못했다 — 「NetworkPolicy 58건이 있다」와 「그 58건이 경계로 동작한다」(§18.1), 「Secret 계약 16개가 다 있다」와 「그 값이 맞다」(§13.2), 「secrets-encryption: true 가 켜져 있다」와 「재암호화가 끝났다」(§6.2).

그 선을 만든 것이 넷이다. sudo 가 없어 k3s secrets-encrypt status 와 /etc/hyeonworks/ 아래를 못 읽었고(§1.2), 같은 이유로 루트 SSD 의 약 53G — 컨테이너 이미지 저장소로 보이는 — 를 귀속하지 못했으며 Tempo 의 로컬 작업공간도 재지 못했다(§7.4). Keycloak 관리 API 를 부르지 않아 realm 내용은 discovery endpoint 까지만 봤고(§9.3), 중앙 문서의 runbook 20편·plan 27편 약 21,900줄과 vendored chart 155,560줄은 인용을 확인할 때만 열었다(§1.2, §21.2).

그리고 「관측」이라고 적었는데 증거 파일에 원문이 없는 것이 여덟 가지 있다. CPU·메모리· swap, 노드 allocatable, §16.1 의 root filesystem 계산에 쓴 85,786,652,672, Host Nginx 파일의 줄 수와 mtime, PV 열 개의 nodeAffinity, k3s drop-in 의 바이트 동일성, 호스트의 systemd 서비스 다섯, 스크립트 네 개의 줄 수. 여덟 다 라이브에서는 참이지만 §1.2 가 정의한 「관측 = 증거 원문이 있다」를 어긴다. 다시 주장하려면 그 명령을 돌려 증거로 남겨야 한다.

마지막으로 이것은 2026-09-20 한 번의 스냅숏이다. 파드의 재시작 횟수가 대부분 24일 전 1~4회로 찍혀 있다 — 이 시스템은 움직인다. 숫자를 인용하기 전에 §16 의 명령을 다시 돌린다.


제2부 — 근거

20. 증거 색인

전부 final/evidence/raw/<id>.txt 에 원문이, final/evidence/meta/<id>.json 에 command·cwd·executedAt·exitCode·revision·sha256 이 있다. 모두 2026-09-20 에 실행했다. 19벌은 ssh desktop 으로 종료 코드 0, 한 벌(tailscale-peer-vantage)은 별도 호스트에서 종료 코드 7 이다 — 마지막 명령인 NodePort curl 의 연결 거부가 그 증거의 결론이라 비정상이 아니다. meta 의 exitCodeNote 에 그 사실을 적었다.

id 무엇을 증명하나 증명하지 않는 것
cluster-node-and-pods 노드 사양과 전 namespace 파드 Ready Ready 가 기능 정상은 아니다
cluster-services-and-ingress Service type 과 Ingress host, 외부 노출이 NodePort 하나 Host Nginx allowlist 는 안 보인다
cluster-networkpolicy-and-storage NetworkPolicy 58건, PV 10개 Bound CNI 집행 여부는 모른다
prometheus-targets-and-rules 30/30 healthy, alert 155·recording 86, firing 0 155개 조건을 주입 시험한 것이 아니다
alertmanager-receivers-and-alerts receiver 2개 qualified, active·silence 0 Slack 전달 성공 여부는 모른다
aistor-objectstore-and-bucket-usage Initialized/green, drive 1/1, 버킷 사용량·quota율 S3 기능·복구 가능성은 모른다
secret-inventory-names-only Secret 이름과 type 값의 정확성·회전 여부는 모른다
host-nginx-active-config 활성 nginx 설정 전문 저장소 어느 후보와 같은지는 별도 대조
host-private-dns-config dnsmasq 2 인스턴스와 정적 응답 공유기·Tailscale 등록은 호스트 밖
edge-tls-certificates 각 hostname 이 제시하는 인증서 갱신 자동화 동작은 모른다
edge-boundary-probe public 200, NodePort LAN 거부·loopback 404 외부망에서의 차단은 모른다
k3s-config-dropins-and-storage drop-in 2개, XFS noquota, 디스크 사용량 secrets-encrypt status 는 못 읽었다
node-resource-allocation request/limit 합계와 실사용 부하 시험이 아니다
running-container-images 실제 이미지 tag·digest 저장소 고정값과의 대조는 별도
traefik-live-helmchartconfig 라이브에 trustedIPs: 10.42.0.1/32 존재 저장소 기본 root 가 이를 렌더하는지는 별도
platform-repo-loc 영역별 파일·줄 수 줄 수가 품질이 아니다
git-remote-and-gitea-repos 원격 main = 로컬 HEAD, Gitea 저장소 20+ 전부 public, CI 디렉터리 없음, .helm/·local-recovery.env 미추적 이 기계에서 push 했다는 직접 증거는 아니다
backup-absence CronJob·ScheduledBackup·Backup 0건, Cluster 에 backup 섹션 없음 수동 pg_dump 같은 다른 방식의 백업 이력은 모른다
tailscale-peer-vantage 다른 호스트에서 Tailscale split DNS 동작, 관리 UI 접근, NodePort 거부 LAN·Tailscale 밖에서의 동작은 여전히 모른다
disk-usage-attribution 워크로드별 실사용량, 루트 파일시스템 내역, local PV 의 kubelet_volume_stats_* 가 파일시스템 전체를 되풀이한다는 것 sudo 가 없어 컨테이너 이미지 저장소 약 53G 를 귀속하지 못했다. Tempo 로컬도 못 쟀다

21. 원본 색인

21.1 분석 대상 저장소

/home/donghyeon/workspace/platform @ 16c337bcc91b27ac0f074154b8337e4c8dc17ebb (commit 2개: fa76531 Initial commit, 16c337b Add platform infrastructure configuration. 원격 없음, working tree clean)

경로 이 문서에서 근거로 쓴 절
README.md §1.1, §6.3, §14
infrastructure/networking/traefik/** §4.4, §4.5, §17.2
infrastructure/networking/host-nginx/** §4.1~§4.3
infrastructure/networking/private-dns/** §5
infrastructure/namespaces/** §2.3, §11.2
infrastructure/storage/** §7
infrastructure/security/k3s/** §6.2, §13.1, §13.5
services/platform-postgres{,-keycloak}/** §8
services/keycloak/** §9.2
services/gitea/** §10.1, §9.5
services/minio-aistor/** §10.2, §9.3
services/pgadmin/** §10.3
services/observability/** §11 전체
scripts/** §13.3, §14
.gitignore §13.1, §17.3

21.2 중앙 설계·운영 문서

/home/donghyeon/workspace/docs/platform (git 없음, 85파일 28,708줄)

묶음 편수 기준일 전량 읽음
architecture/ 16 (.md 15 + platform-overview.md.orig) 2026-07-23 ~ 2026-08-09 ✅ (.orig 제외)
adr/ 10 2026-07-22 ~ 2026-08-01 ✅
observability/ 10 2026-08-15 ✅ (08 제외 9편)
runbooks/ 20 2026-07-22 ~ 2026-08-13 참조만
plans/ 27 2026-07-31 ~ 2026-08-15 참조만
README.md 1 2026-08-09 ✅

중앙 문서를 이 저장소로 복사하지 않았다. 이 SSOT 가 인용한 문장은 본문에 「기록」으로 표시했고, 원문은 위 경로에 있다. 그 경로가 사라지면 이 문서의 「기록」 항목은 재확인할 수 없게 된다 — 그것이 §19(4)의 한계와 같은 종류의 제약이다.