10.2. キャッシュを設定する

次のデータは、ローカルキャッシュを使用して、クラスター内の各ノードのローカルに保持されます。

レルム、ユーザー、認可のローカルキャッシュは、デフォルトで最大 10,000 エントリーを保持するように設定されています。デフォルトで、ローカルキーキャッシュは最大 1,000 エントリーを保持でき、1 時間ごとに期限切れになります。したがって、外部クライアントまたはアイデンティティープロバイダーからキーを定期的にダウンロードする必要があります。

最適な実行時間を実現し、データベースへの追加のラウンドトリップを回避するには、各キャッシュの設定で、エントリーの最大数がデータベースのサイズと一致していることを確認する必要があります。キャッシュできるエントリーが増えると、サーバーがデータベースからデータを取得しなければならない回数が少なくなります。メモリーの使用率とパフォーマンスの間で何が犠牲になるかを評価する必要があります。

1 つの Red Hat build of Keycloak ノードが共有データベース内のデータを更新すると、他のすべてのノードはそれを認識する必要があるため、キャッシュからそのデータを無効にします。

work キャッシュはレプリケートされたキャッシュであり、これらの無効化メッセージの送信に使用されます。このキャッシュのエントリー/メッセージは有効期限が非常に短いため、このキャッシュのサイズが時間の経過とともに増加することを想定する必要はありません。

authenticationSessions 分散キャッシュは、認証プロセス中に、認証セッションとそれに関連する他のデータを保存するために使用されます。

分散可能キャッシュに依存すると、クラスター内のどのノードでも認証セッションを利用できるため、ユーザーは認証状態を失うことなく任意のノードにリダイレクトできます。ただし、実稼働環境に対応したデプロイメントでは、常にセッションアフィニティーを考慮し、セッションが最初に作成されたノードにユーザーをリダイレクトすることを優先する必要があります。これにより、ノード間の不要な状態遷移が回避され、CPU、メモリー、ネットワークの使用率が向上します。

ユーザーセッションとクライアントセッションは、ユーザーがログアウトを実行するとき、クライアントがトークンの取り消しを実行するとき、または有効期限に達したときに自動的に破棄されます。

セッションデータは、デフォルトでデータベースに保存され、以下のキャッシュにオンデマンドでロードされます。

分散可能なキャッシュに依存することで、キャッシュされたユーザーおよびクライアントセッションはクラスター内のノードで利用できます。これにより、ユーザーはデータベースからセッションデータをロードせずに任意のノードにリダイレクトされます。ただし、実稼働環境に対応したデプロイメントでは、常にセッションアフィニティーを考慮し、セッションが最初に作成されたノードにユーザーをリダイレクトすることを優先する必要があります。これにより、ノード間の不要な状態遷移が回避され、CPU、メモリー、ネットワークの使用率が向上します。

ユーザーセッションおよびクライアントセッションのこれらのインメモリーキャッシュは、デフォルトでノードごとに 10000 エントリーに制限されるため、大規模なインストールの場合、Red Hat build of Keycloak の全体的なメモリー使用量が減少します。内部キャッシュは、キャッシュエントリーごとに 1 人の所有者のみで実行されます。メモリー消費とデータベース使用状況間のトレードオフを検討し、キャッシュのさまざまなサイズを設定する、Red Hat ビルドの Keycloak のキャッシュ設定ファイル(conf/cache-ispn.xml)を編集して、それらのキャッシュの < memory max-count="..."/> を設定するようにしてください。

このセットアップのすべてのセッションはインメモリーに保存されるため、次の 2 つの副次的な影響があります。* すべての Keycloak ノードでセッションを取得する * すべての Keycloak ノードの再起動 * 増加するメモリー消費

このセットアップを有効にするには、次の手順に従います。

次のキャッシュは、オフラインセッションを保存するために使用されます。

通常のユーザーおよびクライアントセッションキャッシュと同様に、オフラインユーザーおよびクライアントセッションキャッシュも、デフォルトではノードごとに 10000 エントリーに制限されます。メモリーからエビクトされた項目は、必要に応じてデータベースからオンデマンドでロードされます。メモリー消費とデータベース使用状況間のトレードオフを検討し、キャッシュのさまざまなサイズを設定する、Red Hat ビルドの Keycloak のキャッシュ設定ファイル(conf/cache-ispn.xml)を編集して、それらのキャッシュの < memory max-count="..."/> を設定するようにしてください。

メモリー使用量を減らすために、特定のキャッシュに保存されているエントリー数の上限を配置することができます。キャッシュの上限を指定するには、以下のコマンドライン引数 --cache-embedded-${CACHE_NAME}-max-count=, に ${CACHE_NAME} を上限を適用するキャッシュの名前に置き換える必要があります。たとえば、上限 1000 を offlineSessions キャッシュに適用するには、configure --cache-embedded-offline-sessions-max-count=1000 を設定します。上限は、actionToken、authenticationSessions、loginFailures、work のキャッシュでは定義できません。

分散キャッシュは、クラスター内のノードのサブセットでキャッシュエントリーをレプリケートし、エントリーを固定所有者ノードに割り当てます。

データの信頼できる主要なソース(authenticationSessions、loginFailures、actionTokens)の各分散キャッシュには、デフォルトで 2 所有者があります。つまり、2 つのノードには特定のキャッシュエントリーのコピーがあります。非所有者ノードは、データを取得するために、特定のキャッシュの所有者にクエリーを実行します。両方の所有者ノードがオフラインになると、すべてのデータが失われます。

デフォルトの所有者数は、3 つ以上のノードを持つクラスターセットアップで 1 つのノード (所有者) で障害が発生しても継続できる数です。所有者の数は、可用性要件に合わせて自由に変更できます。所有者の数を変更するには、conf/cache-ispn.xml を開き、分散キャッシュの owner=<value> 値を任意の値に変更します。

独自のキャッシュ設定ファイルを指定するには、次のコマンドを入力します。

bin/kc.[sh|bat] start --cache-config-file=my-cache-file.xml

設定ファイルは conf/ ディレクトリーに相対的です。

高可用性用およびマルチノードのクラスター化セットアップ用に Red Hat build of Keycloak サーバーを設定するために、CLI オプション cache-remote-host、cache-remote-port、cache-remote-username、cache-remote-password が導入され、XML ファイル内の設定が簡素化されました。上記の CLI パラメーターのいずれかが存在する場合、XML ファイル内にリモートストアに関連する設定が存在しないしないものと想定されます。