Keycloak 백업, 복원, 마이그레이션

1️⃣ + Realm/Client/User 설정 백업 방법

1. Keycloak Export 기능 사용

Keycloak에서는 Realm 단위로 전체 설정을 백업할 수 있는 내장 기능을 제공합니다.

# 단일 Realm 백업
$ ./kc.sh export --dir /opt/keycloak-backup --realm myrealm --users realm_file

# 전체 Realm 백업
$ ./kc.sh export --dir /opt/keycloak-backup --users realm_file

옵션 설명:

• --dir: 백업 파일이 저장될 디렉토리
• --realm: 백업 대상 Realm (지정하지 않으면 전체)
• --users realm_file: 사용자 정보 포함

2. 백업 파일 구조

/opt/keycloak-backup/
  ├── myrealm-realm.json
  ├── myrealm-users-0.json
  └── ...

• *-realm.json: Realm 구성 정보 (Client, Roles, Mappers 등)
• *-users-0.json: 사용자 및 Credential 정보

3. 복원 시 import 사용

$ ./kc.sh import --dir /opt/keycloak-backup

주의사항: 복원 시에는 해당 Realm이 존재하지 않아야 함 (덮어쓰기 아님)

2️⃣ + kcadm.sh 또는 Admin REST API 이용한 마이그레이션

1. kcadm.sh 개요

kcadm.sh는 Keycloak CLI 도구로, Realm/Client/User를 커맨드라인에서 조작 가능하게 해줍니다.

초기 로그인:

$ ./kcadm.sh config credentials --server http://localhost:8080/auth \
  --realm master --user admin --password admin

2. Realm 가져오기/내보내기

# Realm export
$ ./kcadm.sh get realms/myrealm > myrealm.json

# Realm import
$ ./kcadm.sh create realms -f myrealm.json

3. REST API를 이용한 자동화 마이그레이션

Keycloak은 REST API를 완전하게 지원합니다. 다음은 Python을 이용한 예시입니다.

import requests

# Access Token 획득
resp = requests.post('http://localhost:8080/realms/master/protocol/openid-connect/token', data={
    'client_id': 'admin-cli',
    'username': 'admin',
    'password': 'admin',
    'grant_type': 'password'
})
token = resp.json()['access_token']

# Realm 목록 조회
headers = {'Authorization': f'Bearer {token}'}
realms = requests.get('http://localhost:8080/admin/realms', headers=headers)
print(realms.json())

이 방식을 통해 자동화된 백업 및 동기화도 구현 가능합니다.

3️⃣ + 버전 업그레이드 시 주의사항

1. 사전 점검 체크리스트

• DB 백업 (PostgreSQL, MariaDB 등)
• Realm Export
• 사용자 Export (kcadm 또는 --users realm_file)
• 사용 중인 Provider (custom SPI) 호환 여부 확인
• Keycloak 테마 커스터마이징 여부 확인

2. 업그레이드 예시 (컨테이너 환경)

# 현재 버전: quay.io/keycloak/keycloak:20.0
# 업그레이드 대상: quay.io/keycloak/keycloak:24.0

docker pull quay.io/keycloak/keycloak:24.0

주의: 17버전 이후 Quarkus 기반 Keycloak로 완전히 전환되었으므로, standalone.xml 설정은 무시되고 conf/keycloak.conf 기반 설정으로 변경됩니다.

3. 마이그레이션 전략

✅ 마무리 요약

• Realm/Client/User 구성은 Export/Import 기능 또는 kcadm/REST API를 통해 관리 가능
• 마이그레이션은 자동화 스크립트와 버전 변경 사항 문서를 참고해야 안전
• 업그레이드 전에는 반드시 데이터베이스와 Realm 설정을 이중 백업해야 함