Caching overview

A cacheable response is an HTTP response that Cloud CDN can store and quickly retrieve, thus allowing for faster load times. Not all HTTP responses are cacheable.

Cache modes

With cache modes, you can control the factors that determine whether Cloud CDN caches your content.

Cloud CDN offers three cache modes, which define how responses are cached, whether Cloud CDN respects cache directives sent by the origin, and how cache TTLs are applied.

The available cache modes are shown in the following table:

Cache mode	Behavior
CACHE_ALL_STATIC	Automatically caches static content that doesn't have the no-store or private directive. Origin responses that set valid caching directives are also cached. This is the default behavior for Cloud CDN-enabled backends created by using the gcloud command-line tool or the REST API.
USE_ORIGIN_HEADERS	Requires origin responses to set valid cache directives and valid caching headers. Responses without these directives are forwarded from the origin.
FORCE_CACHE_ALL	Unconditionally caches successful responses, overriding any cache directives set by the origin. This mode is not appropriate if the backend serves private, per-user content, such as dynamic HTML or API responses.

Caution: When you set the cache mode to FORCE_CACHE_ALL, the default time to live (TTL) for content caching is 3600 seconds (1 hour), unless you explicitly set a different TTL. Accepting the new default TTL of 1 hour might cause some entries that were previously considered fresh (due to having longer TTLs from origin headers) to now be considered stale.

Caution: The FORCE_CACHE_ALL mode overrides cache directives (Cache-Control and Expires) but does not override other origin response headers. In particular, a Vary header is still honored, and may suppress caching even in the presence of FORCE_CACHE_ALL. For more information, see Vary headers.

Note: The FORCE_CACHE_ALL mode overrides the maximum age specified for any signed URLs or signed cookies through the Cache entry maximum age setting in the Google Cloud Console or the gcloud --signed-url-cache-max-age option.

For setup instructions, see Setting the cache mode.

Static content

Static content is content that is always the same, even when accessed by different users. The CSS that you use to style your site, JavaScript to provide interactivity, video, and image content typically don't change for each user for a given URL (cache key), and thus benefit from being cached across Cloud CDN's global edge network.

When you set the cache mode to CACHE_ALL_STATIC, Cloud CDN automatically caches responses for the following:

• Web Assets, including CSS (text/css), JavaScript (application/javascript) and all web fonts, including WOFF2 (font/woff2)
• Images, including JPEG (image/jpg) and PNG (image/png)
• Videos, including H.264, H.265, and MP4 (video/mp4) +. Audio files, including MP3 (image/mpeg) and MP4 (audio/mp4)
• Formatted documents, including PDF (application/pdf)

Important: The static content rules described here apply only to successful responses (for example, HTTP 200 OK responses). By contrast, error responses are cached based on the negative caching settings, regardless of content type.

The following table provides a summary.

