From d35117a976debd7189dbd2eeecf2c4b79fe213c9 Mon Sep 17 00:00:00 2001 From: wbsong111 Date: Thu, 25 Jun 2026 16:11:18 +0900 Subject: [PATCH] docs: capture internal-CA trust requirement for vmauth/perses OIDC + perses login=preferred_username Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/monitoring-deploy-test.md | 6 +++++- doc/victoria-metrics-architecture.md | 10 ++++++++-- .../helm/victoria-metrics-auth/0.33.0/CUSTOM-README.md | 1 + 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/monitoring-deploy-test.md b/doc/monitoring-deploy-test.md index 191e4aa..1db825e 100644 --- a/doc/monitoring-deploy-test.md +++ b/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`으로 조정함. diff --git a/doc/victoria-metrics-architecture.md b/doc/victoria-metrics-architecture.md index 4036c97..aad49b3 100644 --- a/doc/victoria-metrics-architecture.md +++ b/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) | diff --git a/manifests/helm/victoria-metrics-auth/0.33.0/CUSTOM-README.md b/manifests/helm/victoria-metrics-auth/0.33.0/CUSTOM-README.md index 011fbf4..e726fee 100644 --- a/manifests/helm/victoria-metrics-auth/0.33.0/CUSTOM-README.md +++ b/manifests/helm/victoria-metrics-auth/0.33.0/CUSTOM-README.md @@ -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