Caching Details

Cacheability

Not all HTTP responses are cacheable. 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 is a response to a GET request.

Its status code is 200, 203, 206, 300, 301, 302, 307, or 410.

It has a Cache-Control: public header.

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

Make the bucket publicly readableand add the required Cache-Control headers to each object in that bucket
that you want to be cacheable.

Note: An alternative to making content public is to keep it private and
instead use signed URLs.

There are also checks that block caching of responses. A response isn't
cached if any of the following are true:

It has a Set-Cookie header.

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.

Note that if Cache-Control: no-store, no-cache, or private is present
but the content is still being cached, this is because URL signing is
configured. For information on how to
prevent responses from being cached, refer to the
Preventing caching section.

Maximum size

10 MB (10,485,760 bytes) if the origin server does not support byte range
requests

Any response with a body larger than the maximum size is not cached.

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.

For backend services,
Cloud CDN defaults to using the complete request URI as
the cache key. For example, https://example.com/images/cat.jpg 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 http://example.com/images/cat.jpg or
https://example.com/images/cat.jpg?user=user1 do not match.

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
https://example.com/images/cat.jpg receives a cache key of
example.com/images/cat.jpg. After that, requests for both
https://example.com/images/cat.jpg and
http://example.com/images/cat.jpg count as matches for that
cache entry.

Host: You can omit the host from the key. If you omit the host, then
requests for example.com and example2.com can both match the same
cache entry. A request for https://example.com/images/cat.jpg followed by
a request for https://example2.com/images/cat.jpg 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
https://example.com/images/cat.jpg?user=user1 receives a cache key of
https://example.com/images/cat.jpg, so
https://example.com/images/cat.jpg?user=user1 and
https://example.com/images/cat.jpg?user=user2 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, the cache key
consists of the URI without the query string. Thus
https://example.com/images/cat.jpg,
https://example.com/images/cat.jpg?user=user1, and
https://example.com/images/cat.jpg?user=user2 are equivalent.

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 https://example.com/images/cat.jpg?user=user1&color=blue creates
a cache key of https://example.com/images/cat.jpg?user=user1 which
also matches https://example.com/images/cat.jpg?user=user1&color=red.
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 exceptuser are used in the cache key.

With the above blacklist configured and an input of
https://example.com/images/cat.jpg?user=user1&color=blue, Cloud CDN
creates a cache key of https://example.com/images/cat.jpg?color=blue which
also matches https://example.com/images/cat.jpg?user=user2&color=blue
but not https://example.com/images/cat.jpg?user=user1&color=red.
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 uses 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 are 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 cannot serve a response without first
contacting one of your backends.

If the previously cached response has Last-Modified and/or ETag headers,
Cloud CDN can attempt to use the information in those headers to
validate the cache entry with the backend. Cloud CDN performs
this validation slightly differently depending on whether the response was
cached using byte range requests:

If the response was cached using byte range requests, Cloud CDN
initiates a separate validation request that includes If-Modified-Since
and/or If-None-Match headers.

Otherwise, Cloud CDN adds If-Modified-Since and/or
If-None-Match headers to the client request and forward the modified request
to the backend.

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.

If the previously cached response has neither a Last-Modified nor an ETag
header, Cloud CDN ignores the expired cache entry and forward
the client request to the backend unmodified.

Note that a cache entry's expiration time is an upper bound on how long the
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.

Support for byte range requests

A response that satisfies the following criteria indicates that the origin
server supports byte range requests:

Its status code is 200 OK or 206 Partial Content.

It has an Accept-Ranges: bytes header.

It has a Content-Length and/or Content-Range header.

It has an ETag header with a strong validator and/or a Last-Modified
header.

Google Cloud Storage supports byte range requests for most objects. However,
Cloud Storage does not support byte range requests for objects with
Content-Encoding: gzip metadata unless the client request includes an
Accept-Encoding: gzip header. If you have Cloud Storage objects larger than
10 MB in size, make sure they do not have Content-Encoding: gzip metadata.
Refer to Viewing and Editing Object
Metadata for information on how to edit
object metadata.

