Additional, space-separated purge keys for the response.
Fastly reads this header from responses. It is proprietary to Fastly.
Surrogate-Key header on a response from a backend server tells Fastly to index that response against the specified key (or keys), as well as the cache key which is the subject of the current request. These 'surrogate keys' cannot be used to find and serve the content in a request, but can be used to target the content for purging.
For example, consider a request to an e-commerce site for
/category/shoes, which elicits a response from the backend server with the following headers:
Cache-Control: max-age=86400Surrogate-Key: product-62952 product-1043 product-14534
In the example above, the response will be cached, with the primary cache key being linked to "/category/shoes" (depending on the cache key configuration in
vcl_hash), but will also be indexed against the keys "product-62952", "product-1043" and "product-14534" for purging purposes. In this use case, this allows changes to a product to automatically purge all the pages on which that product appears, and not just the product page itself.
While it's conventional to add surrogate keys to a response at the backend server, it's also possible to add them using VCL in
vcl_fetch, by setting the value of the
Surrogate-Key backend response header:
set beresp.http.Surrogate-Key = "key1 key2 key3";
Individual keys are limited to 1024 bytes in length, and the total length of the
Surrogate-Key header may not exceed 16,384 bytes. If either of these limits are reached while parsing a
Surrogate-Key header, the key currently being parsed and all keys following it within the same header will be ignored.
Fastly will automatically strip the
Surrogate-Key header from responses unless the header
Fastly-Debug is present in the request. Setting
Fastly-Debug: 1 on a request is one way to see which surrogate keys, if any, are associated with a resource in the cache.
User contributed notes
We welcome comments that add use cases, ideas, tips, and caveats. All comments will be moderated before publication. To post support questions, visit our support center and we'll find you the help you need.