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
- In the Google Cloud console, go to the Load balancing page.
- Click the name of your external Application Load Balancer.
- Click Edit.
- For Backend configuration, select a backend, and then click Edit.
- Make sure that Enable Cloud CDN is selected.
- At the bottom of the window, click Advanced configurations.
- 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
- Click Update.
- 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
- In the Google Cloud console, go to the Load balancing page.
- Click the name of your external Application Load Balancer.
- Click Edit.
- For Backend configuration, select a backend, and then click Edit.
- Make sure that Enable Cloud CDN isn't selected.
- At the bottom of the window, click Advanced configurations.
- For Additional CDN options > Serve while stale, select Disable serve while stale.
- 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 --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 }