Proxy Cache

古いプラグインバージョンのドキュメントを閲覧しています。

Looking for the plugin's configuration parameters? You can find them in the Proxy Cache configuration reference doc.

Proxy Cacheプラグインは、 Kong Gatewayのリバースプロキシキャッシュ実装を提供します。設定可能な応答コードとコンテンツタイプ、およびリクエスト方法に基づいて、応答エンティティをキャッシュします。コンシューマごと、またはサービスごとにキャッシュできます。

キャッシュエンティティは設定可能な期間保存され、その後、同じリソースにリクエストが送られるとリソースが再度取得され、保存されます。キャッシュエンティティは、有効期限が切れる前にAdmin APIを介して強制的に削除することもできます。

このプラグインの高度なバージョンもあり、Enterpriseサブスクリプションで利用できます。 Proxy Cache Advancedプラグインは、オープンソースのProxy CacheプラグインをRedisおよびRedis Sentinelのサポートで拡張します。

戦略

kong-plugin-proxy-cacheは、さまざまなバックエンド形式でのプロキシキャッシュデータの保存をサポートするように設計されています。現在、次の戦略が提供されています。

• memory：lua_shared_dict。デフォルトのディクショナリkong_db_cacheは、関連のないデータベースキャッシュエンティティを格納するために、Kongの他のプラグインや要素でも使用されることに注意してください。このディクショナリを使用するとプロキシキャッシュプラグインを簡単に起動できますが、大量に使用するとKongのデータベースキャッシュ操作の他の側面に圧力がかかるため、大規模なインストールにはお勧めしません。現時点では、カスタムのNginxテンプレートを使用して別のlua_shared_dictを定義することをお勧めします。

キャッシュキー

Kongは、リクエストメソッド、完全なクライアントリクエスト（リクエストパスやクエリパラメータなど）、およびリクエストに関連付けられたAPIまたはコンシューマのUUIDに基づいて、各キャッシュ要素にキーを設定します。これは、キャッシュがAPIやコンシューマ間で区別されることも意味します。現在、キャッシュキーの形式はハードコードされており、調整できません。内部的には、キャッシュキーは、構成部分を連結した16進数でエンコードされたMD5合計として表されます。これは次のように計算されます。

key = md5(UUID | method | request)

ここで、 methodは OpenRestyngx.req.get_method()呼び出しによって定義され、 requestは Nginx $request変数によって定義されます。Kongは、指定されたリクエストに関連付けられたキャッシュキーをX-Cache-Key応答ヘッダーとして返します。前述のように、特定のリクエストのキャッシュキーを事前に計算することも可能です。

キャッシュ制御

cache_control構成オプションを有効にすると、Kong はRFC7234で定義されている要求および応答の Cache-Control ヘッダーを尊重しますが、いくつかの例外があります。

• キャッシュの再検証はまだサポートされていないため、 proxy-revalidateなどのディレクティブは無視されます。
• 同様に、 no-cacheの動作は簡素化され、エンティティが完全にキャッシュされなくなります。
• Varyによるセカンダキーの計算はまだサポートされていません。

キャッシュステータス

Kongは、 X-Cache-Statusヘッダーを介してリクエストのプロキシキャッシュ動作のステータスを識別します。このヘッダーには、いくつかの値が考えられます。

• Miss：リクエストはキャッシュで満たされたものの、リソースのエントリがキャッシュに見つからなかったため、リクエストはアップストリームに転送されました。
• Hit：リクエストは満たされ、キャッシュから提供されました。
• Refresh：リソースはキャッシュ内に見つかりましたが、キャッシュコントロールの動作またはハードコードされたcache_ttlのしきい値に達したため、リクエストを満たすことができませんでした。
• Bypass：プラグインの設定に基づいて、キャッシュから要求を満たすことができませんでした。

ストレージTTL

Kongは、規定のcache_ttlまたはCache-Control値よりも長く、リソースエンティティをストレージエンジンに保存できます。そのため、Kongは有効期限を過ぎてもリソースのキャッシュされたコピーを保持することができます。これにより、max-ageとmax-staleのヘッダーを使用できるクライアントは、必要に応じてデータの古いコピーを要求できます。

アップストリームでの停止

Kongのコアリクエスト処理モデルの実装により、現時点では、アップストリームに到達できない場合にプロキシキャッシュプラグインを使用して古いキャッシュデータを提供することはできません。アップストリームに到達できない場合にエラーを返す代わりにKongがキャッシュデータを提供できるようにするために、古いデータをキャッシュ内に保持するために非常に大きなstorage_ttl（数時間または数日単位）を定義することをおすすめします。アップストリームが停止した場合、cache_ttlプラグインの構成値を増やすことで、古いデータが「新しい」とみなされる場合があります。そうすることで、Kongが障害の発生したアップストリームサービスへの接続を試みる前に、以前は古いとみなされていたデータがクライアントに提供されるようになります。

Admin API

このプラグインは、マネージド・キャッシュエンティティへのいくつかのエンドポイントを提供します。これらのエンドポイントは、proxy-cache RBACリソースに割り当てられます。

Admin APIには、キャッシュエンティティを調べてパージ（消去）するための次のエンドポイントが用意されています。

キャッシュエンティティを取得する

2つのエンドポイントが利用可能です。1つは既知のプラグインインスタンスを検索するためのもので、もう1つはすべてのプロキシキャッシュプラグインのデータストアで特定のキャッシュキーを検索するものです。両方のエンドポイントの返り値は同じです。

エンドポイント

エンドポイント

応答

キャッシュエンティティが存在する場合

HTTP 200 OK

指定されたキーを持つエンティティが存在しない場合

HTTP 400 Not Found

キャッシュエンティティを削除する

2つのエンドポイントが利用可能です。1つは既知のプラグインインスタンスを検索するためのもので、もう1つはすべてのプロキシキャッシュプラグインのデータストアで特定のキャッシュキーを検索するものです。両方のエンドポイントの返り値は同じです。

エンドポイント

エンドポイント

応答

キャッシュエンティティが存在する場合

HTTP 204 No Content

指定されたキーを持つエンティティが存在しない場合

HTTP 400 Not Found

すべてのキャッシュエンティティをパージ（消去）する

エンドポイント

応答

HTTP 204 No Content

このエンドポイントは、全proxy-cacheプラグインのキャッシュエンティティすべてがパージ（消去）されるので注意してください。