Keycloakの設定をローカル開発環境間で共有する方法（export / pg_dump）

はじめに

あるプロジェクトで OSS の Keycloak を認証基盤として利用しており、開発者間でローカル環境用にKeycloakの設定を共有する方法を調査しました。
Keycloakの設定を複数環境に共有する方法として、エクスポートファイルやダンプファイルの利用が考えられますが、コンテナの起動～設定の取り込みを一連の手順として整理しようとすると、いくつか工夫が必要でした。
本投稿では、Keycloak の設定を複数環境へ共有する方法として、エクスポートファイルおよびダンプファイルを用いた手順を解説するとともに、運用上工夫した点や使い分けの方針について紹介します。

環境

• Windows 11
• Docker : 28.4.0
• WSL : 2.6.2.0
• PostgreSQL : 17
• Keycloak: 26.3.3

設定共有の全体像

• AさんがKeycloakの諸々の設定を行う
• BさんがAさんの設定した内容でローカル環境にKeycloakを立ち上げる

設定内容をローカル環境に取り込む際、毎回コンテナを作り直す前提です。
稼働済みのコンテナを残すパターンは考慮しません。

エクスポート用のコンテナ作成

前提として、公式に記載の通りコンテナを起動するとKeycloakに同梱の開発用データベース (H2) がデータベースとして利用されます。

docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.3.3 start-dev

少しKeycloakを動作確認する程度ならこれでも良いですが、エクスポートファイルやダンプファイルを取得しづらくなります。本格的に開発に入る前にデータベース用のコンテナを用意するか、ホストマシン上にデータを保存する設定にしておくとあとが楽です。

本稿ではデータベース用のコンテナを用意する前提で進めます。この工程はエクスポートファイルとダンプファイルのどちらを使用する場合も共通です。

以下のような docker-compose.yml を任意の場所に配置し、docker compose up を実行します。

docker-compose.yml

services:
  keycloak-db:
    image: postgres:17
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    ports:
      - "5433:5432"

  keycloak-service:
    image: quay.io/keycloak/keycloak:26.3.3
    container_name: keycloak-service
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      KC_DB: postgres
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_DB_URL_HOST: keycloak-db
      KC_DB_URL_PORT: 5432
      KC_DB_URL_DATABASE: keycloak
    ports:
      - "8081:8080"
    depends_on:
      - keycloak-db
    volumes:
      - ./export:/opt/keycloak/data/import
    command: start-dev

正常にコンテナが立ち上がると、http://localhost:8081 でKeycloakのコンソールにアクセスできます。

Keycloakのコンソールでレルムやユーザーを作成して、他の開発者に共有したい設定を入れておきます。

Keycloakのエクスポートファイルを利用する場合

Keycloakのエクスポート/インポート機能を利用して、エクスポート用のコンテナ作成で設定した内容を他の開発環境に移行します。
コンソール画面からレルム設定をエクスポートする方法もありますが、ここではCLI経由でエクスポートファイルを出力する方法を取ります。

1. エクスポートファイルの出力

# エクスポート用にフォルダ作成
# docker exec -it {コンテナ名} mkdir -p {エクスポート用のフォルダ}
docker exec -it keycloak-service mkdir -p /opt/keycloak/data/export

# エクスポートファイル出力
# docker exec -it {コンテナ名} /opt/keycloak/bin/kc.sh export --dir {エクスポート用のフォルダ} --users realm_file
docker exec -it keycloak-service /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export --users realm_file

# エクスポートファイルをホスト側の任意のディレクトリにコピー
# docker cp {コンテナ名}:{エクスポート用のフォルダ} {ホスト側のコピー先}
docker cp keycloak-service:/opt/keycloak/data/export /export-to-host

エクスポートに成功すると、レルム単位で JSON ファイルが出力されます。

.
└── export-to-host/
    ├── master-realm.json
    ├── test-realm.json
    └── ...

2. エクスポートしたファイルのインポート

Keycloakの設定をインポートするためのymlを作成しておきます。

先のdocker-compose.ymlとの違いは以下です

