Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
Keycloak 2개 + PostgreSQL 2개로 SSO를 만들고, 파드와 DB를 일부러 죽여 본 기록
로컬 쿠버네티스 실습 시리즈 목차 · 글 15개
- 1편Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind
- 2편Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
- 3편NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
- 4편kube-prometheus-stack 설치와 Grafana 접속: kind 클러스터 모니터링과 target down 해결
- 5편Fluent Bit과 Loki로 쿠버네티스 로그 모으기: kind 실습과 Grafana 조회, AWS 확장 예시
- 6편cert-manager로 Gateway API HTTPS 붙이기: 사설 CA, 자동 갱신, 만료 알림까지 kind 실습
- 7편Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
- 8편OpenTelemetry로 쿠버네티스 트레이스 모으기: Collector, Tempo, 샘플링과 장애 훈련까지 kind 실습
- 9편Argo CD로 쿠버네티스 GitOps 전환하기: Helm 설치 넘겨받기, Sealed Secrets, Keycloak SSO와 장애 훈련까지 kind 실습
- 부록Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
- 10편Trivy Operator로 쿠버네티스 취약점 점검하기: 이미지·설정·비밀값 스캔, Grafana 경보, Argo CD로 고치기까지 kind 실습
- 번외편Trivy로 찾은 컨테이너 이미지 취약점 고치기: nginx apk upgrade, Go 의존성 올리기, Grafana처럼 직접 못 고치는 경우까지
- 11편Istio Ambient 모드로 서비스 메시 붙이기: 사이드카 없이 mTLS, 권한 정책, waypoint 트래픽 분할과 장애 훈련까지 kind 실습
- 12편Strimzi로 쿠버네티스에 Kafka 올리기: KRaft 브로커 3대, SCRAM·ACL, 소비 지연 경보와 장애·업그레이드 훈련까지 kind 실습
- 13편Airflow를 쿠버네티스에 올리기: KubernetesExecutor, git-sync DAG 배포, 재시도·catchup부터 스케줄러 장애와 3.4 업그레이드까지 kind 실습
Keycloak은 로그인과 사용자·권한 관리를 대신해 주는 오픈소스 인증 서버이고, 운영에서는 개발 모드(start-dev)가 아니라 외부 데이터베이스와 고정 주소를 쓰는 운영 모드(start)로 띄웁니다. kind 클러스터에 Keycloak Operator 26.8.2로 Keycloak 2개를, CloudNativePG 1.30.1로 PostgreSQL 2개(주 서버 + 복제본)를 띄우고, 6편의 HTTPS 위에서 Grafana 로그인을 Keycloak SSO로 바꿨습니다. 그룹에 따라 Admin과 Viewer가 나뉘고 그룹이 없는 사용자는 거부되는 것까지 확인했습니다. 그다음 Keycloak 파드와 DB 주 서버를 일부러 죽여, Keycloak 쪽은 끊김 없이 넘어가고 DB 쪽은 약 8초 동안 로그인이 실패하는 것을 측정했습니다. 설치 중에는 CRD 누락으로 인한 운영자 CrashLoopBackOff, 한 노드에 몰린 파드, 포트가 빠진 토큰 주소, 스스로 막힌 가져오기 Job을 만났고, 원인과 해결 방법을 함께 정리했습니다.
1~6편의 kind 클러스터(노드 3개, Envoy Gateway, kube-prometheus-stack의 Grafana·Prometheus, cert-manager 사설 CA HTTPS)를 이어서 씁니다. Keycloak 26.8.2, Keycloak Operator 26.8.2, CloudNativePG 1.30.1(차트 0.29.1), PostgreSQL 18.6 기준입니다. 백업은 pg_dump로 받고 복구까지 확인했으며, 객체 저장소를 쓰는 연속 백업(특정 시점 복구)은 로컬에 저장소가 없어 구성 방법만 설명합니다. 비밀번호와 클라이언트 비밀값은 모두 클러스터 안에서 무작위로 만들어 Secret에만 넣었습니다.
이번 편에서 만드는 구성
6편까지 Grafana는 관리자 계정 하나로 로그인했습니다. 사람이 늘면 계정을 Grafana마다, 도구마다 따로 만들게 되고, 퇴사자 계정 정리도 도구마다 해야 합니다. SSO(Single Sign-On)는 로그인을 한 곳(인증 서버)에 모으고, 각 도구는 그 인증 서버가 발급한 토큰을 믿게 하는 방식입니다. 이번 편에서는 Keycloak을 인증 서버로 두고 Grafana를 첫 번째 연결 대상으로 붙입니다.
7편 구성 요소
| 구성 요소 | 개수·위치 | 역할 |
|---|---|---|
| Keycloak | 2개(워커 노드마다 1개) | 로그인 화면, 사용자·그룹 관리, 토큰 발급 |
| Keycloak Operator | 1개 | Keycloak 리소스를 보고 StatefulSet, Service, 설정을 만들어 줌 |
| PostgreSQL(CloudNativePG) | 2개(주 서버 + 복제본) | 사용자, 클라이언트, 세션 저장 |
| Gateway(6편) | 1개 | https://keycloak.localhost:8443에서 TLS를 풀고 Keycloak으로 전달 |
| Grafana(4편) | 1개 | Keycloak으로 로그인하고 그룹을 역할로 바꿈 |
| Prometheus(4편) | 1개 | Keycloak과 PostgreSQL 지표 수집 |
글이 길어서 순서를 먼저 적어 둡니다. Keycloak 종류와 실행 모드를 정리하고, DB → Keycloak → realm → Grafana 순서로 만든 뒤, 지표·장애·백업을 확인합니다.
Keycloak의 종류: 배포판, 설치 방식, 실행 모드
Keycloak을 검색하면 설정 방법이 서로 다른 글이 섞여 나옵니다. 대부분 아래 세 가지 중 하나가 달라서 생기는 차이입니다. 무엇을 기준으로 한 글인지 먼저 구분하면 헷갈림이 크게 줄어듭니다.
배포판: 무엇을 설치하나
| 배포판 | 특징 | 구분하는 방법 |
|---|---|---|
| Keycloak(현재, Quarkus 기반) | CNCF 프로젝트인 오픈소스 Keycloak. 17 버전(2022년)부터 Quarkus 기반이 기본. 이 글의 26.8.2가 여기에 해당 | 설정을 kc.sh 옵션·환경 변수로 줌. 주소에 /auth가 없음 |
| 예전 WildFly 기반 Keycloak | 16 버전까지의 기본 배포판. 지금은 지원이 끝남 | standalone.xml, JBoss CLI, 주소의 /auth가 보이면 이 방식의 글 |
| Red Hat build of Keycloak | Red Hat이 유상 지원하는 Keycloak 빌드. 예전 Red Hat SSO(RH-SSO, WildFly 기반)의 후속 | 버전 번호와 지원 정책이 Red Hat 기준. 사용법은 오픈소스 Keycloak과 거의 같음 |
쿠버네티스 설치 방식
| 방식 | 장점 | 주의할 점 |
|---|---|---|
| Keycloak Operator(공식) | Keycloak 리소스 하나로 StatefulSet, 서비스, 클러스터링, ServiceMonitor, realm 가져오기를 관리. 버전을 Keycloak과 같이 냄 | CRD와 운영자 버전을 함께 관리해야 함. 운영자가 모르는 설정은 unsupported.podTemplate으로 우회 |
| 커뮤니티 Helm 차트(codecentric keycloakx 등) | Helm values로 익숙하게 관리 | 공식 지원이 아니므로 Keycloak 새 버전 반영 속도와 기본값을 직접 확인 |
| Bitnami Helm 차트 | 많이 쓰여 예제가 많음 | 2025년 Bitnami 이미지 배포 정책이 바뀌어, 새로 시작한다면 이미지 출처와 갱신 정책을 먼저 확인 |
| 직접 매니페스트 | 모든 것을 직접 통제 | 클러스터링, 헬스 체크, 업그레이드 절차를 모두 직접 만들어야 함 |
실행 모드: start-dev와 start
| 항목 | 개발 모드(start-dev) | 운영 모드(start) |
|---|---|---|
| DB | 내장 H2 파일 DB | 외부 DB 필수(이 글은 PostgreSQL) |
| 주소(hostname) | 설정하지 않아도 됨 | 고정 주소 설정 필요. 토큰의 발급자(iss)가 이 주소가 됨 |
| HTTP | HTTP 허용 | 기본은 HTTPS. 프록시에서 TLS를 끝내면 프록시 헤더 설정과 함께 HTTP를 켬 |
| 캐시·클러스터 | 혼자 동작 | 여러 개가 하나의 클러스터로 묶여 세션을 나눠 가짐 |
| 용도 | 로컬에서 기능 확인 | 실제 사용자 로그인 |
Keycloak Operator는 항상 운영 모드로 띄웁니다. 이 실습의 시작 로그에도 Profile prod activated가 찍혔습니다. 그래서 DB, 주소, 프록시 설정을 처음부터 운영과 같은 방식으로 정해야 합니다. Keycloak 운영 환경 설정 가이드
DB 먼저: CloudNativePG로 PostgreSQL 2개 띄우기
Keycloak은 사용자, 클라이언트, 세션을 DB에 저장합니다. Keycloak 파드가 여러 개여도 DB가 하나뿐이면 DB가 죽는 순간 로그인이 멈추므로, DB도 이중화합니다. CloudNativePG는 PostgreSQL을 쿠버네티스 리소스(Cluster)로 관리하는 운영자로, 주 서버와 복제본을 만들고 주 서버가 죽으면 복제본을 주 서버로 올립니다. CloudNativePG 문서
helm repo add cnpg https://cloudnative-pg.github.io/chartshelm upgrade --install cnpg cnpg/cloudnative-pg --version 0.29.1 \ -n cnpg-system --create-namespace --waitapiVersion: postgresql.cnpg.io/v1kind: Clustermetadata: name: keycloak-db namespace: keycloakspec: instances: 2 # 주 서버 1 + 복제본 1 affinity: enablePodAntiAffinity: true podAntiAffinityType: required # 두 인스턴스를 반드시 다른 노드에 bootstrap: initdb: database: keycloak owner: keycloak # 비밀번호는 운영자가 만들어 Secret keycloak-db-app에 넣음 storage: size: 2Gi resources: requests: cpu: 100m memory: 256Mi limits: memory: 512Mi적용하고 92초 뒤 두 인스턴스가 준비되었습니다. 결과에서 운영에 바로 쓰이는 것은 서비스와 Secret입니다.
NAME INSTANCES READY STATUS PRIMARYkeycloak-db 2 2 Cluster in healthy state keycloak-db-1
keycloak-db-1 primary lab-worker2keycloak-db-2 replica lab-worker
서비스: keycloak-db-rw(항상 주 서버), keycloak-db-ro(복제본만), keycloak-db-r(아무 인스턴스)Secret: keycloak-db-app(사용자·비밀번호), keycloak-db-ca, keycloak-db-server, keycloak-db-replication복제 상태(pg_stat_replication): streaming | asyncKeycloak은 keycloak-db-rw에 연결합니다. 주 서버가 바뀌면 운영자가 이 서비스가 가리키는 파드를 바꿔 주므로, Keycloak 설정은 바꿀 필요가 없습니다. 비밀번호도 운영자가 만든 Secret을 그대로 참조하므로 사람이 볼 일이 없습니다.
운영 포인트
복제는 기본이 비동기(async)라서, 주 서버가 죽는 순간 아직 복제본에 넘어가지 않은 마지막 쓰기가 사라질 수 있습니다. 이 손실이 허용되지 않는다면 동기 복제(
minSyncReplicas·maxSyncReplicas)와 인스턴스 3개를 검토합니다. 또 kind 기본 저장소(local-path)는 볼륨이 노드에 묶여 있어서, 노드가 사라지면 그 인스턴스는 다른 노드에서 새로 복제해 와야 합니다. 클라우드에서는 영역(AZ)을 넘나드는 블록 스토리지와 함께 인스턴스를 영역마다 나눠 둡니다.
Keycloak Operator 설치: CRD가 4개로 늘었다
Keycloak Operator는 공식 저장소(keycloak-k8s-resources)의 매니페스트로 설치합니다. 예전 안내에 따라 CRD 2개(keycloaks, keycloakrealmimports)와 운영자만 적용했더니, 운영자가 CrashLoopBackOff에 빠졌습니다.
Couldn't start informer for keycloaksamlclients.k8s.keycloak.org/v2alpha1 resources... GET .../apis/k8s.keycloak.org/v2alpha1/namespaces/keycloak/keycloaksamlclients ... Message: Not Found.Failed to start application: java.lang.RuntimeException: Failed to start quarkus26.8 버전의 운영자는 클라이언트를 리소스로 관리하는 기능(KeycloakOIDCClient, KeycloakSAMLClient)도 감시하는데, 그 CRD가 없으니 시작하지 못한 것입니다. 저장소의 kustomization.yml에 필요한 파일 목록이 있어서, 그 목록대로 CRD 4개를 모두 적용하자 11초 만에 Running이 되었습니다.
V=26.8.2B=https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/$V/kuberneteskubectl apply -f $B/keycloaks.k8s.keycloak.org-v1.ymlkubectl apply -f $B/keycloakrealmimports.k8s.keycloak.org-v1.ymlkubectl apply -f $B/keycloakoidcclients.k8s.keycloak.org-v1.yml # 26.8에서 필요kubectl apply -f $B/keycloaksamlclients.k8s.keycloak.org-v1.yml # 26.8에서 필요kubectl apply -n keycloak -f $B/kubernetes.yml
$ kubectl api-resources --api-group=k8s.keycloak.orgkeycloakoidcclients k8s.keycloak.org/v2alpha1 KeycloakOIDCClientkeycloakrealmimports k8s.keycloak.org/v2beta1 KeycloakRealmImportkeycloaks kc k8s.keycloak.org/v2beta1 Keycloakkeycloaksamlclients k8s.keycloak.org/v2alpha1 KeycloakSAMLClient운영 포인트
운영자를 올릴 때는 버전마다 CRD 목록과 API 버전이 바뀌었는지 먼저 봅니다. 파일을 하나씩 나열해 적용하기보다, 저장소의 kustomization처럼 버전별로 묶인 목록을 그대로 쓰는 편이 빠뜨림이 없습니다. 운영자는 기본적으로 자기가 설치된 네임스페이스만 감시하므로, Keycloak 리소스도 같은 네임스페이스(keycloak)에 둡니다. Keycloak Operator 설치 문서
Keycloak 리소스: 주소, 프록시, 관리자 비밀번호
관리자 초기 계정은 매니페스트에 쓰지 않고, 클러스터 안에서 무작위 비밀번호로 Secret을 만들었습니다. 이 계정은 이름 그대로 처음 들어가기 위한 임시 계정입니다.
umask 077openssl rand -base64 24 | tr -d '\n' > password # 파일 이름이 Secret의 키 이름이 된다kubectl create secret generic keycloak-bootstrap-admin -n keycloak \ --from-literal=username=temp-admin --from-file=passwordrm passwordapiVersion: k8s.keycloak.org/v2beta1kind: Keycloakmetadata: name: keycloak namespace: keycloakspec: instances: 2 db: vendor: postgres host: keycloak-db-rw database: keycloak usernameSecret: {name: keycloak-db-app, key: username} passwordSecret: {name: keycloak-db-app, key: password} http: httpEnabled: true # TLS는 Gateway에서 끝냄(6편) hostname: hostname: https://keycloak.localhost:8443 proxy: headers: xforwarded # Envoy가 붙이는 X-Forwarded-* 헤더를 믿음 ingress: enabled: false # Ingress 대신 HTTPRoute bootstrapAdmin: user: secret: keycloak-bootstrap-admin additionalOptions: - name: metrics-enabled value: "true" - name: event-metrics-user-enabled value: "true" serviceMonitor: enabled: true labels: release: kps scheduling: topologySpreadConstraints: # 이유는 아래 '운영 함정' 참고 - maxSkew: 1 topologyKey: kubernetes.io/hostname whenUnsatisfiable: DoNotSchedule nodeTaintsPolicy: Honor labelSelector: matchLabels: app: keycloak resources: requests: {cpu: 200m, memory: 768Mi} limits: {memory: 1536Mi}hostname은 브라우저가 보는 전체 주소입니다. 포트까지 적은 이유는 Windows에서 들어오는 포트가 8443이기 때문입니다. 이 값이 토큰의 발급자(iss)가 되므로, 한 번 정하면 바꾸기 어렵습니다. 바꾸면 이 주소를 기준으로 토큰을 검증하던 모든 앱의 설정을 함께 바꿔야 합니다. Keycloak hostname 설정 문서
Gateway에는 6편의 HTTPS 리스너에 붙는 라우트를 추가했습니다. 6편에서 인증서에 keycloak.localhost를 미리 넣고 HTTP → HTTPS 이동에도 넣어 두었기 때문에, 인증서와 리다이렉트는 손댈 것이 없습니다.
apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata: name: keycloak namespace: keycloakspec: parentRefs: - name: lab-gateway namespace: default sectionName: https hostnames: - keycloak.localhost rules: - backendRefs: - name: keycloak-service port: 808082초 뒤 Ready가 되었고, 로그에서 두 파드가 하나의 클러스터로 묶이는 것을 볼 수 있습니다. 파드끼리 서로를 찾는 방법(JGroups jdbc-ping)은 DB에 자기 주소를 적어 두고 서로 읽는 방식이라, 별도 설정이 필요 없었습니다.
Keycloak 26.8.2 on JVM (powered by Quarkus …) started in 5.878s.Profile prod activated.ISPN000078: Starting JGroups channel `ISPN` with stack `jdbc-ping`ISPN100000: Node keycloak-1 joined the cluster운영 함정 3가지: 몰린 파드, 빠진 포트, 스스로 막힌 Job
Keycloak이 Ready가 된 뒤 확인해 보니 문제가 세 가지 있었습니다. 모두 에러 없이 “동작은 하는” 상태라 확인하지 않으면 지나치기 쉬운 것들입니다.
첫째, 두 파드가 모두 lab-worker 한 노드에 떠 있었습니다. 운영자는 기본 분산 규칙(topologySpreadConstraints)을 넣지만, 값이 whenUnsatisfiable: ScheduleAnyway라 “가능하면 나눠라” 수준입니다. 이 상태로는 노드 하나가 죽으면 Keycloak 두 개가 함께 죽어서 이중화한 의미가 없습니다.
둘째, 설정 정보(discovery 문서)의 토큰 주소에 포트가 빠져 있었습니다. 처음에는 hostname.backchannelDynamic: true를 켜 두었는데, 이 옵션은 일부 주소를 요청이 들어온 Host로 만듭니다. Envoy가 Host에서 포트를 떼고 넘기다 보니 :8443이 사라졌고, 이 주소를 그대로 쓰는 앱은 토큰을 받지 못합니다. 옵션을 끄자 모든 주소가 hostname 기준으로 고정되었습니다.
# backchannelDynamic: trueissuer: https://keycloak.localhost:8443/realms/mastertoken: https://keycloak.localhost/realms/master/protocol/openid-connect/token ← 포트 없음
# 끈 뒤token: https://keycloak.localhost:8443/realms/master/protocol/openid-connect/token셋째, 첫 번째 문제를 고치려고 “같은 라벨(app.kubernetes.io/instance: keycloak)이 있는 노드에는 띄우지 마라”는 required podAntiAffinity를 넣었습니다. 그러자 realm 가져오기 Job 파드가 5분 넘게 Pending에 머물렀습니다.
0/3 nodes are available: 1 node(s) had untolerated taint(s),2 node(s) didn't match pod anti-affinity rules.
# 가져오기 Job 파드의 라벨과 배치 규칙labels: app=keycloak-realm-import, app.kubernetes.io/instance=keycloakaffinity: podAntiAffinity required, app.kubernetes.io/instance=keycloak운영자는 가져오기 Job을 Keycloak과 같은 설정으로 만듭니다. 그래서 Job 파드도 같은 라벨과 규칙을 물려받았고, “Keycloak이 있는 노드는 피하라”는 규칙 때문에 워커 2대를 모두 피했습니다. 남은 control-plane 노드는 테인트로 막혀 있어 갈 곳이 없었습니다. 서버 파드에만 있는 라벨(app: keycloak)로 분산 규칙(DoNotSchedule)을 걸자 Job 파드는 영향을 받지 않았고, 서버 파드는 노드마다 하나씩 배치되었습니다. Topology Spread Constraints 문서

