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 oris evicted to make room for new content. You might want to remove an objectfrom the cache before its normal expiration time. You can force an objector set of objects to be ignored by the cache by requesting a cache invalidation.

Cache invalidation, sometimes calledcache purging, is the process ofdeclaring cached content to be invalid. This process causes the entry to beremoved from the cache and then refilled from the backend server the next timethat the content is requested.

Cloud CDN supports the use of cache tags and invalidation matchers, such ashost and URL path, for invalidation requests.

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

It's important to ensure that the backend server is returning the correctcontent before you request the cache invalidation. Otherwise, whenCloud CDN requests the content again, it might cache the incorrectcontent.

Invalidations requests are rate limited. You can submit up to 500 invalidationrequests per minute. Each invalidation request takes effect in about 10 seconds.

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

Invalidation by URLs

Each invalidation request specifies a path pattern that identifies the objector set of objects that should be invalidated. The path pattern can be either aspecific 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 whosepaths begin with that prefix are invalidated.

The path pattern is compared with the path component of the URL, which iseverything 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 thatdiffer only by query string. For example, if you have two images,/images.php?image=fred.png and/images.php?image=barney.png, you cannotinvalidate onlyfred.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. Forexample, if you haveexample.com andexample2.com pointed to the sameload balancer, and you invalidate/images/cat.jpg, bothexample.com/images/cat.jpg andexample2.com/images/cat.jpg are invalidated.

You can restrict the invalidation to only one of the hosts by specifying thehost.

Invalidation by cache tags

Cache tags (orsurrogate keys) let you invalidate content based onarbitrary metadata.

Note: Cache tags are different fromcache keys.

These tags are defined with theCache-Tag HTTP header in a backendresponse. Cache tags from the backend in theCache-Tag HTTP responseheader 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 thisdecision is logged asRESPONSE_CACHE_TAG_INVALID inLoadBalancerLogEntry.cacheDecision.

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

• Cached object #1 with tagsjs,2020-12-23, andprod
• Cached object #2 with tagscss,2020-11-30, andprod
• Cached object #3 with tagsimg2020-11-30, andstaging

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

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

• Cached object #1 with URLhttps://staging.example.com/img/cat.jpg and taga
• Cached object #2 with URLhttps://example.com/img/cat.jpg and taga
• Cached object #3 with URLhttps://staging.example.com/js/cat.js and taga
• Cached object #4 with URLhttps://staging.example.com/img/logo.jpg and tagb

When you issue a request to invalidate objects where the host isstaging.example.com, the path/img/*, and the taga, only object #1 isinvalidated. 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 thatan invalidation has completed even though a small number of caches have notyet processed the invalidation request. This situation is rare andcorrects itself automatically.

Best practices

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

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

As an alternative to routine invalidations, you can proactively set appropriateexpiration times on responses or use different URLs for different versionsof your content. For more information about expiration times, seeExpiration times and validation requests.

Invalidation with Shared VPC cross-project service referencing

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

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

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

What's next

• To learn how to invalidate your Cloud CDN cached content, seeInvalidating cached content.

• To learn about which content is cacheable or non-cacheable, seeCaching overview.