Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

Proxy Caching Advanced

This plugin provides a reverse proxy cache implementation for Kong. It caches response entities based on configurable response code and content type, as well as request method. It can cache per-Consumer or per-API. Cache entities are stored for a configurable period of time, after which subsequent requests to the same resource will re-fetch and re-store the resource. Cache entities can also be forcefully purged via the Admin API prior to their expiration time.

Configuration Reference

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

  • Setting a target's health status in the load balancer
  • Validating configurations against schemas
  • Uploading the declarative configuration using the /config endpoint

Enable the plugin on a service

For example, configure this plugin on a service by making the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=proxy-cache-advanced"  \
    --data "config.response_code=200" \
    --data "config.request_method=GET" \
    --data "config.request_method=HEAD" \
    --data "config.content_type=text/plain" \
    --data "config.content_type=application/json" \
    --data "config.cache_control=false" \
    --data "config.strategy=memory" \
    --data "config.memory.dictionary_name=kong_db_cache"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <proxy-cache-advanced-example>
config: 
  response_code:
  - 200
  request_method:
  - GET
  - HEAD
  content_type:
  - text/plain
  - application/json
  cache_control: false
  strategy: memory
  memory.dictionary_name: kong_db_cache
plugin: proxy-cache-advanced

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <proxy-cache-advanced-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

plugins:
- name: proxy-cache-advanced
  service: {SERVICE}
  config: 
    response_code:
    - 200
    request_method:
    - GET
    - HEAD
    content_type:
    - text/plain
    - application/json
    cache_control: false
    strategy: memory
    memory.dictionary_name: kong_db_cache

SERVICE is the id or name of the service that this plugin configuration will target.

Configure this plugin on a service:

  1. In Konnect Cloud, select the service on the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Scroll down to Plugins and click New Plugin.
  4. Find and select the Proxy Caching Advanced plugin.

  5. Enter the following parameters, updating the default or sample values as needed:

    • Config.Response Code: 200
    • Config.Request Method: GET
    • Config.Request Method: HEAD
    • Config.Content Type: text/plain
    • Config.Content Type: application/json
    • Config.Cache Control: false
    • Config.Strategy: memory
    • Config.Memory.dictionary Name: kong_db_cache
  6. Click Create.

Configure this plugin on a service:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.

  4. Find and select the Proxy Caching Advanced plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already prefilled.

  7. Enter the following parameters, updating the default or sample values as needed:

    • Config.Response Code: 200
    • Config.Request Method: GET
    • Config.Request Method: HEAD
    • Config.Content Type: text/plain
    • Config.Content Type: application/json
    • Config.Cache Control: false
    • Config.Strategy: memory
    • Config.Memory.dictionary Name: kong_db_cache
  8. Click Create.

Enable the plugin on a route

For example, configure this plugin on a route with:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=proxy-cache-advanced"  \
    --data "config.response_code=200" \
    --data "config.request_method=GET" \
    --data "config.request_method=HEAD" \
    --data "config.content_type=text/plain" \
    --data "config.content_type=application/json" \
    --data "config.cache_control=false" \
    --data "config.strategy=memory" \
    --data "config.memory.dictionary_name=kong_db_cache"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <proxy-cache-advanced-example>
config: 
  response_code:
  - 200
  request_method:
  - GET
  - HEAD
  content_type:
  - text/plain
  - application/json
  cache_control: false
  strategy: memory
  memory.dictionary_name: kong_db_cache
plugin: proxy-cache-advanced

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <proxy-cache-advanced-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

plugins:
- name: proxy-cache-advanced
  route: <route>
  config: 
    response_code:
    - 200
    request_method:
    - GET
    - HEAD
    content_type:
    - text/plain
    - application/json
    cache_control: false
    strategy: memory
    memory.dictionary_name: kong_db_cache

ROUTE is the id or name of the route that this plugin configuration will target.

