Enable dynamic compression

Dynamic compression works with a global external HTTP(S) load balancer (classic) to automatically compress responses served by Cloud CDN between the origin and the client. The size of the data sent over the network is reduced by 60% to 85% in typical cases.

The size reduction reduces the time it takes to download content. For important assets like stylesheets (CSS), scripts (JavaScript), and video manifests (HLS/DASH), this can reduce page load and video start times.

You can learn more about the benefits of compressing responses in the Web Fundamentals guide.

You can enable compression on a backend service or a backend bucket.

Example use cases

Dynamic compression directly reduces the size of data sent from the Cloud CDN edge to the client. This can directly do the following:

Reduce the size of CSS and JavaScript, helping web pages render faster and reducing the time to First Contentful Paint, an important web performance metric.
Have a large, positive impact when caching REST API responses, such as JSON payloads. These payloads compress well due to the repeated keys, whitespace, and braces. Caching public APIs for 5-10 seconds is a popular approach to reducing origin load while maintaining the freshness of data.

Even without caching, compressing these responses can reduce the total bytes sent by up to 90%.
Improve playback start time for video delivery and join latency for live streaming. Large live playlists (manifests) have a significant amount of repeated data, including the host + path prefix of each segment, as well as the HLS or DASH playlist metadata. The faster the playlist loads or playlist updates can be downloaded, the less time a client is waiting to parse and start downloading the referenced video segments. HLS and DASH playlists often see a total size reduction of more than 90%.

Before you begin

Make sure that you have a Cloud CDN-enabled global external HTTP(S) load balancer (classic) and a backend configured. If you don't have Cloud CDN currently configured, you can follow one of the setup guides.
Your backend has compressible content ready to serve, such as web assets or video manifests between 1 KiB and 10 MiB (inclusive).
Make sure that clients don't rely on fetching partial content with range requests or with strong ETags. These are incompatible with dynamic compression.
Make sure that clients can handle responses without content-length headers. Cache misses that Cloud CDN compresses don't have content-length headers.
You have the IAM Compute Load Balancer Admin role (roles/compute.loadBalancerAdmin), which is required to make changes to your backend configuration.

Enable compression on a backend service or backend bucket

To enable compression, follow these steps.

Console

Add a new origin

To add a new origin:

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

Go to Cloud CDN origins
Click Add origin. The New origin page is displayed.
In the Origin basics section, complete the following:
1. In the Origin name field, enter a name for your origin.
  
  The name that you choose must start with a lowercase letter followed by up to 62 lowercase letters, numbers, or hyphens. The name can't end with a hyphen.
2. Select an Origin configuration:
  - Backend bucket: Use a Cloud Storage bucket as an origin. In Define your backend bucket, you select either a new Cloud Storage bucket or an existing Cloud Storage bucket.
  - Custom origin: Use a custom origin. In Define your custom origin, enter the IP address or domain name and a port that Cloud CDN uses to connect to your origin.
  - Backend service: Use a load balancer that is configured as a backend. In Define your backend service, select the backend service to use. If you don't have a backend service already configured, you can configure one now.
3. To continue, click Next.
In the Host and path rules section, select either of the following:
- Select an existing load balancer: You can choose an existing load balancer from the Select a load balancer list.
- Create a new load balancer for me: Cloud CDN can create a new load balancer for you. Enter a name for your new load balancer in the Load Balancer name field.
  
  The name must start with a lowercase letter, followed by up to 62 lowercase letters, numbers, or hyphens. The name can't end with a hyphen.
To continue, click Next.
In the Basic options section, follow these steps.
1. For Cache mode, select one of the following:
  - Cache static content: We recommend this setting for most situations.
  - Use origin settings based on Cache-Control headers: Cloud CDN caches responses with valid-control directives in the response headers, such as Cache-Control: public, max_age=3600.
  - Force cache all content: This forces Cloud CDN to cache all content, ignoring any private, no-store, or no-cache directives.
    
    Warning: This setting might result in Cloud CDN caching private, user-identifiable data. Only use this on backends not serving private or dynamic content, such as Cloud Storage buckets.
2. For Cache static content and Force cache all content, you can set the following:
  - Client time to live: Allows you to set a shorter time to live for browsers or clients, and have those clients revalidate against Cloud CDN on a more regular basis.
    
    The value of client time to live can't be greater than the maximum time to live but can be equal.
  - Default time to live: Specifies the default time to live for cached content served by this origin, for responses that don't already have a valid time to live.
    
    The value of default time to live can't be set to a value greater than the maximum time to live but can be equal.
3. For Cache static content, select the Maximum time to live.
  
  Maximum time to live allows you to set the maximum time to live for cached content served by this origin.