Category	MIME types
Web assets	text/css text/ecmascript text/javascript application/javascript
Fonts	Any Content-Type matching font/*
Images	Any Content-Type matching image/*
Videos	Any Content-Type matching video/*
Audio	Any Content-Type matching audio/*
Formatted document types	application/pdf and application/postscript

Cloud CDN inspects the Content-Type HTTP response header, which reflects the MIME type of the content being served.

Note the following:

• Your origin's web server software must set the Content-Type for each response. Many web servers automatically set the Content-Type header, including NGINX, Varnish, and Apache.

• Cloud Storage sets the Content-Type header automatically on upload when you use the Cloud Console or the gsutil tool to upload content.

• If a response is cacheable based on its MIME type but has a Cache-Control response header of private or no-store, or a Set-Cookie header (see the full list of rules), it isn't cached.

Important: Other content types, such as HTML (text/html) and JSON (application/json), are not cached by default for successful responses. These types of responses are typically dynamic (per user). Examples include shopping carts, product pages with user personalization, and authenticated API responses. Negative caching, if enabled, can still cause them to be cached for certain status codes, however.

Cloud CDN doesn't use file extensions in the URL path to determine whether a response is cacheable because many valid cacheable responses aren't reflected in URLs.

If you want to cache text/html and application/json content types, you must set explicit Cache-Control headers in the response, being careful not to accidentally cache one user's data and serve it to all users.

Cacheable content

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

Cloud CDN may periodically change the exact set of conditions under which it caches content. If you want to explicitly prevent Cloud CDN from caching your content, follow the guidelines in RFC 7234 to determine how to specify a guaranteed-uncacheable response. See also the non-cacheable content based on origin headers section.

Cloud CDN stores responses in cache if all of the following are true.

Attribute	Requirement
Served by	Backend service, backend bucket, or an external backend with Cloud CDN enabled
In response to	GET request
Status code	200, 203, 204, 206, 300, 301, 302, 307, 308, 404, 405, 410, 421, 451, or 501.
Freshness	The response has a Cache-Control header with a max-age or s-maxage directive, or an Expires header with a timestamp in the future. For cacheable responses without an age (for example, with no-cache), the public directive must be explicitly provided. With the CACHE_ALL_STATIC cache mode, if no freshness directives are present, a successful response with static content type is still eligible for caching. With the FORCE_CACHE_ALL cache mode, any successful response is eligible for caching. This might result in caching of private, per-user (user identifiable) content. You should only set FORCE_CACHE_ALL on backends that aren't serving private or dynamic content, such as Cloud Storage buckets. If negative caching is enabled and the status code matches one for which negative caching specifies a TTL, the response is eligible for caching, even without explicit freshness directives.
Content	Contains a valid Content-Length, Content-Range, or Transfer-Encoding: chunked header. For example, a Content-Length header that correctly matches the size of the response.
Size	Less than or equal to the maximum size. For responses with sizes between 10 MB and 5 TB, see the additional cacheability constraints described in byte range requests.

For Cloud Storage backend buckets, following are several ways to satisfy these requirements:

• Make your bucket publicly readable. This is the approach that we recommend for public content. With this setting, anyone on the internet can view and list your objects and their metadata, excluding ACLs. The recommended practice is to dedicate specific buckets for public objects. For more information, see Recommended bucket architecture.

• Make the individual objects publicly readable. We don't recommend this approach.

By default, when the entire bucket is public, or the individual objects are public and the individual objects don't specify Cache-Control metadata, Cloud Storage assigns a Cache-Control: public, max-age=3600 header to the object. You can set different values by using Cache-Control metadata.

For an example that shows how to configure an external HTTP(S) load balancer with a backend bucket, see Setting up Cloud CDN with a backend bucket.

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

Maximum size

Cloud CDN enforces a maximum size for each response. Any response with a body larger than the maximum size is not cached but is still delivered to the client.

The maximum size varies depending on whether the origin server supports byte range requests.

Origin server supports byte range requests	Origin server does not support byte range requests
5 TB (5,497,558,138,880 bytes)	10 MB (10,485,760 bytes)

Nearly all modern web servers (including NGINX, Apache, and Varnish) support byte range requests.

Non-cacheable content based on origin headers

There are checks that block caching of responses. Cloud CDN may periodically change the exact set of conditions under which it caches content, so if you want to explicitly prevent Cloud CDN from caching your content, follow the guidelines in the standard (RFC 7234) to determine how to specify a guaranteed-uncacheable response.

Cloud CDN doesn't cache a response if it does not meet the requirements for Cacheable content, or if any of the following is true.

Attribute	Requirement
Served by	Backend service or external backend that doesn't have Cloud CDN enabled
Cookie	Has a Set-Cookie header
Vary header	Has a value other than Accept, Accept-Encoding, or Origin
Response directive	Response has a Cache-Control header with the no-store or private directive (unless using the FORCE_CACHE_ALL cache mode, in which case the Cache-Control header is ignored)
Request directive	Request has a Cache-Control: no-store directive
Request authorization	Request has an Authorization header, unless overridden by the response Cache-Control.
Size	Larger than the maximum size

If Cache-Control: no-store or private is present, but the content is still being cached, this is due to one of the following:

• URL signing is configured.
• The Cloud CDN cache mode is set to force caching of all responses.

Preventing caching

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

1. Make sure that Cloud CDN cache mode isn't set to the FORCE_CACHE_ALL mode, which unconditionally caches all successful responses.
2. 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.
3. Do not sign URLs that provide access to private information. When content is accessed by using a signed URL, it is potentially eligible for caching regardless of any Cache-Control directives in the response.
4. For origin (cache fill) requests that include the Authorization request header, Cloud CDN only caches responses that include the public, must-revalidate, or s-maxage cache control directives when the cache mode is set to USE_ORIGIN_HEADERS or CACHE_ALL_STATIC. This prevents accidentally caching per-user content and/or content that requires authentication. The FORCE_CACHE_ALL cache mode does not have this restriction.

Adding custom response headers

With custom response headers, you can specify headers that the global external HTTP(S) load balancer (classic) adds to proxied responses. Custom response headers let you reflect the cache status to your clients, client geographic data, and your own static response headers.

For the list of headers, see Variables that can appear in the header value.

For instructions, see Working with custom response headers.

Custom response headers are not supported for Cloud CDN deployments on global external HTTP(S) load balancers.

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, and 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.

For backend buckets, the default is for the cache key to consist of the URI without the protocol or host. By default, only query parameters that are known to Cloud Storage are included as part of the cache key (for example, "generation").

Thus, for a given backend bucket, the following URIs resolve to the same cached object:

• http://example.com/images/cat.jpg
• https://example.com/images/cat.jpg
• https://example.com/images/cat.jpg?user=user1
• http://example.com/images/cat.jpg?user=user1
• https://example.com/images/cat.jpg?user=user2
• https://media.example.com/images/cat.jpg
• https://www.example.com/images/cat.jpg

You can change which parts of the URI are used in the cache key. While the filename and path 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.

URI part	Customization	Example URLs that have the same cache key
Protocol	Omit the protocol from the cache key.	https://example.com/images/cat.jpg http://example.com/images/cat.jpg
Host	Omit the host from the cache key.	https://example.com/images/cat.jpg https://example2.com/images/cat.jpg
Query string	Omit the query string from the cache key. Selectively omit or include portions of the query string.	https://example.com/images/cat.jpg?user=user1 https://example.com/images/cat.jpg?user=user2

In addition to including or omitting the entire query string, you can use portions of the query string by using include lists and exclude lists.

Query string include list

You can selectively control which query string parameters Cloud CDN incorporates into cache keys. For example, if you create an include list of user, thenhttps://example.com/images/cat.jpg?user=user1&color=blue creates a cache key of https://example.com/images/cat.jpg?user=user1 that 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 include list, and not specify an exclude list.

Query string include list for Cloud Storage cache keys

Preview

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Note: Make sure that you're using gcloud SDK version 358.0.0 or later.

Including URL query parameters in cache keys for Cloud Storage buckets helps support cache busting. Cache busting is the process of allowing a user to find a new version of the file that has been uploaded, even if the old version is still validly cached by TTL.

You can include-list specific query parameters in the cache key used for serving responses from a backend bucket. Although Cloud Storage does not serve different content or route based on query parameters, you can choose to include parameters that allow you to cache-bust static content stored in Cloud Storage buckets.

For example, you can append a ?version=VERSION or ?hash=HASH query parameter that is based on the underlying content. This limits the need to proactively invalidate content and aligns with modern web development workflows, where web frameworks and URLs use a hash of the content to avoid serving stale objects across deployments.

Because including query parameters in the cache key is opt-in only, Cloud CDN doesn't support excluding query parameters from a cache key to a backend bucket.

Query string exclude list

You can selectively control which query string parameters Cloud CDN ignores by using an exclude list. For example, if you create an exclude list of user, all query string parameters except user are used in the cache key.

With the exclude list 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 that 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 exclude list, and not specify an include list.

Query parameter order

The generated cache key doesn't depend on the order of the query parameters.

For example, the following query parameters generate the same cache key:

• info=123&variant=13e&geography=US
• geography=US&variant=13e&info=123

HTTP headers and HTTP cookies cache key settings

Preview

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Note: Make sure that you're using gcloud SDK version 358.0.0 or later.

You can improve cache hit rates and origin offload with the following cache key configuration settings.

• For backend services and buckets: Use HTTP headers as part of cache keys by including named headers in the cache key configuration.
• For backend services only: Use named HTTP cookies as cache keys, such as for A/B (multivariate) testing, canarying, and similar scenarios.

Note: Increasing the number of unique cache keys can reduce the cache hit rate, especially if there is a large number of possible values.

Cache requests that include additional HTTP headers or HTTP cookies in the request are cached on the third request in a cache location for that cache key. This reduces the impact of high cardinality header/cookie values on your cache eviction rates. Under normal circumstances and user traffic conditions, this should not be noticeable and ensures that popular content remains cached.

Including request headers

To cache additional variations of a response, you can include additional request headers in the cache key.

Some headers are not allowed in cache keys because they are typically very high cardinality. In most cases, the values of these headers are either unique per user (Cookie,Authorization) or have thousands of likely values (Referer, User-Agent, Accept). For example, the User-Agent header can have over 5000 unique values given the large variety of browsers, user-devices, and operating systems. These types of headers would have a severe negative impact on cache hit rates.

Cloud CDN doesn't allow the following headers to be included in the list of headers:

• Accept
• Accept-Encoding
• Authority, because this is controlled by configuration (cdnPolicy.includeHost)
• Authorization, typically per-user as in OAuth Bearer tokens
• CDN-Loop
• Connection
• Content-MD5
• Content-Type
• Cookie
• Date
• Forwarded, often per-client or per-proxy
• From
• Host, because this is controlled by configuration (cdnPolicy.includeHost)
• If-Match, If-Modified-Since, or If-None-Match
• Origin
• Proxy-Authorization
• Range
• Referer (or Referrer)
• User-Agent
• Want-Digest
• X-CSRFToken and X-CSRF-Token as used by Django and Ruby on Rails
• X-Forwarded-For, often per-client or per-proxy
• X-User-IP
• Any header starting with the following:
  • Access-Control-, such as Access-Control-Request-Headers and Access-Control-Request-Method
  • Sec-Fetch-
  • Sec-GFE-
  • Sec-Google-
  • X-Amz-
  • X-GFE-
  • X-Goog-
  • X-Google-

Notes:

• Request header values are used to generate the cache key before any additions or modifications performed with custom headers.
• Only valid HTTP header field names are accepted per RFC 7230.
• Header field names are case-insensitive, and duplicates are rejected.

Same headers with different values

Suppose the user sends multiple same-named headers with different header values—for example:

My-Header: Value1
My-Header: Value2

In this case, Cloud CDN modifies the request by assuming that the header must follow the standard convention that allows some headers to have multiple values. Cloud CDN collapses them into a comma-separated list to send to the backend, so it's as if the client sent the following:

My-Header: Value1, Value2

Including named cookies

Preview

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Note: Make sure that you're using gcloud SDK version 358.0.0 or later.

An HTTP cookie is a name=value pairing, and a request can include multiple HTTP cookies, either separated by a semicolon on the same line, or as discrete Cookie request headers with one cookie per header.

You can provide a list of cookie names (up to 3).

User agents (such as web browsers) often limit the number of cookies stored per domain to 4 KB; make sure not to send too many (or too large) cookies, as the user agent might not send all cookies in a request. This can impact whether a user receives a specific cached response.

If you are serving your static content from a different hostname from which you issue cookies, ensure that the Domain attribute of the cookie (and the Path) attribute allows the cookie to be sent along with requests for static content.

If a request includes multiple instances of the same cookie name, only the first one is honored.

Cache control directives

HTTP cache control directives affect Cloud CDN's behavior, as outlined in the following table.

N/A signifies that a directive is not applicable to a request or response.

Directive	Request	Response
no-store	When present in a request, Cloud CDN honors this and does not store the response in the cache.	A response with no-store isn't cached. This can be overridden on a per-backend basis with the FORCE_CACHE_ALL cache mode.
no-cache	The no-cache request directive is ignored to prevent clients from potentially initiating or forcing revalidation to the origin.	A response with no-cache is cached but must be revalidated with the origin before being served. This can be overridden on a per-backend basis with the FORCE_CACHE_ALL cache mode.
public	N/A	This directive is not required for cacheability, but it is a best practice to include it for content that should be cached by proxies.
private	N/A	A response with the private directive isn't cached by Cloud CDN, even if the response is otherwise considered cacheable. Clients (such as browsers) might still cache the result. This can be overridden on a per-backend basis with the FORCE_CACHE_ALL cache mode. Use no-store to prevent all caching of responses.
max-age=SECONDS	The max-age request directive is ignored. A cached response is returned as if this header was not included in the request.	A response with the max-age directive is cached up to the defined SECONDS.
s-maxage=SECONDS	N/A	A response with the s-maxage directive is cached up to the defined SECONDS. If both max-age and s-maxage are present, s‑maxage is used by Cloud CDN. Responses with this directive aren't served stale. s-max-age (two hyphens) is not valid for the purposes of caching.
min-fresh=SECONDS	The min-fresh request directive is ignored. A cached response is returned as if this header was not included in the request.	N/A
max-stale=SECONDS	The max-stale request directive dictates the maximum staleness (in seconds) that the client is willing to accept. Cloud CDN honors this, and returns a stale cached response only if the staleness of the response is less than the max-stale directive. Otherwise, it revalidates before serving the request.	N/A
stale-while-revalidate=SECONDS	N/A	A response with stale-while-revalidate is served to a client for up to SECONDS while revalidation takes place asynchronously. This behavior can be enabled for all responses by setting cdnPolicy.serveWhileStale on the backend.
stale-if-error=SECONDS	The stale-if-error request directive is ignored. A cached response is returned as if this header was not included in the request.	This response header has no effect.
must-revalidate	N/A	A response with must-revalidate is revalidated with the origin server after it expires. Responses with this directive aren't served stale.
proxy-revalidate		A response with proxy-revalidate is revalidated with the origin server after it expires. Responses with this directive aren't served stale.
immutable	N/A	No effect. This is passed on to the client in the response.
no-transform	N/A	No transforms are applied by Cloud CDN.
only-if-cached	The only-if-cached request directive is ignored. A cached response is returned as if this header was not included in the request.	N/A

Where possible, Cloud CDN endeavors to be RFC-compliant (HTTP RFC 7234), but favors optimizing for cache offload and minimizing the impact that clients can have on hit rate and/or overall origin load.

For responses that use the HTTP/1.1 Expires header:

• The value of the Expires header must be a valid HTTP-date as defined in RFC 7231.
• A date value in the past, an invalid date, or a value of 0 indicates that the content has already expired and requires revalidation.
• If a Cache-Control header is present in the response, Cloud CDN ignores the Expires header.

The presence of a valid, future Expires header in the response lets the response be cached, and does not require other cache directives to be specified.

The HTTP/1.0 Pragma header, if present in a response, is ignored and passed through as-is to the client. Client requests with this header are passed to the origin and do not impact how a response is served by Cloud CDN.

Vary headers

The Vary header indicates that the response varies depending on the client's request headers. In addition to the request URI, Cloud CDN respects Vary headers that origin servers include in responses. 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: */*.

