bin/kc.[sh|bat] update-compatibility metadata --file=/path/to/file.json機能の有効化/無効化、またはKeycloakのバージョン、設定、プロバイダー、およびテーマを変更する際に、ローリングアップデート戦略を使用してデプロイメントをアップデートできるかどうかを判断するには、アップデート互換性コマンドを使用します。結果は、ローリングアップデートが可能かどうか、または再作成アップデートが必要かどうかを示します。
現在のバージョンでは、古いバージョンと新しいバージョンでKeycloakのバージョンが同じ場合に、ローリングアップデートが可能であることが示されています。将来のバージョンのKeycloakでは、ローリングアップデートが可能かどうかを判断するために、設定、イメージ、およびバージョンからの追加情報を使用するように動作が変更される可能性があります。
これは完全にスクリプト化可能であるため、アップデート手順では、実行された変更に応じてローリングまたは再作成戦略を実行するためにその情報を使用できます。また、GitOpsフレンドリーでもあり、以前の設定のメタデータをファイルに保存できます。新しい設定とともにCI/CDパイプラインでこのファイルを使用して、ローリングアップデートが可能かどうか、または再作成アップデートが必要かどうかを判断します。
Keycloak Operatorを使用している場合は、ローリングアップデートによるダウンタイムの回避ガイドとAuto戦略に進んで、詳細を確認してください。
このガイドでは、ローリングアップデートとは、少なくとも2つのノードで構成されるデプロイメントでダウンタイムなしで実行できるアップデートのことです。Keycloakを1つずつアップデートします。古いデプロイメントノードの1つをシャットダウンし、新しいデプロイメントノードを起動します。新しいノードの起動プローブが成功を返すまで待ってから、次のKeycloakノードに進みます。起動プローブの有効化と使用方法の詳細については、ヘルスチェックによるインスタンスステータスの追跡ガイドを参照してください。
再作成アップデートはダウンタイムなしとは互換性がなく、適用するにはダウンタイムが必要です。新しいバージョンでノードを起動する前に、古いバージョンを実行しているクラスターのすべてのノードをシャットダウンします。
ローリングアップデートが可能かどうかを判断するには、アップデート互換性コマンドを実行します。
古い設定で必要なメタデータを生成します。
新しい設定でメタデータをチェックして、アップデート戦略を決定します。
|
このコマンドは現在、限定的な機能のみを提供しています。現時点では、ローリングアップデートが可能かどうかを判断するために、Keycloakのバージョンと埋め込まれたInfinispanのバージョンのみを考慮しています。これらが変更されていない場合、ローリングアップデートが可能であると報告します。 現在のバージョンでは、設定変更はまだ検証されておらず、すべての設定変更がローリングアップデートの対象であると想定しています。カスタム拡張機能とテーマの変更にも同じことが当てはまります。 これを使用する良いユースケースは、たとえば、Keycloakのテーマまたはカスタム拡張機能を変更するときにローリングアップデートを実行し、Keycloakのバージョンが変更された場合にのみ再作成アップデートを実行したい場合などです。これはまだローリングアップデートを許可していません。 これらのコマンドの利用者は、今日存在する制限事項を知っておく必要がありますが、内部の動作やメタデータファイルの構造に依存すべきではありません。代わりに、ローリングアップデートが可能かどうかを判断するための内部ロジックの将来の機能強化から恩恵を受けるために、 |
メタデータを生成するには、同じKeycloakバージョンと設定オプションを使用して次のコマンドを実行します。
bin/kc.[sh|bat] update-compatibility metadata --file=/path/to/file.jsonこのコマンドは、startコマンドで使用されるすべてのオプションを受け入れます。コマンドは、デバッグ目的で、メタデータをJSON形式でコンソールに表示します。--fileパラメーターを使用すると、メタデータをファイルに保存できます。このファイルを後続のcheckコマンドで使用します。
|
環境変数またはCLI引数を介して設定されているかどうかにかかわらず、上記コマンドを実行するときにすべての設定オプションが含まれていることを確認してください。 いずれかの設定オプションを省略すると、メタデータが不完全になり、次のステップで誤った結果が報告される可能性があります。 |
このコマンドは、前のコマンドで生成されたメタデータをチェックし、現在の設定およびKeycloakバージョンと比較します。新しいKeycloakバージョンにアップグレードする場合は、このコマンドを新しいバージョンで実行する必要があります。
bin/kc.[sh|bat] update-compatibility check --file=/path/to/file.json
これらの要件を満たせない場合、不正な結果になります。 |
コマンドは結果をコンソールに出力します。たとえば、ローリングアップデートが可能な場合は、次のように表示されます。
[OK] Rolling Update is available.ローリングアップデートが不可能な場合、コマンドは非互換性に関する詳細を提供します。
[keycloak] Rolling Update is not available. 'keycloak.version' is incompatible: 26.2.0 -> 26.2.1 (1)| 1 | この例では、Keycloakバージョン26.2.0はバージョン26.2.1と互換性がなく、ローリングアップデートは不可能です。 |
コマンド終了コード
自動化パイプラインでアップデートタイプを決定するために、コマンドの終了コードを使用します。
| 終了コード | 説明 |
|---|---|
|
ローリングアップデートは可能です。 |
|
予期しないエラーが発生しました（メタデータファイルが見つからないか破損しているなど）。 |
|
無効なCLIオプション。 |
|
ローリングアップデートは不可能です。新しい設定を適用する前に、デプロイメントをシャットダウンする必要があります。 |
|
ローリングアップデートは不可能です。機能 |
Keycloak Operatorは、ローリングアップデートが可能かどうかを判断するために、上記で説明した機能を使用します。詳細については、ローリングアップデートによるダウンタイムの回避ガイドとAuto戦略を参照してください。