Configure this plugin on a route:

  1. In Konnect Cloud, select the service from the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Select the route.
  4. Scroll down to Plugins and click Add Plugin.
  5. Find and select the Proxy Caching Advanced plugin.

  6. Enter the following parameters, updating the default or sample values as needed:

    • Config.Response Code: 200
    • Config.Request Method: GET
    • Config.Request Method: HEAD
    • Config.Content Type: text/plain
    • Config.Content Type: application/json
    • Config.Cache Control: false
    • Config.Strategy: memory
    • Config.Memory.dictionary Name: kong_db_cache
  7. Click Create.

Configure this plugin on a route:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.

  5. Find and select the Proxy Caching Advanced plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Scoped.
  7. Add the Route ID if it is not already prefilled.

  8. Enter the following parameters, updating the default or sample values as needed:

    • Config.Response Code: 200
    • Config.Request Method: GET
    • Config.Request Method: HEAD
    • Config.Content Type: text/plain
    • Config.Content Type: application/json
    • Config.Cache Control: false
    • Config.Strategy: memory
    • Config.Memory.dictionary Name: kong_db_cache
  9. Click Create.

Enabling the plugin on a consumer

For example, configure this plugin on a consumer with:

$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
    --data "name=proxy-cache-advanced"  \
    --data "config.response_code=200" \
    --data "config.request_method=GET" \
    --data "config.request_method=HEAD" \
    --data "config.content_type=text/plain" \
    --data "config.content_type=application/json" \
    --data "config.cache_control=false" \
    --data "config.strategy=memory" \
    --data "config.memory.dictionary_name=kong_db_cache"

CONSUMER is the id or username of the consumer that this plugin configuration will target.

You can combine consumer.id, service.id, or route.id in the same request, to further narrow the scope of the plugin.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <proxy-cache-advanced-example>
config: 
  response_code:
  - 200
  request_method:
  - GET
  - HEAD
  content_type:
  - text/plain
  - application/json
  cache_control: false
  strategy: memory
  memory.dictionary_name: kong_db_cache
plugin: proxy-cache-advanced

Then, apply it to a consumer by annotating the KongConsumer resource as follows:

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: {CONSUMER}
  annotations:
    konghq.com/plugins: <proxy-cache-advanced-example>
    kubernetes.io/ingress.class: kong

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any Service, Consumer, or Route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a consumer by adding this section to your declarative configuration file:

plugins:
- name: proxy-cache-advanced
  consumer: {CONSUMER}
  config: 
    response_code:
    - 200
    request_method:
    - GET
    - HEAD
    content_type:
    - text/plain
    - application/json
    cache_control: false
    strategy: memory
    memory.dictionary_name: kong_db_cache

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Configure this plugin on a consumer:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Consumers and click View for the consumer row.
  3. Select the Plugins tab.
  4. Click Add Plugin.

  5. Find and select the Proxy Caching Advanced plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Global.

  7. Enter the following parameters, updating the default or sample values as needed:

    • Config.Response Code: 200
    • Config.Request Method: GET
    • Config.Request Method: HEAD
    • Config.Content Type: text/plain
    • Config.Content Type: application/json
    • Config.Cache Control: false
    • Config.Strategy: memory
    • Config.Memory.dictionary Name: kong_db_cache
  8. Click Create.

Enable the plugin globally

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=proxy-cache-advanced"  \
    --data "config.response_code=200" \
    --data "config.request_method=GET" \
    --data "config.request_method=HEAD" \
    --data "config.content_type=text/plain" \
    --data "config.content_type=application/json" \
    --data "config.cache_control=false" \
    --data "config.strategy=memory" \
    --data "config.memory.dictionary_name=kong_db_cache"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-proxy-cache-advanced>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  response_code:
  - 200
  request_method:
  - GET
  - HEAD
  content_type:
  - text/plain
  - application/json
  cache_control: false
  strategy: memory
  memory.dictionary_name: kong_db_cache