4. For Cache keys, select one of the following from the Cache key list:
  - Default: Includes query parameters that are known to Cloud Storage.
  - Custom: Select the cache key components, such as query string or HTTP headers, that Cloud CDN uses to distinguish between cache entries.
5. For Advanced options, complete the following:
  1. Select a compression mode in the Compression mode list.
    
    To enable dynamic compression, select Automatic.
  2. For Serve while stale, select a length of time that Cloud CDN continues serving stale content on a cache miss or origin error.
6. For Restricted content, select one of the following:
  - Allow public access to my content cached by Cloud CDN: We recommend this setting for most situations.
  - Restrict access using signed URLs and signed cookies: Allows you to restrict access to authorized viewers. You provide a time-limited URL or cookie that grants users access for a limited time. For more information, see Use signed urls and Use signed cookies.
7. Optional: Add custom response headers. For more information, see Create custom headers in backend services.
8. Optional: Enable negative caching. For more information, see Use negative caching.
9. Optional: Add specific headers that, when present, bypass the cache. For more information, see Bypass the cache.
To create the origin, click Done.

Edit an existing origin

To edit an existing Cloud CDN origin:

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

Go to Cloud CDN origins
Click on the origin name that you want to edit, and then click Edit.
In the Origin basics section, click Next.
In the Host and path rules section, click Next.
In the Cache performance section, navigate to Advanced options.
In the Compression mode list, select Automatic.
To apply your changes, click Done.

gcloud

For backend services, use the gcloud beta compute backend-services create or gcloud beta compute backend-services update command with the --compression-mode flag.

For backend buckets, use the gcloud beta compute backend-buckets create or gcloud beta compute backend-buckets update command with the --compression-mode flag.

For a new backend service, use the create command:

gcloud beta compute backend-services create BACKEND_SERVICE_NAME \
    --compression-mode=AUTOMATIC

For an existing backend service, use the update command:

gcloud beta compute backend-services update BACKEND_SERVICE_NAME \
    --compression-mode=AUTOMATIC

For a new backend bucket, use the create command:

gcloud beta compute backend-buckets create BACKEND_BUCKET_NAME
    --compression-mode=AUTOMATIC

For an existing backend bucket, use the update command:

gcloud beta compute backend-buckets update BACKEND_BUCKET_NAME
    --compression-mode=AUTOMATIC

The compression-mode can be one of the following:

AUTOMATIC: Automatically uses the best compression based on the Accept-Encoding header sent by the client. In most cases, this results in Brotli compression being favored.
DISABLED (default): Disables compression.

API

For backend services, use the Method: backendServices.insert or Method: backendServices.update API call.

For backend buckets, use the Method: backendBuckets.insert or Method: backendBuckets.update API call.

Use one of the following API calls:

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

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

Add the following snippet to the JSON request body:

"compressionMode": AUTOMATIC

The compression-mode can be one of the following:

AUTOMATIC (recommended): Automatically uses the best compression based on the Accept-Encoding header sent by the client. In most cases, this results in Brotli compression being favored.
DISABLED (default): Disables compression.

Within a few minutes, your configuration propagates to all edge locations. Compressible content served from the backend is compressed before being delivered to the client.

Compression modes

The default compression mode is DISABLED. Only backends with a loadBalancingScheme of EXTERNAL can configure a compression mode other than DISABLED.

AUTOMATIC mode allows Cloud CDN to choose the best compression method based on the following:

The client's accepted encoding
The response's anticipated compression ratio
Cloud CDN's compression speed (throughput)

Brotli can yield an additional 10% to 20% reduction in download size for most content types over Gzip, with similar decompression performance, making it faster overall when considering download time and decompression speed on the client.

Cloud CDN determines the compression level to balance total download size and CPU cost on the client. Higher compression levels do not always benefit performance, especially on lower-powered mobile devices.

When is a response compressed?

Uncompressed responses served from the backend (origin) with a Content-Type header that matches the compressible content types are compressed based on the client's Accept-Encoding header.

Most web browsers provide an Accept-Encoding header with a set of weighted values. For example, Google Chrome typically sends Accept-Encoding: br;q=1.0, gzip;q=0.8, *;q=0.1, which sets a preference for Brotli over Gzip. The final *;q=0.1 means that any other compression scheme has the lowest preference.

Other clients might specify a preference without weights—for example, Accept-Encoding: gzip, compress, br. In this case, the server chooses based on its own preferences.

Dynamic compression prefers Brotli (br) over other compression encodings if no preferences (weights) are provided by the client.

For example, given an Accept-Encoding header in a client request, the response is compressed (or not) according to the information in the following table.

