Change cache modes

This page provides instructions for changing cache modes with Cloud CDN. Cache modes let you configure how Cloud CDN caches your content.

Before you begin

  • Read about cache modes and static content.

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

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

    gcloud components update

Setting the cache mode

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

The available cache modes are shown in the following table:

Cache mode Behavior
CACHE_ALL_STATIC Automatically caches successful responses with static content that aren't otherwise uncacheable. Origin responses that set valid caching directives are also cached.

This is the default behavior for Cloud CDN-enabled backends created by using the Google Cloud CLI or the REST API.
USE_ORIGIN_HEADERS Requires successful origin responses to set valid 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 content, such as dynamic HTML or API responses.

Error responses may be cached even in the absence of valid cache directives.

Before you set the cache mode to FORCE_CACHE_ALL, consider the following behaviors:

  • For signed URLs or signed cookies, FORCE_CACHE_ALL overrides the maximum age specified through the Cache entry maximum age setting in the Google Cloud console or the gcloud --signed-url-cache-max-age option.

  • FORCE_CACHE_ALL changes the time to live (TTL) of any previously cached content. This change can cause some entries that were previously considered fresh (due to having longer TTLs from origin headers) to be considered stale, and it can cause some entries that were previously considered stale to be considered fresh.

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

To configure cache modes for a Cloud CDN-enabled backend:

Console

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

    Go to the Load balancing page

  2. Click the name of your external Application Load Balancer.
  3. Click Edit .
  4. In Backend configuration, select a backend and click Edit .
  5. Make sure that Enable Cloud CDN is selected.
  6. Under Cache mode, select one of the following options:
    • Cache static content (recommended): Static content is web assets that don't change for each user. Static content is based on the Content-Type in the response. For more information, see static content.
    • Use origin settings based on Cache-Control headers: Cache responses with valid cache directives in the response headers.
    • Force cache all content: Cache all successful content served by the origin, ignoring any private or no-store directives.
  7. Click Save.

gcloud

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update command with the --cache-mode flag.

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --cache-mode flag.

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --cache-mode=CACHE_MODE

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --cache-mode=CACHE_MODE

Replace CACHE_MODE with one of the following:

  • CACHE_ALL_STATIC (default): Automatically caches static content. Responses that are marked as uncacheable (private or no-store directives in Cache-Control response headers) aren't cached. To cache dynamic content, the content must have valid caching headers.

  • USE_ORIGIN_HEADERS: Requires the origin to set valid caching headers to cache content. Responses without these headers aren't cached at Google's edge and require a full trip to the origin on every request, potentially impacting performance and increasing load on the origin server.

  • FORCE_CACHE_ALL: Caches all content (that is, successful responses), ignoring any private or no-store directives in Cache-Control response headers. This might result in caching of private, per-user (user identifiable) content. Only enable this on backends that are not serving private or dynamic content, such as Cloud Storage buckets. Don't enable this on backends that are serving private or dynamic content.

API

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

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

Use one of the following API calls:

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

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "cacheMode": (CACHE_ALL_STATIC | USE_ORIGIN_HEADERS | FORCE_CACHE_ALL)

Replace CACHE_MODE with one of the following:

  • CACHE_ALL_STATIC (default): Automatically caches static content if the origin does not set valid caching headers. Responses that are marked as uncacheable (private or no-store directives in Cache-Control response headers) aren't cached. To cache dynamic content, the content must have valid caching headers.

  • USE_ORIGIN_HEADERS: Requires the origin to set valid caching headers to cache content. Responses without these headers aren't cached at Google's edge and require a full trip to the origin on every request, potentially impacting performance and increasing load on the origin server.

  • FORCE_CACHE_ALL: Caches all content (that is, successful responses), ignoring any private or no-store directives in Cache-Control response headers. This might result in caching of private, per-user (user identifiable) content. You should only enable this on backends that are not serving private or dynamic content, such as Cloud Storage buckets.