고친 뒤 Headlamp에서 본 파드 목록입니다. keycloak-0과 keycloak-1, keycloak-db-1과 keycloak-db-2가 각각 lab-worker와 lab-worker2에 나뉘어 있고, realm 가져오기 Job(lab-4z9vt)은 Completed로 끝났습니다.
이 설정들을 바꾸는 동안 Keycloak은 StatefulSet 롤링 교체로 한 개씩 바뀌었습니다. 교체 77초 동안 1초마다 접속한 74번이 모두 200이었습니다. 6편에서 hostPort로 띄운 Envoy가 교체 중 72초 동안 끊겼던 것과 비교하면, 여러 개를 띄우는 것이 왜 중요한지 보입니다.
운영 포인트
이중화는 파드 수가 아니라 “서로 다른 장애 영역에 있느냐”로 확인합니다. 배포 뒤에는
kubectl get pods -o wide로 노드를, 클라우드라면 영역(zone)까지 확인합니다. 운영자가 만드는 부속 파드(Job 등)가 서버의 배치 규칙을 물려받는지도 함께 봅니다.
realm과 클라이언트: 비밀값 없이 선언하기
realm은 Keycloak 안의 독립된 사용자 공간입니다. 사용자, 그룹, 클라이언트(로그인을 맡기는 앱), 보안 정책이 realm마다 따로 있습니다. 관리용 master realm은 Keycloak 관리자 전용으로 두고, 실제 사용자는 별도 realm(lab)에 둡니다.
KeycloakRealmImport는 realm 설정을 JSON(여기서는 YAML) 그대로 넣는 리소스입니다. 클라이언트 비밀값과 사용자 비밀번호는 ${...} 자리표시자로 두고, 실제 값은 Secret에서 채우게 했습니다. 그래서 이 파일은 Git에 올려도 비밀값이 없습니다. Keycloak realm 가져오기 문서
apiVersion: k8s.keycloak.org/v2beta1kind: KeycloakRealmImportmetadata: name: lab namespace: keycloakspec: keycloakCRName: keycloak placeholders: GRAFANA_CLIENT_SECRET: secret: {name: lab-realm-secrets, key: grafana-client-secret} ALICE_PASSWORD: secret: {name: lab-realm-secrets, key: alice-password} # BOB_PASSWORD, CAROL_PASSWORD 동일 realm: realm: lab enabled: true sslRequired: external bruteForceProtected: true # 로그인 실패가 반복되면 잠시 잠금 failureFactor: 5 passwordPolicy: "length(12) and notUsername" accessTokenLifespan: 300 # 액세스 토큰 5분 ssoSessionIdleTimeout: 1800 # 30분 동안 활동이 없으면 SSO 세션 종료 groups: - name: grafana-admins - name: grafana-editors - name: grafana-viewers clients: - clientId: grafana publicClient: false # 기밀 클라이언트: Grafana 서버가 비밀값으로 토큰을 받음 secret: ${GRAFANA_CLIENT_SECRET} standardFlowEnabled: true # 브라우저 로그인(Authorization Code) directAccessGrantsEnabled: false redirectUris: - https://grafana.localhost:8443/login/generic_oauth webOrigins: - https://grafana.localhost:8443 attributes: pkce.code.challenge.method: S256 post.logout.redirect.uris: https://grafana.localhost:8443/login protocolMappers: - name: groups protocol: openid-connect protocolMapper: oidc-group-membership-mapper config: claim.name: groups full.path: "false" id.token.claim: "true" access.token.claim: "true" userinfo.token.claim: "true" users: # alice: grafana-admins, bob: grafana-viewers, carol: 그룹 없음redirectUris를 정확한 주소 하나로 둡니다.*를 쓰면 공격자가 만든 주소로 로그인 결과(코드)를 빼돌릴 수 있습니다.directAccessGrantsEnabled: false는 앱이 사용자 아이디·비밀번호를 직접 받아 Keycloak에 넘기는 방식을 막습니다. 비밀번호는 Keycloak 화면에서만 입력되어야 SSO의 의미가 있습니다.- PKCE(S256)는 로그인 중간에 코드가 새도 그 코드만으로는 토큰을 받을 수 없게 합니다.
- groups 매퍼는 사용자의 그룹 이름을 토큰과 userinfo에
groups로 넣습니다. Grafana는 이 값을 보고 역할을 정합니다.
가져오기는 26초 걸렸고, Job 로그에 Realm 'lab' imported가 찍혔습니다.
주의
KeycloakRealmImport는 realm이 없을 때 한 번 만드는 용도입니다. 이미 realm이 있으면 덮어쓰지 않으므로, 파일을 고쳐 다시 적용해도 기존 realm은 바뀌지 않습니다. 운영 중 변경은 관리 콘솔, Admin REST API, 또는 이를 이용하는 설정 관리 도구로 하고, 그 변경 절차를 따로 정해 둡니다.
Grafana SSO 연결: 프런트 채널과 백 채널
OIDC 로그인에는 두 종류의 통신이 있습니다. 브라우저가 Keycloak 로그인 화면으로 이동하는 프런트 채널과, Grafana 서버가 Keycloak에 직접 코드를 보내 토큰으로 바꾸는 백 채널입니다. 둘은 출발지가 달라서 주소도 다르게 줄 수 있습니다.
Grafana가 쓰는 Keycloak 주소
| 설정 | 누가 호출 | 주소 |
|---|---|---|
auth_url |
브라우저 | https://keycloak.localhost:8443/realms/lab/.../auth(Gateway, HTTPS) |
token_url |
Grafana 서버 | http://keycloak-service.keycloak.svc:8080/realms/lab/.../token(클러스터 내부) |
api_url(userinfo) |
Grafana 서버 | http://keycloak-service.keycloak.svc:8080/realms/lab/.../userinfo |
백 채널을 내부 주소로 둔 이유가 있습니다. 클러스터 안에서 keycloak.localhost:8443은 Windows 쪽 포트라 바로 닿지 않습니다. 맞추려면 CoreDNS 재작성과 Grafana의 사설 CA 신뢰를 추가로 설정해야 합니다. 내부 주소를 쓰면 그런 설정이 필요 없고, 토큰의 발급자는 Keycloak의 hostname 설정 덕분에 어느 주소로 받아도 같습니다. 대신 클러스터 내부 구간은 암호화되지 않으므로, 운영에서는 서비스 메시(mTLS)나 Keycloak 자체 TLS로 이 구간도 보호할지 정합니다.
# 07-kps-grafana-sso-values.yaml (kube-prometheus-stack의 grafana 하위 차트)grafana: envValueFrom: GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: # 비밀값은 values가 아니라 Secret에서 secretKeyRef: {name: grafana-oauth, key: client-secret} grafana.ini: auth: disable_login_form: false # 관리자 폼 로그인은 비상용으로 남김 auth.generic_oauth: enabled: true name: Keycloak allow_sign_up: true client_id: grafana scopes: openid email profile use_pkce: true auth_url: https://keycloak.localhost:8443/realms/lab/protocol/openid-connect/auth token_url: http://keycloak-service.keycloak.svc:8080/realms/lab/protocol/openid-connect/token api_url: http://keycloak-service.keycloak.svc:8080/realms/lab/protocol/openid-connect/userinfo login_attribute_path: preferred_username email_attribute_path: email groups_attribute_path: groups role_attribute_path: contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'grafana-editors') && 'Editor' || contains(groups[*], 'grafana-viewers') && 'Viewer' || '' role_attribute_strict: truerole_attribute_path는 그룹 목록을 보고 Grafana 역할을 고르는 식입니다. 어느 그룹에도 없으면 빈 값이 나오는데, role_attribute_strict: true라서 이 경우 기본 역할(Viewer)을 주지 않고 로그인을 거부합니다. Keycloak에 계정만 있으면 누구나 Grafana를 볼 수 있게 되는 것을 막는 설정입니다. Grafana Keycloak 연동 문서