The table in the Non-cacheable content section lists the Vary headers that allow content to be cached. Other Vary header values prevent content from being cached.

The FORCE_CACHE_ALL cache mode does not override this behavior. The Vary headers are important to avoid cache poisoning between multiple possible origin server responses. It would be dangerous for FORCE_CACHE_ALL to cause those responses to be cached.

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

Expiration times and validation requests

A cache entry's expiration time defines how long a cache entry remains valid. The value provided by the s-maxage (or max-age or expires) value allows for automatic revalidation of stale, user-generated cached content.

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 the cache. If the expiration time has passed, Cloud CDN attempts to revalidate the cache entry by contacting one of your backends. This is done before serving the response, unless you enable serve-while-stale, in which case revalidation is performed asynchronously.

For some cache modes, you can set TTL values. For more information, see Using TTL settings and overrides.

The cache mode affects how freshness is determined.

Cache mode	Validation behavior
CACHE_ALL_STATIC	The origin headers (Cache-Control: s-maxage, Cache-Control: max-age, or Expires headers) are consulted to determine freshness. For static content, if origin headers are not present, the configured default_ttl determines freshness. After the static content is older than default_ttl, Cloud CDN revalidates it.
USE_ORIGIN_HEADERS	Each cache entry in a Cloud CDN cache has an expiration time defined by the Cache-Control: s-maxage, Cache-Control: max-age, or Expires headers in accordance with RFC 7234.
FORCE_CACHE_ALL	Instead of origin headers, the configured default_ttl determines freshness. After the content is older than default_ttl, Cloud CDN revalidates it.

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.

