6. 운영 백업/복구 — Realm export/import, DB 백업, 키 관리

Keycloak 운영 백업/복구 (6) — “DB 백업 + Realm Export” 2겹으로 설계하기

Technote · Keycloak · 운영/DR · (환경 예시: Docker + PostgreSQL + Reverse Proxy)

RPO/RTO 설계 Realm export/import pg_dump/pg_restore 키/시크릿 관리 복구 리허설

목차

1. 백업의 “정답”은 2겹이다
2. 레이어1: DB 백업(가장 중요)
3. 레이어2: Realm export/import(설정 스냅샷)
4. 키/인증서/시크릿: “복구 실패 1순위”
5. 복구 Runbook (장애 시 그대로 따라하기)
6. 정기 검증(복구 리허설) 체크리스트
7. 레퍼런스

Layer 1 (필수): DB 백업• 사용자/클라이언트/Realm 데이터• 장애 복구/롤백의 기준점• pg_dump → pg_restore• RPO/RTO 결정의 핵심Layer 2 (보강): Realm export• 설정 스냅샷(Realm 중심)• 변경 이력/감사/이동에 유리• kc.sh export/import• “단독 DR”로는 부족할 수 있음실무 함정: 키/시크릿/인증서• TLS 인증서/프록시 헤더• Realm Keys(Active/Passive)• DB만 살려도 “로그인 루프” 발생• 복구 runbook에 반드시 포함

1) 백업의 “정답”은 2겹이다

Keycloak은 사용자/클라이언트/Realm 등 핵심 데이터를 관계형 DB에 저장합니다. 그래서 “DB 백업”은 선택이 아니라 운영의 기본 축입니다. (DB가 살아있으면 컨테이너는 버려도 재기동 가능)

권장 조합
✅ (필수) DB 백업: 장애 복구/롤백/DR의 기준점
✅ (보강) Realm export: 설정 스냅샷/이관/감사/변경관리용

2) 레이어1: DB 백업(가장 중요)

왜 DB 백업이 “1순위”인가?

Keycloak의 운영 데이터(사용자/클라이언트/realm 등)는 DB가 소스오브트루스입니다. 따라서 업그레이드/장애/롤백 모두 DB 백업이 없으면 “안전한 복구”가 불가능해집니다.

논리백업 기본기

PostgreSQL 기준으로 pg_dump로 덤프를 만들고 pg_restore로 복구하는 흐름이 가장 표준적입니다. (custom format -Fc 권장)

2-1) pg_dump 예시 (custom format 권장)

# (예시) Keycloak DB 논리 백업
# -Fc : custom format (pg_restore 사용)
# --no-owner/--no-privileges : 환경 이관시 권한 충돌 방지에 유리
export PGPASSWORD='***'
pg_dump -h 127.0.0.1 -p 5432 -U keycloak -d keycloak \
  -Fc --no-owner --no-privileges \
  -f /backups/keycloak_$(date +%Y%m%d_%H%M).dump

2-2) pg_restore 예시

# (예시) 복구용 새 DB 준비 후 restore
createdb -h 127.0.0.1 -p 5432 -U keycloak keycloak

pg_restore -h 127.0.0.1 -p 5432 -U keycloak \
  --clean --if-exists \
  -d keycloak /backups/keycloak_20251228_0300.dump

운영 팁 (RPO/RTO 감각)
• “야간 1회 DB 백업”은 흔한 기본값이지만, 로그인 장애가 돈/업무에 직결되면 더 촘촘한 주기가 필요합니다.
• DR은 “백업 파일 존재”가 아니라 “복구 리허설 성공”으로만 증명됩니다. (아래 6번 참고)

3) 레이어2: Realm export/import(설정 스냅샷)

Keycloak은 kc.sh export/kc.sh import로 Realm 데이터를 파일로 내보내고 다시 가져올 수 있습니다. 다만 문서에서 안내하듯, export/import는 서버 시작과는 다른 실행 흐름로 다루는 것이 안전합니다.

주의
“운영 중 무중단으로 export/import를 막 던지는 방식”은 예상치 못한 꼬임을 만들 수 있습니다.
현실적으로는 DB 백업(항시) + Realm export(변경관리/이관/정기 스냅샷) 조합이 안정적입니다.

3-1) Realm export 예시

