bin/kc.[sh|bat] start-dev --http-relative-path /authKeycloak 17以降、デフォルトのディストリビューションはQuarkusを搭載するようになりました。レガシーのWildFly搭載ディストリビューションは2022年6月まで引き続き利用可能ですが、できるだけ早く移行を開始することを強く推奨します。
新しいディストリビューションには、以下を含むいくつかの互換性を損なう変更が含まれています。
Keycloakの設定方法が大幅に変更されました
Quarkusはアプリケーションサーバーではなく、アプリケーションを構築するためのフレームワークです
デフォルトのコンテキストパスから/authが削除されました
カスタムプロバイダーのパッケージングとデプロイ方法が異なります
KubernetesおよびOpenShift用の新しいオペレーターとCRD
移行を行う前に、新しいディストリビューションのインストールと設定方法を理解するために、新しいサーバーガイドを読むことを強く推奨します。
WildFly版Keycloakディストリビューションは、複雑なXMLファイルを設定に使用しており、これらのファイルを操作するためにCLIツール（jboss-cli）が必要でした。これらのファイルはアップグレードにも複雑さをもたらし、以前のバージョンから設定をアップグレードするためにエラーが発生しやすいスクリプトが使用されていました。
新しいQuarkus搭載ディストリビューションは、代わりにシンプルな設定ファイルを利用し、対応するCLI引数と環境変数をオプションとして使用することで、Keycloakの設定が大幅に容易になりました。ただし、これにより、以前のディストリビューションから設定を自動的に移行することができなくなります。
新しいQuarkus搭載ディストリビューションに移行するための最初のステップは、レガシーディストリビューションに適用している設定変更を理解し、新しいサーバーガイドに従って、新しいディストリビューションに必要な設定を適用することです。
注意すべき点の1つは、新しいディストリビューションは設定に関してより意見が強く、より良いデフォルトを提供し、自分で設定する必要性を減らすことを目指していることです。ただし、常にバランスが取れているとは限らず、カバーされていないユースケースがあるかもしれません。
新しいディストリビューションで調整する必要があるものを設定できない場合は、GitHub Discussionsでディスカッションを開始してください。
新しいリリースが利用可能になるまでは、conf/quarkus.propertiesファイルを介してQuarkusレベルの設定を直接適用することで、新しいディストリビューションを設定することが可能です。Keycloakチームによってテストおよびサポートされていない設定を適用することになるため、これは控えめに使用することをお勧めします。
WildFlyとは異なり、Quarkusはアプリケーションサーバーではありません。アプリケーションサーバーはアプリケーションを動的にデプロイし、ランタイム時にメモリにロードされるものを変更できますが、Quarkusではこれは不可能です。
一方、Quarkusはコンテナに不変性、より高速な起動、およびより高い予測可能性をもたらします。
WildFlyディストリビューションでは、カスタムプロバイダーをホットデプロイしたり、データベースベンダーをランタイム設定として変更したりできましたが、これはもはやサポートされていません。
代わりに、Quarkusディストリビューションはランタイムを最適化する個別のビルドステップを提供します。ここで注意すべき重要な点の1つは、ビルドステップは実際にKeycloakソースをビルドするのではなく、拡張プロセスを通じてランタイムを最適化するだけであり、これは非常に高速で、ランタイムにロードされるものを完全に最適化できることです。
Keycloakのインストールの一部として、CIを通じて、またはベースのKeycloakイメージを拡張するカスタムコンテナイメージを作成することにより、このビルドステップを実行することをお勧めします。
ただし、Keycloakをこの点でWildFlyディストリビューションとほぼ同じように動作させる自動ビルドモードもあります。これには起動時間のペナルティが伴いますが、それでもWildFlyディストリビューションよりもランタイムをより適切に最適化できます。
Keycloak Wildflyディストリビューションには、Keycloakに初期ユーザーを追加するためのadd-user-keycloak.shという名前のスクリプトが含まれていました。これらはQuarkusディストリビューションには含まれなくなりました。
最初の管理者ユーザーを追加するには、ユーザーのユーザー名とパスワードに環境変数KC_BOOTSTRAP_ADMIN_USERNAMEとKC_BOOTSTRAP_ADMIN_PASSWORDを設定します。Keycloakは最初の起動時にこれらを使用して、管理者権限を持つ最初のユーザーを作成します。管理者権限を持つ最初のユーザーが存在したら、コマンドラインツールkcadm.sh（Linux）またはkcadm.bat（Windows）を使用して追加のユーザーを作成します。
デフォルトでは、新しいQuarkusディストリビューションはコンテキストパスから/authを削除します。/authを再導入するには、http-relative-pathビルドオプションを使用します。例:
bin/kc.[sh|bat] start-dev --http-relative-path /auth相対パスが指定されている場合でも、ルートから相対パスにリダイレクトすることが可能です。具体的には、ユーザーがlocalhost:8080/にアクセスすると、ページはlocalhost:8080/authにリダイレクトされます。
WildFlyディストリビューションと同様に、カスタムプロバイダーはデプロイメントディレクトリにコピーすることでKeycloakにデプロイされます。新しいディストリビューションでは、プロバイダーをstandalone/deploymentsではなくprovidersディレクトリにコピーする必要があります。standalone/deploymentsは存在しなくなりました。追加の依存関係もprovidersディレクトリにコピーされます。
新しいディストリビューションでは、カスタムプロバイダー用の個別のクラスパスがなくなったため、含める追加の依存関係にはより注意が必要になる場合があります。さらに、EARパッケージング形式とjboss-deployment-structure.xmlファイルはサポートされなくなりました。
WildFlyディストリビューションはカスタムプロバイダーを自動的に検出しましたが、Keycloakの実行中にカスタムプロバイダーをホットデプロイする機能もサポートしていましたが、これはもはやサポートされていません。providersディレクトリのプロバイダーまたは依存関係を変更する場合は、その後ビルドを実行するか、自動ビルド機能でサーバーを再起動する必要があります。
プロバイダーが使用するAPIによっては、プロバイダーにいくつかの変更を加える必要がある場合もあります。Keycloak SPIのクラスのみを利用している場合は必要ないはずですが、WildFlyの他のAPIを使用している場合は、いくつかの変更が必要になる場合があります。さらに、セッション/ステートレスBeanのようなJavaEE APIはサポートされなくなりました。
KubernetesおよびOpenShiftでQuarkusディストリビューションを使用するには、新しいオペレーターを使用する必要があります。古いオペレーターは新しいディストリビューションをサポートしていません。
「直接的な」移行パスはありません。新しいオペレーターを使用してKeycloakをインストールするには、新しいQuarkusディストリビューションに基づく新しいKeycloakデプロイメントを作成するために、新しいカスタムリソース（CR）を作成する必要があります。
古いオペレーターと新しいオペレーターは、CRDで異なるAPIGroupとバージョンを使用しているため、同じ名前空間でも共存できます。
古いオペレーターの場合、apiVersionは
apiVersion: keycloak.org/v1alpha1新しいオペレーターの場合、apiVersionは
apiVersion: k8s.keycloak.org/v2alpha1kubectlコマンドを使用し、2つのCRDがクラスターにインストールされている場合は、APIグループを含む完全修飾名を使用してください。例:
$ kubectl get keycloaks.k8s.keycloak.org新しいオペレーターは、クライアント、ユーザー、およびレルムCRDを直接サポートしていません。代わりに、レルムインポートを実行するための1つのCRDを提供します。この新しいCRを使用すると、レルムをラップすることでユーザー、クライアントなどをインポートできます。