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>
2026-06-25 16:11:18 +09:00
parent 9fab760992
commit d35117a976
3 changed files with 14 additions and 3 deletions
@@ -9,6 +9,7 @@ vmauth는 VictoriaMetrics 에코시스템의 인증·라우팅 프록시다. vms
 - vmauth **v1.138.0+** 부터 `jwt.oidc.issuer`로 OIDC Discovery 기반 JWT 검증을 지원한다 (Enterprise 아님). 본 카탈로그는 v1.144.0 기준이다.
 - 쓰기 경로(remote_write)는 vmauth를 경유하지 않는다. vmagent는 vminsert에 직접 쓴다.
 - vmcluster, (로그 사용 시) vlogs가 먼저 배포되어 있어야 한다.
+- ⚠️ **Keycloak이 사내 CA 서명이면 `root-ca-cert` Secret이 먼저 있어야 한다.** custom-values가 이를 `/ca`에 마운트하고 `SSL_CERT_FILE=/ca/ca.crt`로 신뢰시킨다. 없으면 vmauth가 OIDC discovery를 TLS 검증 못 해(`x509: certificate signed by unknown authority`) **OIDC verifier 초기화 실패 → 모든 JWT 401**. (퍼블릭 CA Keycloak이면 불필요 — 해당 블록 제거 가능)

 ```sh
 helm upgrade vmauth ./ -f custom-values.yaml --install -n monitoring