적용 후 Grafana 로그인 화면에는 관리자 폼 아래에 “Sign in with Keycloak” 버튼이 생깁니다. 버튼을 누르면 Keycloak의 lab realm 로그인 화면으로 이동하고, 비밀번호는 이 화면에서만 입력합니다.
브라우저 로그인 과정을 curl로 그대로 재현해 세 사용자를 확인했습니다. Grafana의 SSO 버튼 → Keycloak 로그인 화면 → 아이디·비밀번호 제출 → Grafana 콜백 순서입니다.
[alice] Grafana 콜백 → 302 https://grafana.localhost:8443/[alice] /api/user/orgs → [{"orgId":1,"name":"Main Org.","role":"Admin"}]
[bob] Grafana 콜백 → 302 https://grafana.localhost:8443/[bob] /api/user/orgs → [{"orgId":1,"name":"Main Org.","role":"Viewer"}]
[carol] Grafana 콜백 → 302 https://grafana.localhost:8443/login[carol] loginError: "IdP did not return a role attribute, please contact your administrator"# Grafana 로그Failed to extract role ... [oauth.role_attribute_strict_violation]
alice로 로그인한 뒤 Grafana 프로필입니다. 이름, 이메일, 사용자 이름이 Keycloak에서 받아 온 값이라 “Synced via Generic OAuth”로 표시되고, Grafana에서 직접 고칠 수 없습니다. 사용자 정보는 Keycloak 한 곳에서 관리한다는 뜻입니다.
carol은 Keycloak 로그인 자체는 성공했지만 Grafana에서 거부되었습니다. 인증(누구인가)은 Keycloak이, 권한(무엇을 할 수 있나)은 그룹을 보고 Grafana가 정한다는 구분이 이 결과에 그대로 나타납니다.