# (예시) 특정 realm을 디렉토리로 export
# /opt/keycloak/bin/kc.sh 경로는 공식 컨테이너/배포에서 흔히 사용됩니다.
# (운영 환경에서는 export 작업을 “계획된 절차”로 수행하세요.)
/opt/keycloak/bin/kc.sh export \
  --dir /opt/keycloak/data/export \
  --realm my-realm \
  --users realm_file

3-2) Realm import 예시

# (예시) import 디렉토리를 준비해두고 import 실행
/opt/keycloak/bin/kc.sh import \
  --dir /opt/keycloak/data/import

Export/Import를 쓰면 좋은 순간
• “이 Realm 설정, 누가/언제/어떻게 바뀌었지?” → 스냅샷/변경관리
• 테스트/스테이징 환경으로 Realm 복제
• IaC/운영 자동화(Operator 기반 realm import 등)로 확장할 발판

4) 키/인증서/시크릿: “복구 실패 1순위”

DB/Realm을 잘 살렸는데도 로그인/리다이렉트가 터지는 이유는 대개 “외부 환경값”입니다. 특히 Reverse Proxy + Hostname + 키/인증서가 복구 성공률을 좌우합니다.

4-1) Realm Keys(Active/Passive) 감각

• Keycloak Admin Console에서 Realm settings → Keys로 키 상태를 확인합니다.
• 키는 Active/Passive/Disabled 같은 상태 개념이 있으며, Passive 키는 “새 토큰 발급에는 쓰지 않지만 이전 토큰 검증에는 유효”할 수 있습니다.
• 운영에서 “키 교체/만료/회전”은 인증 장애로 직결되므로, 백업/복구 문서에 반드시 포함하세요.

4-2) TLS/프록시/호스트네임 (복구 장애의 단골)

프록시 뒤에서 Forwarded/X-Forwarded-Proto 처리가 어긋나면
• https인데 http로 인식 → mixed-content/redirect loop
• admin 접근 경로가 꼬임 → 무한 로딩/로그인 실패
같은 현상이 재발합니다.

5) 복구 Runbook (장애 시 그대로 따라하기)

목표: “새 Keycloak 컨테이너/서버”에 “정상 DB + 정상 외부설정”을 얹어 로그인까지 복구

1. 현재 장애 범위 확인: UI/토큰발급/관리콘솔/클라이언트 로그인 중 어디가 죽었는지 분리
2. DB 상태 확보: 최근 백업 파일과 복구 가능한 DB 계정/권한 확인
3. 복구 타겟 환경 준비: (권장) 기존과 같은 Keycloak 버전으로 먼저 복구 → 이후 업그레이드
4. DB restore: pg_restore로 DB를 먼저 살리고 Keycloak을 기동
5. Health 확인: 관리 포트에서 /health/ready로 ready 확인
6. 외부 노출 설정 확인: reverse proxy/hostname 설정(https, host) 재점검
7. Smoke test: 대표 클라이언트 1개로 로그인/토큰발급/로그아웃까지 확인

5-1) Health 체크 예시

# (예시) Keycloak health endpoint
# 기본적으로 metrics/health는 관리 포트(기본 9000)에서 노출될 수 있습니다.
curl -fsS http://127.0.0.1:9000/health/ready

6) 정기 검증(복구 리허설) 체크리스트

백업은 “복구 테스트”를 하지 않으면 백업이 아닙니다.
최소 월 1회, 또는 큰 변경(업그레이드/프록시 변경/인증서 교체) 전후로 리허설을 추천합니다.

• ✅ 최근 DB 덤프 파일로 “새 환경”에 restore 성공
• ✅ Keycloak 기동 후 /health/ready OK
• ✅ 대표 realm 로그인 + 토큰 발급 + refresh OK
• ✅ Admin Console 접속 OK (권한 포함)
• ✅ reverse proxy(https) 환경에서 redirect/mixed-content 없음
• ✅ 키/인증서(Realm Keys, TLS) 정상

---

레퍼런스

• Keycloak Server Administration Guide
• Keycloak: Configuring the database
• Keycloak Upgrading Guide
• Keycloak: Management Interface
• Keycloak: Health checks
• Keycloak Operator: Realm Import
• PostgreSQL: pg_dump
• PostgreSQL: pg_restore
• Red Hat Keycloak: Realm Keys(Active/Passive)
• Keycloak 26.1.0 release note (passive keys behavior)

※ 본 글은 “운영 Runbook” 관점의 정리이며, 실제 운영 정책(RPO/RTO, 암호화, 접근통제)은 조직 보안 기준에 맞춰 조정하세요.