Accept-Encoding request header	Response encoding
`gzip, compress, br`	Brotli (br)
`deflate`	Not compressed
`gzip;q=1.0, br;q=0.8, *;q=0.1`	Gzip
`deflate, gzip`	Gzip
`identity`	Not compressed

Compressible content types

Dynamic compression applies to the following MIME types, based on the Content-Type HTTP response header. Responses that don't have a Content-Type response header aren't compressed.

Common content types and their MIME types include the following:

HTML content: text/html
Stylesheets: text/css
JavaScript: application/javascript
JSON: application/json
HLS playlists: application/x-mpegURL or application/vnd.apple.mpegURL
DASH manifests: application/dash+xml

The following table summarizes how the MIME type affects compressibility.

	Compressible MIME types
Exact match	application/x-javascript application/x-sdch-dictionary application/javascript application/xml application/csv application/json application/json+protobuf application/signed-exchange application/vnd.apple.mpegurl application/wasm application/x-plist application/x-protobuffer application/x-protobuf application/x-nacl application/x-pnacl font/ttf font/otf font/eot image/svg+xml image/pwg-raster image/x-icon image/vnd.microsoft.icon video/vnd.mpeg.dash.mpd audio/mpegURL application/dash+xml application/vnd.ms-sstr+xml
Pattern match	application/+json application/+xml application/mpegURL text/

Compressible MIME types

Exact match

application/x-javascript
application/x-sdch-dictionary
application/javascript
application/xml
application/csv
application/json
application/json+protobuf
application/signed-exchange
application/vnd.apple.mpegurl
application/wasm
application/x-plist
application/x-protobuffer
application/x-protobuf
application/x-nacl
application/x-pnacl
font/ttf
font/otf
font/eot
image/svg+xml
image/pwg-raster
image/x-icon
image/vnd.microsoft.icon
video/vnd.mpeg.dash.mpd
audio/mpegURL
application/dash+xml
application/vnd.ms-sstr+xml

Pattern match

application/*+json
application/*+xml
application/*mpegURL
text/*

Image and video formats (such as image/jpeg, image/png, and video/mpeg4) are almost always already compressed, so Cloud CDN doesn't compress them. Re-compressing an already compressed response rarely reduces file size, and clients might exhibit unexpected behavior when receiving a response of this kind.

When is a response not compressed?

Dynamic compression doesn't compress a response that has one or more of the following characteristics:

The response doesn't have a Content-Type header that matches a compressible content type.
It doesn't have a Content-Length header.
It's smaller than 1 KiB.

The time spent compressing and decompressing often offsets any benefits. There's also less content to compress, which can reduce the effectiveness of compression and lead to a lower compression ratio.
It's larger than 10 MiB.
It has a Cache-Control: no-transform header.
It has a Vary: Accept-Encoding header.

Range requests

When Cloud CDN compresses a response, Cloud CDN adds an Accept-Ranges: none header and replaces any existing Accept-Ranges headers. Cache hits for such responses ignore Range headers.

This prevents serving incorrect partial content to clients because there is no way to be sure whether a client expects a range of bytes from the compressed or uncompressed form of a resource.

ETags

When dynamic compression compresses a response, any strong ETag headers are weakened, as required by RFC 7232 section 2.3. For example, ETag: "xyzzy" is replaced with ETag: W/"xyzzy".

Vary header

When serving a response that has the potential to be compressed (depending on the request), Cloud CDN adds the Vary: Accept-Encoding header to the response.

Logging

The Cloud CDN and external HTTP(S) load balancer logs include a compressionStatus field in the jsonPayload indicating whether the response was compressed by the load balancer as well as the compression type.

{
  insertId: "1c02hw9g3gjay67"
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry"
    statusDetails: "response_sent_by_backend"
    cacheId: "IAD-862d661f"
    compressionStatus: "br"
  }
}

Billing

When a response is compressed by Cloud CDN or Cloud Load Balancing, the relevant cache egress or internet egress (respectively) is measured against the final compressed bytes sent to the client.

If you are serving a large amount of compressible responses, this can result in a reduction in your monthly egress fees, as well as increased performance for end users.

Metrics

When compression is enabled, the existing https/response_bytes_count metric under loadbalancing.googleapis.com reports the compressed response size.

You should expect to see a drop in total response bytes (and egress throughput).

If you are serving a large amount of text-based content that compresses well, such as HTML, CSS, JavaScript, or JSON, you might see a large drop in response bytes.

For more information, see Monitoring.

What's next

To understand how cache modes make it easier to cache content, see Using cache modes.
To enable Cloud CDN for your HTTP(S) load balanced instances and storage buckets, see Using Cloud CDN.
To learn about invalidating caches, see Cache invalidation overview.
To find GFE points of presence, see Cache locations.