Serving 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 revalidating the content asynchronously in the background.

The stale-while-revalidate setting serves existing content from the cache (if available) for a specified number of seconds past the cache entry expiration time while revalidating content with the origin.

You can set the header from your origin by setting the stale-while-revalidate HTTP response header.

Cloud CDN can enable this on your behalf by setting the cdnPolicy.serveWhileStale setting. This setting dictates how long, after the response has expired, that Cloud CDN can continue serving a stale version. By default, this is 86400s (1 day).

The serveWhileStale setting combines both the stale-while-revalidate and the stale-if-error HTTP caching features.

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-max-age, 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.

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

    gcloud components update
    

Serving stale content while revalidating

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. At the bottom of the window, click Advanced configurations.
  7. Under Serve while stale, select one of the following options:
    • 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 or gcloud compute backend-buckets update command with the --serve-while-stale flag.

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update 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
}

Disabling serving stale content

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 isn't selected.
  6. At the bottom of the window, click Advanced configurations.
  7. Under 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 or gcloud compute backend-services update 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
}