Caching overview

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 modeBehavior
CACHE_ALL_STATICAutomatically 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_HEADERSRequires successful origin responses to setvalid cache directives and valid caching headers. Successful responses without these directives are forwarded from the origin.
FORCE_CACHE_ALLUnconditionally 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_ALL overrides the maximum age specified through theCacheentry maximum age setting in the Google Cloud console or thegcloud--signed-url-cache-max-age option.

  • FORCE_CACHE_ALL changes 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_ALL overrides cache directives (Cache-Control andExpires)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)
Important: The static content rules described here apply only to successfulresponses (for example, HTTP200 OK responses). By contrast, error responsesare cached based on thenegative cachingsettings, regardless of content type.

The following table provides a summary.

CategoryMIME types
Web assetstext/css text/ecmascript text/javascript application/javascript
FontsAnyContent-Type matchingfont/*
ImagesAnyContent-Type matchingimage/*
VideosAnyContent-Type matchingvideo/*
AudioAnyContent-Type matchingaudio/*
Formatted document typesapplication/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 theContent-Type for eachresponse. Many web servers automatically set theContent-Type header,including NGINX, Varnish, and Apache.

  • Cloud Storage sets theContent-Type headerautomaticallywhen you use the Google Cloud console or the Google Cloud CLI to upload content.

  • Cloud Storage always provides aCache-Control header 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_ALL mode to overridethe values sent by Cloud Storage.

  • If you want to cachetext/html andapplication/json content types, youmust setexplicitCache-Control headers 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.

AttributeRequirement
Served byBackend service, backend bucket, or an external backend with Cloud CDN enabled
In response toGET request
Status code

200,203,204,206,300,301,302,307,308,404,405,410,421,451, or501.

Freshness

The response has aCache-Control header with amax-age ors-maxage directive, or anExpires header with a timestamp in the future.

For cacheable responses without an age (for example, withno-cache), thepublic directive must be explicitly provided.

With theCACHE_ALL_STATIC cache mode, if no freshness directives are present, a successful response with static content type is still eligible for caching.

With theFORCE_CACHE_ALL cache mode, any successful response is eligible for caching. This might result in caching of private, per-user content. You should only setFORCE_CACHE_ALL on backends that aren't serving private or dynamic content, such as Cloud Storage buckets.

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 validContent-Length,Content-Range, orTransfer-Encoding: chunked header.

For origins that use more advanced HTTP protocol versions (HTTP/2 and later), the response need not have such headers.

SizeLess 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:

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 requestsOrigin 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.

AttributeRequirement
Served byBackend service or external backend that doesn't have Cloud CDN enabled
CookieHas aSet-Cookie header
Vary headerHas 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 directiveResponse 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 directiveRequest has aCache-Control: no-store directive
Request authorizationRequest has anAuthorization header, unlessoverridden by the response Cache-Control.
SizeLarger 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:

  1. Make sure that Cloud CDN cache mode isn't set to theFORCE_CACHE_ALL mode, which unconditionally caches all successfulresponses.
  2. Include aCache-Control: private header 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.
  3. Don'tsign URLs that provide access to privateinformation. When content is accessed by using a signed URL, it is potentiallyeligible for caching regardless of anyCache-Control directives in theresponse.
  4. For origin (cache fill) requests that include theAuthorization requestheader, Cloud CDN only caches responses that include thepublic,must-revalidate, ors-maxage cache control directives when the cache modeis set toUSE_ORIGIN_HEADERS orCACHE_ALL_STATIC. This preventsaccidentally caching per-user content and content that requiresauthentication. TheFORCE_CACHE_ALL cache 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.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 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 partCustomizationExample URLs that have the same cache key
ProtocolOmit the protocol from the cache key.
  • https://example.com/images/cat.jpg
  • http://example.com/images/cat.jpg
HostOmit 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 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=US
  • geography=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.
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 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:

  • Accept
  • Accept-Encoding
  • Authority, because this is controlled by configuration (cdnPolicy.includeHost)
  • Authorization, typically per-user as in OAuthBearer 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, orIf-None-Match
  • Origin
  • Proxy-Authorization
  • Range
  • Referer (orReferrer)
  • User-Agent
  • Want-Digest
  • X-CSRFToken andX-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 asAccess-Control-Request-Headers andAccess-Control-Request-Method
    • Sec-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:

  1. Define a custom request headerfor your backend service. Include one or more variables for the customrequest header value.
  2. 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_type
  • user_agent_family
  • client_region
  • client_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: Value2

In 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, Value2

Include 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.

DirectiveRequestResponse
no-store When present in a request, Cloud CDN honors this and does not store the response in the cache.

A response withno-store isn't cached.

This can be overridden on a per-backend basis with theFORCE_CACHE_ALL cache mode.

no-cacheTheno-cache request directive is ignored to prevent clients from potentially initiating or forcing revalidation to the origin.

A response withno-cache is cached but must be revalidated with the origin before being served.

This can be overridden on a per-backend basis with theFORCE_CACHE_ALL cache mode.

publicN/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.

privateN/A

A response with theprivate 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 theFORCE_CACHE_ALL cache mode. Useno-store to prevent all caching of responses.

max-age=SECONDSThemax-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=SECONDSN/A

A response with thes-maxage directive is cached up to the definedSECONDS.

If bothmax-age ands-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=SECONDSThemin-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

Themax-stale request directive dictates the maximumstaleness (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 themax-stale directive. Otherwise, it revalidates before serving the request.

N/A
stale-while-revalidate=SECONDSN/A

A response withstale-while-revalidate is served to a client for up toSECONDS while revalidation takes place asynchronously.

This behavior can be enabled for all responses by settingcdnPolicy.serveWhileStale on the backend.

stale-if-error=SECONDSThestale-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-revalidateN/A

A response withmust-revalidate is revalidated with the origin server after it expires.

Responses with this directive aren't served stale.

proxy-revalidate

A response withproxy-revalidate is revalidated with the origin server after it expires.

Responses with this directive aren't served stale.

immutableN/ANo effect. This is passed on to the client in the response.
no-transformN/ANo transforms are applied by Cloud CDN.
only-if-cachedTheonly-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 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 modeValidation behavior
CACHE_ALL_STATICThe 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_HEADERSEach 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_ALLInstead 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 aLast-Modified orETag header.
  • The client request is aGET request that does not containIf-Modified-Since orIf-None-Match headers.

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 includesIf-Modified-SinceandIf-None-Match headers.
  • Otherwise, Cloud CDN addsIf-Modified-Since andIf-None-Match headers 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 OK or206 Partial Content
  • Header:Accept-Ranges: bytes
  • Header:Content-Length, and for a206 Partial Content response, aContent-Range value that indicates the complete length of the origin object.For example,Content-length: 0-100/999 is cacheable whereasContent-length: 0-100/* isn't.
  • Header:Last-Modified andETag with 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 theUser-Agent orAccept-Encoding header, 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:

Cloud CDN with request collapsing enabled.
Cloud CDN with request collapsing enabled (click to enlarge).

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.

Cloud CDN without request collapsing enabled.
Cloud CDN without request collapsing enabled (click to enlarge).

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 typeDefault behaviorConfigurableBenefits of collapsing
Chunk requestsEnabledNoCan significantly reduce origin bandwidth
Item requestsEnabledYesCan 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

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

  1. In the Google Cloud console, go to theLoad Balancing page.

    Go to the Load balancing page

  2. Click the name of your external Application Load Balancer.
  3. ClickEdit.
  4. InBackend configuration, select a backend and clickEdit.
  5. Make sure thatEnable Cloud CDN is selected.
  6. At the bottom of the window, clickAdvanced configurations.
  7. UnderBypass cache on request header, clickAdd header.
  8. Type a header name, such asPragma orAuthorization.
  9. ClickUpdate.
  10. 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

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.