Using 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 Cloud SDK:

    gcloud components update
    

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 404 Not found 120 seconds
HTTP 405 Method not found 60 seconds
HTTP 410 Gone 120 seconds
HTTP 421 Misdirected request 60 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.

When a backend isn't performing well, the backend can have an increase in traffic because usually responses are successes that get cached. During the period of high latency, responses get fetched fresh every time, which might delay bringing the backend back online. By caching failure responses, such as 500 Internal Server Errors, for short periods of time, Cloud CDN provides time for error recovery.

Console

The Cloud Console isn't currently supported.

gcloud

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

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

gcloud beta compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --negative-caching
gcloud beta 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 beta 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/beta/projects/PROJECT_ID/global/backendBuckets
PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices
PUT https://compute.googleapis.com/compute/beta/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 the STATUS_CODE, you can specify HTTP status codes 300, 301, 308, 404, 405, 410, 421, 451 and 501,

For each status code, you can specify a number of seconds to cache responses. Omit the TTL field to disable negative caching for the status code.

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 applies to all responses with the specified response code, and overrides any caching headers.

Disable negative caching

gcloud

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

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

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

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/beta/projects/PROJECT_ID/global/backendBuckets
PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices
PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "negativeCaching": OFF
}