By default, when the expiration time value exceeds 30 days (2,592,000 seconds), Cloud CDN treats the expiration value as if it were 2,592,000 seconds. Downstream clients still see the accurate values of max-age and s-maxage, even if they exceed 30 days.

Eviction

There is no guarantee that a cache entry remains in the cache until it expires because unpopular entries can be evicted before they expire at any time to make room for new content. As an upper bound, cache entries that aren't accessed for 30 days are automatically evicted.

For more information, see Eviction and expiration.

Use conditional requests for validation

Cloud CDN can attempt to use the information in the cached response headers to validate the cache entry with the backend. This happens when both of the following are true:

• The previously cached response has a Last-Modified or ETag header.
• The client request is a GET request that does not contain If-Modified-Since or If-None-Match headers.

Cloud CDN performs this validation slightly differently depending on whether the response was cached by using byte range requests:

• If the response was cached by 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 forwards 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 does not have a Last-Modified or an ETag header, Cloud CDN ignores the expired cache entry and forwards the client request to the backend unmodified.

Support for byte range requests

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

• Status code: 200 OK or 206 Partial Content
• Header: Accept-Ranges: bytes
• Header: Content-Length and/or Content-Range
• Header: Last-Modified and/or ETag with a strong validator

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, make sure that they do not have Content-Encoding: gzip metadata. For information about how to edit object metadata, see Viewing and editing object metadata.

