Getting started

This page helps you to get started with Cloud CDN image optimization, explaining how to configure image optimization and list of supported operations with examples.

Prerequisites

For Cloud CDN image optimization to work, ensure that the following prerequisites are met:

  • Cloud CDN cache policy must be enabled on the URL route or the associated backend service or bucket, and the image optimization feature must be active on that URL map route.

  • Image optimization is supported for Global External Application Load Balancers only. classic Application Load Balancer are not supported.

  • The client request must include an Accept header indicating it can receive image content, such as image/webp, image/avif, image/*, or */*.

  • The origin server must respond with an HTTP 200 status code and a supported image Content-Type header.

  • The imop query parameter must be included in the URL and contain one or more valid transformation operations.

Configure image optimization

To use image optimization, you must enable Cloud CDN on the relevant route, backend service, or backend bucket.

gcloud

You must add configurations to your YAML file and import it to the URL map as image optimization policies are defined inside the routeAction object.

Export your existing URL map configuration to a local YAML file:

gcloud beta compute url-maps export YOUR_URL_MAP_NAME \
    --global \
    --destination my-url-map.yaml

Edit the my-url-map.yaml file in a text editor and add the cachePolicy field to the selected routeAction or defaultRouteAction sections.

name: image-matcher
routeRules:
  --description: ImageOptimizationService
    matchRules:
       --prefixMatch: /images/
    priority: 1
    routeAction:
       imageOptimizationPolicy:
         queryParameterInterpretation: ENABLED

Import the updated URL map

gcloud beta compute url-maps import YOUR_URL_MAP_NAME \
    --global \
    --source my-url-map.yaml

Supported image formats

Cloud CDN image optimization supports specific input and output formats based on the request configuration and origin content type headers.

Supported input formats

The following formats are supported as input from your origin server:

  • HEIF
  • ICO
  • BMP
  • JP2K (JPEG 2000)

Supported output formats

Cloud CDN edge can process, cache, and serve optimized image derivatives in the following formats:

  • JPEG
  • GIF
  • PNG
  • TIFF
  • WEBP
  • AVIF
  • BRUNSLI

Supported origin content types

Image optimization is attempted when your origin server responds with one of the following Content-Type headers:

  • image/jpeg
  • image/png
  • image/webp
  • image/gif
  • image/bmp
  • image/tiff
  • image/avif
  • image/heif
  • image/jp2
  • image/x-j (brunsli)
  • text/ico, image/ico, image/icon, application/ico, image/x-icon, or image/vnd.microsoft.icon

Image transformation URL

To perform dynamic image transformations, add the imop query parameter to your image URL. This parameter holds a transformation string, which consists of one or more operations applied in sequence.

The transformation string uses the following format rules:

  • Use a semicolon (;) to separate each individual operation.
  • Use a comma (,) to separate the internal parameters within each individual operation.
  • Only one operation of a given type can be included in a single query string.

The baseline syntax uses the following structure:

?imop=[OPERATION_1];[OPERATION_2];...[OPERATION_N]

To perform multiple actions on an image simultaneously, append a chained parameter string to the image URL. For example, to resize an image to 800 pixels wide, set the compression quality to 85, and convert the format to WebP, append the parameter string.

For example,

https://www.example.com/image.jpg?imop=Resize,width=800;Compress,quality=85;Convert,format=webp;

Policy structure

The image optimization policy acts as the core configuration wrapper containing every property relevant to the functionality of the image optimization feature.

Name

Description

Configuration

queryParameterInterpretation

Enum value that determines whether the query parameter for image optimization will be interpreted in the data plane.

Required. If set to DISABLED, query parameters for transformation will be ignored by the policy, effectively disabling this feature. If set to ENABLED, this feature will be enabled.

Policy dependencies and validation

The image optimization policy has a dependency on Cloud CDN caching. For this feature to work, a Cache Policy must be explicitly set on one of two locations:

  • The same URL map route where the Image optimization policy is being configured.

  • A backend service or backend bucket related to that exact route.

The image optimization policy is applied strictly in conjunction with the active, underlying Cache Policy.

Image optimization ordering rules

Operations listed in the imop query parameter are processed from left to right, with the exception of the following absolute system overrides:

  • metadata and scale operations are always executed first.
  • canvas operations are always executed last.

All input assets undergo automatic normalization before these transformations execute. EXIF orientation markers and ICC color profiles are applied directly to the image pixels before any metadata is stripped, ensuring coordinate integrity remains accurate for subsequent structural actions.

What's next