Configure caching behavior

Media CDN serves content as close to users as possible by using Google's global edge caching infrastructure to cache content and reduce load on origin infrastructure.

You can control how content is cached for each route. This lets you optimize behavior based on the type of content, client request attributes, and your freshness requirements.

Cacheability

The following sections describe what responses Media CDN caches and how to improve cache offload.

Default caching behavior

By default, the following cache-related settings apply to each Edge Cache service:

Default cache mode of CACHE_ALL_STATIC:
- Respects origin cache directives, such as Cache-Control or Expires, up to a configurable max TTL.
- Caches static media types automatically with a default TTL of 3600s, if no origin cache directives are present.
- Caches HTTP 200, 204, and 206 status codes (negative caching is not enabled).
Does not cache responses that have no-store or private cache-control directives or that are otherwise uncacheable.

Responses that are not static content or that are missing valid cache directives are not cached unless caching is explicitly configured. To learn how to override the default behavior, see the documentation on cache modes .

The default behavior is equivalent to the following cdnPolicy. Routes without an explicit cdnPolicy configured behave as if they have the following configuration:

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    includeProtocol: false
    excludeHost: false
    excludeQueryString: false
  signedRequestMode: DISABLED
  negativeCaching: false

Cacheable responses

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

You can configure cache modes for each route to override this behavior (for example, using the CACHE_ALL_STATIC cache mode to cache common media types) even if the origin does not set a cache control directive in the response.

Requests and responses that meet the criteria defined in uncacheable responses supersedes cacheability.

The following table describes the requirements to cache particular HTTP responses. Both GET and HEAD responses must adhere to these requirements.

HTTP attribute	Requirements
Status code	The response status code must be one of 200, 203, 204, 206, 300, 301, 302, 307, 308, 400, 403, 404, 405, 410, 451, 500, 501, 502, 503, or 504.
HTTP methods	`GET` and `HEAD`
Request headers	Most caching request directives are ignored. For more information, see Cache control directives.
Response headers	Contains a valid HTTP caching directive such as `Cache-Control: max-age=3600, public`. Has a cache mode that caches that content, or has an `Expires` header with a date in the future.
Response size	Up to 100 GiB.

The HTTP Age header is set based on when Media CDN first cached the response, and typically represents the seconds since the object was cached at an origin shielding location. If your origin generates an Age response header, use the FORCE_CACHE_ALL cache mode to prevent revalidations when Age exceeds the cache TTL.

For more information about how Media CDN interprets HTTP caching directives, see Cache control directives.

Origin requirements

To allow Media CDN to cache origin responses larger than 1 MiB, an origin must include the following in the response headers for GET requests, unless specified otherwise:

A Last-Modified or ETag HTTP response header (a validator).
A valid HTTP Date header.
A valid Content-Length header.
The Content-Range response header, in response to a Range GET request. The Content-Range header must have a valid value in the form of bytes x-y/z (where z is the object size).

The default origin protocol is HTTP/2. If your origins only support HTTP/1.1, you can set the protocol field explicitly for each origin.

Uncacheable responses

The following table details the request and response attributes that prevent a response from being cached. Responses that are cacheable but that match "uncacheable" criteria aren't cached.

HTTP attribute	Requirement
Status code	A status code other than those defined as cacheable, such as HTTP 401, HTTP 412, or HTTP 505. These status codes are typically representative of client-facing issues and not origin status. Caching those responses can lead to "cache poisoning" scenarios where a user-triggered "bad" response is cached for all users.
Request headers	For requests with an `Authorization` request header, responses must include a `public` Cache-Control directive to be cached. A `no-store` directive in the request causes the response not to be cached. For more information, see Cache control directives.
Response headers	Has a `Set-Cookie` header. Has a `Vary` header other than `Accept`, `Accept-Encoding`, `Access-Control-Request-Headers`, `Access-Control-Request-Method`, `Origin`, `Sec-Fetch-Dest`, `Sec-Fetch-Mode`, `Sec-Fetch-Site`, `X-Goog-Allowed-Resources`, or `X-Origin`. In `CACHE_ALL_STATIC` or `USE_ORIGIN_HEADERS` mode, has a `no-store` or `private` cache control directive.
Response size	Greater than 100 GiB.

These rules apply in addition to the configured cache mode. Specifically:

With the CACHE_ALL_STATIC cache mode configured, only responses that are considered static content or responses with valid cache directives in their response headers are cached. Other responses are proxied as is.
The FORCE_CACHE_ALL cache mode caches all responses unconditionally, subject to the uncacheability requirements stated earlier.
The USE_ORIGIN_HEADERS cache mode requires responses to set valid cache directives in their response headers in addition to being a cacheable status code.