Popular web server software also supports byte range requests. Consult your web server software's documentation for details about how to enable support. For more information about byte range requests, see 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).

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 does not forward the client request to the external HTTP(S) load balancer. Instead, the cache initiates 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 doesn'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 doesn't store content that's larger than 1 MB until the second time that content is accessed.

Due to its distributed nature, Cloud CDN might sometimes fetch the final chunk from the origin more than once per location. This only impacts the first few requests per cache key.

Request collapsing (coalescing)

Request collapsing (also called coalescing) actively collapses multiple user-driven cache fill requests for the same cache key into a single origin request per edge node. This can actively reduce the load on the origin, and applies to both item requests (responses fetched directly) and chunk requests, where Cloud CDN uses Range requests to fetch larger objects more efficiently.

Request collapsing is enabled by default.

Collapsed requests behave in the following manner:

• Collapsed requests log both the client-facing request and the (collapsed) cache fill request.
• The leader of the collapsed session is used to make the origin fill request.
• Request attributes that aren't part of the cache key, such as the User-Agent or Accept-Encoding header, only reflect the leader of the collapsed session.
• Requests that do not have the same cache key cannot be collapsed.

The following diagram shows how requests are coalesced:

Cloud CDN with request collapsing enabled (click to enlarge)

In comparison, with request collapsing disabled or for requests that cannot be coalesced, the number of origin requests and responses can be equal to the number of clients attempting to retrieve an object not currently cached.

