This plugin provides a reverse GraphQL proxy cache implementation for Kong. It caches response entities based on
configuration. It can cache by GraphQL query or vary headers. 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
Example plugin configuration
Enable on a service
Enable on a route
Enable globally
The following examples provide some typical configurations for enabling
the graphql-proxy-cache-advanced
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=graphql-proxy-cache-advanced" \
--data "config.strategy=memory"
Replace SERVICE_NAME|SERVICE_ID
with 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: graphql-proxy-cache-advanced-example
config:
strategy: memory
plugin: graphql-proxy-cache-advanced
Next, apply the KongPlugin resource to a
service by annotating the
service as follows:
apiVersion: v1
kind: Service
metadata:
name: SERVICE_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: graphql-proxy-cache-advanced-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with 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
.
Add this section to your declarative configuration file:
plugins:
- name: graphql-proxy-cache-advanced
service: SERVICE_NAME|SERVICE_ID
config:
strategy: memory
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
You can configure this plugin through the Konnect UI.
From the
Service Hub, select a service version, then set up the plugin:
- In the Plugins section, click Add Plugin.
- Find and select the GraphQL Proxy Caching Advanced plugin.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Click Create.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Services section, click View for the
service row.
- From the plugin section, click Add Plugin.
- Find and select the GraphQL Proxy Caching Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already pre-filled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Click Create.
The following examples provide some typical configurations for enabling
the graphql-proxy-cache-advanced
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=graphql-proxy-cache-advanced" \
--data "config.strategy=memory"
Replace ROUTE_NAME|ROUTE_ID
with 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: graphql-proxy-cache-advanced-example
config:
strategy: memory
plugin: graphql-proxy-cache-advanced
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: graphql-proxy-cache-advanced-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
service:
name: echo
port:
number: 80
Replace ROUTE_NAME|ROUTE_ID
with 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
.
Add this section to your declarative configuration file:
plugins:
- name: graphql-proxy-cache-advanced
route: ROUTE_NAME
config:
strategy: memory
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
You can configure this plugin through the Konnect UI.
From the
Service Hub, select a service version, then set up the plugin:
- Select a route.
- In the Plugins section, click Add Plugin.
- Find and select the GraphQL Proxy Caching Advanced plugin.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Click Create.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Routes from the menu, then click View for the
route row.
- From the plugin section, click Add Plugin.
- Find and select the GraphQL Proxy Caching Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the route ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Click Create.
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.
The following examples provide some typical configurations for enabling
the graphql-proxy-cache-advanced
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/plugins/ \
--data "name=graphql-proxy-cache-advanced" \
--data "config.strategy=memory"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-graphql-proxy-cache-advanced>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
strategy: memory
plugin: graphql-proxy-cache-advanced
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: graphql-proxy-cache-advanced
config:
strategy: memory
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Plugins from the menu, then click New Plugin.
- Find and select the GraphQL Proxy Caching Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, set the plugin scope to Global.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- 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 graphql-proxy-cache-advanced . |
service.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
Type: boolean
Default value: true |
Whether this plugin will be applied. |
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.cache_ttl
Type: integer
Default value: 300
|
TTL in seconds of cache entities. Must be a value greater than 0.
|
config.strategy
required
Type: string
Default value: memory
|
The backing data store in which to hold cached entities. Accepted value is memory .
|
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.
|
Strategies
GraphQL Proxy Caching Advanced Plugin is designed to support storing GraphQL 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
graphql-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.
Cache Key
Kong keys each cache elements based on the GraphQL query that is being send
in the HTTP request body. Internally, cache keys are represented as a
hexadecimal-encoded MD5 sum of the concatenation of the constituent parts.
key = md5(UUID | headers | body)
Where headers
contains the headers defined in vary_headers. vary_headers
defaults to NONE.
Kong will return the cache key associated with a given request as the
X-Cache-Key
response header.
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.
Admin API
This plugin provides several endpoints to managed cache entities. These endpoints are assigned to the graphql-proxy-cache-advanced
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
graphql-proxy-cache-advanced plugins data stores for the given cache key. Both endpoints have the same return value.
Endpoint
/graphql-proxy-cache-advanced/:plugin_id/caches/:cache_id
Attributes |
Description |
plugin_id |
The UUID of the graphql-proxy-cache-advanced plugin |
cache_id |
The cache entity key as reported by the X-Cache-Key response header |
Endpoint
/graphql-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
If the entity with the given key does not exist
Delete Cache Entity
Two separate endpoints are available: one to look up a known plugin instance, and another that searches all graphql-proxy-cache-advanced
plugins data stores for the given cache key. Both endpoints have the same return value.
Endpoint
/graphql-proxy-cache-advanced/:plugin_id/caches/:cache_id
Attributes |
Description |
plugin_id |
The UUID of the graphql-proxy-cache-advanced plugin |
cache_id |
The cache entity key as reported by the X-Cache-Key response header |
Endpoint
/graphql-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
If the entity with the given key does not exist
Purge All Cache Entities
Endpoint
/graphql-proxy-cache-advanced/
Response
Note that this endpoint purges all cache entities across all graphql-proxy-cache-advanced
plugins.