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.

Enable Cloud CDN and customize cache keys

These instructions activate Cloud CDN for a load balanced backend service 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.

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

  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 the component from the cache keys for this backend service.

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

Optional flags:

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

Update 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 Cloud 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

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

  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 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

Update cache keys to use HTTP headers

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

Console

The Google Cloud console is not 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,...]

Update cache keys to use named cookies

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

Console

The Google Cloud console is not supported for this feature.

gcloud

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

What's next