Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Supported Installation Options
      • Supported Linux Distributions
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.1.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • FIPS 140-2
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • File Permissions Reference
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Cache Time To Live (TTL)
  • Prerequisites
  • Global proxy caching
  • Service level proxy caching
  • Route level proxy caching
  • Consumer level proxy caching
Kong Gateway
3.1.x
  • Home
  • Kong Gateway
  • Get Started
  • Proxy Caching
You are browsing documentation for an outdated version. See the latest documentation here.

Proxy Caching

One of the ways Kong delivers performance is through caching. The Proxy Cache plugin accelerates performance by caching responses based on configurable response codes, content types, and request methods. When caching is enabled, upstream services are not bogged down with repetitive requests, because Kong Gateway responds on their behalf with cached results. Caching can be enabled on specific Kong Gateway objects or for all requests globally.

Cache Time To Live (TTL)

TTL governs the refresh rate of cached content, which is critical for ensuring that clients aren’t served outdated content. A TTL of 30 seconds means content older than 30 seconds is deemed expired and will be refreshed on subsequent requests. TTL configurations should be set differently based on the type of the content the upstream service is serving.

  • Static data that is rarely updated can have longer TTL

  • Dynamic data should use shorter TTL to avoid serving outdated data

Kong Gateway follows RFC-7234 section 5.2 for cached controlled operations. See the specification and the Proxy Cache plugin parameter reference for more details on TTL configurations.

Enable caching

The following tutorial walks through managing proxy caching across various aspects in Kong Gateway.

Prerequisites

This chapter is part of the Get Started with Kong series. For the best experience, it is recommended that you follow the series from the beginning.

Start with the introduction Get Kong, which includes a list of prerequisites and instructions for running a local Kong Gateway.

Step two of the guide, Services and Routes, includes instructions for installing a mock service used throughout this series.

If you haven’t completed these steps already, complete them before proceeding.

Global proxy caching

Installing the plugin globally means every proxy request to Kong Gateway will potentially be cached.

  1. Enable proxy caching

    The Proxy Cache plugin is installed by default on Kong Gateway, and can be enabled by sending a POST request to the plugins object on the Admin API:

    curl -i -X POST http://localhost:8001/plugins \
      --data "name=proxy-cache" \
      --data "config.request_method=GET" \
      --data "config.response_code=200" \
      --data "config.content_type=application/json; charset=utf-8" \
      --data "config.cache_ttl=30" \
      --data "config.strategy=memory"
    

    If configuration was successful, you will receive a 201 response code.

    This Admin API request configured a Proxy Cache plugin for all GET requests that resulted in response codes of 200 and response Content-Type headers that equal application/json; charset=utf-8. cache_ttl instructed the plugin to flush values after 30 seconds.

    The final option config.strategy=memory specifies the backing data store for cached responses. More information on strategy can be found in the parameter reference for the Proxy Cache plugin.

  2. Validate

    You can check that the Proxy Cache plugin is working by sending GET requests and examining the returned headers. In step two of this guide, services and routes, you setup a /mock route and service that can help you see proxy caching in action.

    First, make an initial request to the /mock route. The Proxy Cache plugin returns status information headers prefixed with X-Cache, so use grep to filter for that information:

    curl -i -s -XGET http://localhost:8000/mock/requests | grep X-Cache
    

    On the initial request, there should be no cached responses, and the headers will indicate this with X-Cache-Status: Miss.

    X-Cache-Key: c9e1d4c8e5fd8209a5969eb3b0e85bc6
    X-Cache-Status: Miss
    

    Within 30 seconds of the initial request, repeat the command to send an identical request and the headers will indicate a cache Hit:

    X-Cache-Key: c9e1d4c8e5fd8209a5969eb3b0e85bc6
    X-Cache-Status: Hit
    

    The X-Cache-Status headers can return the following cache results:

    State Description
    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 could be satisfied in cache, but an entry for the resource was not found in cache, and the request was proxied upstream.
    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.

Service level proxy caching

The Proxy Cache plugin can be enabled for specific services. The request is the same as above, but the request is sent to the service URL:

curl -X POST http://localhost:8001/services/example_service/plugins \
   --data "name=proxy-cache" \
   --data "config.request_method=GET" \
   --data "config.response_code=200" \
   --data "config.content_type=application/json; charset=utf-8" \
   --data "config.cache_ttl=30" \
   --data "config.strategy=memory"

Route level proxy caching

The Proxy Caching plugin can be enabled for specific routes. The request is the same as above, but the request is sent to the route URL:

curl -X POST http://localhost:8001/routes/example_route/plugins \
   --data "name=proxy-cache" \
   --data "config.request_method=GET" \
   --data "config.response_code=200" \
   --data "config.content_type=application/json; charset=utf-8" \
   --data "config.cache_ttl=30" \
   --data "config.strategy=memory"

Consumer level proxy caching

In Kong Gateway, consumers are an abstraction that defines a user of a service. Consumer-level proxy caching can be used to cache responses per consumer.

  1. Create a consumer

Consumers are created using the consumer object in the Admin API.

curl -X POST http://localhost:8001/consumers/ \
  --data username=sasha
  1. Enable caching for the consumer
curl -X POST http://localhost:8001/consumers/sasha/plugins \
   --data "name=proxy-cache" \
   --data "config.request_method=GET" \
   --data "config.response_code=200" \
   --data "config.content_type=application/json; charset=utf-8" \
   --data "config.cache_ttl=30" \
   --data "config.strategy=memory"

Manage cached entities

The Proxy Cache plugin supports administrative endpoints to manage cached entities. Administrators can view and delete cached entities, or purge the entire cache by sending requests to the Admin API.

To retrieve the cached entity, submit a request to the Admin API /proxy-cache endpoint with the X-Cache-Key value of a known cached value. This request must be submitted prior to the TTL expiration, otherwise the cached entity has been purged.

For example, using the response headers above, pass the X-Cache-Key value of c9e1d4c8e5fd8209a5969eb3b0e85bc6 to the Admin API:

curl -i http://localhost:8001/proxy-cache/c9e1d4c8e5fd8209a5969eb3b0e85bc6

A response with 200 OK will contain full details of the cached entity.

See the Proxy Cache plugin documentation for the full list of the Proxy Cache specific Admin API endpoints.


Previous Rate Limiting
Next Key Authentication
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023