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>
This commit is contained in:
wbsong111
@@ -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`으로 조정함.
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user