Customize cache keys

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.

Enabling Cloud CDN and customizing the cache keys

These instructions activate Cloud CDN for a load balanced backend service or bucket and customize the cache key by excluding one or more components. 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.

Console

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

    Go to Cloud CDN

  2. Click Add origin.
  3. In the Origin pull-down menu, click Select origin.
  4. Select the origin for which you want to enable CDN.
  5. In the row of the origin, click Configure.

    If Cloud CDN is already enabled on this origin, first click the menu, select Edit, and then click Configure.

  6. Clear the checkboxes for any fields that you want to omit from the cache key for this backend service.

  7. Click Save.

  8. Click Add.

gcloud

Specify one or more of the optional flags to exclude that parameter from the cache keys for this backend service or backend bucket.

gcloud compute backend-services update BACKEND_SERVICE \
    --enable-cdn
gcloud compute backend-buckets update BACKEND_BUCKET \
    --enable-cdn

Optional flags:

  • --no-cache-key-include-protocol
  • --no-cache-key-include-host
  • --no-cache-key-include-query-string

Updating cache keys to re-add 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 re-add the protocol, host, and query string to the cache key for an existing backend service that already has CDN enabled.

Console

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

    Go to Cloud CDN

  2. In your load balancer's row, click Menu and then click Edit.
  3. In the row of the backend service or backend bucket that you want to modify, click Configure.
  4. Under Cache key, select Custom.
  5. Select the Protocol, Host, and Query string checkboxes.
  6. Leave the Query string parameters field blank.
  7. Click Save.
  8. Click Update.

gcloud

To re-add one component only, specify that flag alone. 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
gcloud compute backend-buckets update BACKEND_BUCKET \
    --cache-key-include-query-string

Updating cache keys to use an include or exclude list of query strings

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

Console

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

    Go to Cloud CDN

  2. In your load balancer's row, click Menu and then click Edit.
  3. In the row of the backend service that you want to modify, click Configure.
  4. Under Cache key, select Custom.
  5. Confirm that the Query string checkbox is selected.
  6. If you want to specify query string parameters that should 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.

  7. Enter your comma-separated list of strings in the Query string parameters field.

  8. Click Save.

  9. Click Update.

gcloud

Use this command to set the string user to be the include list.

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

Use this command to add the string user to an exclude list.

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

Updating cache keys to use HTTP headers

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

Console

The Google Cloud console is not currently supported for this feature.

gcloud

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

Updating cache keys to use named cookies

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

Console

The Google Cloud console is not currently supported for this feature.

gcloud

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

What's next

  • To check whether Cloud CDN is serving responses from cache, see Viewing logs.