Cache filter

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig.

  • v3 API reference

  • v3 SimpleHTTPCache API reference

  • This filter doesn’t support virtual host-specific configurations.

  • When the cache is enabled, cacheable requests are only sent through filters in the upstream_http_filters chain and not through any filters in the regular filter chain that are further upstream than the cache filter, while non-cacheable requests still go through the listener filter chain. It is therefore recommended for consistency that only the router filter should be further upstream in the listener filter chain than the cache filter.

../../../_images/cache-filter-chain.svg

The HTTP Cache filter implements most of the complexity of HTTP caching semantics.

For HTTP Requests:

  • HTTP Cache respects request’s Cache-Control directive. For example, if request comes with Cache-Control: no-store the request won’t be cached, unless ignore_request_cache_control_header is true.

  • HTTP Cache wont store HTTP HEAD Requests.

For HTTP Responses:

  • HTTP Cache only caches responses with enough data to calculate freshness lifetime as per RFC7234.

  • HTTP Cache respects Cache-Control directive from the upstream host. For example, if HTTP response returns status code 200 with Cache-Control: max-age=60 and no vary header, it will be cached.

  • HTTP Cache only caches responses with status codes: 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 451, 501.

HTTP Cache delegates the actual storage of HTTP responses to implementations of the HttpCache interface. These implementations can cover all points on the spectrum of persistence, performance, and distribution, from local RAM caches to globally distributed persistent caches. They can be fully custom caches, or wrappers/adapters around local or remote open-source or proprietary caches. Built-in cache storage backends include SimpleHttpCacheConfig (in-memory) and FileSystemHttpCacheConfig (persistent; LRU).

Architecture and extension points

Envoy’s HTTP caching is split into:

  • HTTP Cache filter (extension name envoy.filters.http.cache, category envoy.filters.http) — configured via CacheConfig to apply HTTP caching semantics.

  • Cache storage backends (extension category envoy.http.cache) — the filter delegates object storage/retrieval to a backend, selected via a nested typed_config in CacheConfig.

Example configuration

Example filter configuration with a SimpleHttpCache cache implementation:

http-cache-configuration.yaml
29          http_filters:
30          - name: "envoy.filters.http.cache"
31            typed_config:
32              "@type": "type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig"
33              typed_config:
34                "@type": "type.googleapis.com/envoy.extensions.http.cache.simple_http_cache.v3.SimpleHttpCacheConfig"

Example filter configuration with a FileSystemHttpCache cache implementation:

http-cache-configuration-fs.yaml
29          http_filters:
30          - name: envoy.filters.http.cache
31            typed_config:
32              "@type": type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig
33              typed_config:
34                "@type": type.googleapis.com/envoy.extensions.http.cache.file_system_http_cache.v3.FileSystemHttpCacheConfig
35                manager_config:
36                  thread_pool:
37                    thread_count: 2
38                cache_path: /var/cache/envoy
39                max_cache_size_bytes: 1073741824

See also

Envoy Cache Sandbox

Learn more about the Envoy Cache filter in the step by step sandbox.

HTTP Cache filter (proto file)

CacheConfig API reference.

In-memory storage backend

SimpleHttpCacheConfig API reference.

Persistent on-disk storage backend

Docs page for File System Http Cache; links to FileSystemHttpCacheConfig API reference.