Serve stale content

This page provides information about serving stale, expired content with Cloud CDN. Serving stale content lets Google's global cache continue to serve content when your origin server is unreachable or is returning errors to Cloud CDN.

The reasons to do this are as follows:

  • You prefer to serve stale content to users rather than returning errors to users.
  • Serving stale content avoids latency when the cache gets a request for content that has just expired. Rather than having to wait for a synchronous revalidation to the backend, the cache serves the stale content that has just expired, while triggering a separate revalidation.

To enable this behavior, your backend can specify the stale-while-revalidate directive in the response Cache-Control header. Cloud CDN will then serve that content from cache (if available) for the specified number of seconds past the cache entry expiration time. Asynchronously, Cloud CDN will revalidate content with the origin.

Cloud CDN enables this on your behalf with the cdnPolicy.serveWhileStale setting. This setting dictates how long, after the response has expired, that Cloud CDN can continue serving a stale version. If not otherwise specified in the response, this is 86400s (1 day).

Cloud CDN does not support the stale-if-error directive. This directive instructs the cache to avoid serving stale content unless synchronous revalidation with the backend has failed with particular error status codes.

The default, minimum, and maximum values are as follows:

  • Default: 86,400 seconds (one day)
  • Minimum: 0 seconds (disables the feature)
  • Maximum: 604,800 seconds (one week)

Stale content is served up to the specified limit past the cache entry expiration time, which is defined by the max-age, s-maxage, or Expires headers. For more information, see Expiration times and validation requests.

If a Cloud CDN edge cache does not have a cached copy of the object to serve stale, or the object has reached the maximum stale TTL, Cloud CDN synchronously revalidates the content with the origin. If the origin returns an error at that time, Cloud CDN returns the origin error.

Logging and User Agent

The asynchronous requests made by Cloud CDN appear to your origin server exactly like the normal revalidation requests that occur when not serving stale content. The exception is that they are tagged with a User-Agent header containing Cloud-CDN-Google.

Asynchronous requests are also separately logged to Cloud Logging, so a user request that is served stale generates two log entries: the first for the content actually served to the user, and the second for the revalidation request to the origin. Like synchronous revalidations, Cloud CDN may send a conditional request in some circumstances, or just re-request the content unconditionally. In either case, the response code logged to Cloud Logging corresponds to the original request to Cloud CDN; for example, a 200 OK for an unconditional request, or a 304 Not Modified if the user's original response was conditional.

Client max-stale request directive

Clients can request a shorter stale service time by specifying a max-stale cache-control directive. If specified, this directive controls the amount of staleness the client tolerates.

If the cached content is more stale than the client's max-stale value, Cloud CDN revalidates the content before serving.

The client cannot request a max-stale value greater than the value configured with the serve-while-stale configuration option and the stale-while-revalidate cache-control directive from the origin.

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

Serve stale content while revalidating

Console

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

    Go to Load balancing

  2. Click the name of your external Application Load Balancer.
  3. Click Edit.
  4. For Backend configuration, select a backend, and then click Edit.
  5. Make sure that Enable Cloud CDN is selected.
  6. At the bottom of the window, click Advanced configurations.
  7. For Additional CDN options, select one of the following options for Serve while stale:
    • 1 minute
    • 5 minutes
    • 10 minutes
    • 30 minutes
    • 1 day (recommended)
    • 7 days
  8. Click Update.
  9. Click Update again.

gcloud

For backend buckets, use the gcloud compute backend-buckets create command or the gcloud compute backend-buckets update command with the --serve-while-stale flag.

For backend services, use the gcloud compute backend-services create command or the gcloud compute backend-services update command command with the --serve-while-stale flag.

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --serve-while-stale=SECONDS

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --serve-while-stale=SECONDS

For example:

gcloud compute backend-services update my-backend-service
    --serve-while-stale=180s

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": {
  "serveWhileStale": SECONDS
}

Disable serving stale content

Console

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

    Go to Load balancing

  2. Click the name of your external Application Load Balancer.
  3. Click Edit.
  4. For Backend configuration, select a backend, and then click Edit.
  5. Make sure that Enable Cloud CDN isn't selected.
  6. At the bottom of the window, click Advanced configurations.
  7. For Additional CDN options > Serve while stale, select Disable serve while stale.
  8. Click Update.
  9. Click Update again.

gcloud

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --serve-while-stale flag value set to 0.

For backend services, use the gcloud compute backend-services create command or the gcloud compute backend-services update command command with the --serve-while-stale flag value set to 0.

gcloud compute backend-services (create | update) (BACKEND_SERVICE_NAME | BACKEND_BUCKET_NAME)
    --serve-while-stale=0

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": {
  "serveWhileStale": 0
}