plugin: proxy-cache-advanced

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: proxy-cache-advanced
  config: 
    response_code:
    - 200
    request_method:
    - GET
    - HEAD
    content_type:
    - text/plain
    - application/json
    cache_control: false
    strategy: memory
    memory.dictionary_name: kong_db_cache

Configure this plugin globally:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. Find and select the Proxy Caching Advanced plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, set the plugin scope to Global.

  6. Enter the following parameters, updating the default/sample values as needed:

    • Config.Response Code: 200
    • Config.Request Method: GET
    • Config.Request Method: HEAD
    • Config.Content Type: text/plain
    • Config.Content Type: application/json
    • Config.Cache Control: false
    • Config.Strategy: memory
    • Config.Memory.dictionary Name: kong_db_cache
  7. Click Create.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter Description
name
required

Type: string		 The name of the plugin, in this case proxy-cache-advanced.
service.id

Type: string		 The ID of the Service the plugin targets.
route.id

Type: string		 The ID of the Route the plugin targets.
consumer.id

Type: string		 The ID of the Consumer the plugin targets.
enabled
required

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.response_code
required

Type: array of type integer

Default value: 200, 301, 404

Upstream response status code considered cacheable. The integers must be a value between 100 and 900.
config.request_method
required

Type: array of string elements

Default value: ["GET","HEAD"]

Downstream request methods considered cacheable. Available options: HEAD, GET, POST, PATCH, PUT.
config.content_type
required

Type: array of string elements

Default value: text/plain, application/json

Upstream response content types considered cacheable. The plugin performs an exact match against each specified value; for example, if the upstream is expected to respond with a application/json; charset=utf-8 content-type, the plugin configuration must contain said value or a Bypass cache status is returned.
config.vary_headers
optional

Type: array of string elements

Relevant headers considered for the cache key. If undefined, none of the headers are taken into consideration.
config.vary_query_params
optional

Type: array of string elements

Relevant query parameters considered for the cache key. If undefined, all params are taken into consideration.
config.cache_ttl

Type: integer

Default value: 300

TTL in seconds of cache entities.
config.cache_control
required

Type: boolean

Default value: false

When enabled, respect the Cache-Control behaviors defined in RFC7234.
config.storage_ttl
optional

Type: integer

Number of seconds to keep resources in the storage backend. This value is independent of cache_ttl or resource TTLs defined by Cache-Control behaviors.
config.strategy
required

Type: string

The backing data store in which to hold cache entities. Accepted values are: memory and redis.
config.memory.dictionary_name
required

Type: string

Default value: kong_db_cache

The name of the shared dictionary in which to hold cache entities when the memory strategy is selected. Note that this dictionary currently must be defined manually in the Kong Nginx template.
config.redis.host
semi-optional

Type: string

Host to use for Redis connection when the redis strategy is defined.
config.redis.port
semi-optional

Type: integer

Default value: 6379

Port to use for Redis connections when the redis strategy is defined. Must be a value between 0 and 65535. Default: 6379.
config.redis.ssl
optional

Type: boolean

Default value: false

If set to true, then uses SSL to connect to Redis.

Note: This parameter is only available for Kong Gateway versions 2.2.x and later.
config.redis.ssl_verify
optional

Type: boolean

Default value: false

If set to true, then verifies the validity of the server SSL certificate. Note that you need to configure the lua_ssl_trusted_certificate to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

Note: This parameter is only available for Kong Gateway versions 2.2.x and later.
config.redis.server_name
optional

Type: string

Specifies the server name for the new TLS extension Server Name Indication (SNI) when connecting over SSL.

Note: This parameter is only available for Kong Gateway versions 2.2.x and later.
config.redis.timeout
semi-optional

Type: number

Default value: 2000

Connection timeout to use for Redis connection when the redis strategy is defined.
config.redis.password
semi-optional

