본문으로 건너뛰기

Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련

Keycloak 2개 + PostgreSQL 2개로 SSO를 만들고, 파드와 DB를 일부러 죽여 본 기록

로컬 쿠버네티스 실습 시리즈 목차 · 글 15개
  1. 1편Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind
  2. 2편Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
  3. 3편NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
  4. 4편kube-prometheus-stack 설치와 Grafana 접속: kind 클러스터 모니터링과 target down 해결
  5. 5편Fluent Bit과 Loki로 쿠버네티스 로그 모으기: kind 실습과 Grafana 조회, AWS 확장 예시
  6. 6편cert-manager로 Gateway API HTTPS 붙이기: 사설 CA, 자동 갱신, 만료 알림까지 kind 실습
  7. 7편Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
  8. 8편OpenTelemetry로 쿠버네티스 트레이스 모으기: Collector, Tempo, 샘플링과 장애 훈련까지 kind 실습
  9. 9편Argo CD로 쿠버네티스 GitOps 전환하기: Helm 설치 넘겨받기, Sealed Secrets, Keycloak SSO와 장애 훈련까지 kind 실습
  10. 부록Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
  11. 10편Trivy Operator로 쿠버네티스 취약점 점검하기: 이미지·설정·비밀값 스캔, Grafana 경보, Argo CD로 고치기까지 kind 실습
  12. 번외편Trivy로 찾은 컨테이너 이미지 취약점 고치기: nginx apk upgrade, Go 의존성 올리기, Grafana처럼 직접 못 고치는 경우까지
  13. 11편Istio Ambient 모드로 서비스 메시 붙이기: 사이드카 없이 mTLS, 권한 정책, waypoint 트래픽 분할과 장애 훈련까지 kind 실습
  14. 12편Strimzi로 쿠버네티스에 Kafka 올리기: KRaft 브로커 3대, SCRAM·ACL, 소비 지연 경보와 장애·업그레이드 훈련까지 kind 실습
  15. 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 문서

Terminal window
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg cnpg/cloudnative-pg --version 0.29.1 \
-n cnpg-system --create-namespace --wait
07-keycloak-db.yaml (일부)
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: keycloak-db
namespace: keycloak
spec:
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 PRIMARY
keycloak-db 2 2 Cluster in healthy state keycloak-db-1
keycloak-db-1 primary lab-worker2
keycloak-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 | async

Keycloak은 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 quarkus

26.8 버전의 운영자는 클라이언트를 리소스로 관리하는 기능(KeycloakOIDCClient, KeycloakSAMLClient)도 감시하는데, 그 CRD가 없으니 시작하지 못한 것입니다. 저장소의 kustomization.yml에 필요한 파일 목록이 있어서, 그 목록대로 CRD 4개를 모두 적용하자 11초 만에 Running이 되었습니다.

Terminal window
V=26.8.2
B=https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/$V/kubernetes
kubectl apply -f $B/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f $B/keycloakrealmimports.k8s.keycloak.org-v1.yml
kubectl 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.org
keycloakoidcclients k8s.keycloak.org/v2alpha1 KeycloakOIDCClient
keycloakrealmimports k8s.keycloak.org/v2beta1 KeycloakRealmImport
keycloaks kc k8s.keycloak.org/v2beta1 Keycloak
keycloaksamlclients k8s.keycloak.org/v2alpha1 KeycloakSAMLClient

운영 포인트

운영자를 올릴 때는 버전마다 CRD 목록과 API 버전이 바뀌었는지 먼저 봅니다. 파일을 하나씩 나열해 적용하기보다, 저장소의 kustomization처럼 버전별로 묶인 목록을 그대로 쓰는 편이 빠뜨림이 없습니다. 운영자는 기본적으로 자기가 설치된 네임스페이스만 감시하므로, Keycloak 리소스도 같은 네임스페이스(keycloak)에 둡니다. Keycloak Operator 설치 문서

Keycloak 리소스: 주소, 프록시, 관리자 비밀번호

관리자 초기 계정은 매니페스트에 쓰지 않고, 클러스터 안에서 무작위 비밀번호로 Secret을 만들었습니다. 이 계정은 이름 그대로 처음 들어가기 위한 임시 계정입니다.

umask 077
openssl rand -base64 24 | tr -d '\n' > password # 파일 이름이 Secret의 키 이름이 된다
kubectl create secret generic keycloak-bootstrap-admin -n keycloak \
--from-literal=username=temp-admin --from-file=password
rm password
apiVersion: k8s.keycloak.org/v2beta1
kind: Keycloak
metadata:
name: keycloak
namespace: keycloak
spec:
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 이동에도 넣어 두었기 때문에, 인증서와 리다이렉트는 손댈 것이 없습니다.

