docs: capture internal-CA trust requirement for vmauth/perses OIDC + perses login=preferred_username

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

doc/monitoring-deploy-test.md

@@ -186,6 +186,8 @@ curl -sk -X PUT "$KC/admin/realms/$REALM/users/$SAU" -H "$H" -H "$JSON" \
 ### 3.3 시크릿 (평문 목 — external-secrets/Infisical 대체) — ✅ 실행 완료 (2026-06-25)
 
 > `monitoring` ns 선생성 필요(ArgoCD `CreateNamespace`는 sync 시점 → 사전 생성). perses OIDC `client_secret`은 perses-values.yaml에 인라인이라 별도 Secret 불필요(목). `root-ca-cert`·`alertmanager-notify`만 필요.
+>
+> ⚠️ `root-ca-cert`는 **vmauth·perses 양쪽**이 마운트(SSL_CERT_FILE)해 Keycloak OIDC TLS 검증에 사용. **누락 시 vmauth가 JWT 검증 불가(x509)** — 본 테스트에서 실제 발생(§8 참조).
 
 ```sh
 kubectl create namespace monitoring --dry-run=client -o yaml | kubectl apply -f -
@@ -279,7 +281,7 @@ vm-stack `test/` 패턴(port-forward + curl) 적응.
 |---|------|------|
 | 1 | 파드 | ✅ **15/15 Running** |
 | 2 | 메트릭 | ✅ `count(up)`=**9**(acct0)/**36**(multitenant), status=success. vmagent 스크레이프→vminsert 적재 정상 |
-| 3 | 인증 라우팅 | ✅ Keycloak `perses-vmauth` client_credentials 토큰의 `vm_access:{metrics_account_id:0,logs_account_id:0}` → vmauth가 acct0 라우팅, count=9. ⚠️ 아래 발견사항 |
+| 3 | 인증 라우팅 | ✅ (CA 수정 후 재검증) Keycloak `perses-vmauth` 토큰 `vm_access:{...:0}` → vmauth가 **실제 JWT 검증** 후 acct0 라우팅(count=9), 무토큰 401. ※ 초기엔 vmauth CA 미신뢰로 검증 실패→`unauthorized_user` 폴백이 가렸음(아래 발견사항) |
 | 4 | 로그 | ✅ vlselect `logsql`(AccountID:0) 데이터 존재. otelcol→vlinsert 적재 확인 |
 | 5 | 멀티테넌시 | ◐ 부분 — acct0/multitenant 라우팅 확인. demo01/demo02(acct1/2)는 워크로드 없어 데이터 없음 → 격리 양성검증만, 음성검증(타 테넌트 차단)은 워크로드 필요 |
 | 6 | perses | ◐ 로그인(`paasup`, global-admin)✅ + 대시보드 4종·데이터소스(victoriametrics/victorialogs) provisioning 적용✅. 인터랙티브 패널 렌더는 브라우저 로그인 필요(미실시) |
@@ -333,6 +335,8 @@ vm-stack `test/` 패턴(port-forward + curl) 적응.
 - **발견 이슈 / 개선사항 (반영 결과)**:
   - ✅ **vmcluster/vlogs OutOfSync 해결** — ApplicationSet `ignoreDifferences`(StatefulSet `/spec/volumeClaimTemplates`) 추가 → 11/11 Synced.
   - ✅ **`unauthorized_user` 제거 완료** — vmauth 미인증 접근 차단(무토큰/무효토큰 401). vmalert는 vmselect 직결.
+  - 🔴→✅ **vmauth가 JWT를 검증 못 하던 문제(중대)** — vmauth가 Keycloak OIDC discovery를 사내 CA 미신뢰로 가져오지 못해(x509) **OIDC verifier 초기화 실패 → 모든 JWT 검증 불가**. `unauthorized_user`가 이를 가려 그동안 acct0 폴백으로만 동작(=JWT 인증 실효 없음). **수정**: vmauth에 `root-ca-cert` 마운트 + `SSL_CERT_FILE=/ca/ca.crt` → OIDC verifier 정상, 유효 JWT 검증 성공·무토큰 401 재확인. (Perses 대시보드 unauthorized도 이 때문이었음)
+    → **교훈**: Keycloak이 사내 CA면 **vmauth·perses 등 JWT/OIDC 소비자 모두 CA 신뢰 설정 필수**.
   - ◐ **perses 데이터소스/시크릿** — E2E 중 `perses-provisioning` 수동 apply. 정식 배포 시 ArgoCD 경로(또는 dip-console)로 포함 필요 (남은 backlog).
   - **Perses OIDC login = `preferred_username`** (v0.53.1 실측) — globalAdminUsers/RoleBinding은 username 기준(앞서 "sub UUID" 가정은 오류, 정정함).
   - ArgoCD 설치 위치 `platform` ns — ApplicationSet ns를 `platform`으로 조정함.

doc/victoria-metrics-architecture.md

@@ -167,7 +167,13 @@ sequenceDiagram
 - **Clients**: `perses`(UI 로그인), `perses-vmauth`(datasource service-account, client_credentials), `vmauth-client`(선택, 직접 API).
 - **vmauth**: `config.users[].jwt.oidc.issuer = https://keycloak.example.org/realms/paasup`.
 - **테넌트 온보딩**: Keycloak Group + user attribute만 추가 → **재배포 불필요**.
