Customize cache keys
Stay organized with collections Save and categorize content based on your preferences.

This page explains how to customize Cloud CDN cache keys.

Changing cache key configuration might result in a sudden drop in the cache hit ratio if new requests start using cache keys that are different from old cache key entries. Similarly, changing the cache key creator does not necessarily invalidate cached entries if new requests use the same key as old cache keys. To invalidate existing cached entries, see Invalidating cached content.

Before you begin

This page assumes an understanding of Cloud CDN, Cloud CDN cache keys, and load balanced backend services. We recommend reviewing these pages before proceeding.

Enable Cloud CDN and customize cache keys

These instructions activate Cloud CDN for a load balanced backend service and customize the cache key. If you don't already have a load balancer to use as an origin, see the external Application Load Balancer documentation for instructions to create one.

Backend buckets don't include the protocol or host in the cache key because these don't influence how objects are referenced within a Cloud Storage bucket. However, they include a set of query string parameters that are specific to Cloud Storage, which might affect the response and might be extended by a customizable list of parameter names.

Console

In the Google Cloud console, go to the Cloud CDN page.

Go to Cloud CDN
Click the name of the origin that you want to update.
Click Edit.

If more than one load balancer is attached to the origin, select the load balancer that you want to update from the Edit menu.
To expand the Cache performance section, click Next.
For Cache key, select Custom.
In the Cache key components section, by default, all components are selected. Clear checkboxes for any components that you want to exclude from the cache key.
Click Done.

gcloud

To exclude one or more components from the cache keys for a backend service, use the gcloud compute backend-services update command.

gcloud compute backend-services update BACKEND_SERVICE \
    --no-cache-key-include-protocol \
    --no-cache-key-include-host \
    --no-cache-key-include-query-string

For backend buckets, use the gcloud compute backend-buckets update command.

API

To exclude one or more components from the cache key, specify configuration options in the cacheKeyPolicy section of cdnPolicy for the backendServices resource.

For backend services, use the backendServices.update method API call.

PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE

For backend buckets, use the backendBuckets.update method API call.

PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "cacheKeyPolicy": [
    {
      "includeProtocol": false,
      "includeHost": false,
      "includeQueryString": false
    }
  ]
}

Update cache keys to add the protocol, host, and query string

By default, backend services configured to use Cloud CDN include all components of the request URI in cache keys. If you previously indicated that one or more components should be excluded, you can use the following steps to include them again.

These instructions add the protocol, host, and query string to the cache key for an existing backend service that already has Cloud CDN enabled.

Console

In the Google Cloud console, go to the Cloud CDN page.

Go to Cloud CDN
Click the name of the origin that you want to update.
Click Edit.

If more than one load balancer is attached to the origin, select the load balancer that you want to update from the Edit menu.
To expand the Cache performance section, click Next.
For Cache key, select Custom.
In the Cache key components section, select the Protocol, Host, and Query string checkboxes.
Click Done.

gcloud

To add one or more components to the cache keys for a backend service, use the gcloud compute backend-services update command.

Any unspecified flags are left unchanged.

gcloud compute backend-services update BACKEND_SERVICE \
    --cache-key-include-protocol \
    --cache-key-include-host \
    --cache-key-include-query-string

API

To add one or more components to the cache key, specify configuration options in the cacheKeyPolicy section of cdnPolicy for the backendServices resource.

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "cacheKeyPolicy": [
    {
      "includeProtocol": true,
      "includeHost": true,
      "includeQueryString": true
    }
  ]
}

Update cache keys to use an include or exclude list of query string parameters

These instructions set Cloud CDN cache keys to use an include list or exclude list with query string parameters.

Console

In the Google Cloud console, go to the Cloud CDN page.

Go to Cloud CDN
Click the name of the origin that you want to update.
Click Edit.

If more than one load balancer is attached to the origin, select the load balancer that you want to update from the Edit menu.
To expand the Cache performance section, click Next.
For Cache key, select Custom.
In the Cache key components section, select the Query string checkbox. Then, select either of the following options:
- If you want to specify query string parameters that must be part of the cache key, select Include only selected.
- If you want to specify that all query string parameters except the ones that you list are included in the cache key, select Include all but selected.
Click Add parameter and specify the parameters.
Click Done.

gcloud

To specify an include list or an exclude list for a backend service, specify query string parameters by using the gcloud compute backend-services update command.