Type: string

Password to use for Redis connection when the redis strategy is defined. If undefined, no AUTH commands are sent to Redis.

This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
config.redis.database
semi-optional

Type: integer

Default value: 0

Database to use for Redis connection when the redis strategy is defined.
config.redis.sentinel_master
semi-optional

Type: string

Sentinel master to use for Redis connection when the redis strategy is defined. Defining this value implies using Redis Sentinel.
config.redis.sentinel_username
semi-optional

Type: string

Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication will not be performed. This requires Redis v6.2.0+.

This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
config.redis.sentinel_password
semi-optional

Type: string

Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.

This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format.
config.redis.sentinel_role
semi-optional

Type: string

Sentinel role to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel. Available options: master, slave, any.
config.redis.sentinel_addresses
semi-optional

Type: array of string elements

Sentinel addresses to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel. Each string element must be a hostname. The minimum length of the array is 1 element.
config.redis.cluster_addresses
semi-optional

Type: array of string elements

Cluster addresses to use for Redis connection when the redis strategy is defined. Defining this value implies using Redis cluster. Each string element must be a hostname. The minimum length of the array is 1 element.
config.redis.keepalive_backlog
optional

Type: integer

If specified, limits the total number of opened connections for a pool. If the connection pool is full, all connection queues beyond the maximum limit go into the backlog queue. Once the backlog queue is full, subsequent connect operations will fail and return nil. Queued connect operations resume once the number of connections in the pool is less than keepalive_pool_size. Note that queued connect operations are subject to set timeouts.
config.redis.keepalive_pool
optional

Type: string

Default value: generated from string template

The custom name of the connection pool. If not specified, the connection pool name is generated from the string template "<host>:<port>" or "<unix-socket-path>".
config.redis.keepalive_pool_size
optional

Type: integer

Default value: 30

The size limit for every cosocket connection pool associated with every remote server, per worker process. If no keepalive_pool_size is specified and no keepalive_backlog is specified, no pool is created. If no keepalive_pool_size is specified and keepalive_backlog is specified, then the pool uses the default value 30.
config.bypass_on_err
optional

Type: boolean

Default value: false

Unhandled errors while trying to retrieve a cache entry (such as redis down) are resolved with Bypass, with the request going upstream.
Warning: The content_type parameter requires an exact match. For example, if your Upstream expects application/json; charset=utf-8 and the config.content_type value is only application/json (a partial match), then the proxy cache is bypassed.

Strategies

kong-plugin-enterprise-proxy-cache is designed to support storing proxy cache data in different backend formats. Currently, the following strategies are provided:

  • memory: A lua_shared_dict. Note that the default dictionary, kong_db_cache, is also used by other plugins and elements of Kong to store unrelated database cache entities. Using this dictionary is an easy way to bootstrap the proxy-cache-advanced plugin, but it is not recommended for large-scale installations as significant usage will put pressure on other facets of Kong’s database caching operations. It is recommended to define a separate lua_shared_dict via a custom Nginx template at this time.
  • redis: Supports Redis and Redis Sentinel deployments.

Cache Key

Kong keys each cache elements based on the request method, the full client request (e.g., the request path and query parameters), and the UUID of either the API or Consumer associated with the request. This also implies that caches are distinct between APIs and/or Consumers. Currently the cache key format is hard-coded and cannot be adjusted. Internally, cache keys are represented as a hexadecimal-encoded MD5 sum of the concatenation of the constituent parts calculated as follows:

key = md5(UUID | method | request)

Where method is defined via the OpenResty ngx.req.get_method() call, and request is defined via the Nginx $request variable. Kong will return the cache key associated with a given request as the X-Cache-Key response header. It is also possible to precalculate the cache key for a given request as noted above.

Cache Control

