Purging best practices

This guide provides best practices for purging with Fastly.

Select the best purging method for your use cases

Fastly has different purging methods that let you precisely purge only the objects you want updated. Familiarize yourself with each method so that you're purging only what you need.

Use soft purging

Soft purging marks objects as stale instead of immediately deleting them. This can help you avoid traffic spikes to your origin and respond to client requests even when your origin servers are down.

Understand how purging interacts with shielding

If you plan on enabling shielding on your service, it's important to understand how it may impact the way content is purged. When shielding is enabled, a request from an end user may traverse two Fastly POPs before being forwarded to your origin server. This may cause issues that prevent purging from working as expected, such as encountering race conditions or stale content becoming fresh.

Encountering race conditions

Because the order in which caches are purged can't be controlled, it's possible that a request might reach a purged edge POP first, then be forwarded to a shield POP that has not yet been purged. The shield POP will deliver the cached content to the edge POP, which will cache it, resulting in the pre-purge content remaining in Fastly cache.

A solution to this race condition problem is to purge twice. For purge all operations, execute the two purges around 30 seconds apart. For URL and surrogate key purges, execute the two purges around two seconds apart.

You can automate the purge all operations by comparing the cache generation value. Purge all operations cause the cache generation value to change. Add the req.vcl.generation VCL variable or FASTLY_CACHE_GENERATION environment variable to a response at a shield POP, and then compare with the local value at the edge POP. If they differ, the edge POP should not cache the response. The following example shows how this can be implemented in VCL:

Stale content becoming fresh

If you use soft purging and your service is configured to serve stale content, the shield POP may serve stale content to the edge POP, which then becomes re-cached with a fresh TTL.

A solution to this problem is to disable the use of stale content for asynchronous revalidation when a POP is acting as a shield:

  1. CDN services
  2. Compute services

You can prevent the inadvertent caching of stale content at the edge POP by disabling the use of stale content for asynchronous revalidation when a POP is acting as a shield:

sub vcl_recv { ... }
Fastly VCL
if (fastly.ff.visits_this_service > 0) {
set req.max_stale_while_revalidate = 0s;
}

This code will continue to allow stale content to be used when an origin is sick. To disable that as well, set req.max_stale_if_error to 0s.

Understand how the Vary header interacts with purging methods

The Vary header is used on responses to indicate that the response can only be used for requests with a specific header value. While there are many use cases for the Vary header, one option is to cache (and then purge) logged in and logged out variants of a page separately.

To do this, use surrogate keys to purge. Surrogate key purges target objects by the surrogate key, not the cache key, so they will only invalidate variants that have the key. If an object has multiple variants in cache and only some of them match the key you have requested to purge, only those variants will be invalidated.

When using URL purge, the purge targets objects by cache key, so all variants of the object are purged. Purge all invalidates all content in the service, so implicitly all variants of all objects are purged.

Use versioned URLs for select content types instead of purging

In certain situations, it may be more efficient to deliver updated content by publishing it at a new URL, rather than purging.

While your web pages should maintain URLs to optimize SEO and avoid breaking inbound links, the assets the page loads, such as videos, images, scripts, and stylesheets, are typically linked only from pages you control, so their URLs can change. When you update a page, you can often give every asset it loads a new URL.

With new asset URLs, the Fastly platform sends requests from the updated page to your origin to fetch the new assets, while requests from older versions of the page continue to be served from assets cached at the edge.

Versioned URLs can take many forms. Here are some examples:

  • /script.js?v=2021-01-01T00:00:00: Using the time when the site was updated is a simple mechanism, but if you don't update the entire site in one atomic operation, you may create cache fragmentation.
  • /script.js?v=12: Using a version number works well if your site has a single overall version number.
  • /script.195bb21f.js: Putting a hash of the content in the filename is an effective stateless solution and favored by many web frameworks.

All these URL paths would be considered separate objects by Fastly. Serve these kinds of assets from your origin server with a long cache TTL, and consider setting the immutable cache directive:

Cache-Control: max-age=31556952, immutable

HINT: When using versioned URLs for assets, avoid performing purge all operations because it will remove all versioned assets.