Caching Details


Not all HTTP responses are cacheable. Google Cloud CDN caches only those responses that meet all the requirements in this section. Some of these requirements are specified by RFC 7234, and others are specific to Cloud CDN.

A response can be stored in Cloud CDN caches only if all of the following are true:

  • It was served by a backend service or backend bucket with Cloud CDN enabled.
  • It was a response to a GET request.
  • The status code was 200, 203, 300, 301, 302, 307, or 410.
  • It has either a Content-Length header or a Transfer-Encoding header.

Additionally, the response must meet both of the following two requirements:

  • It has a Cache-Control: public header.
  • It has a Cache-Control: s-maxage, Cache-Control: max-age, or Expires header.

For backend buckets, you can satisfy these two requirements by marking the object as shared publicly.

There are also checks that will block caching of responses. A response will not be cached if any of the following are true:

  • It has a Set-Cookie header.
  • Its body exceeds 10 MB.
  • It has a Vary header with a value other than Accept, Accept-Encoding, or Origin.
  • It has a Cache-Control: no-store, no-cache, or private directive.
  • The corresponding request had a Cache-Control: no-store directive.

These requirements might be relaxed in the future, allowing Cloud CDN to cache additional responses. To prevent a response from being cached, include a Cache-Control: no-store header if the response should not be stored in any cache, even a web browser's cache, or a Cache-Control: private header if it should not be stored in Cloud CDN caches.

Large objects, partial responses, and validations requests

The Beta release of Cloud CDN Large Object Caching introduces support for content larger than 10 MB, improves support for partial responses, and changes the way expired cache entries are validated with the origin server. There's more information on the Large Object Caching page.

Cache entries

Cache keys

Each cache entry in a Cloud CDN cache is identified by a cache key. When a request comes into the cache, the cache converts the URI of the request into a cache key, then compares it with keys of cached entries. If it finds a match, the cache returns the object associated with that key.

By default, Cloud CDN uses the complete request URI as the cache key. For example, is the complete URI for a particular request for the cat.jpg object. This string is used as the default cache key. Only requests with this exact string match. Requests for or do not match.

For backend services, you can change which parts of the URI are used in the cache key. While the file path and file name must always be part of the key, you can include or omit any combination of protocol, host, or query string when customizing your cache key. Using cache keys describes how to customize your cache keys.

  • Protocol: You can omit the protocol from the key. If you omit the protocol, then a request for receives a cache key of After that, requests for both and count as matches for that cache entry.
  • Host: You can omit the host from the key. If you omit the host, then requests for and can both match the same cache entry. A request for followed by a request for results in a cache hit for the second request.
  • Query string: You can omit the query string from the cache key. If you omit the query string, then a request for receives a cache key of, so and can both match the same entry. You can also selectively omit or include portions of the query string.

In addition to including or omitting the entire query string, you also have the option of using portions of the query string via whitelists and blacklists.

For backend buckets, you cannot customize cache keys.

Query string whitelist

You can selectively control which query string parameters Cloud CDN incorporates into cache keys. For example, if you create a whitelist of user, then creates a cache key of which also matches To use this option, you must include the query string, specify a non-empty whitelist, and not specify a blacklist.

Query string blacklist

You can selectively control which query string parameters Cloud CDN ignores through a blacklist. For example, if you create a blacklist of user, then all query string parameters except user are used in the cache key.

With the above blacklist configured and an input of, Cloud CDN creates a cache key of which also matches but not To use this option, you must include the query string, specify a non-empty blacklist, and not specify a whitelist.

Vary headers

In addition to the request URI, Cloud CDN respects any Vary headers that origin servers include in responses. The Vary header indicates that the response varies depending on the client's request headers. For example, if a response specifies Vary: Accept, Cloud CDN will use one cache entry for requests that specify Accept: image/webp,image/*,*/*;q=0.8 and another for requests that specify Accept: */*.

Vary headers are sometimes used when serving compressed content. Cloud CDN does not compress or decompress responses itself, but it can serve responses that were compressed by the origin server. If your origin server chooses whether to serve compressed or uncompressed content based on the value of the Accept-Encoding request header, make sure the response specifies Vary: Accept-Encoding.

Responses with Vary headers will be cached only if the header has one of the values listed in Cacheability.

Expiration times and validation requests

Each cache entry in a Cloud CDN cache has an expiration time defined by the Cache-Control: s-maxage, Cache-Control: max-age, and/or Expires headers in accordance with RFC 7234. If more than one is present, Cache-Control: s-maxage takes precedence over Cache-Control: max-age, and Cache-Control: max-age takes precedence over Expires.

When Cloud CDN receives a request, it looks up the corresponding cache entry and checks its age. If the cache entry exists and is fresh enough, the response can be served from cache. If, however, the expiration time has passed, Cloud CDN will forward the request through your load balancer to one of your backends.

If the previously cached response has a Last-Modified and/or ETag header, Cloud CDN can make the forwarded request conditional by adding If-Modified-Since and/or If-None-Match headers. If the cached copy is still up to date, the backend can validate the existing cache entry by sending a 304 Not Modified response. In this case, the backend sends only the response headers, not the response body. Cloud CDN inserts the new response headers into the cache, updates the expiration time, and serves the new response headers and cached response body to the client.

Note that the expiration time is an upper bound on how long a cache entry remains valid. There is no guarantee that a cache entry will remain in the cache until it expires. Cache entries for unpopular content can be evicted to make room for new content. Regardless of the specified expiration time, cache entries that aren't accessed for 30 days are automatically removed.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud CDN Documentation