Using cache modes

This page provides instructions for using 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 Cloud SDK:

  gcloud components update
  

  Note: Make sure that you're using gcloud SDK version 309.0.0 or later.

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
USE_ORIGIN_HEADERS	Requires origin responses to set valid cache directives and valid caching headers. Responses without these directives are forwarded from the origin. This is the default behavior for Cloud CDN-enabled backends created by using the gcloud command-line tool or the REST API.
CACHE_ALL_STATIC	Automatically caches static content that doesn't have the no-store, private, or no-cache directive. Origin responses that set valid caching directives are also cached.
FORCE_CACHE_ALL	Unconditionally caches responses, overring any cache directives set by the origin. Make sure not to cache private, per-user content (such as dynamic HTML or API responses) if using a shared backend with this mode configured.

Caution: When you set the cache mode to FORCE_CACHE_ALL, the default time to live (TTL) for content caching is 3600 seconds (1 hour), unless you explicitly set a different TTL. Accepting the new default TTL of 1 hour might cause some entries that were previously considered fresh (due to having longer TTLs from origin headers) to now be considered stale.

Caution: The FORCE_CACHE_ALL mode 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 HTTP(S) 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 content served by the origin, ignoring any private, no-store or no-cache 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: Automatically caches static content. Responses that are marked as uncacheable (private, no-store, or no-cache 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. This is the default behavior for Cloud CDN-enabled backends created by using the gcloud command-line tool or the REST API.

• FORCE_CACHE_ALL: Caches all content, ignoring any private, no-store, or no-cache 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. Responses that are marked as uncacheable (private, no-store, or no-cache 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. This is the default behavior for Cloud CDN-enabled backends created by using the gcloud command-line tool or the REST API.

• FORCE_CACHE_ALL: Caches all content, ignoring any private, no-store, or no-cache 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.