Skip to content

HTTP Caching

The performance of web sites and applications can be significantly improved by reusing previously fetched resources. Web caches reduce latency and network traffic and thus lessen the time needed to display a representation of a resource. By making use of HTTP caching, Web sites become more responsive.

HTTP Cache Middleware

Traefik Enterprise's HTTP Cache Middleware allows you to add caching to your routers and improve the performance of your infrastructure. The cache middleware follows the RFC 7234.

Cache Status

Unless configured not to, the middleware also adds a cache status header (X-Cache-Status) to responses, to indicate whether the request did HIT, MISS or BYPASS the cache.

  • HIT: The response was fetched from the cache, and the request did not reach the upstream application
  • MISS: The response was fetched from the upstream application and not from the cache
  • BYPASS: The request or response did not allow HTTP caching

Middleware Options

maxTtl

Required, Default=300

Set the maxTtl option to the maximum amount of seconds after which you want cached HTTP responses to expire and be invalidated. The time after which an HTTP response is no longer cached will be the lowest value between what is configured in maxTtl and the specified expiry time in the HTTP response headers.

For example, if a response has an Expires header set to expire after 10 minutes but the middleware is configured with a maxTtl of 5 minutes, the response will only be cached for 5 minutes.

labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl=300"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-http-cache
spec:
  plugin:
    httpCache:
      maxTtl: 300
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl=300"
"labels": {
  "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl": 300
}
labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl=300"
http:
  middlewares:
    test-http-cache:
      plugin:
        httpCache:
          maxTtl: 300
[http.middlewares]
  [http.middlewares.test-http-cache.plugin.httpCache]
    maxTtl = 300

disableCacheStatusHeader

Optional, Default=false

The disableCacheStatusHeader option prevents the middleware from adding a X-Cache-Status header to responses. See the section on cache status for more information on this header.

labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.disableCacheStatusHeader=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-http-cache
spec:
  plugin:
    httpCache:
      disableCacheStatusHeader: true
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.disableCacheStatusHeader=true"
"labels": {
  "traefik.http.middlewares.test-http-cache.plugin.httpCache.disableCacheStatusHeader": "true"
}
labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.disableCacheStatusHeader=true"
http:
  middlewares:
    test-http-cache:
      plugin:
        httpCache:
          disableCacheStatusHeader: true
[http.middlewares]
  [http.middlewares.test-http-cache.plugin.httpCache]
    disableCacheStatusHeader = true

maxStale

Optional, Default=0

The maxStale option allows the middleware to serve stale responses when allowed by the request's cache-control directive max-stale. It controls the duration in seconds a stale cached entry is kept in cache and served.

labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxStale=30"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-http-cache
spec:
  plugin:
    httpCache:
      maxStale: 30
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxStale=30"
"labels": {
  "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxStale": "30"
}
labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxStale=30"
http:
  middlewares:
    test-http-cache:
      plugin:
        httpCache:
          maxStale: 30
[http.middlewares]
  [http.middlewares.test-http-cache.plugin.httpCache]
    maxStale = 30

excludedResponseCodes

Optional, Default=""

The excludedResponseCodes option configures the response status codes or range of response status codes for which the cache is disabled.

The status code ranges are inclusive (500-599 will trigger with every code between 500 and 599, 500 and 599 included).

You can define either a status code as a number (500), as multiple comma-separated numbers (500,502), as ranges by separating two codes with a dash (500-599), or a combination of the two (404,418,500-599).

labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.excludedResponseCodes=404,300-399"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-http-cache
spec:
  plugin:
    httpCache:
      excludedResponseCodes: 
        - "404"
        - "300-399"
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.excludedResponseCodes=404,300-399"
"labels": {
  "traefik.http.middlewares.test-http-cache.plugin.httpCache.excludedResponseCodes": "404,300-399"
}
labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.excludedResponseCodes=404,300-399"
http:
  middlewares:
    test-http-cache:
      plugin:
        httpCache:
          excludedResponseCodes:
            - "404"
            - "300-399"
[http.middlewares]
  [http.middlewares.test-http-cache.plugin.httpCache]
    excludedResponseCodes = ["404", "300-399"]

Cache Storages

At the moment, Traefik Enterprise only provides the in-memory store option.

Memory

The memory storage stores the cache content in the proxy memory. It is efficient and requires very little configuration. However, with this storage each proxy maintains its own cache and does not share it with other proxy instances. Also, it has to be noted that the memory limit is set per middleware and is not global to the proxy. In other words, if you have multiple middlewares with differents memory limits, they will add-up, but if you share the same middleware accros multiple routers they will use the same limit.

memory.limit

Optional, Default="1Gi"

The memory.limit option specifies the maximum amount of memory that the cache can use for storing HTTP responses. Its value is measured in bytes, and can be expressed as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.

Measure Unit Exponent Bytes Unit Exponent Bytes
kilo- K 10^3 1000 Ki 1024 1024
mega- M 10^6 100 000 Mi 1024^2 1 048 576
giga- G 10^9 100 000 000 Gi 1024^3 1 073 741 824
tera- T 10^12 100 000 000 000 Ti 1024^4 1 099 511 627 776
peta- P 10^15 100 000 000 000 Pi 1024^5 1 125 899 906 842 624
exa- E 10^18 100 000 000 000 000 Ei 1024^6 1 152 921 504 606 846 976

Do not exceed the proxy memory limits

The value given to memory.limit should remain within the bounds of each proxy's specified memory limit. By default, Traefik Enterprise proxies have a limit of 4 gigabytes of memory on many platforms, but this can be customized by modifying the generated installation manifests (see the section Installing/Customizing for more information).

labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit=3Gi"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-http-cache
spec:
  plugin:
    httpCache:
      memory:
        limit: "3Gi"
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit=3Gi"
"labels": {
  "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit": "3Gi"
}
labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit=3Gi"
http:
  middlewares:
    test-http-cache:
      plugin:
        httpCache:
          memory:
            limit: "3Gi"
[http.middlewares]
  [http.middlewares.test-http-cache.plugin.httpCache.memory]
    limit = "3Gi"

Advanced Configuration Example

Below is an advanced configuration that enables the memory cache store, sets its size limit to 3Gi and also assigns a maximum TTL of 600 seconds to cached entries.

labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl=600"
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit=3Gi"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-http-cache
spec:
  plugin:
    httpCache:
      maxTtl: 600
      memory:
        limit: "3Gi"
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl=600"
- "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit=3Gi"
"labels": {
    "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl": "600",
    "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit": "3Gi",
}
labels:
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.maxTtl=600"
  - "traefik.http.middlewares.test-http-cache.plugin.httpCache.memory.limit=3Gi"
http:
  middlewares:
    test-http-cache:
      plugin:
        httpCache:
          maxTtl: 600
          memory:
            limit: "3Gi"
[http.middlewares]
  [http.middlewares.test-http-cache.plugin.httpCache]
    maxTtl = 600
    [http.middlewares.test-http-cache.plugin.httpCache.memory]
      limit = "3Gi"

Purging the Cache

The cache can be purged with teectl using the delete cache command. Specific middleware caches can be purged using the --names flag, which accepts a comma separated list of middleware names. Alternatively all caches can be purged using the --all flag.

Example:

teectl delete cache --names="cache-middleware1@kubernetescrd,cache-middleware-2@traefikee"
teectl delete cache --all

Namespaced resources

Middleware names must be suffixed by the provider name they are defined in.