Keycloakは年4回の頻度でバージョンが上がり続けるプロダクトです。認証基盤という止められない土台を、breaking changeとDBスキーマ移行をさばきながらどう追随させるか。リリースサイクルの読み方から、自動/手動のDB移行、ダウンタイム最小化、ロールバックまで、実構築の現場で使う勘所を整理します。
01まず全体像 — Keycloakは「上がり続ける」前提で設計する
Keycloakは認証基盤という「止められない土台」でありながら、プロダクト自体は活発にリリースが続きます。コミュニティ版(keycloak.org)はマイナーリリースが年4回のペースで、メジャーは2〜3年に一度という頻度で更新されます。塩漬けにできる性質のミドルウェアではなく、「上がり続ける前提」で運用設計する必要がある、というのがまず押さえたい点です。
本記事は現行のQuarkusベースのディストリビューション(26系以降)を基準にします。旧WildFlyベース(標準サポート終了済み)からの移行は前提が大きく異なるため、Quarkusディストリビューションへの移行を別途参照してください。バージョン依存の細かい挙動は動くバージョンで変わり得るので、必ず公式のUpgrading Guideで最終確認する、という姿勢を通します。
02リリースサイクルとLTSの読み方
運用計画の出発点はサポート期間の把握です。コミュニティ版とRed Hat build of Keycloak(RHBK)でライフサイクルが異なるため、どちらを使っているかで戦略が変わります。
- コミュニティ版：マイナーが年4回、メジャーが2〜3年に一度。コミュニティ版には明示的なLTSラベルはなく、実質的に最新に追随し続ける運用が前提になります。
- RHBK(サブスクリプション)：マイナーは約6か月ごと(コミュニティの偶数マイナー 26.0 / 26.2 / 26.4 …に対応、奇数は飛ばす)。ライフサイクルポリシーによれば、メジャーバージョンのフルサポート+メンテナンスは26.xで最低2年、27.x以降は3年。個々のマイナーはパッチ(マイクロ)更新が約12か月、具体的には「2つ先のマイナーが出るまで」提供されます。
つまりRHBKでは「1マイナーを約1年安定運用し、年1〜2回上げる」計画が組めます。エンタープライズで変更管理を厳格に回すなら、サポート期間が明確なRHBKを選ぶ判断は理にかなっています。逆にコミュニティ版なら、四半期ごとの追随を運用カレンダーに織り込むのが現実的です。
03breaking changeの追随 — Release-specific changesを起点にする
アップグレードの実務は、公式の「Release-specific changes」を一件ずつ潰す作業に尽きます。Keycloakのポリシーでは、マイナー/パッチでの破壊的変更は原則バグ修正に限られ、しかもopt-in(明示設定で有効化)とされています。廃止(deprecation)はマイナーでも起こり得ますが、機能の実削除は次のメジャーまで持ち越されます。この「マイナーは基本互換、削除はメジャー」という約束が、計画を立てる土台になります。
実際に効いてくる変更の型を挙げます。
- 設定オプションの改廃：起動オプションのリネーム・廃止。例えば近年では
spi-dblock-jpa-lock-wait-timeoutがtransaction-setup-timeoutに置き換わるといった変更が入っています。ビルド時オプションの扱いはビルド時/実行時コンフィグの分離と密接なので、そちらも合わせて確認します。 - デフォルト値の変更：セキュリティ強化に伴うデフォルトの厳格化。挙動が変わるのに設定を触っていないため気づきにくい類です。
- 機能の非推奨化：例として、レガシーなToken Exchange V1が非推奨になっています。後継はユースケース依存で、公式が主に推奨するのは既定で有効なStandard Token Exchange V2(
token-exchange-standard:v2)です。加えて、internal→externalのケースに限りIdentity Brokering APIs V2が、external→internalではStandard Token Exchange V2とJWT Authorization Grantの併用が推奨されます。移行猶予のあるうちに、自環境のユースケースに合う後継へ寄せておくのが定石です。
04DBスキーマ移行 — Liquibaseの自動/手動を使い分ける
Keycloakのスキーマ移行はLiquibaseで管理され、リリースごとの変更セットが同梱されます。デフォルトでは、新バージョンを初回起動した際にスキーマが自動適用されます。小〜中規模なら自動で十分ですが、エンタープライズでは以下の2点で「手動戦略」を選ぶ場面が出てきます。
- 変更内容を事前レビューしたい：本番DBに何が流れるかをDBAが承認してから流す運用。
- 大規模テーブルのインデックス生成：ある特定テーブルの件数が30万件(300000)を超えると、自動移行はインデックス作成をスキップし、SQLをログに出力する挙動になります。巨大テーブルで長時間ロックがかかるのを避けるための安全機構です。この場合、出力されたSQLを計画停止やオフピークで手動適用します。
手動戦略は、connections-jpaプロバイダの migration-strategy を manual に設定します。この状態で起動すると、必要な変更が bin/keycloak-database-update.sql に書き出され、サーバーは移行を実行せずに停止します。DBAはこのSQLをレビューして適用し、その後あらためて新バージョンを起動する、という2段構えになります。変更セットの実体は model/jpa/src/main/resources/META-INF 配下にバージョンごとのXMLとして置かれており、何が変わるかはソースでも追えます。
05ダウンタイム最小化 — update-compatibilityで判定する
近年のKeycloakは、同一 major.minor ストリーム内のパッチ更新について、ゼロダウンタイムのローリング更新をサポート対象・既定有効としました。パッチ間ではDBスキーマとキャッシュ(Infinispan)の後方互換が保たれるため、新旧のノードが一時的に混在しても動作します。ただしこれはパッチレベルの話で、マイナー・メジャーをまたぐ場合は前提が変わります。
ローリング更新が可能かは、感覚で判断せず update-compatibility コマンドで機械的に判定できます。
- メタデータ採取：現行バージョン・現行設定で
bin/kc.sh update-compatibility metadata --file=/path/to/file.jsonを実行し、稼働構成のスナップショットをJSONで取得。 - 互換チェック：新バージョン・新設定で
bin/kc.sh update-compatibility check --file=/path/to/file.jsonを実行し、旧構成と比較。
判定は終了コードで返ります。0=ゼロダウンタイムのローリング更新が可能、3=recreate戦略が必要(全ノード停止を伴う)、4=ローリング更新機能が無効。CI/CDに組み込めば、「今回はローリングで行けるか、計画停止が要るか」をリリースごとに自動で切り分けられます。Operator運用なら更新戦略を Auto にしておくと、この判定に基づく更新を任せられます。
Kubernetes上の可用性設計そのものはKubernetes上のKeycloakやAWS上のHA構成で扱っています。マイナー/メジャー跨ぎでスキーマが前進する更新では、原則ローリングが効かない前提で、青緑デプロイや計画停止を組み合わせるのが安全です。
06ロールバック設計 — 「戻せない前提」で守りを固める
もっとも誤解されやすいのがロールバックです。前述のとおりDBスキーマ移行はフォワードオンリーで、Liquibaseが勝手に前の状態へ戻すことはできません。したがってロールバック戦略は「アプリのバイナリを戻す」話ではなく、「移行前のDB状態を復元できるか」の話になります。実務では次の順序で守りを固めます。
- 移行前スナップショット：DBのフルバックアップ、またはRDS等ならスナップショットを移行直前に取得。復元手順とRTO/RPOの考え方は監視・アラート設計や一般的なDR設計の枠組みに沿って事前に握っておきます。
- ステージングでの本番相当リハーサル：本番のダンプを流し込んだ環境で移行を通し、所要時間・ロック・件数閾値の挙動を実測。この「時間の実測」がメンテナンスウィンドウ設計の根拠になります。
- 切り戻し判断基準の明文化:「どの症状が出たら旧バージョン+復元DBに戻すか」を事前に決め、当日の判断を属人化させない。
07テーマ/SPI/クライアントの互換 — サーバーの外側を忘れない
アップグレードで見落とされがちなのが、サーバー本体ではなく「その周辺」です。公式の推奨手順も、サーバー→アダプター→クライアントライブラリ(Admin/Authorization/Policy enforcer)の順で上げる、と明記しています。周辺の互換で特に注意する点を挙げます。
- カスタムテーマ：FreeMarkerテンプレートやテーマ構造はバージョン間で変わります。標準テーマから継承・上書きしている画面は、新バージョンの標準テーマと差分を取り直す必要があります。カスタムの作り方はカスタムテーマ開発を参照。
- カスタムSPI/プロバイダ:User Storage SPI、Authenticator、Event Listenerなど自作拡張はKeycloakのAPIに依存します。非推奨APIの削除でコンパイル/ロードが通らなくなることがあるため、対象バージョンでのビルド確認が必須です(User Storage SPI、カスタムAuthenticator)。
- クライアント/アダプター：アプリ側のOIDC/SAMLアダプターやAdmin RESTを叩くIaC(Admin REST APIのIaC化)も、APIの後方互換とはいえ挙動差を検証対象に含めます。
これらは「サーバーは上がったのに管理画面のログイン画面が崩れる」「起動時にプロバイダのロードで落ちる」といった形で表面化します。サーバー単体のスモークテストだけでなく、テーマ描画・カスタムフロー・外部連携までを含む回帰テストの束を、アップグレード用の検証セットとして常備しておくのが堅実です。
—まとめ — 検証の型を資産化する
Keycloakのバージョンアップは、単発の作業ではなく「毎年繰り返す運用プロセス」です。要点を再掲します。
- 計画：サポート期間(コミュニティは追随前提、RHBKはマイナー約12か月)から逆算して上げるタイミングを予約する。
- 追随：Release-specific changesを自環境でトリアージし、有効化機能に触れる変更だけを検証対象に落とす。
- DB移行：本番は手動戦略でSQLをレビュー。30万件閾値のインデックスは計画的に。移行前バックアップは必須。
- 無停止:
update-compatibilityでローリング可否を機械判定。パッチは無停止、マイナー/メジャー跨ぎは計画停止前提。 - 周辺：テーマ・SPI・アダプターまで含めた回帰テストを検証セットとして資産化する。
この「検証の型」を一度作ってしまえば、以降のアップグレードは同じレールに乗せて回せます。EMWはKeycloakでエンタープライズの認証基盤を実構築してきた経験から、この型づくりと移行検証を支援しています。実案件の概要は導入事例もご覧ください。