service-catalog/manifests/helm/perses/0.21.0/CUSTOM-README.md

Perses 배포 (Keycloak OIDC 로그인 + 대시보드 프로비저닝)

Perses는 Apache 2.0 라이선스의 대시보드/시각화 플랫폼이다(Grafana AGPLv3 대체). Keycloak OIDC로 로그인하고, VictoriaMetrics·VictoriaLogs를 데이터소스로 사용한다.

1. 배포 방법

사전 준비

Keycloak 리소스는 배포 환경에 항상 존재하는 paasup realm에 생성한다 (realm 신규 생성 금지). issuer: https://keycloak.example.org/realms/paasup.

1. Client perses 생성 (confidential, Valid Redirect URIs: https://perses.example.org/api/auth/providers/oidc/keycloak/callback)
2. datasource용 service-account Client perses-vmauth 생성 (client_credentials 활성화, vm-access Client Scope 연결 → vm_access 클레임으로 플랫폼 조회 권한). vmauth CUSTOM-README.md 3장 참조.
3. (사내 CA 사용 시) Keycloak TLS CA Secret 생성

   kubectl create secret generic root-ca-cert -n monitoring --from-file=ca.crt=./ca.crt
   

helm upgrade perses ./ -f custom-values.yaml --install -n monitoring

2. custom-values.yaml 설정 설명

2.1 OIDC 로그인 (config.security)

enable_auth: true + Keycloak OIDC provider. enable_native: true로 네이티브 로그인도 병행 가능하다.

2.2 secret_key (쿠키 서명 키)

미설정 시 파드 재시작마다 랜덤 생성되어 OIDC state 쿠키가 무효화된다. 운영에서는 Secret으로 고정한다(custom-values.yaml의 PERSES_SECURITY_ENCRYPTION_KEY 주석 참조).

2.3 SSL_CERT_FILE

사내 CA로 서명된 Keycloak을 신뢰하도록 /ca/ca.crt를 마운트하고 환경변수로 지정한다.

2.4 사이드카 프로비저닝

sidecar.enabled: true이면 perses.dev/resource: "true" 라벨이 붙은 ConfigMap을 자동 로드한다. 대시보드·데이터소스·프로젝트가 이 방식으로 등록된다(아래 4장).

3. 권한 관리 (Perses RBAC)

⚠️ Perses v0.53.1은 OIDC groups claim 자동 동기화를 지원하지 않는다. 로그인 시 Keycloak sub(UUID)가 Perses User의 name이 된다.

따라서 권한은 Perses 자체 RBAC로 관리한다.

• Role (Project별): owner(actions:[*]), editor(Dashboard/Datasource/Folder/Secret/Variable 전체 + Project/Role/RoleBinding read), viewer(read-only)
• RoleBinding: subject = {kind: User, name: <Keycloak UUID>}

그룹 멤버 → RoleBinding 매핑은 자동이 아니므로, 운영자가 온보딩 시점에 직접 Keycloak UUID를 조회해 RoleBinding을 생성한다(또는 CronJob으로 자동화 — 참고 구현: vm-stack install/14-onboard-project.sh). 별도 스크립트는 카탈로그에 포함하지 않는다.

온보딩 절차 (테넌트마다, Perses REST API)

PERSES=https://perses.example.org
KC=https://keycloak.example.org
# Keycloak 관리자 토큰 → UUID 조회 (sub == Perses User name)
KTOKEN=$(curl -s -X POST "$KC/realms/master/protocol/openid-connect/token" \
  -d grant_type=password -d client_id=admin-cli -d username=admin -d password="$KC_ADMIN_PW" | jq -r .access_token)
UID=$(curl -s "$KC/admin/realms/paasup/users?username=alice" -H "Authorization: Bearer $KTOKEN" | jq -r '.[0].id')

# 1) Project 생성 (이미 사이드카로 생성됐다면 생략)
curl -s -X POST "$PERSES/api/v1/projects" -H 'Content-Type: application/json' \
  -d '{"kind":"Project","metadata":{"name":"tenant-demo01"}}'

# 2) editor RoleBinding (subject = Keycloak UUID)
curl -s -X POST "$PERSES/api/v1/projects/tenant-demo01/rolebindings" \
  -H 'Content-Type: application/json' -d "{
    \"kind\":\"RoleBinding\",
    \"metadata\":{\"name\":\"editors\",\"project\":\"tenant-demo01\"},
    \"spec\":{\"role\":\"editor\",\"subjects\":[{\"kind\":\"User\",\"name\":\"$UID\"}]}
  }"

Role(owner/editor/viewer)은 Project 생성 시 1회만 정의하면 재사용된다(/api/v1/projects/<p>/roles).

4. 대시보드/데이터소스 프로비저닝 (files/perses-provisioning.yaml)

perses.dev/resource: "true" 라벨 ConfigMap이며 사이드카가 자동 로드한다.

# 데이터소스 URL / OAuth client_secret 등을 환경에 맞게 수정 후 적용
kubectl apply -f files/perses-provisioning.yaml

포함 리소스 (project: monitoring)

리소스	이름	비고
Dashboard	k8s-node-overview	노드 CPU/메모리/디스크/네트워크
Dashboard	k8s-workloads	네임스페이스별 Pod/리소스/Deployment/PVC
Dashboard	k8s-pod-diagnostics	Pod 로그·이벤트 (VictoriaLogs)
Dashboard	k8s-pod-history	Pod 재배포/재시작 이력
Datasource	victoriametrics	Prometheus 호환 → vmauth:8427
Datasource	victorialogs	LogsQL → vmauth:8427
Secret	vmauth-platform-admin	vmauth용 OAuth client_credentials

4.1 데이터소스 인증 — OAuth client_credentials (전면 JWT/OIDC)

victoriametrics/victorialogs 데이터소스는 vmauth(:8427)를 향하며, HTTPProxy secret으로 Keycloak service-account 토큰(client_credentials)을 사용한다.

{ "kind": "Secret", "metadata": {"name": "vmauth-platform-admin", "project": "monitoring"},
  "spec": { "oauth": {
    "clientID": "perses-vmauth",
    "clientSecret": "perses-vmauth-secret-changeme",
    "tokenURL": "https://keycloak.example.org/realms/paasup/protocol/openid-connect/token",
    "scopes": ["openid"] } } }

Perses가 토큰을 자동 발급·갱신하며, 해당 토큰의 vm_access 클레임이 vmauth에서 테넌트 라우팅을 결정한다.

⚠️ Perses는 로그인 사용자의 OIDC 토큰을 업스트림 데이터소스로 전달하지 않는다. 데이터소스 쿼리는 항상 위 service-account 토큰(서버사이드)으로 나간다. 사용자 단위 데이터 격리가 필요하면 Project별 데이터소스+service-account를 분리한다.

5. 배포 검증

kubectl port-forward -n monitoring svc/perses 8080:8080
# 브라우저: http://localhost:8080 → Keycloak 로그인 → monitoring 프로젝트 대시보드 확인