모니터링: 무엇을 보고 있어야 하나
Keycloak 리소스의 serviceMonitor와 직접 만든 PodMonitor(PostgreSQL)에 release: kps 라벨을 붙여, 4편의 Prometheus가 네 대상을 모두 수집합니다.
up{namespace="keycloak"} job=keycloak-service pod=keycloak-0 (9000) 1 job=keycloak-service pod=keycloak-1 (9000) 1 job=keycloak/keycloak-db pod=keycloak-db-1 (9187) 1 job=keycloak/keycloak-db pod=keycloak-db-2 (9187) 1기본 지표에는 JVM, HTTP, 캐시 정보는 있지만 “로그인이 몇 번 성공·실패했나”는 없습니다. event-metrics-user-enabled를 켜면 사용자 이벤트가 keycloak_user_events_total로 나옵니다. 파드마다 따로 세므로 조회할 때는 합쳐서 봅니다. Keycloak 이벤트 지표 문서
keycloak_user_events_total{error="",event="login",realm="lab"} 3.0keycloak_user_events_total{error="",event="code_to_token",realm="lab"} 2.0keycloak_user_events_total{error="",event="user_info_request",realm="lab"} 2.0운영에서 볼 만한 조회식
| 보고 싶은 것 | PromQL |
|---|---|
| 로그인 실패율(5분) | `sum(rate(keycloak_user_events_total{event=“login_error”}[5m])) / sum(rate(keycloak_user_events_total{event=~“login |
| 실패 원인별 수 | sum by (error) (rate(keycloak_user_events_total{event="login_error"}[5m])) |
| Keycloak 대상 수 | count(up{job="keycloak-service"} == 1) |
| DB 복제 지연(초) | max(cnpg_pg_replication_lag) |
| 마지막 백업 시각 | cnpg_collector_last_available_backup_timestamp |
로그인 실패율이 갑자기 오르면 비밀번호 대입 공격이나 외부 연동(LDAP 등) 장애를, 실패 원인별 수에서 invalid_user_credentials가 대부분인지 다른 오류인지를 구분해 봅니다. 6편처럼 알림 규칙을 만들 때는 지표가 아예 없을 때를 잡는 규칙도 함께 둡니다.
장애 훈련 1: Keycloak 파드를 죽였을 때
alice가 로그인한 상태에서 keycloak-0을 강제 종료(--grace-period=0 --force)하고, 1초마다 접속하면서 기존 SSO 세션과 새 로그인을 시험했습니다.
15:38:02 keycloak-0 강제 종료15:38:04 종료 직후 alice SSO 재사용: 비밀번호 없이 로그인 성공15:38:04 종료 직후 bob 새 로그인: 성공keycloak-1 로그: ISPN100001: Node keycloak-0 left the clusterkeycloak-0 복귀 25초접속 응답: 200 × 33 (실패 0)복귀 후 alice SSO 재사용: 성공남은 한 개가 모든 요청을 받았고, alice의 SSO 세션도 살아 있었습니다. Keycloak 26은 사용자 세션을 메모리 캐시뿐 아니라 DB에도 저장하기 때문에(persistent user sessions), 파드가 죽어도 세션이 사라지지 않습니다. 예전 버전에서 “Keycloak을 재시작하면 모두 다시 로그인해야 한다”던 경험과 다른 부분입니다.
운영 포인트
한 개가 죽어도 버티려면 남은 한 개가 전체 부하를 감당할 수 있어야 합니다. 리소스는 “평소 부하 ÷ 파드 수”가 아니라 “평소 부하 ÷ (파드 수 − 1)“을 기준으로 잡고, PodDisruptionBudget으로 노드 점검 때 두 개가 동시에 내려가지 않게 합니다.
장애 훈련 2: DB 주 서버를 죽였을 때
이번에는 bob이 1초 간격으로 계속 새로 로그인하게 해 두고, PostgreSQL 주 서버(keycloak-db-1)를 강제 종료했습니다.
15:38:38 keycloak-db-1(주 서버) 강제 종료15:38:40 ~ 15:38:47 로그인 실패 6회 (Keycloak 단계)15:38:59 Cluster 상태의 주 서버 표시가 keycloak-db-2로 바뀜 (21초)로그인 결과: 성공 54 / 실패 6클러스터 정상 상태 복구: 91초 (옛 주 서버는 복제본으로 돌아옴)
NAME INSTANCES READY STATUS PRIMARYkeycloak-db 2 2 Cluster in healthy state keycloak-db-2DB가 바뀌는 약 8초 동안은 로그인이 실패했습니다. 주 서버가 없는 동안에는 세션 저장 같은 쓰기를 할 수 없기 때문입니다. 그 뒤로는 Keycloak 설정을 전혀 바꾸지 않았는데도 로그인이 다시 성공했습니다. keycloak-db-rw 서비스가 새 주 서버를 가리키게 되었기 때문입니다. 장애 후 lab realm의 사용자 수(3명)도 그대로였습니다.
운영 포인트
DB 장애 전환 시간 동안의 로그인 실패는 피할 수 없으므로, 이 시간을 측정해 두고 서비스 목표(SLO)에 반영합니다. 이 실습은 강제 종료였고, 노드 자체가 응답하지 않는 장애에서는 장애 판단에 시간이 더 걸릴 수 있습니다. 비동기 복제라 이 몇 초 사이의 마지막 쓰기가 사라질 수 있다는 점도 함께 기록해 둡니다.
백업과 복구: 받아 둔 백업으로 실제로 살려 보기
이중화는 장비 장애를 막아 주지만, 실수로 지운 realm이나 잘못된 일괄 변경은 복제본에도 그대로 복제됩니다. 그래서 백업은 따로 필요합니다. 이 실습에서는 pg_dump로 논리 백업을 받고, 새 DB에 풀어서 내용이 같은지 확인했습니다.
# 복제본에서 덤프(주 서버 부하를 줄임)kubectl exec -n keycloak keycloak-db-1 -c postgres -- pg_dump -Fc -d keycloak > keycloak-YYYYMMDD-HHMM.dump# → 1초 이내, 264K, 테이블 데이터 101개
# 빈 Cluster(keycloak-db-restore)를 만들고 복원kubectl exec -i -n keycloak keycloak-db-restore-1 -c postgres -- \ pg_restore -d keycloak --no-owner --role=keycloak < keycloak-YYYYMMDD-HHMM.dump# → 1초
# 원본과 비교(realm별 사용자 수)원본: lab|3 master|1복원본: lab|3 master|1lab 클라이언트 수: 7 / 7백업 파일에는 사용자 비밀번호 해시와 클라이언트 비밀값이 들어 있습니다. 그래서 이 파일은 블로그 폴더가 아니라 권한을 600으로 둔 WSL 안 폴더에만 두었습니다. 운영에서도 백업 저장소의 접근 권한과 암호화를 DB와 같은 수준으로 관리합니다.
pg_dump는 받은 시점으로만 돌아갈 수 있습니다. 운영에서는 CloudNativePG의 Barman Cloud 플러그인으로 S3 같은 객체 저장소에 기본 백업과 WAL(변경 기록)을 계속 보내, 원하는 시각으로 되돌리는 특정 시점 복구(PITR)를 씁니다. 이 실습 클러스터는 아직 이 설정이 없어서 firstRecoverabilityPoint와 lastSuccessfulBackup이 비어 있습니다. 위 표의 마지막 백업 시각 지표로 백업이 멈추지 않았는지 감시하는 것까지가 백업 구성입니다. CloudNativePG Barman Cloud 플러그인
운영 포인트
백업은 복원해 본 적이 있어야 백업입니다. 이 실습처럼 별도 DB에 정기적으로 복원해서 핵심 데이터(realm, 사용자 수, 클라이언트 수)를 비교하는 절차를 일정으로 잡아 둡니다. 복원에 걸린 시간도 함께 기록해 두면, 장애 때 “언제 복구되느냐”는 질문에 답할 수 있습니다.
Keycloak이 죽었을 때 들어갈 문: 비상용 관리자 로그인
모든 도구의 로그인을 Keycloak에 모으면 Keycloak이 죽었을 때 아무도 못 들어가는 상황이 생깁니다. 그래서 Grafana의 관리자 폼 로그인은 끄지 않고 비상용(break-glass)으로 남겨 두었습니다. Keycloak을 0개로 줄여 확인했습니다.
Keycloak 파드 수: 0SSO 버튼: 302 → https://keycloak.localhost:8443/.../auth → Keycloak 503관리자 폼 로그인: 200login: admin isGrafanaAdmin: True authLabels: []SSO는 503으로 막혔지만 관리자 계정으로는 들어갈 수 있었습니다. 확인 뒤 다시 2개로 되돌렸습니다. 비상용 계정의 비밀번호는 금고(비밀 관리 도구)에 두고, 사용하면 기록을 남기고 바로 바꾸는 절차를 함께 정합니다.
운영 체크리스트
이번 실습에서 확인한 것과 운영으로 옮길 때 추가로 할 일을 정리합니다.
- Keycloak은 운영 모드(start)로, 외부 DB와 고정
hostname으로 띄운다. hostname은 토큰 발급자가 되므로 처음에 정확히 정한다. - 운영자를 설치·업그레이드할 때는 버전별 CRD 목록을 확인한다(26.8은 4개).
- Keycloak과 DB 모두 2개 이상으로 두고, 실제로 서로 다른 노드·영역에 있는지 확인한다. 운영자의 기본 분산 규칙은 권장 수준이다.
- 운영자가 만드는 Job 같은 부속 파드가 서버의 배치 규칙을 물려받는지 확인한다.
- 비밀값(관리자 비밀번호, DB 비밀번호, 클라이언트 비밀값)은 Secret으로만 다루고, realm 파일에는 자리표시자를 쓴다.
- 부트스트랩 관리자(temp-admin)는 처음 들어갈 때만 쓰고, 영구 관리자 계정을 만든 뒤 지운다.
- 관리 콘솔(
/admin)은 외부에 그대로 열지 말고, 내부망이나 별도 주소로만 접근하게 하는 방법을 검토한다. - 클라이언트는 정확한 redirect URI, PKCE, direct grant 끔으로 설정하고, 그룹 없는 사용자는 거부(strict)한다.
- 로그인 성공·실패 지표와 DB 복제 지연, 마지막 백업 시각을 수집하고 알림을 건다.
- 장애 전환 시간(이 실습은 DB 약 8초)을 측정해 기록하고, 백업은 정기적으로 복원해 본다.
- SSO가 죽었을 때 쓸 비상용 관리자 로그인을 도구마다 남겨 둔다.
- 시작 로그의 “Updating the configuration and installing your custom providers”는 시작할 때마다 설정 빌드를 한다는 뜻이다. 운영에서는 미리 빌드한 이미지(
kc.sh build)와startOptimized: true로 시작 시간을 줄이는 것을 검토한다.
자주 묻는 질문
Keycloak을 1개만 띄우면 안 되나요?
실습이나 사용자가 적은 내부 도구라면 1개로도 동작합니다. 다만 그 1개가 재시작되는 동안 연결된 모든 도구에 새로 로그인할 수 없습니다. 이 실습에서 2개로 띄운 경우에는 파드 하나를 죽여도 접속 33번이 모두 성공했고, 설정 변경 중 롤링 교체에서도 74번이 모두 성공했습니다.
DB를 클라우드 관리형(RDS 등)으로 쓰면 CloudNativePG는 필요 없나요?
필요 없습니다. Keycloak 리소스의 `db.host`와 Secret만 관리형 DB로 바꾸면 됩니다. 이중화, 장애 전환, 백업을 클라우드가 맡는 대신 비용이 들고, 이 글의 장애 훈련과 백업 복원 확인은 관리형 DB에서도 똑같이 해 봐야 합니다.
KeycloakOIDCClient로 클라이언트를 만들면 realm 가져오기가 필요 없나요?
26.8에서 KeycloakOIDCClient는 v2alpha1(미리보기 단계) API입니다. 이 글에서는 realm 전체(그룹, 사용자, 클라이언트)를 한 번에 만들기 위해 KeycloakRealmImport를 썼습니다. 클라이언트를 리소스로 계속 관리하는 방식은 API가 안정화되는 것을 보고 도입을 검토하는 편이 안전합니다.
작성 방식과 다음 편
이 글의 명령, 오류 메시지, 측정값은 1편의 실습 PC에서 직접 실행한 것이며, 설정은 Keycloak, Keycloak Operator, CloudNativePG, Grafana 공식 문서를 기준으로 했습니다. 비밀번호와 비밀값은 출력하지 않았습니다. 실행 기록 정리와 글 작성에 AI 도구를 함께 사용했습니다. 다음 편에서는 OpenTelemetry로 트레이스를 모아, 지금까지 만든 메트릭(4편)과 로그(5편)에 이어 세 번째 관측 신호를 붙입니다.