Caching overview Stay organized with collections Save and categorize content based on your preferences.
A cacheable response is an HTTP response that Cloud CDN can store and quicklyretrieve, thus allowing for faster load times. Not all HTTP responses arecacheable.
Cache modes
With cache modes, you can control the factors that determine whetherCloud CDN caches your content.
Cloud CDN offers three cache modes, which define how responsesare cached, whether Cloud CDN respects cache directives sent by theorigin, and howcache TTLs are applied.
The available cache modes are shown in the following table:
| Cache mode | Behavior |
|---|---|
CACHE_ALL_STATIC | Automatically caches successful responses withstatic content that isn't otherwisenon-cacheable. Origin responses that set valid caching directives are also cached. This behavior is thedefault for Cloud CDN-enabled backends created by using the Google Cloud CLI or the REST API. |
USE_ORIGIN_HEADERS | Requires successful origin responses to setvalid cache directives and valid caching headers. Successful 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 (user identifiable) content, such as dynamic HTML or API responses. |
Error responsesmay be cached evenin the absence of valid cache directives.
Before you set the cache mode toFORCE_CACHE_ALL, consider the followingbehaviors:
Forsigned URLs or signed cookies,
FORCE_CACHE_ALLoverrides the maximum age specified through theCacheentry maximum age setting in the Google Cloud console or thegcloud--signed-url-cache-max-ageoption.FORCE_CACHE_ALLchanges the time to live (TTL) of any previously cachedcontent. This change can cause some entries that were previously consideredfresh (due to having longer TTLs from origin headers) to be considered stale,and it can cause some entries that were previously considered stale to beconsidered fresh.FORCE_CACHE_ALLoverrides cache directives (Cache-ControlandExpires)but does not override other origin response headers. In particular, aVaryheader might suppress caching even if the cache mode isFORCE_CACHE_ALL. Formore information, seeVary headers.
For setup instructions, seeSetting the cache mode.
Static content
Static content is content that is always the same, even when accessed bydifferent users. The CSS that you use to style your site, JavaScript to provideinteractivity, video, and image content typically don't change for each user fora given URL (cache key), and thus benefit from being cached acrossCloud CDN's global edge network.
When you set the cache mode toCACHE_ALL_STATIC, and a responsedoes not have explicit caching directives inCache-Control orExpiresheaders, Cloud CDNautomatically caches that response for thefollowing:
- 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 (
audio/mpeg) and MP4 (audio/mp4) - Formatted documents, including PDF (
application/pdf)
200 OK responses). By contrast, error responsesare cached based on thenegative cachingsettings, regardless of content type.The following table provides a summary.
| Category | MIME types |
|---|---|
| Web assets | text/css text/ecmascript text/javascript application/javascript |
| Fonts | AnyContent-Type matchingfont/* |
| Images | AnyContent-Type matchingimage/* |
| Videos | AnyContent-Type matchingvideo/* |
| Audio | AnyContent-Type matchingaudio/* |
| Formatted document types | application/pdf andapplication/postscript |
Cloud CDN inspects theContent-Type HTTP response header, whichreflects theMIMEtypeof the content being served.
Note the following:
Your origin's web server software must set the
Content-Typefor eachresponse. Many web servers automatically set theContent-Typeheader,including NGINX, Varnish, and Apache.Cloud Storage sets the
Content-Typeheaderautomaticallywhen you use the Google Cloud console or the Google Cloud CLI to upload content.Cloud Storage always provides a
Cache-Controlheader toCloud CDN. If no value is explicitly chosen, it sends a default value.As a result, all successful Cloud Storage responses are cachedaccording to Cloud Storage default values, unless you explicitlyadjust thecache control metadata forobjects in Cloud Storage or useFORCE_CACHE_ALLmode to overridethe values sent by Cloud Storage.If you want to cache
text/htmlandapplication/jsoncontent types, youmust setexplicitCache-Controlheaders in the response,being careful not to accidentally cache one user's data and serve it to allusers.
If a response is cacheable based on its MIME type but has aCache-Controlresponse header ofprivate orno-store, or aSet-Cookieheader, it isn't cached. To learn more, seecacheability rules.
Other content types, such as HTML (text/html) and JSON(application/json), are not cached by default for successful responses. Thesetypes of responses are typically dynamic (per user). Examples include shoppingcarts, product pages with user personalization, and authenticated APIresponses.Negative caching, if enabled, canstill cause them to be cached for certain status codes, however.
Cloud CDN doesn't use file extensions in the URL path to determinewhether a response is cacheable because many valid cacheable responses aren'treflected in URLs.
Cacheable content
Cloud CDN caches responses that meet all of the requirements inthis section. Some of these requirements are specified byRFC7234, and others arespecific to Cloud CDN.
Cloud CDN may periodically change the exact set of conditions underwhich it caches content. If you want to explicitly prevent Cloud CDNfrom caching your content, follow the guidelines in RFC 7234 todetermine how to specify a guaranteed-uncacheable response. See also thenon-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 |
|
| Freshness | The response has a For cacheable responses without an age (for example, with With the With the Ifnegative 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 | For HTTP/1 origins, the response must contain a valid For origins that use more advanced HTTP protocol versions (HTTP/2 and later), the response need not have such headers. |
| Size | Less than or equal to themaximum size. For responses with sizes between 10 MiB and 100 GiB, see the additional cacheability constraints described inbyte range requests. |
For Cloud Storage backend buckets, follow these additional suggestions:
Make your bucket publicly readable.This is the approach that we recommend for public content. With thissetting, anyone on the internet can view and list your objects and theirmetadata, excluding ACLs. The recommended practice is to dedicate specificbuckets for public objects.
Usemanaged folders tomake a portion of your bucket publicly readable.
Make individual objects publicly readable.We don't recommend this approach, because it uses a legacy,Cloud Storage-specific permissioning system.
Don't store the object in a bucket that hasRequester Pays enabledor resides within aVirtual Private Cloud service perimeter.
Don't encrypt the object by usingcustomer-managed encryption keys orcustomer-supplied encryption keys.
By default, when an object is public and doesn't specifyCache-Controlmetadata, Cloud Storage assigns aCache-Control: public, max-age=3600header to the object. You can set different values by usingCache-Control metadata.
For an example that shows how to configure an external Application Load Balancer with a backendbucket, seeSetting up Cloud CDN with a backendbucket.
Note: If you want to keep your content private, useprivate origin authenticationorsigned URLs.Maximum size
Cloud CDN enforces a maximum size for each response. Any response witha body larger than the maximum size is not cached but is still delivered to theclient.
The maximum size varies depending on whether the origin server supportsbyterange requests.
| Origin server supports byte range requests | Origin server does not support byte range requests |
|---|---|
| 100 GiB (107,374,182,400 bytes) | 10 MiB (10,485,760 bytes) |
Nearly all modern web servers (including NGINX, Apache, and Varnish) supportbyte range requests.
Non-cacheable content based on origin headers
There are checks that block caching of responses. Cloud CDN mayperiodically change the exact set of conditions under which it caches content,so if you want to explicitly prevent Cloud CDNfrom caching your content, follow the guidelines in the standard (RFC7234) to determine how to specify aguaranteed-uncacheable response.
Cloud CDN doesn't cache a response if it does not meet the requirementsforCacheable 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 aSet-Cookie header |
Vary header | Has a value other thanAccept,Accept-Encoding,Access-Control-Request-Headers,Access-Control-Request-Method,Origin,Sec-Fetch-Dest,Sec-Fetch-Mode,Sec-Fetch-Site,X-Goog-Allowed-Resources,X-Origin, or one of the headers that are configured to be part of thecache key settings. |
| Response directive | Response has aCache-Control header with theno-store orprivate directive (unless using theFORCE_CACHE_ALL cache mode, in which case theCache-Control header is ignored) |
| Request directive | Request has aCache-Control: no-store directive |
| Request authorization | Request has anAuthorization header, unlessoverridden by the response Cache-Control. |
| Size | Larger than themaximum size |
IfCache-Control: no-store orprivate is present, but thecontent 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.
Prevent caching
To prevent private information from being cached in Cloud CDNcaches, do the following:
- Make sure that Cloud CDN cache mode isn't set to the
FORCE_CACHE_ALLmode, which unconditionally caches all successfulresponses. - Include a
Cache-Control: privateheader in responses that shouldn't bestored in Cloud CDN caches, or aCache-Control: no-storeheader in responses that shouldn't be stored in any cache, even a webbrowser's cache. - Don'tsign URLs that provide access to privateinformation. When content is accessed by using a signed URL, it is potentiallyeligible for caching regardless of any
Cache-Controldirectives in theresponse. - For origin (cache fill) requests that include the
Authorizationrequestheader, Cloud CDN only caches responses that include thepublic,must-revalidate, ors-maxagecache control directives when the cache modeis set toUSE_ORIGIN_HEADERSorCACHE_ALL_STATIC. This preventsaccidentally caching per-user content and content that requiresauthentication. TheFORCE_CACHE_ALLcache mode does not have thisrestriction.
Custom response headers
Withcustom response headers,you can specify headers that the classic Application Load Balancer adds to proxiedresponses. Custom response headers let you reflect the cache status to yourclients, client geographic data, and your own static response headers.
For instructions, seeConfigure custom response headers.
Cache keys
Each cache entry in a Cloud CDN cache is identified by acachekey. When a request comes into the cache, the cache converts the URI of therequest 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 aparticular request for thecat.jpg object. This string is used as the defaultcache key. Only requests with this exact string match. Requests forhttp://example.com/images/cat.jpg orhttps://example.com/images/cat.jpg?user=user1 don't match.
For backend buckets, the default is for the cache key to consist of the URIwithout the protocol or host. By default, only query parameters that are knownto 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 cachedobject:
http://example.com/images/cat.jpghttps://example.com/images/cat.jpghttps://example.com/images/cat.jpg?user=user1http://example.com/images/cat.jpg?user=user1https://example.com/images/cat.jpg?user=user2https://media.example.com/images/cat.jpghttps://www.example.com/images/cat.jpg
You can change which parts of the URI are used in the cache key. While thefilename and path must always be part of the key, you can include or omit anycombination of protocol, host, or query string when customizing your cache key.Using cache keys describes how to customize yourcache keys.
| URI part | Customization | Example URLs that have the same cache key |
|---|---|---|
| Protocol | Omit the protocol from the cache key. |
|
| Host | Omit the host from the cache key. |
|
| Query string | Omit the query string from the cache key. Selectively omit or include portions of the query string. |
|
In addition to including or omitting the entire query string, you can useportions of the query string by using include lists and exclude lists.
Query string include list
You can selectively control which query string parameters Cloud CDNincorporates into cache keys. For example, if you create an include list ofuser, thenhttps://example.com/images/cat.jpg?user=user1&color=bluecreates a cache key ofhttps://example.com/images/cat.jpg?user=user1 thatalso matcheshttps://example.com/images/cat.jpg?user=user1&color=red.
To use this option, you must include the query string, specify anon-empty include list, andnot specify an exclude list.
Query string include list for Cloud Storage cache keys
Note: Make sure that you're using gcloud CLI version369.0.0 or later.Including URL query parameters in cache keys for Cloud Storage bucketshelps supportcache busting. Cache busting lets a user retrieve a new versionof the file that has been uploaded, even if the earlier version is still validlycached based on the TTL setting.
You can use an include list with query string parameters in the cache key used forserving responses from a backend bucket. Although Cloud Storage doesnot serve different content or route based on query parameters, you can chooseto include parameters that allow you to cache-bust static content stored inCloud Storage buckets.
For example, you can append a?version=VERSION or?hash=HASH query parameterthat is based on the underlying content. This limits the need to proactivelyinvalidate content and aligns with modern web development workflows, where webframeworks and URLs use a hash of the content to avoid serving stale objectsacross deployments.
Because including query parameters in the cache key is opt-in only,Cloud CDN doesn't support excluding query parameters from a cache keyto a backend bucket.
Query string exclude list
You can selectively control which query string parameters Cloud CDNignores by using an exclude list. For example, if you create an exclude list ofuser, all query string parametersexceptuser are used in the cache key.
With the exclude list configured and an input ofhttps://example.com/images/cat.jpg?user=user1&color=blue, Cloud CDNcreates a cache key ofhttps://example.com/images/cat.jpg?color=blue that alsomatcheshttps://example.com/images/cat.jpg?user=user2&color=blue but nothttps://example.com/images/cat.jpg?user=user1&color=red.
To use this option, you must include the query string, specify a non-emptyexclude list, andnot 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=USgeography=US&variant=13e&info=123
HTTP headers and HTTP cookies settings
Note: Make sure that you're using gcloud CLI version 369.0.0 or later.You can improve cache hit rates and origin offload with the following cache keyconfiguration settings:
- For backend services and buckets: Use HTTP headers as part of cachekeys by including named headers in the cache key configuration.
- For backend services only: Use named HTTP cookies as cache keys, such asfor A/B (multivariate) testing, canarying, and similar scenarios.
Cache requests that include additional HTTP headers or HTTP cookies in therequest are cached on the third request in a cache location for that cache key.This reduces the impact of high-cardinality header or cookie values on yourcache eviction rates. Under normal circumstances and user traffic conditions,this shouldn't be noticeable and helps ensure that popular content remainscached.
Include request headers
To cache additional variations of a response, you can include additional requestheaders in the cache key.
Some headers are not allowed in cache keys because they aretypically very high cardinality. In most cases, the values of these headers areeither unique per user (Cookie,Authorization) or have thousands of likelyvalues (Referer,User-Agent,Accept). For example, theUser-Agent headercan have over 5,000 unique values given the large variety of browsers,user-devices, and operating systems. These types of headers would have asevere negative impact on cache hit rates.
Only valid HTTP header field names are accepted perRFC 7230.Header field names are case-insensitive, and duplicates are rejected.
You may optionally configure your origin server to include configured cache-keyrequest headers in theVary response. It is not required forCloud CDN, but can be helpful for downstream caches. For moreinformation, seeVary headers.
Cloud CDN doesn't allow the following headers to be included in thelist of headers:
AcceptAccept-EncodingAuthority, because this is controlled by configuration (cdnPolicy.includeHost)Authorization, typically per-user as in OAuthBearertokensCDN-LoopConnectionContent-MD5Content-TypeCookieDateForwarded, often per-client or per-proxyFromHost, because this is controlled by configuration (cdnPolicy.includeHost)If-Match,If-Modified-Since, orIf-None-MatchOriginProxy-AuthorizationRangeReferer(orReferrer)User-AgentWant-DigestX-CSRFTokenandX-CSRF-Tokenas used by Django and Ruby on RailsX-Forwarded-For, often per-client or per-proxyX-User-IP- Any header starting with the following:
Access-Control-, such asAccess-Control-Request-HeadersandAccess-Control-Request-MethodSec-Fetch-Sec-GFE-Sec-Google-X-Amz-X-GFE-X-Goog-X-Google-
Use custom variables with request headers
Cache keys are helpful when you need to serve content differently basedon each user's device and location. For example, you can enable a responsivewebsite to serve the appropriate images for users that are viewing contentbased on their device type or set a helpful default language based on their location.You can define cache keys by using custom request headers and custom variables.
To use custom variables with request headers, do the following:
- Define a custom request headerfor your backend service. Include one or more variables for the customrequest header value.
- Update the cache keyto use the custom request header.
For Cloud CDN, you can use only the following variables when definingheaders that are both custom request headers and cache key headers:
device_request_typeuser_agent_familyclient_regionclient_region_subdivision
Cloud CDN limits the variables to help maintain cache performance.This is similar to limits on theheaders that can be used as cache keys.
For example, if you could specifyX-Lat-Long:{client_city_lat_long} as acustom request header and then addX-Lat-Long to your set of cache keyheaders, Cloud CDN would attempt to cache one copy of the response foreach value ofclient_city_lat_long. This would ultimately lead to cacheoveruse, unnecessary content flushing, and reduced opportunity to return cachehits.
For these reasons, variables that have high cardinality aren't included in thelist of variables that are used to define custom request headers andsubsequently cache keys.
Same headers with different values
Suppose the user sends multiple same-named headers with different headervalues—for example:
My-Header: Value1My-Header: Value2In this case, Cloud CDN modifies the request by assuming that theheader must follow the standard convention that allows some headers to havemultiple values. Cloud CDN collapses them into a comma-separated listto send to the backend, so it's as if the client sent the following:
My-Header: Value1, Value2Include named cookies
Note: Make sure that you're using gcloud CLI version369.0.0 or later.An HTTP cookie is aname=value pairing, and a request can includemultiple HTTP cookies, either separated by a semicolon on the same line, oras discreteCookie request headers with one cookie per header.
You can provide a list of up to five cookie names.
User agents (such as web browsers) often limit the number of cookiesstored 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 arequest. This can impact whether a user receives a specific cached response.
If you are serving your static content from a different hostname from which youissue cookies, ensure that theDomain attribute of the cookie(and thePath) attribute allows the cookie to be sent along with requestsfor static content.
If a request includes multiple instances of the same cookie name, only the firstone is honored.
Cache control directives
HTTP cache control directives affect Cloud CDN's behavior, as outlinedin 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 This can be overridden on a per-backend basis with the |
no-cache | Theno-cache request directive is ignored to prevent clients from potentially initiating or forcing revalidation to the origin. | A response with This can be overridden on a per-backend basis with the |
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 This can be overridden on a per-backend basis with the |
max-age=SECONDS | Themax-age request directive is ignored. A cached response is returned as if this header was not included in the request. | A response with themax-age directive is cached up to the definedSECONDS. |
s-maxage=SECONDS | N/A | A response with the If both Responses with this directive aren't served stale.
|
min-fresh=SECONDS | Themin-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 Cloud CDN honors this, and returns a stale cached response only if the staleness of the response is less than the | N/A |
stale-while-revalidate=SECONDS | N/A | A response with This behavior can be enabled for all responses by setting |
stale-if-error=SECONDS | Thestale-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 Responses with this directive aren't served stale. |
proxy-revalidate | A response with 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 | Theonly-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 RFC7234), but favors optimizing for cache offload and minimizing the impact thatclients can have on hit rate and overall origin load.
For responses that use the HTTP/1.1Expires header:
- The value of the
Expiresheader must be a valid HTTP-date asdefined in RFC 7231. - A date value in the past, an invalid date, or a value of
0indicates that thecontent has already expired and requires revalidation. - If a
Cache-Controlheader is present in the response,Cloud CDN ignores theExpiresheader.
The presence of a valid, futureExpires header in the response lets theresponse be cached, and does not require other cache directives to be specified.
The HTTP/1.0Pragma header, if present in a response, is ignored andpassed through as-is to the client. Client requests with this header arepassed to the origin and don't impact how a response is served byCloud CDN.
Vary headers
TheVaryheader indicates that the response varies depending on the client'srequest headers. In addition to the request URI, Cloud CDN respectsVary headers that origin servers include in responses. For example, if aresponse specifiesVary: Accept, Cloud CDN uses one cache entry forrequests that specifyAccept: image/webp,image/*,*/*;q=0.8 and another forrequests that specifyAccept: */*.
The table in theNon-cacheable content section liststheVary headers that allow content to be cached. OtherVary header valuesprevent content from being cached.
TheFORCE_CACHE_ALL cache mode doesnot override this behavior. TheVaryheaders are important to avoid cache poisoning between multiple possible originserver responses. It would be dangerous forFORCE_CACHE_ALL to cause thoseresponses to be cached.
Vary headers are sometimes used when serving compressed content.Cloud CDN does not compress or decompress responses itself (unlessdynamic compression isenabled), but it can serve responses that the origin server has compressed. If yourorigin server chooses whether to serve compressed content or uncompressed content basedon the value of theAccept-Encoding request header, make sure that theresponse specifiesVary: Accept-Encoding.
When usingHTTP headers in the cache key,Cloud CDN caches multiple copies of the response based on the valuesof the specified request headers, similar toVary support but without theneed for the origin server to explicitly specify anyVary response header.If the origin does specify the cache-key headers in theVary response,Cloud CDN treats the response correctly, the same as if theheaders were not mentioned in theVary response.
Expiration times and validation requests
A cache entry's expiration time defines how long a cache entry remains valid.The value provided by thes-maxage (ormax-age orexpires) value allowsfor automatic revalidation of stale, user-generated cached content.
When Cloud CDN receives a request, it looks up the correspondingcache 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 haspassed, Cloud CDN attempts to revalidate the cache entry by contactingone of your backends. This is done before serving the response, unless youenableserve-while-stale, inwhich case revalidation is performed asynchronously.
For some cache modes, you can set TTL values. For more information, seeUsing 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, orExpires headers) are consulted to determine freshness. For static content, if origin headers are not present, the configureddefault_ttl determines freshness. After the static content is older thandefault_ttl, Cloud CDN revalidates it. |
USE_ORIGIN_HEADERS | Each cache entry in a Cloud CDN cache has an expiration time defined by theCache-Control: s-maxage,Cache-Control: max-age, orExpires headers in accordance with RFC 7234. |
FORCE_CACHE_ALL | Instead of origin headers, the configureddefault_ttl determines freshness. After the content is older thandefault_ttl, Cloud CDN revalidates it. |
If more than one is present,Cache-Control: s-maxage takesprecedence overCache-Control: max-age, andCache-Control: max-age takes precedence overExpires.
By default, when the expiration time value exceeds 30 days (2,592,000seconds), Cloud CDN treats the expiration value as if it were 2,592,000seconds. Downstream clients still see the accurate values ofmax-age ands-maxage, even if they exceed 30 days.
Eviction
There is no guarantee that a cache entry remains in the cache until it expiresbecause unpopular entries can be evicted before they expireat any time tomake room for new content. As an upper bound, cache entries that aren't accessedfor 30 days are automatically evicted.
For more information, seeEviction and expiration.
Use conditional requests for validation
Cloud CDN can attempt to use the information in the cached responseheaders to validate the cache entry with the backend. This happens whenboth of the following are true:
- The previously cached response has a
Last-ModifiedorETagheader. - The client request is a
GETrequest that does not containIf-Modified-SinceorIf-None-Matchheaders.
Cloud CDN performs this validation slightly differently depending onwhether the response was cached by usingbyte rangerequests:
- If the response was cached by using byte range requests, Cloud CDNinitiates a separate validation request that includes
If-Modified-SinceandIf-None-Matchheaders. - Otherwise, Cloud CDN adds
If-Modified-SinceandIf-None-Matchheaders to the client request and forwards the modified requestto the backend.
If the cached copy is still up to date, the backend can validate the existingcache entry by sending a304 Not Modified response. In this case, the backendsends only the response headers, not the response body. Cloud CDNinserts 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 aLast-Modified or anETagheader, Cloud CDN ignores the expired cache entry and forwardsthe client request to the backend unmodified.
Support for byte range requests
A response that satisfies the following criteria indicates that the originserver supports byte range requests:
- Status code:
200 OKor206 Partial Content - Header:
Accept-Ranges: bytes - Header:
Content-Length, and for a206 Partial Contentresponse, aContent-Rangevalue that indicates the complete length of the origin object.For example,Content-length: 0-100/999is cacheable whereasContent-length: 0-100/*isn't. - Header:
Last-ModifiedandETagwith a strong validator.
Cloud Storage supports byte range requests for most objects. However,Cloud Storage does not support byte range requests for objects withContent-Encoding: gzip metadata unless the client request includes anAccept-Encoding: gzip header. If you have Cloud Storage objects larger than10 MB, make sure that they don't haveContent-Encoding: gzipmetadata. For information about how to edit object metadata, seeViewing andediting object metadata.
Popular web server software also supports byte range requests. Consult thedocumentation for your web server for details about how to enable support. Formore information about byte range requests, see theHTTP specification.
When an origin server supports byte range requests, a Cloud CDNcache declines to store an otherwise cacheable response the first time it isrequested if either of the following is true:
- The response body is incomplete because the client requested only part of thecontent.
- The response body is larger than 1 MB (1,048,576 bytes).
When this happens and the response would otherwise satisfy the normalcacheability requirements, the cache records that the originserver supports byte range requests for that cache key and forwards the originserver's response to the client.
On a cache miss, the cache checks whether the origin server is known to supportbyte range requests. If byte range requests are known to be supported for thecache key, the cache does not forward the client request to the external Application Load Balancer.Instead, the cache initiates its own byte range cache fillrequests for the missing parts of the content.
The origin server returns a206 Partial Content response whenCloud CDN initiates its own byte range cache fill request. For a206 Partial Content response to be considered while caching, it must includeaContent-Range header with acomplete-length directive that doesn'tinclude asterisks, for example,0-100/999. Cloud CDN then caches thatreturned206 Partial Content response and uses it to respond to future clientrequests for that content.
A cache stores a206 Partial Content response only when it is received inresponse to a byte range request that the cache initiated. Because a cachedoesn't initiate a byte range request unless it had previously recorded that theorigin server supports byte range requests for that cache key, a given cachedoesn't store content that's larger than 1 MB until the second time thatcontent is accessed.
Due to its distributed nature, Cloud CDN might sometimes fetch thefinal chunk from the origin more than once per location. This only impacts thefirst few requests per cache key.
Request collapsing (coalescing)
Request collapsing (also calledcoalescing) actively collapses multipleuser-driven cache fill requests for the same cache key into a single originrequest per edge node. This can actively reduce the load on the origin, andapplies to bothitem requests (responses fetched directly) andchunk requests, whereCloud CDN usesRange requests to fetch larger objects moreefficiently.
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.
- Theleader of the collapsed session is used to makethe origin fill request.
- Request attributes that aren't part of the cache key,such as the
User-AgentorAccept-Encodingheader, only reflect theleader of the collapsed session. - Requests that don't have the same cache key cannot be collapsed.
The following diagram shows how requests are coalesced:
In comparison, with request collapsing disabled or for requests that cannot becoalesced, the number of origin requests andresponses can be equal to thenumber of clients attempting to retrieve an object that's not cached.
For all types of requests, collapsing is enabled by default. For item requesttypes, you can disable collapsing. We recommend disabling collapsing for itemrequests in highly latency sensitive scenarios, such as ad-serving, where originload is not a consideration.
The following table summarizes the default behavior and configurability fordifferent 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 |
Todisable item request collapsing using the Google Cloud CLI for a backend bucketthat references a Cloud Storage bucket:
Note: Google Cloud CLI support for the--request-coalescing flag was introducedin Google Cloud CLIversion 330.0.0.gcloud
Use thegcloud compute backend-services orbackend-buckets command:
gcloud compute backend-services updateBACKEND_SERVICE_NAME \ --no-request-coalescing
To enable item request collapsing on a backend bucket using the Google Cloud CLI:
gcloud
Use thegcloud compute backend-buckets command:
gcloud compute backend-buckets updateBACKEND_BUCKET_NAME \ --request-coalescing
To enable item request collapsing using the Google Cloud CLI for a backend service,including VM groups and external backends:
gcloud
Use thegcloud compute backend-services command:
gcloud compute backend-services updateBACKEND_SERVICE_NAME \ --request-coalescing
Requests initiated by Cloud CDN
When your origin server supportsbyte range requests,Cloud CDN can send multiple requests to your origin server in reactionto a single client request. Cloud CDN can initiate two types ofrequests: validation requests and byte range requests.
If the response that indicated that your origin server supported byte range requestsfor a particular cache key has expired, Cloud CDN initiatesa validation request to confirm that the content hasn't changed and that yourorigin server still supports range requests for the content. If your originserver responds with a304 Not Modified response, Cloud CDNproceeds to serve the content by using byte ranges. Otherwise,Cloud CDN forwards your origin server's response to theclient. You control expiration times by using theCache-Control andExpiresresponse headers.
On a cache miss, Cloud CDN initiates cache fill requests for aset of byte ranges that overlap the client request. If some ranges of thecontent requested by the client are present in the cache,Cloud CDN serves whatever it can from the cache and sends byterange requests for only the missing ranges to your origin server.
Each byte range request initiated by Cloud CDN specifies a rangethat begins at an offset that's a multiple of 2,097,136 bytes. With the possibleexception of the final range, each range is also 2,097,136 bytes. Ifthe content isn't a multiple of that size, the final range is smaller. Thesize 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,999of content that is not present in the cache. In this example,Cloud CDN could initiate two GET requests, one for the first2,097,136 bytes of the content and another for the second 2,097,136 bytes. Thisresults in 4,194,272 bytes of cache fill even though the client requested only3,000,000 bytes.
When you use a Cloud Storage bucket as your origin, each GET request isbilled as a separateClass B operation.You are charged for all GET requests processed by Cloud Storage,including any requests initiated by Cloud CDN. When a response isserved entirely from a Cloud CDN cache, no GET requests are sent toCloud Storage, and you are not charged for any Cloud Storageoperations.
When Cloud CDN initiates a validation request or byte rangerequest, it does not include client-specific headers such asCookie orUser-Agent.
In the Cloud LogginghttpRequest.userAgent field,Cloud-CDN-Google means that Cloud CDN initiated the request.
Bypass the cache
Cache bypass allows requests containing specific request headers to bypass thecache, even if the content was previously cached.
This section provides information about bypassing the cache with HTTP headers,such asPragma andAuthorization. This feature is useful when you want tomake sure that your users or customers always have the latest content fetchedfresh from the origin server. You might want to do this for testing, setting upstaging directories, or scripts.
If a specified header matches, the cache is bypassed for all cache modesettings, evenFORCE_CACHE_ALL. Cache bypass results in a large number ofcache misses if the specified headers are common to many requests.
Before you begin
Ensure that Cloud CDN is enabled; for instructions, seeUsing Cloud CDN.
If necessary, update to the latest version of the Google Cloud CLI:
Note: Make sure that you're using gcloud CLI versiongcloud components update
324.0.0or later.
Configure cache bypass
You can specify up to five HTTP header names. Values are case-insensitive.The header name must be avalid HTTP header fieldtoken.A header name must not appear more than once in the list of added headers. Forthe rules about valid header names, seeHow custom headerswork.
Console
- In the Google Cloud console, go to theLoad Balancing page.
- Click the name of your external Application Load Balancer.
- ClickEdit.
- InBackend configuration, select a backend and clickEdit.
- Make sure thatEnable Cloud CDN is selected.
- At the bottom of the window, clickAdvanced configurations.
- UnderBypass cache on request header, clickAdd header.
- Type a header name, such as
PragmaorAuthorization. - ClickUpdate.
- ClickUpdate again.
gcloud
For backend buckets, use thegcloud compute backend-bucketscreate orgcloud compute backend-bucketsupdate commandwith the--bypass-cache-on-request-headers flag.
For backend services, use thegcloud compute backend-servicescreate orgcloud compute backend-servicesupdate commandwith 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 theMethod: backendBuckets.insert,Method: backendBuckets.update,orMethod: backendBuckets.patchAPI call.
For backend services, use theMethod: backendServices.insert,Method: backendServices.update,orMethod: backendServices.patchAPI 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 } ]}Disable cache bypass
gcloud
For backend buckets, use thegcloud compute backend-bucketscreate orgcloud compute backend-bucketsupdate commandwith the--no-bypass-cache-on-request-headers flag.
For backend services, use thegcloud compute backend-servicescreate orgcloud compute backend-servicesupdate commandwith 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 theMethod: backendBuckets.insert orMethod: backendBuckets.updateAPI call.
For backend services, use theMethod: backendServices.insert orMethod: backendServices.updateAPI call.
Use one of the following API calls:
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBucketsPUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKETPOST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServicesPUT 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, seeUsingcache modes.
- To enable Cloud CDN for your HTTP(S) load balanced instances andstorage buckets, seeUsing Cloud CDN.
- To learn about invalidating caches, seeCache invalidationoverview.
- To find GFE points of presence, seeCache locations.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.