Notes:

Responses that are not cached don't have their cache control directives or other headers changed and are proxied as is.
Responses can have their Cache-Control and Expires headers collapsed into a single Cache-Control field. For example, a response with Cache-Control: public and Cache-Control: max-age=100 on separate lines would be collapsed as Cache-Control: public,max-age=100.
Uncacheable responses (responses that would never be cached) are not counted as Cache Egress from a billing perspective.

Using cache modes

Cache modes allow you to configure when Media CDN should respect origin cache directives, cache static media types, and cache all responses from the origin, regardless of the directives set.

Cache modes are configured at the route-level and, combined with TTL overrides, allow you to configure cache behavior by host, path, query parameters, and headers (any matchable request parameters).

By default, Media CDN uses the CACHE_ALL_STATIC cache mode, which automatically caches common static media types for 1 hour (3600 seconds), while prioritizing any cache directives specified by the origin for cacheable responses.
You can increase or decrease the cache TTL applied to responses without an explicit cache TTL set (a max-age or s-maxage directive) by setting the cdnPolicy.defaultTtl field on a route.
To prevent caching non-success responses for longer than intended, non-2xx (non-success) status codes are not cached according to their Content-Type (MIME type) and don't have the default TTL applied.

The available cache modes, which are set on the cdnPolicy.cacheMode of each route, are shown in the following table.

Cache mode	Behavior
`USE_ORIGIN_HEADERS`	Requires origin responses to set valid cache directives and valid caching headers. For a full list of requirements, see Cacheable responses.
`CACHE_ALL_STATIC`	Automatically caches successful responses with static content, unless they have a `no-store` or `private` directive. Valid caching directives from the origin are prioritized. Static content includes video, audio, images, and common web assets as defined by the MIME type in the `Content-Type` response header.
`FORCE_CACHE_ALL`	Unconditionally caches successful responses, overriding any cache directives set by the origin. Make sure not to serve private, per-user content (such as dynamic HTML or API responses) with this mode configured.
BYPASS_CACHE	Any request that matches a route with this cache mode configured bypasses the cache, even if there is a cached object that matches that cache key. We recommend using this only for debugging because Media CDN is designed as a planet-scale cache infrastructure and not a general purpose proxy.

Static content MIME types

The CACHE_ALL_STATIC cache mode allows Media CDN to automatically cache common static content such as video, audio, images, and common web assets based on the MIME type returned in the Content-Type HTTP response header. However, regardless of media type, Media CDN prioritizes any explicit Cache-Control or Expires headers in the origin response.

The following table lists the MIME types that can be cached automatically with the CACHE_ALL_STATIC cache mode.

Responses are not automatically cached if they don't have a Content-Type response header with a value that matches the following values. You must ensure that the response sets a valid cache directive, or you must use the FORCE_CACHE_ALL cache mode to unconditionally cache responses.

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

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 Google Cloud console or the gcloud CLI to upload content.
Cloud Storage always provides a Cache-Control header to Media CDN. If no value is explicitly chosen, it sends a default value. As a result, all successful Cloud Storage responses are cached according to Cloud Storage default values, unless you explicitly adjust the cache control metadata for objects in Cloud Storage or use FORCE_CACHE_ALL mode to override the values sent by Cloud Storage.

If a response is cacheable based on its MIME type but has a Cache-Control response directive of private or no-store or a Set-Cookie header, it isn't cached.

Other media types, such as HTML (text/html) and JSON (application/json), are not cached by default. These types of responses are typically dynamic (per user), and are also not well suited for Media CDN's architecture. We recommend using Cloud CDN for serving web assets and for caching API responses.

Configure cache TTLs

Time to live (TTL) overrides let you set default TTL values for cached content and override TTL values set in the max-age and s-maxage cache control directives (or Expires headers) set by your origins.

TTLs, whether set by overrides or by using a cache directive, are optimistic. Content that is rarely accessed or unpopular might be evicted from the cache prior to the TTL being reached.

The following table shows three TTL settings.

Setting Default Minimum Maximum Description Applicable cache modes