Use this command to set the query string parameter user to the include list of a backend service.

gcloud compute backend-services update BACKEND_SERVICE \
    --cache-key-include-query-string \
    --cache-key-query-string-whitelist user

Use this command to set the query string parameter user to the exclude list of a backend service.

gcloud compute backend-services update BACKEND_SERVICE \
    --cache-key-include-query-string \
    --cache-key-query-string-blacklist user

Use this command to set the query string parameter user to the include list of a backend bucket.

gcloud compute backend-buckets update BACKEND_BUCKET \
    --cache-key-query-string-whitelist user

API

To specify an include list or an exclude list for a backend service, specify query string parameters in the cacheKeyPolicy section of cdnPolicy for the backendServices resource.

To specify an include list, add the following snippet to the JSON request body:

"cdnPolicy": {
  "cacheKeyPolicy": [
    {
      "queryStringWhitelist": [QUERY_STRINGS]
    }
  ]
}

Replace QUERY_STRINGS with a comma-separated list of query string parameters.

To specify an exclude list, add the following snippet:

"cdnPolicy": {
  "cacheKeyPolicy": [
    {
      "queryStringBlacklist": [QUERY_STRINGS]
    }
  ]
}

Update cache keys to use HTTP headers

These instructions set Cloud CDN cache keys to use HTTP headers, which can include allowed custom variables.

Console

In the Google Cloud console, go to the Cloud CDN page.

Go to Cloud CDN
Click the name of the origin that you want to update./
Click Edit.

If more than one load balancer is attached to the origin, select the load balancer that you want to update from the Edit menu.
To expand the Cache performance section, click Next.
For Cache key, select Custom.
In the Cache key components section, select the HTTP headers checkbox.
To specify one or more HTTP headers, click Add HTTP header.
Click Done.

gcloud

Use the gcloud compute backend-services update command with the cache-key-include-http-header option.

gcloud compute backend-services update BACKEND_SERVICE \
    --cache-key-include-http-header=[HEADER_FIELD_NAMES,...]

Replace HEADER_FIELD_NAMES with a comma-separated list of header names.

API

Specify HTTP headers for cache keys in the cacheKeyPolicy section of cdnPolicy for the backendServices resource.

Add the following snippet to the JSON request body:

"cdnPolicy": {
  "cacheKeyPolicy": [
    {
      "includeHttpHeaders": [HEADER_FIELD_NAMES]
    }
  ]
}

Replace HEADER_FIELD_NAMES with a comma-separated list of header names.

If the specified cache key header is also specified as a custom request header, you can't use the full range of variables.

For more information, see Use custom variables with request headers.

Update cache keys to use named cookies

These instructions set Cloud CDN cache keys to use HTTP cookies.

Console

In the Google Cloud console, go to the Cloud CDN page.

Go to Cloud CDN
Click the name of the origin that you want to update.
Click Edit.

If more than one load balancer is attached to the origin, select the load balancer that you want to update from the Edit menu.
To expand the Cache performance section, click Next.
For Cache key, select Custom.
In the Cache key components section, select the Named cookies checkbox.
To specify one or more cookies, click Add named cookie.
Click Done.

gcloud

Use the gcloud compute backend-services update command with the cache-key-include-named-cookie option.

gcloud compute backend-services update BACKEND_SERVICE \
    --cache-key-include-named-cookie=[NAMED_COOKIES,...]

Replace NAMED_COOKIES with a comma-separated list of named cookies.

API

To specify an include list or an exclude list for a backend service, specify query string parameters in the cacheKeyPolicy section of cdnPolicy for the backendServices resource.

To specify an include list, add the following snippet to the JSON request body:

"cdnPolicy": {
  "cacheKeyPolicy": [
    {
      "includeNamedCookies": [NAMED_COOKIES]
    }
  ]
}

Replace NAMED_COOKIES with a comma-separated list of query string parameters.

What's next

To check whether Cloud CDN is serving responses from cache, see Logs and metrics for caching.

Customize cache keys Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Enable Cloud CDN and customize cache keys

Console

gcloud

API

Update cache keys to add the protocol, host, and query string

Console

gcloud

API

Update cache keys to use an include or exclude list of query string parameters

Console

gcloud

API

Update cache keys to use HTTP headers

Console

gcloud

API

Update cache keys to use named cookies

Console

gcloud

API

What's next

Customize cache keys
Stay organized with collections Save and categorize content based on your preferences.