When the cache_control configuration option is enabled, Kong will respect request and response Cache-Control headers as defined by RFC7234, with a few exceptions:

  • Cache revalidation is not yet supported, and so directives such as proxy-revalidate are ignored.
  • Similarly, the behavior of no-cache is simplified to exclude the entity from being cached entirely.
  • Secondary key calculation via Vary is not yet supported.

Cache Status

Kong identifies the status of the request’s proxy cache behavior via the X-Cache-Status header. There are several possible values for this header:

  • Miss: The request could be satisfied in cache, but an entry for the resource was not found in cache, and the request was proxied upstream.
  • Hit: The request was satisfied and served from cache.
  • Refresh: The resource was found in cache, but could not satisfy the request, due to Cache-Control behaviors or reaching its hard-coded cache_ttl threshold.
  • Bypass: The request could not be satisfied from cache based on plugin configuration.

Storage TTL

Kong can store resource entities in the storage engine longer than the prescribed cache_ttl or Cache-Control values indicate. This allows Kong to maintain a cached copy of a resource past its expiration, which in turn allows clients capable of using max-age and max-stale headers to request stale copies of data if necessary.

Upstream Outages

Due to an implementation in Kong’s core request processing model, at this point, the proxy-cache-advanced plugin cannot be used to serve stale cache data when an upstream is unreachable. To equip Kong to serve cache data in place of returning an error when an upstream is unreachable, we recommend defining a very large storage_ttl (on the order of hours or days) in order to keep stale data in the cache. In the event of an upstream outage, stale data can be considered fresh by increasing the cache_ttl plugin configuration value. By doing so, data that would have previously been considered stale is now served to the client, before Kong attempts to connect to a failed upstream service.

Admin API

This plugin provides several endpoints to managed cache entities. These endpoints are assigned to the proxy-cache-advanced RBAC resource.

The following endpoints are provided on the Admin API to examine and purge cache entities:

Retrieve a Cache Entity

Two separate endpoints are available: one to look up a known plugin instance, and another that searches all proxy-cache-advanced plugins data stores for the given cache key. Both endpoints have the same return value.

Endpoint

/proxy-cache-advanced/:plugin_id/caches/:cache_id
Attributes Description
plugin_id The UUID of the proxy-cache-advanced plugin
cache_id The cache entity key as reported by the X-Cache-Key response header

Endpoint

/proxy-cache-advanced/:cache_id
Attributes Description
cache_id The cache entity key as reported by the X-Cache-Key response header

Response

If the cache entity exists

HTTP 200 OK

If the entity with the given key does not exist

HTTP 400 Not Found

Delete a Cache Entity

Two separate endpoints are available: one to look up a known plugin instance, and another that searches all proxy-cache-advanced plugins data stores for the given cache key. Both endpoints have the same return value.

Endpoint

/proxy-cache-advanced/:plugin_id/caches/:cache_id
Attributes Description
plugin_id The UUID of the proxy-cache-advanced plugin
cache_id The cache entity key as reported by the X-Cache-Key response header

Endpoint

/proxy-cache-advanced/:cache_id
Attributes Description
cache_id he cache entity key as reported by the X-Cache-Key response header

Response

If the cache entity exists:

HTTP 204 No Content

If the entity with the given key does not exist:

HTTP 400 Not Found

Purge All Cache Entities

Endpoint

/proxy-cache-advanced/

Response

HTTP 204 No Content

Note that this endpoint purges all cache entities across all proxy-cache-advanced plugins.

Changelog

Kong Gateway 2.8.x (plugin version 0.5.7)

  • Added the redis.sentinel_username and redis.sentinel_password configuration parameters.

  • The redis.password, redis.sentinel_username, and redis.sentinel_password configuration fields are now marked as referenceable, which means they can be securely stored as secrets in a vault. References must follow a specific format.

  • Fixed plugin versions in the documentation. Previously, the plugin versions were labelled as 1.3-x and 2.2.x. They are now updated to align with the plugin’s actual versions, 0.4.x and 0.5.x.