Setting	Default	Minimum	Maximum	Description	Applicable cache modes
Default TTL	1 hour (3600 seconds)	0 seconds	1 year (31,536,000 seconds)	The TTL to set when the origin has not specified a `max-age` or an `s-maxage` header. If the origin specifies an `s-maxage` header, it is used instead of the default TTL value here. When using `FORCE_CACHE_ALL` to unconditionally cache all responses, the default TTL is used to set the cache TTL. All other values and directives are ignored.	`CACHE_ALL_STATIC` `FORCE_CACHE_ALL`
Max TTL	1 day (86400 seconds)	0 seconds	1 year (31,536,000 seconds)	For cacheable responses, the maximum TTL to allow. Values greater than this are capped at the value of `maxTtl`.	`CACHE_ALL_STATIC`
Client TTL	Not set by default.	0 seconds	1 day (86400 seconds)	For cacheable responses, the maximum TTL to allow in the downstream (client-facing) response if this needs to be different from other TTL values.	`CACHE_ALL_STATIC` `FORCE_CACHE_ALL`

Default TTL

1 hour
(3600 seconds)

0 seconds

1 year
(31,536,000 seconds)

The TTL to set when the origin has not specified a max-age or an s-maxage header.

If the origin specifies an s-maxage header, it is used instead of the default TTL value here.

When using FORCE_CACHE_ALL to unconditionally cache all responses, the default TTL is used to set the cache TTL. All other values and directives are ignored.

CACHE_ALL_STATIC

FORCE_CACHE_ALL

Max TTL 1 day
(86400 seconds) 0 seconds 1 year
(31,536,000 seconds) For cacheable responses, the maximum TTL to allow. Values greater than this are capped at the value of maxTtl. CACHE_ALL_STATIC

Client TTL

Not set by default.

0 seconds

1 day
(86400 seconds)

For cacheable responses, the maximum TTL to allow in the downstream (client-facing) response if this needs to be different from other TTL values.

CACHE_ALL_STATIC

FORCE_CACHE_ALL

Setting any TTL value to zero (0 seconds) causes every request to be revalidated with the origin before a response is served and increases load to the origin if set too broadly.

When the cache mode is set to Use Origin Headers, TTL settings cannot be configured because Media CDN relies on the origin to drive behavior.

Notes:

The value for max TTL must always be greater than (or equal to) the value of default TTL.
The value for client TTL must always be smaller than (or equal to) the value of max TTL.
When Media CDN overrides an origin TTL value, the Cache-Control header to the client also reflects that value.
If the origin sets an Expires header and Media CDN overrides the effective TTL (based on the timestamp), the Expires header is replaced with a Cache-Control header in the downstream response to the client.

Negative caching

Negative caching defines how non-success HTTP status codes (those other than 2xx) are cached by Media CDN.

This lets you cache error responses such as redirects (HTTP 301 and 308) and not found (HTTP 404) responses closer to users, as well as reduce origin load more broadly if the response is unlikely to change and can be cached.

By default, negative caching is disabled. The following table shows the default values for each status code when negative caching is enabled and negativeCachingPolicy isn't used.

Status codes	Reason-phrase	TTL
HTTP 300	Multiple Choices	10 minutes
HTTP 301 and HTTP 308	Permanent Redirect	10 minutes
HTTP 404	Not Found	120 seconds
HTTP 405	Method Not Found	60 seconds
HTTP 410	Gone	120 seconds
HTTP 451	Unavailable for Legal Reasons	120 seconds
HTTP 501	Not Implemented	60 seconds

The default set of negative caching codes matches the heuristically cacheable status codes described in HTTP RFC 9110, with the following exceptions:

HTTP code 414 (URI Too Long) is not supported for caching, to avoid cache poisoning.
HTTP code 451 (Unavailable for Legal Reasons) is supported for caching, as described in HTTP RFC 7725.

If you need to configure your own per-status code TTLs, and override the default behavior, you can configure a cdnPolicy.negativeCachingPolicy. This lets you set the TTL for any of the status codes allowed by Media CDN: 300, 301, 302, 307, 308, 400, 403, 404, 405, 410, 451, 500, 501, 502, 503, and 504.

For example, to set a short, 5-second TTL for HTTP 404 (Not Found) responses, and a 10-second TTL for HTTP 405 (Method Not Allowed) responses, use the following YAML definition on each applicable route:

cdnPolicy:
  negativeCaching: true
  negativeCachingPolicy:
    "404": 5s
    "405": 10s
  # other status codes to apply TTLs for

To prevent cache poisoning, we don't recommend enabling caching for either status code 400 (Bad Request) or 403 (Forbidden). Ensure that your origin server returns either code as a result of examining only the components of the request that are included in the cache key. Cache poisoning can occur, for example, when the origin server responds with a 403 error response in the absence of a correct Authorization header. In this case, caching the 403 error response results in Media CDN serving the 403 error response to all subsequent requests until the TTL expires, even if the requests have a correct Authorization header.

To disable negative caching: