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
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.
- 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.
- Enter an HTTP status code.
- 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
Console
- In the Google Cloud console, 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.
- Clear the checkbox next to Enable negative caching.
- 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 --no-negative-caching
flag.
For backend services, use the gcloud compute backend-services
create or
gcloud compute backend-services
update command
with the --no-negative-caching
flag.
gcloud 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/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": OFF }