• cmdでインポートファイルを読み込む設定をしていること
• KC_BOOTSTRAP_ADMIN_USERNAME,KC_BOOTSTRAP_ADMIN_PASSWORD の設定がないこと
  • KC_BOOTSTRAP_ADMIN_に既存ユーザーを設定するとエラーになることがあります

update.yml

services:
  keycloak-db:
    image: postgres:17
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    ports:
      - "5433:5432"

  keycloak-service:
    image: quay.io/keycloak/keycloak:26.3.3
    container_name: keycloak-service
    environment:
      KC_DB: postgres
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_DB_URL_HOST: keycloak-db
      KC_DB_URL_PORT: 5432
      KC_DB_URL_DATABASE: keycloak
    ports:
      - "8081:8080"
    depends_on:
      - keycloak-db
    volumes:
      - ./export:/opt/keycloak/data/import
    command: start-dev --import-realm

Keycloakの設定を取り込むローカル環境で、update.yml とエクスポートファイルを以下のように配置し、docker compose up を実行すると、インポートファイルの内容に基づいたKeycloakが起動します。

.
├── update.yml
└── export/
    ├── master-realm.json
    ├── test-realm.json
    └── ...

Keycloakの設定を更新する場合
既に稼働している Keycloak 用のコンテナとデータの永続化領域を削除してから、新しいエクスポートファイルを使用してインポートの手順を行います。

docker rm keycloak-service keycloak-db
rm -rf ./postgres-data

ダンプファイルを利用する場合

データベースのバックアップをダンプファイルに出力してエクスポート用のコンテナ作成で設定した内容を他の開発環境に移行する方法です。
ここでは PostgreSQL を前提としているため、pg_dump を使います。

1. ダンプファイルの出力

# ダンプファイル出力
# docker exec {データベース用のコンテナ名} pg_dump -U {ユーザー名} -d {データベース名} -Fc -f {ダンプファイル名}
docker exec keycloak-db pg_dump -U keycloak -d keycloak -Fc -f /tmp/keycloak.dump

# ダンプファイルをホスト側の任意のディレクトリにコピー
# docker cp {データベース用のコンテナ名}:{ダンプファイルへのパス} {ホスト側のコピー先}
docker cp keycloak-db:/tmp/keycloak.dump /dump-to-host

成功すると、ダンプファイルが出力されます。

.
└── dump-to-host/
    └── keycloak.dump

2. ダンプファイルのリストア

Keycloakの設定を取り込むローカル環境で、docker-compose.yml を使ってコンテナを起動しておきます。
コンテナが正常に起動できたら、以下を実行してリストアします。

# ダンプファイルを起動した PostgreSQL 側のコンテナ内にコピー
# docker cp {ダンプファイルへのパス} {データベース用のコンテナ名}:{コンテナ内のコピー先}
docker cp keycloak.dump keycloak-db:/tmp/keycloak.dump
# ダンプのリストア実行
# docker exec -it {データベース用のコンテナ名} pg_restore -U {ユーザー名} -d {データベース名} {コンテナ内のダンプファイルへのパス}
docker exec -it keycloak-db pg_restore -U keycloak -d keycloak /tmp/keycloak.dump

Keycloakの設定を更新する場合
既に稼働している Keycloak 用のコンテナとデータの永続化領域を削除してから、新しいダンプファイルを使ってリストアの手順を行います。

docker rm keycloak-service keycloak-db
rm -rf ./postgres-data

使い分けについて

• エクスポートファイルはJSON形式、ダンプファイルはバイナリとして出力されるため、普段の開発時には差分が分かりやすく構成管理をしやすいエクスポートファイルの方が扱いやすいです
• クラウド環境等で、Keycloak本体はコンテナ起動、別途データベースを接続して利用する環境にKeycloakの設定情報を移行する際はダンプをリストアするのが楽でした

おわりに

本投稿ではKeycloakの設定を他の開発環境へ移行する方法について説明しました。
docker-compose.yml やエクスポート/ダンプファイルが作成できれば手間なく構成管理できるため、運用の参考になれば幸いです。

We Are Hiring!