Cache invalidation overview

This page provides an overview of Cloud CDN cache invalidation.

What is cache invalidation?

After an object is cached, it normally remains in the cache until it expires or is evicted to make room for new content. You might want to remove an object from the cache before its normal expiration time. You can force an object or set of objects to be ignored by the cache by requesting a cache invalidation.

Cache invalidation, sometimes called cache purging, is the process of declaring cached content to be invalid. This process causes the entry to be removed from the cache and then refilled from the backend server the next time that the content is requested.

Cloud CDN supports the use of cache tags (Preview) and invalidation matchers, such as host and URL path, for invalidation requests.

You can combine these invalidation parameters to target specific cached responses and minimize backend load on the subsequent cache fill.

It's important to ensure that the backend server is returning the correct content before you request the cache invalidation. Otherwise, when Cloud CDN requests the content again, it might cache the incorrect content.

Invalidations requests are rate-limited as follows:

  • For cache tags (Preview), you can submit up to 500 invalidation requests per minute. Each invalidation request takes effect in about 10 seconds.
  • For other invalidation matchers, you can submit at most one invalidation per minute. Each invalidation request takes effect in about one to three minutes.

Cloud CDN doesn't restrict the number of objects or the total size of all invalidated objects for each request.

Invalidation by URLs

Each invalidation request specifies a path pattern that identifies the object or set of objects that should be invalidated. The path pattern can be either a specific path, such as /cat.jpg, or an entire directory structure, such as /pictures/*. The following rules apply to path patterns:

  • The path pattern must start with /.
  • It cannot include ? or #.
  • It must not include an * except as the final character following a /.
  • If it ends with /*, the preceding string is a prefix, and all objects whose paths begin with that prefix are invalidated.

The path pattern is compared with the path component of the URL, which is everything between the hostname and any ? or # that might be present.

If you have URLs that contain a query string, for example /images.php?image=fred.png, you cannot selectively invalidate objects that differ only by query string. For example, if you have two images, /images.php?image=fred.png and /images.php?image=barney.png, you cannot invalidate only fred.png. To invalidate all images served by images.php, use /images.php as the path pattern.

Invalidation for a single host

Cache invalidation invalidates the path for all your hostnames. For example, if you have example.com and example2.com pointed to the same load balancer, and you invalidate /images/cat.jpg, both example.com/images/cat.jpg and example2.com/images/cat.jpg are invalidated.

You can restrict the invalidation to only one of the hosts by adding the --host flag to the command.

Invalidation by cache tags

Cache tags (or surrogate keys) let you invalidate content based on arbitrary metadata.

These tags are defined with the Cache-Tag HTTP header in a backend response. Cache tags from the backend in the Cache-Tag HTTP response header are sent to the client.

Cache tags have the following limits:

  • Must not exceed 120 bytes per tag
  • Must not exceed 4 KiBs (4096 bytes) of total tag names per cached object
  • Must not exceed 50 tags per object

If these tag limits are exceeded, the response isn't cached and this decision is logged as RESPONSE_CACHE_TAG_INVALID in LoadBalancerLogEntry.cacheDecision.

You can specify up to 10 cache tags per invalidation request. When multiple tags are specified in a single invalidation request, they are treated as a logical OR. Consider an example in which you have the following cached objects:

  • Cached object #1 with tags js, 2020-12-23, and prod
  • Cached object #2 with tags css, 2020-11-30, and prod
  • Cached object #3 with tags img 2020-11-30, and staging

When you issue a request to invalidate objects that match tags="prod,2020-11-30", all three cached objects are invalidated. This approach means that you don't need to know or specify all possible tag combinations when you want to invalidate an object.

If you specify invalidation matchers along with cache tags, the invalidation request applies only to the tagged objects that match the invalidation matchers. Consider an example with the following cached objects:

  • Cached object #1 with URL https://staging.example.com/img/cat.jpg and tag a
  • Cached object #2 with URL https://example.com/img/cat.jpg and tag a
  • Cached object #3 with URL https://staging.example.com/js/cat.js and tag a
  • Cached object #4 with URL https://staging.example.com/img/logo.jpg and tag b

When you issue a request to invalidate objects that match --host="staging.example.com" --path="/img/*" --tags="a", only object #1 is invalidated. Objects #2, #3, and #4 don't match the host, path, or tag, respectively.

Invalidation latency

Because Cloud CDN is a distributed system, it might report that an invalidation has completed even though a small number of caches have not yet processed the invalidation request. This situation is rare and corrects itself automatically.

Best practices

Invalidate only what you must because invalidating too much might cause a spike in requests that the caches were serving to suddenly hit your instances or buckets.

Invalidation is intended for use in exceptional circumstances, not as part of your normal workflow. Invalidations don't affect cached copies in web browser caches or caches operated by third-party internet service providers.

As an alternative to routine invalidations, you can proactively set appropriate expiration times on responses or use different URLs for different versions of your content. For more information about expiration times, see Expiration times and validation requests.

Invalidation with Shared VPC cross-project service referencing

Cache invalidation is configured in the frontend project; that is, the project that has the forwarding rule, target proxy, and URL map of the load balancer. So, when you're using a global external Application Load Balancer with Shared VPC cross-project service referencing, by default, service project administrators don't have the required permissions to request cache invalidations.

Cache invalidations can be issued only by principals who have the Identity and Access Management (IAM) roles for configuring load balancer resources in the frontend projects—for example, the Compute Network Admin role (roles/compute.networkAdmin).

Service administrators, who control provisioning of the backend services in a separate project, can work with the load balancer administrator of the frontend project to issue cache invalidation for their cross-project services. For URL rewrites, ensure that the invalidation matches the pre-rewrite host and path that the client sends.

What's next