CacheV2 filter

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

  • 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, and even then only if the router filter does not perform any mutations such as if request_headers_to_add is set.

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

  • For more complex filter chains where some filters must be upstream of the cache filter for correct behavior, or if the router filter is configured to perform mutations via RouteConfiguration the recommended way to configure this so that it works correctly is to configure an internal listener which duplicates the part of the filter chain that is upstream of the cache filter, and the RouteConfiguration.

../../../_images/cache-v2-filter-internal-listener.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 SimpleHttpCacheV2Config (in-memory) and FileSystemHttpCacheV2Config (persistent; LRU).

Architecture and extension points

Envoy’s HTTP caching is split into:

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

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

Example configuration

Example filter configuration with a SimpleHttpCache cache implementation:

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

Example filter configuration with a FileSystemHttpCacheV2 cache implementation:

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

The more complicated filter chain configuration required if mutations occur upstream of the cache filter involves duplicating the full route config into an internal listener (unfortunately this is currently unavoidable):

http-cache-v2-configuration-internal-listener.yaml
37          http_filters:
38          - name: "envoy.filters.http.cache_v2"
39            typed_config:
40              "@type": "type.googleapis.com/envoy.extensions.filters.http.cache_v2.v3.CacheV2Config"
41              override_upstream_cluster: cache_internal_listener_cluster
42              typed_config:
43                "@type": "type.googleapis.com/envoy.extensions.http.cache_v2.simple_http_cache.v3.SimpleHttpCacheV2Config"
44          - name: envoy.filters.http.router
45            typed_config:
46              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
47  - name: cache_internal_listener
48    internal_listener: {}
49    filter_chains:
50    - filters:
51      - name: envoy.filters.network.http_connection_manager
52        typed_config:
53          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
54          codec_type: AUTO
55          stat_prefix: cache_internal_listener
56          route_config:
57            name: local_route
58            virtual_hosts:
59            - name: backend
60              response_headers_to_add:
61              - header:
62                  key: x-something
63                  value: something
64              domains:
65              - "*"
66              routes:
67              - match:
68                  prefix: "/service/1"
69                route:
70                  cluster: service1
71              - match:
72                  prefix: "/service/2"
73                route:
74                  cluster: service2
75          http_filters:
76          - name: envoy.filters.http.router
77            typed_config:
78              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
79
80  clusters:
81  - name: cache_internal_listener_cluster
82    load_assignment:
83      cluster_name: cache_internal_listener_cluster
84      endpoints:
85      - lb_endpoints:
86        - endpoint:
87            address:
88              envoy_internal_address:
89                server_listener_name: cache_internal_listener

See also

HTTP CacheV2 filter (proto file)

CacheV2Config API reference.

In-memory storage backend

SimpleHttpCacheV2Config API reference.

Persistent on-disk storage backend

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

Old cache filter

The deprecated cache filter.