07-keycloak.yaml (일부)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: keycloak
namespace: keycloak
spec:
parentRefs:
- name: lab-gateway
namespace: default
sectionName: https
hostnames:
- keycloak.localhost
rules:
- backendRefs:
- name: keycloak-service
port: 8080

82초 뒤 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: true
issuer: https://keycloak.localhost:8443/realms/master
token: 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=keycloak
affinity: 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이 lab-worker와 lab-worker2에 나뉘어 Running이고, keycloak-db-1·keycloak-db-2, keycloak-operator, cnpg-cloudnative-pg, kps-grafana 파드도 Running이며 가져오기 Job 파드 lab-4z9vt는 Completed, IP 열은 가림
Keycloak·DB·운영자 파드 배치

고친 뒤 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 가져오기 문서

07-realm-lab.yaml (일부)
apiVersion: k8s.keycloak.org/v2beta1
kind: KeycloakRealmImport
metadata:
name: lab
namespace: keycloak
spec:
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: true

role_attribute_path는 그룹 목록을 보고 Grafana 역할을 고르는 식입니다. 어느 그룹에도 없으면 빈 값이 나오는데, role_attribute_strict: true라서 이 경우 기본 역할(Viewer)을 주지 않고 로그인을 거부합니다. Keycloak에 계정만 있으면 누구나 Grafana를 볼 수 있게 되는 것을 막는 설정입니다. Grafana Keycloak 연동 문서

Grafana 로그인 화면에 아이디·비밀번호 입력 칸과 Log in 버튼 아래 Sign in with Keycloak 버튼이 추가된 모습
Sign in with Keycloak 버튼이 생긴 Grafana 로그인 화면
LAB 렐름의 Keycloak 로그인 화면. Sign in to your account 제목 아래 Username or email, Password 입력 칸과 Sign In 버튼
Keycloak lab 렐름 로그인 화면

적용 후 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]
Grafana Profile 화면에 이름 Alice Lab, 이메일 alice@lab.example, 사용자 이름 alice가 Synced via Generic OAuth로 표시됨
Keycloak에서 넘어온 alice의 Grafana 프로필

alice로 로그인한 뒤 Grafana 프로필입니다. 이름, 이메일, 사용자 이름이 Keycloak에서 받아 온 값이라 “Synced via Generic OAuth”로 표시되고, Grafana에서 직접 고칠 수 없습니다. 사용자 정보는 Keycloak 한 곳에서 관리한다는 뜻입니다.

carol은 Keycloak 로그인 자체는 성공했지만 Grafana에서 거부되었습니다. 인증(누구인가)은 Keycloak이, 권한(무엇을 할 수 있나)은 그룹을 보고 Grafana가 정한다는 구분이 이 결과에 그대로 나타납니다.

Grafana 로그인 화면 위에 Login failed, IdP did not return a role attribute, please contact your administrator 오류가 표시됨
그룹이 없는 carol의 로그인 거부

모니터링: 무엇을 보고 있어야 하나

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.0
keycloak_user_events_total{error="",event="code_to_token",realm="lab"} 2.0
keycloak_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 cluster
keycloak-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 PRIMARY
keycloak-db 2 2 Cluster in healthy state keycloak-db-2

DB가 바뀌는 약 8초 동안은 로그인이 실패했습니다. 주 서버가 없는 동안에는 세션 저장 같은 쓰기를 할 수 없기 때문입니다. 그 뒤로는 Keycloak 설정을 전혀 바꾸지 않았는데도 로그인이 다시 성공했습니다. keycloak-db-rw 서비스가 새 주 서버를 가리키게 되었기 때문입니다. 장애 후 lab realm의 사용자 수(3명)도 그대로였습니다.

운영 포인트

DB 장애 전환 시간 동안의 로그인 실패는 피할 수 없으므로, 이 시간을 측정해 두고 서비스 목표(SLO)에 반영합니다. 이 실습은 강제 종료였고, 노드 자체가 응답하지 않는 장애에서는 장애 판단에 시간이 더 걸릴 수 있습니다. 비동기 복제라 이 몇 초 사이의 마지막 쓰기가 사라질 수 있다는 점도 함께 기록해 둡니다.

백업과 복구: 받아 둔 백업으로 실제로 살려 보기

이중화는 장비 장애를 막아 주지만, 실수로 지운 realm이나 잘못된 일괄 변경은 복제본에도 그대로 복제됩니다. 그래서 백업은 따로 필요합니다. 이 실습에서는 pg_dump로 논리 백업을 받고, 새 DB에 풀어서 내용이 같은지 확인했습니다.

Terminal window
# 복제본에서 덤프(주 서버 부하를 줄임)
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|1
lab 클라이언트 수: 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 파드 수: 0
SSO 버튼: 302 → https://keycloak.localhost:8443/.../auth → Keycloak 503
관리자 폼 로그인: 200
login: 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편)에 이어 세 번째 관측 신호를 붙입니다.

사진을 누르면 원본 크기