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.

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.

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.

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.