Cloud CDN without request collapsing enabled (click to enlarge)

For all types of requests, collapsing is enabled by default. For item request types, you can disable collapsing. We recommend disabling collapsing for item requests in highly latency sensitive scenarios, such as ad-serving, where origin load is not a consideration.

The following table summarizes the default behavior and configurability for different request types.

Request type	Default behavior	Configurable	Benefits of collapsing
Chunk requests	Enabled	No	Can significantly reduce origin bandwidth
Item requests	Enabled	Yes	Can reduce origin request volume

To disable item request collapsing using the Cloud SDK for a backend bucket that references a Cloud Storage bucket:

Note: Cloud SDK support for the --request-coalescing flag was introduced in Cloud SDK version 330.0.0.

gcloud

Use the gcloud compute backend-services or backend-buckets command:

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --no-request-coalescing

To enable item request collapsing on a backend bucket using the Cloud SDK:

gcloud

Use the gcloud compute backend-buckets command:

gcloud compute backend-buckets update BACKEND_BUCKET_NAME \
    --request-coalescing

To enable item request collapsing using the Cloud SDK for a backend service, including VM groups and external backends:

gcloud

Use the gcloud compute backend-services command:

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --request-coalescing

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. Cloud CDN can initiate two types of requests: validation requests and byte range requests.

