Using TTL settings and overrides

This page provides instructions for using TTL overrides with Cloud CDN. TTL overrides give you fine-grained control over how long Cloud CDN caches your content before revalidating it.

Before you begin

  • Read about cache modes.

  • 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
    

Setting the default TTL

When you set the cache mode to cache all static content (CACHE_ALL_STATIC) or all content regardless of content type (FORCE_CACHE_ALL), the default time to live (TTL) for content caching is 3600 seconds (1 hour).

To improve cache hit rates for content that doesn't change often, you can override the default TTL so that Cloud CDN revalidates content at the origin less frequently. The maximum allowed value for the default TTL is 31,622,400 seconds (1 year). Infrequently accessed objects might be evicted from the cache before the defined TTL.

Setting a default TTL of 0 means that the response is revalidated at the origin, in cases where the default TTL applies.

When you set the cache mode to cache all content regardless of content type (FORCE_CACHE_ALL), the default TTL overwrites the TTL set in all responses (including those that have a TTL set by origin headers). In this mode, the default TTL is visible to clients, because Cloud CDN sets the public and max-age attributes of the responses served to clients.

For CACHE_ALL_STATIC mode, the default TTL applies to cached content served by an origin for responses that don't have an existing valid TTL (max-age, s-max-age, or Expires header). In CACHE_ALL_STATIC mode, the default TTL doesn't modify the Cache-Control header served to clients. To modify the Cache-Control header in the CACHE_ALL_STATIC mode, you must set the client TTL.

When you set the cache mode to use origin headers (USE_ORIGIN_HEADERS), the default TTL value doesn't apply and cannot be set because Cloud CDN uses the max-age or s-max-age origin directive or the Expires header instead.

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. Make sure that the cache mode is Cache static content (recommended) or Force cache all content. Overriding the TTL values isn't supported when the cache mode is Use origin settings based on Cache-Control headers.
  7. Under Default time to live, select a value.
  8. Click Save.

gcloud

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update command with the --default-ttl flag.

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --default-ttl flag.

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --default-ttl=DEFAULT_TTL
gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --default-ttl=DEFAULT_TTL

Replace DEFAULT_TTL with a value up to 31,622,400 seconds (1 year).

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": {
  "defaultTtl": DEFAULT_TTL
}

Replace DEFAULT_TTL with a value up to 31,622,400 seconds (1 year).

Setting the max TTL

The maximum (max) TTL specifies the maximum allowed TTL within Cloud CDN for cached content served by an origin.

The TTL of a response is capped by the max TTL if one of the following is true:

  • The response attempts to set a max-age or s-maxage higher than the max TTL value.
  • The response has an Expires header more than cdnPolicy.maxTtl seconds in the future.

The max TTL setting does not change the max-age value sent to the client; for more information, see Overriding the maximum client TTL. The max TTL setting only affects how long Cloud CDN attempts to cache the content.

When you set the cache mode to cache all static content (CACHE_ALL_STATIC), by default the max TTL for content caching is set to 86,400 seconds (1 day). The maximum allowed value is 31,622,400 seconds (1 year). However, infrequently accessed objects might be evicted from the cache before the defined TTL.

With FORCE_CACHE_ALL, the TTL is always set to the default TTL; you can't set a max TTL.

The value of the max TTL can be equal to or greater than the value of the default TTL.

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. Make sure that the cache mode is Cache static content (recommended).
  7. Under Maximum time to live, select a value.
  8. Click Save.

gcloud

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update command with the --max-ttl flag.

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --max-ttl flag.

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --max-ttl=MAX_TTL
gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --max-ttl=MAX_TTL

Replace MAX_TTL with a value up to 31,622,400 seconds (1 year).

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": {
  "maxTtl": MAX_TTL
}

Replace MAX_TTL with a value up to 31,622,400 seconds (1 year).

Overriding the client TTL

For all cache modes, Cloud CDN passes Cache-Control headers to the client.

The client TTL lets you set a maximum TTL for what is sent to browsers or clients so that clients revalidate content against Cloud CDN more often, without requiring revalidation at the origin. This way, content can be invalidated within Cloud CDN when necessary, and browsers can discover that the content is invalidated as soon as the client TTL expires.

In FORCE_CACHE_ALL mode, Cloud CDN normally passes the same max-age to the client that it uses internally for proxy caching; however, if a client TTL is specified and is a smaller value, the client TTL is passed to the client in the max-age directive instead. Similarly, in CACHE_ALL_STATIC mode, the client TTL serves as a clamp for whatever max-age is specified by the origin server so that the max-age sent to the browser or client won't be larger than the configured client TTL. If no max-age is specified, the lesser of the default TTL and the client TTL value is used as the max-age sent to the browser or client.

The value of the client TTL cannot be greater than the max TTL.

If an Expires header is present in the origin response, it is removed and replaced with a Cache-Control: max-age directive with the appropriate TTL.

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. Make sure that the cache mode is Cache static content (recommended) or Force cache all content. Overriding the TTL values isn't supported when the cache mode is Use origin settings based on Cache-Control headers.
  7. Under Client time to live, select a value up to 86,400 seconds.
  8. Click Save.

gcloud

For backend services, use the gcloud compute backend-services create or gcloud compute backend-services update command with the --client-ttl flag.

For backend buckets, use the gcloud compute backend-buckets create or gcloud compute backend-buckets update command with the --client-ttl flag.

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --client-ttl=CLIENT_TTL
gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --client-ttl=CLIENT_TTL

Replace CLIENT_TTL with a value up to 86,400 seconds (1 day).

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": {
  "clientTtl": CLIENT_TTL
}

Replace CLIENT_TTL with a value up to 86,400 seconds (1 day).