Popular web server software also supports byte range requests. Consult your web
server software's documentation for details on how to enable support. For more
information on byte range requests, refer to the HTTP
specification.

When an origin server supports byte range requests, a Cloud CDN
cache declines to store an otherwise cacheable response the first time it is
requested if either of the following is true:

The response body is incomplete because the client requested only part of the
content

The response body is larger than 1 MB (1,048,576 bytes) in size.

When this happens and the response would otherwise satisfy the normal
cacheability requirements, the cache records that the origin
server supports byte range requests for that cache key and forwards the origin
server's response to the client.

On a cache miss, the cache checks whether the origin server is known to support
byte range requests. If byte range requests are known to be supported for the
cache key, the cache will not forward the client request to the HTTP(S) load
balancer. Instead, the cache will initiate its own byte range cache fill
requests for the missing parts of the content. If your origin server returns
the requested byte range in a 206 Partial Content response, the cache can
store that range for future requests.

A cache stores a 206 Partial Content response only when it is received in
response to a byte range request that the cache initiated. Because a cache
won't initiate a byte range request unless it had previously recorded that the
origin server supports byte range requests for that cache key, a given cache
won't store content that's larger than 1 MB in size until the second time that
content is accessed.

Requests initiated by Cloud CDN

When your origin server supports byte range requests,
Cloud CDN can send multiple requests to your origin server in
reaction to a single client request. As described below,
Cloud CDN can initiate two types of requests: validation requests
and byte range requests.

If the response that indicated your origin server supported byte range requests
for a particular cache key has expired, Cloud CDN initiates
a validation request to confirm that the content hasn't changed and that your
origin server still supports range requests for the content. If your origin
server responds with a 304 Not Modified response, Cloud CDN
proceeds to serve the content using byte ranges. Otherwise,
Cloud CDN forwards your origin server's response to the
client. You control expiration times using the Cache-Control and Expires
response headers.

On a cache miss, Cloud CDN initiates cache fill requests for a
set of byte ranges that overlap the client request. If some ranges of the
content requested by the client are present in cache and others are not,
Cloud CDN serves whatever it can from cache and sends byte
range requests for only the missing ranges to your origin server.

Each byte range request initiated by Cloud CDN specifies a range
that begins at an offset that's a multiple of 2,097,136 bytes. With the possible
exception of the final range, each range is also 2,097,136 bytes in size; if
the content isn't a multiple of that size, the final range will be smaller. The
size and offsets used in byte range requests might change in the future.

As an example, consider a client request for bytes 1,000,000 through 3,999,999
of content that is not present in cache. In this example,
Cloud CDN could initiate two GET requests, one for the first
2,097,136 bytes of the content and another for the second 2,097,136 bytes. This
results in 4,194,272 bytes of cache fill even though the client requested only
3,000,000 bytes.

When you use a Cloud Storage bucket as your origin, each GET request is billed
as a separate Class B operation. You are
charged for all GET requests processed by Cloud Storage, including any requests
initiated by Cloud CDN. When a response is served entirely from a
Cloud CDN cache, no GET requests are sent to Cloud Storage, and
you are not charged for any Cloud Storage operations.

When Cloud CDN initiates a validation request or byte range
request, it does not include client-specific headers such as Cookie or
User-Agent.

Preventing caching

To prevent private information from being cached in Cloud CDN
caches, do the following:

Include a Cache-Control: private header in responses that should not be
stored in Cloud CDN caches or a Cache-Control: no-store
header in responses that should not be stored in any cache, even a web
browser's cache.

Do not sign URLs that provide access to private
information. When content is accessed using a signed URL, it is potentially
eligible for caching regardless of any Cache-Control directives in the
response.