Caching

Caching lets you offload work from your application servers by returning cached resources directly from the load balancer. It can be applied to any reusable content that is safe to be shared among multiple clients, such as:

• CSS, Javascript, and icon files
• API responses (e.g. JSON) that don’t contain client-specific data
• Small, static HTML pages

The cache runs in memory and doesn’t store state on disk. This makes it very fast, but not durable past a reload of the load balancer. We recommend storing objects for a short duration, such as less than a minute to reduce the chance of serving stale content.

Enable the cache Jump to heading #

1. Add a cache section to your configuration.

   haproxy
   cache mycache
     total-max-size 4
     max-object-size 10000
     max-age 240
     process-vary on
     max-secondary-entries 12

   haproxy
   cache mycache
     total-max-size 4
     max-object-size 10000
     max-age 240
     process-vary on
     max-secondary-entries 12

   Directive	Description
   total-max-size	Sets the total memory the cache can consume in megabytes. The maximum value is 4095.
   max-object-size	Sets the max size in bytes for a single object. Larger objects won’t be stored. It cannot be larger than half of total-max-size.
   max-age	Sets the seconds for an object to stay the cache. It can be overridden with a Cache-Control header.
   process-vary	Available since HAProxy 2.4, HAProxy Enterprise 2.4r1, and ALOHA 13.5. Turn on or off the processing of the Vary header in a response. When set to on, process-vary will process a Vary header if it contains only one or more of the following HTTP headers: accept-encoding, referer, and/or origin. Responses without a Vary header can still be cached if process-vary is on. When process-vary is off, a response containing a Vary header will never be cached. Default: off.
   max-secondary-entries	Available since HAProxy 2.4, HAProxy Enterprise 2.4r1, and ALOHA 13.5. The secondary entries allow you to cache responses that have the same primary key, which is the URL, with different variations of the HTTP headers accept-encoding, referer, and/or origin. By setting max-secondary-entries, you limit the maximum number of variations. Requires process-vary to be on, and must be a positive integer. Default: 10.

2. Add an http-request cache-use and an http-response cache-store directive to a frontend or listen section to enable caching in that section. The filter line is required only when the section includes other filter lines; otherwise, it can be omitted since it’s implicitly defined.

   haproxy
   frontend  fe_main
      bind :80
      filter cache mycache
      http-request cache-use mycache
      http-response cache-store mycache
      default_backend be_main

   haproxy
   frontend  fe_main
      bind :80
      filter cache mycache
      http-request cache-use mycache
      http-response cache-store mycache
      default_backend be_main

   Directive	Description
   http-request cache-use	Fetches the requested resource from the cache. Place an if or unless statement afterwards to include or exclude a resource from being cached.
   http-response cache-store	Saves the resource to the cache once it comes from the server.

Cache based on a condition Jump to heading #

You can select which resources to cache by using an if statement on the http-request cache-use line. You need an if statement only on the http-request cache-use line and not the http-response cache-store line too. The load balancer won’t store items in the cache if there’s no chance of them being used.

Add the ACL path_beg /api/ to cache responses when the requested URL path begins with /api/:

haproxy
cache mycache
  total-max-size 4095
  max-object-size 10000
  max-age 30
backend servers
  http-request cache-use mycache if { path_beg /api/ }
  http-response cache-store mycache
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check

haproxy
cache mycache
  total-max-size 4095
  max-object-size 10000
  max-age 30
backend servers
  http-request cache-use mycache if { path_beg /api/ }
  http-response cache-store mycache
  server s1 192.168.1.25:80 check
  server s2 192.168.1.26:80 check

Cache restrictions Jump to heading #

Objects are cached only if all of the following are true:

• The size of the resource doesn’t exceed max-object-size.
• The response from the server is 200 OK.
• The response doesn’t have a Cache-Control: no-cache header.
• The response doesn’t have a Vary header. If the response does have a Vary header, then process-vary is on and the Vary header contains only one or more of the following HTTP headers: accept-encoding, referrer, and/or origin.

See also Jump to heading #

For complete information on caching, see Cache reference in the HAProxy Configuration Manual.

• To cache a resource, see cache-store action.
• To use a cached resource, see cache-use directive.
• Filters can be used for a variety of purposes. For complete information, see filter action.