백업과 업그레이드

다른 이름: Keycloak backup · pg_dump · pg_restore · realm export · Keycloak upgrade · rollback내용 검토: 2026. 09. 14.

결론부터

Keycloak 백업의 완료 기준은 파일 생성이 아니라 격리된 DB에 복원해 필요한 realm과 client를 읽을 수 있는가이다.

realm export는 설정을 검토·이관하는 데 유용하지만 database의 전체 영속 상태를 대신하지 않는다. 업그레이드 전에 되돌릴 수 있으려면 실행 버전과 호환되는 PostgreSQL 백업과 검증된 복원 절차가 필요하다.

이 장에서 처음 나오는 말4개

logical backup: pg_dump처럼 DB 객체와 데이터를 논리 형식으로 내보내 다른 빈 DB에 복원하는 백업.
realm export: realm 설정과 선택한 객체를 JSON으로 내보내는 이관·부트스트랩 보조물. 전체 DB 복구본은 아니다.
PITRPoint-in-Time Recovery: base backup과 WAL을 이용해 장애 직전의 특정 시점으로 PostgreSQL을 복구하는 방법.
rollback: 업그레이드 실패 때 이전 애플리케이션과 그 버전이 이해하는 DB 상태로 함께 돌아가는 절차.

이 장에서 답할 질문

DB backup과 realm export는 어떤 상태를 다루는가?
복원 검증은 운영 DB를 위험하게 하지 않고 어떻게 수행하는가?
Keycloak 업그레이드에서 image만 이전 버전으로 내리면 안 되는 이유는 무엇인가?

복구 원본과 구성 보조물을 나눈다

대상	주된 수단	용도
PostgreSQL 전체 상태	physical backup/PITR 또는 검증한 logical dump	재해 복구와 upgrade rollback
realm 구성 snapshot	Keycloak export	리뷰, 환경 간 이관, bootstrap 보조
운영 의도	Operator CR, script, IaC	반복 적용할 설정과 변경 이력
secret/private key	별도 secret backup·rotation 체계	DB dump 밖의 runtime credential 복구

Realm export 종류와 실행 조건은 Keycloak import/export 가이드를 따른다. 실행 중 export의 일관성과 사용자 수 제한, startup import의 skip 동작을 확인하고 DB backup과 같은 이름으로 부르지 않는다.

격리된 복원으로 확인한다

cd labs/keycloak
./internal/verify/verify-d24.sh

실습은 live PostgreSQL을 바꾸지 않고 custom-format pg_dump를 생성했다. 같은 고정 image의 network-none 일회성 PostgreSQL과 전용 volume에 pg_restore --exit-on-error로 복원했다. source/restore의 realm·client·user 수가 같았고 복원 DB에 study, d16-upstream realm과 app-a, d18-worker, study-broker client가 있었다. 검증 뒤 임시 container와 volume은 제거했고 live 여섯 service는 healthy였다.

dump에는 password hash, client와 identity 연결 등 민감한 상태가 포함될 수 있다. 암호화·접근 통제·보존 기간·폐기를 적용하고 token이나 row를 검증 로그에 출력하지 않는다. 이 로컬 dump는 ignore된 0700 디렉터리에만 있다.

업그레이드와 되돌리기를 한 절차로 만든다

목표 버전의 release notes, migration guide와 지원 DB/JDK를 읽고 중간 버전 필요 여부를 확인한다.
DB backup과 외부 secret/key/config snapshot을 만들고 격리 복원을 성공시킨다.
운영과 같은 topology·extension·Federation을 가진 staging에서 login, refresh, logout, admin 작업을 시험한다.
rolling update 호환 범위와 DB schema 변경 시점을 확인해 rollout 또는 정지 upgrade를 선택한다.
성공 지표와 중단 기준을 관찰하고, 실패하면 app image와 DB를 합의한 restore point로 함께 되돌린다.

Keycloak update compatibility 문서는 rolling update에서 서로 다른 버전이 함께 동작할 수 있는 조건을 설명한다. 이전 image만 다시 띄우는 것은 이미 바뀐 DB schema를 이전 코드가 이해한다는 보장이 없으므로 rollback이 아니다.

요약

DB 복원은 재해 복구 기준이고 realm export는 구성 이관 보조물이다.
D24는 live 상태를 건드리지 않는 격리 복원으로 핵심 realm/client와 수 일치를 실제 확인했다.
upgrade 전 복원 검증과 staged test를 하고 rollback은 애플리케이션·DB·secret 상태를 함께 다룬다.