Use negative caching

This page provides instructions for using negative caching with Cloud CDN. Negative caching lets you set a different TTL for each status code.

The reason to do this is to apply fine-grained control over caching for common errors or redirects. This can reduce the load on your origins and improve the end-user experience by reducing response latency.

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
```
Note: Make sure that you're using gcloud CLI version 316.0.0 or later.

Status codes and default TTLs

Negative caching applies to specific status codes, which are listed in the following table.

Cloud CDN applies the following default TTLs to these status codes:

Status code	Meaning	TTL
HTTP 300	Multiple choices	10 minutes
HTTP 301 and 308	Permanent redirects	10 minutes
HTTP 302 and 307	Temporary redirects	Not cached by default
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

You can override these default values by using negative caching to set a cache TTL for the specified HTTP status code.

Setting up negative caching

Negative caching lets you configure your service to cache failures as well as successes. This allows Cloud CDN to shield origins from requests that generate errors (like 404 Not Found) in the same way that it shields origins from requests that generate successful responses.

Console

In the Google Cloud console, go to the Load Balancing page.
Go to the Load balancing page
Click the name of your external Application Load Balancer.
Click Edit .
In Backend configuration, select a backend and click Edit .
Make sure that Enable Cloud CDN is selected.
At the bottom of the window, click Advanced configurations.
Click Enable negative caching.
Click Add negative caching policy.
1. Enter an HTTP status code.
2. Select a Cache time to live (TTL).
Click Update.
Click Update again.

gcloud

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

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

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --negative-caching

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --negative-caching

To enable negative caching of only two specific error responses, for example, set responses with status code 404 to be cached for 60 seconds, and responses with status code 405 to be cached for 120 seconds.

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --negative-caching \
    --cache-mode=CACHE_ALL_STATIC \
    --default-ttl=86400 \
    --negative-caching-policy='404=60,405=120'

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": {
  "negativeCaching": ON,
  "negativeCachingPolicy": [
    {
      "code": STATUS_CODE,
      "ttl": TTL_SECONDS
    }
  ]
}

Negative caching must be enabled to configure the negativeCachingPolicy settings. If you omit the policy and have negativeCaching enabled, Cloud CDN uses the default values listed in Status codes and default TTLs.

When specifying a negative caching policy, make sure to specify a cache TTL for all response codes that you want to cache. Cloud CDN doesn't apply any default negative caching when a policy exists.

For STATUS_CODE, you can specify the following HTTP status codes:

300, 301, 302, 307, 308
404, 405, 410, 421, 451
501

For each status code, you can specify a number of seconds to cache responses. To disable negative caching for the status code, exclude the code from your negative caching policy.

The maximum allowed value is 1800 seconds (30 minutes); however, infrequently accessed objects might be evicted from the cache before the defined TTL.

When the cache mode is set to CACHE_ALL_STATIC or USE_ORIGIN_HEADERS, negative caching is applied to responses with the specified response code that lack any Cache-Control or Expires headers.

When the cache mode is set to FORCE_CACHE_ALL, negative caching overrides any caching headers set by the origin, and Cloud CDN will cache the response for the length of time specified by the TTL, or will not cache it at all if no TTL is set.

In addition, when the cache mode is set to FORCE_CACHE_ALL, Cloud CDN will also modify the max-age sent to the client in the Cache-Control header. In particular, if a given error has a configured TTL setting, Cloud CDN will take the lesser of that TTL setting and the client_ttl configuration setting, and send a Cache-Control: public,max-age=N header with that value. If a given error does not have a configured TTL setting, Cloud CDN will remove any Cache-Control header sent by the origin. Cloud CDN will also always remove any Expires header sent by the origin.

If an origin has negative caching initially enabled but then disabled (either manually or by disabling caching for a particular response code), cached error responses are considered valid based only on their Cache-Control or Expires headers. Therefore, once negative caching is disabled, a response with no caching age directives in its headers is not served from cache.

Cloud CDN caches in response to GET requests. For more information, see Cacheable content.

Each cache entry is identified by a cache key.

Disable negative caching