WildFly版Keycloakのサポートは終了し、現行はQuarkus版が唯一の選択肢です。設定モデルが根本から変わったため、standalone.xmlの知識をそのまま持ち込むと必ずつまずきます。本記事ではbuild/startの二相構造を軸に、移行時の落とし穴を実務目線で整理します。
Keycloakは17系(2022年)を境に、ベースランタイムをWildFlyからQuarkusへ全面移行しました。WildFll版(legacy distribution)はすでにメンテナンスが終了しており、Red Hat build of Keycloakを含め、現在の新規構築・アップグレードはQuarkus版が前提です。移行そのものは「JARを差し替えるだけ」では終わりません。設定モデルとライフサイクルが別物になっているからです。本記事は、旧版の運用に慣れた実務者がハマりやすいポイントを、設定対応の視点でまとめます。
01何が根本から変わったのか
WildFly版では、設定の実体は standalone.xml(またはHA構成の standalone-ha.xml)であり、jboss-cli でXMLツリーを操作するのが日常でした。サブシステム単位のツリー構造、CLIバッチ、Undertowのハンドラチェーン——このメンタルモデルはQuarkus版では通用しません。
公式の移行ガイドが明言しているとおり、Quarkus版は「複雑なXMLファイルとjboss-cliを廃し、シンプルな設定ファイル+CLI引数+環境変数」に置き換わりました。設定のソースは conf/keycloak.conf に集約され、キーは <key-with-dashes>=<value> 形式のフラットな構造です。standalone.xml からの自動変換ツールは提供されていません。手作業で設計項目を洗い出して対応付ける必要があります。
02build と start ——二相ライフサイクルを理解する
Quarkus版最大の概念的違いが、ビルドフェーズ(build)とランタイムフェーズ(start)の分離です。bin/kc.sh build は、Quarkusの augmentation(拡張・最適化)を実行し、その結果をディストリビューション内に永続化します。公式の設定ガイドによれば、buildが行う最適化は次のようなものです。
- インストール済みプロバイダに対する「閉世界仮定(closed-world assumption)」の確立——起動のたびにプロバイダレジストリを再構築せずに済む
- 設定ファイルの事前パースによる起動時I/Oの削減
- 特定のDBベンダ向けリソースの事前構成・準備
つまりbuildは「このインスタンスは何者か(どのDB、どのプロバイダ、どの機能フラグで動くか)」を固める工程です。ここで確定した項目は、再buildしない限り変更できません。
03「起動が遅くなった」の正体
移行直後に高確率で挙がる声が「Quarkus版は起動が遅い」です。実はこれ、設定ミスに近い誤解であるケースがほとんどです。
設定ガイドが述べるとおり、kc.sh start や start-dev は、利便性のために裏側で毎回buildを実行します。このbuildは数秒かかります。つまり start をそのまま叩くと、起動のたびに最適化処理が走り、その分だけ遅く見えるわけです。WildFly版の「起動=即プロセス立ち上げ」の感覚で比較すると、遅く感じるのは当然です。
本番の正しい形は、事前に kc.sh build でイメージを最適化しておき、起動時は --optimized を付けてbuildチェックをスキップさせることです。
bin/kc.sh build——CI/コンテナビルド時に一度だけ実行し、最適化済みイメージを作るbin/kc.sh start --optimized——起動時にbuildを走らせず、高速に立ち上げる
WildFly版に近い挙動(起動時に自動build)を維持したい場合の「auto build」モードも用意されていますが、本番で毎回のbuildコストを払う理由はありません。コンテナ運用なら、Dockerfileの中で kc.sh build を実行してカスタムイメージを焼き、実行は start --optimized に統一するのが定石です。
--optimized が付いているか、そして事前buildが済んでいるかを確認します。多くはコマンド設計の問題で、Quarkus本体の性能問題ではありません。04build-time と runtime の切り分けが設計を決める
設定キーは、build-timeオプションとruntimeオプションの2種類に分かれます。公式ドキュメントでは、build-timeオプションに工具(スパナ)アイコンが付いています。この区別が --optimized 運用の成否を分けます。
- build-timeオプション:DBベンダ(
db)、機能フラグ(features)、メトリクス有効化(metrics-enabled)、ヘルスチェック(health-enabled)など。--optimizedで起動する前に、buildで確定しておく必要があります。ここを実行時に変えようとすると反映されません。 - runtimeオプション:DB接続先ホスト(
db-url-host)、認証情報、hostname、TLS証明書、ログレベルなど。再起動だけで変更できます。
移行設計では、まずこの2群に設定項目を仕分けます。「DBベンダはbuild-time、DB接続先はruntime」のように、同じDB関連でも境界がまたがる点が最初の落とし穴です。build-time/runtimeの切り分けは兄弟記事のbuild-time/runtime設定の分離で掘り下げています。
05設定対応表 —— standalone.xml から何に移るか
旧版で触っていた代表的な設定が、Quarkus版でどこに移るかを整理します。バージョンによりキー名は変わり得るため、最終的には利用バージョンのAll configurationで必ず突き合わせてください(下表は新しめのバージョンを基準にした対応の考え方です)。
- データソース定義(datasources subsystem) →
db(ベンダ/build-time)、db-url・db-username・db-password(runtime) - HTTPリスナ/ソケットバインディング →
http-enabled・http-port・https-port、TLSはhttps-certificate-fileほか - プロキシ配下のヘッダ設定 →
proxy-headers(近年proxyオプションから移行) - Infinispanのキャッシュ設定(standalone-ha.xml) →
cache・cache-stack、詳細はconf/cache-ispn.xml - ロギングサブシステム →
log・log-level・log-console-outputほか - SPI/プロバイダ設定(<spi>要素) →
spi-<spi名>-<provider名>-<プロパティ>形式のキー
Infinispanのクラスタ設計は移行時に見落とされやすく、HA構成の要です。InfinispanキャッシュのチューニングやAWS上でのHA構成もあわせて確認しておくと安全です。
06プロバイダ配置 ——deploymentsは無い
WildFly版でカスタムプロバイダやテーマJARを置いていた standalone/deployments ディレクトリは、Quarkus版には存在しません。移行ガイドが明記するとおり、カスタムプロバイダは providers ディレクトリにコピーします。
ここで重要なのが、プロバイダの追加・変更はbuild-timeの領域だという点です。providers の中身を差し替えたら、必ずbuildをやり直す(または auto build で再起動する)必要があります。--optimized 起動のまま providers にJARを放り込んでも、閉世界仮定は再構築されず、新しいプロバイダは認識されません。
providers にCOPY → kc.sh build」の順に固定します。プロバイダ更新=イメージ再ビルド、という運用ルールにしておくと、"入れたのに効かない"事故を防げます。カスタムSPIの作り込みはUser Storage SPIやカスタム認証SPIを参照してください。07-D と JAVA_OPTS ——JVMオプションの渡し方
WildFly版では standalone.conf の JAVA_OPTS にJVMフラグやシステムプロパティを書き込んでいました。Quarkus版でも起動スクリプトは変わり(kc.sh)、素の JAVA_OPTS を上書きすると kc.sh 側が用意する既定のJVMチューニングを丸ごと潰してしまいます。
そこで使うのが JAVA_OPTS_APPEND です。既定オプションを保ったまま、追加のシステムプロパティ(-D)やエージェント設定を後ろに足せます。
JAVA_OPTS_APPEND=-Dsome.property=value bin/kc.sh start --optimized——既定を壊さずに-Dを追加- Keycloak本体の設定は原則
-Dではなく設定キー(conf/keycloak.conf/環境変数/CLI)で与えるのが正道。-Dは、あくまでJVMやサードパーティライブラリ向けに限定する - Keycloakの設定として本来存在しない、Quarkusフレームワーク固有の挙動が必要な場合は
conf/quarkus.propertiesを使う(ただしこれは"設定"ではなく"カスタマイズ"扱いで、build-timeのみサポート)
設定の優先順位は、CLIパラメータ > 環境変数 > conf/keycloak.conf > Java KeyStore(機微情報)の順です。環境変数は KC_<KEY_WITH_UNDERSCORES> 形式(例:KC_DB_URL_HOST)になります。旧版のクセで何でも -D に寄せると、この優先順位から外れて追跡困難になるため避けてください。
—まとめ
Quarkus版への移行は、ファイルの置き換えではなくライフサイクルの再設計です。要点を再掲します。
standalone.xml+jboss-cliは廃止。設定はconf/keycloak.conf+環境変数+CLIに集約- build(何者か)とstart(どう動かすか)を分離し、本番は事前build+
start --optimizedで高速起動 - 「遅い」の多くは毎回のauto buildが原因。
--optimizedで解消する - DBベンダ・機能フラグ・プロバイダはbuild-time、接続先やTLSはruntime。この境界で設計を仕分ける
- プロバイダは
providersへ。変更したら必ず再build - JVMフラグは
JAVA_OPTS_APPENDで追加。Keycloak設定は-Dではなく設定キーで
EMWではWildFly版からQuarkus版への移行を含むエンタープライズ認証基盤の実構築に携わってきました。移行時の設定棚卸しやHA・キャッシュ設計は、導入事例もあわせてご覧ください。バージョン依存の細部は、必ず利用バージョンの公式ドキュメントで最終確認することをおすすめします。