If the response that indicated that 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 by using byte ranges. Otherwise, Cloud CDN forwards your origin server's response to the client. You control expiration times by 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 the cache, Cloud CDN serves whatever it can from the 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. If the content isn't a multiple of that size, the final range is 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 the 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.

In the Cloud Logging httpRequest.userAgent field, Cloud-CDN-Google means that Cloud CDN initiated the request.

Bypassing the cache

Cache bypass allows requests containing specific request headers to bypass the cache, even if the content was previously cached.

This section provides information about bypassing the cache with HTTP headers, such as Pragma and Authorization. This feature is useful when you want to make sure that your users or customers always have the latest content fetched fresh from the origin server. You might want to do this for testing, setting up staging directories, or scripts.

If a specified header matches, the cache is bypassed for all cache mode settings, even FORCE_CACHE_ALL. Cache bypass results in a large number of cache misses if the specified headers are common to many requests.

Before you begin

• Ensure that Cloud CDN is enabled; for instructions, see Using Cloud CDN.

• If necessary, update to the latest version of the Cloud SDK:

  gcloud components update
  

  Note: Make sure that you're using gcloud SDK version 324.0.0 or later.

Configuring cache bypass

You can specify up to five HTTP header names. Values are case-insensitive. The header name must be a valid HTTP header field token. A header name must not appear more than once in the list of added headers. For the rules about valid header names, see How custom headers work.

Console

1. In the Google Cloud Console, go to the Load Balancing page.

   Go to the Load balancing page

2. Click the name of your external HTTP(S) load balancer.
3. Click Edit .
4. In Backend configuration, select a backend and click Edit .
5. Make sure that Enable Cloud CDN is selected.
6. At the bottom of the window, click Advanced configurations.
7. Under Bypass cache on request header, click Add header.
8. Type a header name, such as Pragma or Authorization.
9. Click Update.
10. Click Update again.

gcloud

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --bypass-cache-on-request-headers flag.

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update command with the --bypass-cache-on-request-headers flag.

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --bypass-cache-on-request-headers=BYPASS_REQUEST_HEADER

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --bypass-cache-on-request-headers=BYPASS_REQUEST_HEADER

For example:

gcloud compute backend-services update my-backend-service
    --bypass-cache-on-request-headers=Pragma
    --bypass-cache-on-request-headers=Authorization

api

For backend buckets, use the Method: backendBuckets.insert, Method: backendBuckets.update, or Method: backendBuckets.patch API call.

For backend services, use the Method: backendServices.insert, Method: backendServices.update, or Method: backendServices.patch API call.

For example:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "bypassCacheOnRequestHeaders": [
    {
      "headerName": string
    }
  ]
}

Disabling cache bypass

gcloud

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --no-bypass-cache-on-request-headers flag.

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update command with the --no-bypass-cache-on-request-headers flag.

gcloud compute backend-services (create | update) (BACKEND_SERVICE_NAME | BACKEND_BUCKET_NAME)
    --no-bypass-cache-on-request-headers

api

For backend buckets, use the Method: backendBuckets.insert or Method: backendBuckets.update API call.

For backend services, use the Method: backendServices.insert or Method: backendServices.update API call.

Use one of the following API calls:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets
PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices
PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "fields": "bypassCacheOnRequestHeaders"
}

What's next

• To understand how cache modes make it easier to cache content, see Using cache modes.
• To enable Cloud CDN for your HTTP(S) load balanced instances and storage buckets, see Using Cloud CDN.
• To learn about invalidating caches, see Cache invalidation overview.
• To find GFE points of presence, see Cache locations.