본문으로 건너뛰기

Weaviate RBAC

GenD prod 의 Weaviate (v1.36.12) RBAC 모델 + 사용자별 권한 활성화 절차.

Refs: 결정 epic #753 (closed), design doc docs/DESIGN_WEAVIATE_RBAC_MIGRATION.md.

현 운영 모델 (2026-05-04 기준)​

핵심:

  • weaviate RBAC 활성 (AUTHORIZATION_ENABLE_RBAC=true) + 3 role 등록 (gend-viewer, gend-analyst, gend-engineer)
  • service-account-weaviate 가 AUTHORIZATION_RBAC_ROOT_USERS 멤버 → 모든 권한
  • gend-api 가 항상 root 토큰으로 weaviate 호출
  • 사용자별 권한 차등은 application-layer vector_policy_enforcer 가 단독 책임

3 Role permission 매트릭스​

RoleDocsPublicDocsInternalDocsRestricted
gend-viewerread——
gend-analystreadread—
gend-engineerread+writeread+writeread+write
service-account-weaviate (root)***

각 role 의 정확한 permission JSON 은 infra/weaviate/rbac-init-job.yaml 의 ConfigMap 참조.

가설 1 (group→role 자동 매핑) 미동작​

검증 결과 (2026-05-04):

  • audience=weaviate 토큰의 /v1/users/own-info 응답
  • groups: ["gend-viewer"] 정확히 표시 (Keycloak claim 그대로)
  • roles: null ❌ — 자동 매핑 X

→ Keycloak group 멤버십을 weaviate role 권한으로 자동 변환하지 않음.

사용자별 RBAC 활성화 결정 트리​

직접 호출 use case 발생 시점​

다음 케이스 발생 시 본 가이드의 절차로 활성화:

  • JupyterHub 사용자가 notebook에서 weaviate-client Python lib 으로 직접 vector search
  • Superset / 외부 BI 도구 가 weaviate 를 데이터 source 로 추가
  • 외부 RAG 서비스 (서드파티) 가 weaviate API 직접 호출

현 시점 (2026-05-04) 에는 위 use case 모두 발생 X — gend-api REST 경유로 충분.

Tier 2: Manual assign script (5명 이하)​

scripts/weaviate-rbac/assign-user-role.sh 으로 운영자가 1 사용자씩 등록.

사전 조건​

  • kubectl --context aks-genos-prod 권한
  • Keycloak realm gend 에 사용자 생성 + 그룹 멤버 등록 완료
  • weaviate-api-credentials.client-secret SealedSecret 존재
  • gend-realm-sync.client-secret SealedSecret 존재

실행​

./scripts/weaviate-rbac/assign-user-role.sh <username> <role>

# 예시
./scripts/weaviate-rbac/assign-user-role.sh alice gend-viewer
./scripts/weaviate-rbac/assign-user-role.sh bob gend-engineer

동작 (실제 구현)​

  1. gend-realm-sync master client 으로 Keycloak admin token 발급
  2. Keycloak realm gend 에서 user 존재 확인 (없으면 fail)
  3. weaviate root 토큰 (service-account-weaviate, client_credentials) 발급
  4. weaviate role 존재 확인 (GET /v1/authz/roles/{role}) — rbac-init-job 적용 안 됐으면 fail
  5. POST /v1/authz/users/{username}/assign body {"roles": [<role>]} 호출
  6. GET /v1/authz/users/{username} 으로 assign 결과 검증

본 스크립트는 weaviate client 의 directAccessGrantsEnabled 토글을 하지 않음 — root 토큰 (client_credentials) 만으로 assign 가능. 사용자 토큰 발급은 본 스크립트 범위 외 (audience mapper 또는 token-exchange 별도 절차).

Revoke​

./scripts/weaviate-rbac/revoke-user-role.sh <username> <role>

POST /v1/authz/users/{username}/revoke 호출.

Audience 발급​

사용자가 weaviate 를 직접 호출하려면 토큰의 aud claim 이 weaviate 여야 함. gend-ui 토큰은 [gend-api, account] 라 미달. 두 옵션:

  1. Keycloak audience mapper 추가 (권장): gend-ui client 에 audience mapper 추가 → 토큰에 weaviate audience 포함. 모든 사용자 토큰에 영구 적용.
  2. Token-exchange grant: gend-api 가 사용자 토큰을 weaviate audience 로 변환. gend-api 측 로직 추가 필요.

Tier 3a: CronJob sync 자동화 (5~20명, 정기)​

# infra/weaviate/rbac-sync-cronjob.yaml (예시 — 본 PR 미포함)
spec:
  schedule: "*/5 * * * *"  # 5분 간격
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: sync
              command:
                - sh
                - -c
                - |
                  # 1. Keycloak group 멤버 list 조회 (gend-viewer/analyst/engineer)
                  # 2. weaviate /v1/authz/roles/{role}/users 조회
                  # 3. diff 처리: assign / revoke

본격 구현은 use case 발생 시 별도 epic + sub-issue 로 진행.

Tier 3b: Keycloak SPI (즉시 반영 필요)​

Keycloak custom Service Provider Interface (Java extension) 으로 group 변경 이벤트 listen → weaviate REST API 즉시 호출. 운영 부담 큼 (Java 빌드, Keycloak 이미지 커스터마이즈, 호환성 관리). 20+ 사용자 또는 즉시 반영 SLA 시에만 권장.

참고​

  • design doc: docs/DESIGN_WEAVIATE_RBAC_MIGRATION.md (epic 결정 사항 + 검증 절차)
  • 검증 결과 PR: #763
  • vector_policy_enforcer: apps/api/src/gend_api/services/vector_policy_enforcer.py
  • rbac-init-job: infra/weaviate/rbac-init-job.yaml