-- **Perses 권한**: OIDC groups 자동 동기화 미지원 → Perses 자체 RBAC(Project별 Role/RoleBinding, subject = Keycloak UUID) 수동 관리.
+- **Perses 권한**: OIDC groups 자동 동기화 미지원 → Perses 자체 RBAC(Project별 Role/RoleBinding) 수동 관리. login 식별자는 OIDC **`preferred_username`**(v0.53.1 실측). global-admin은 `sidecar.globalAdminUsers`에 username 지정.
+
+> ⚠️ **사내 CA 신뢰 필수 (중요)** — Keycloak이 **사내 CA**로 서명된 경우, JWT/OIDC 소비자가 issuer의 OIDC discovery/JWKS를 HTTPS로 가져올 때 CA를 신뢰해야 한다. 누락 시:
+> - **vmauth**: OIDC verifier 초기화 실패(`x509: certificate signed by unknown authority`) → **모든 JWT 검증 불가(401)**.
+> - **Perses**: OAuth 토큰 발급/콜백 실패.
+>
+> → **vmauth·perses 모두 `root-ca-cert` Secret 마운트 + `SSL_CERT_FILE=/ca/ca.crt`** 설정(custom-values에 반영됨). `root-ca-cert`는 사전조건 Secret(dip-console가 platform CA 복사).
 
 상세 절차: [victoria-metrics-auth CUSTOM-README](../manifests/helm/victoria-metrics-auth/0.33.0/CUSTOM-README.md) 3장.
 
@@ -272,7 +278,7 @@ GitOps 기반. 역할을 4개로 분리한다.
 |---|---|---|
 | 인증 (Keycloak `paasup`) | **dip-console** | `vm-access` scope·`perses`/`perses-vmauth` client·테넌트 그룹/attribute를 Admin API로 생성 |
 | 시크릿 | **dip-console + Infisical** | Infisical 등록 → external-secrets가 `monitoring` ns Secret 동기화 → 차트는 `existingSecret` 참조 |
-| root-ca-cert | **dip-console** | platform ns → `monitoring` 복사 |
+| root-ca-cert | **dip-console** | platform ns → `monitoring` 복사. **vmauth·perses가 마운트**(SSL_CERT_FILE)해 Keycloak OIDC TLS 검증 — 누락 시 vmauth JWT 검증 불가 |
 | 테넌트 relabel (`vmagent-relabel-configs`) | **dip-console** | 테넌트(demo01/demo02/platform) 추가·수정 |
 | 대시보드 ConfigMap | **카탈로그/ArgoCD** | 정적 → ArgoCD 경로 소스로 적용(사이드카 로드) |
 | StorageClass / Ingress / cert-manager | **플랫폼 기본 배포** | 전제(longhorn, ingress controller, root-ca-issuer) |