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 a wide range of input formats from your origin server. While most formats can be used for processing and output, some formats are Input only and cannot be used as target output formats.

The following image formats are supported from your origin server:

Format Content-Type Header Input/output Usecase scenario
gif image/gif Input and output Standard animated/still format. Animated frames can be extracted using the Freeze operation.
png image/png Input and output Lossless format, ideal for transparency, logos, and digital art.
webp image/webp Input and output Modern, web-optimized format with both lossy and lossless compression.
jpeg image/jpeg Input and output Standard photographic format.
brunsli image/x-j Input and output High-efficiency lossless JPEG repacking format.
tiff image/tiff Input and output High-quality tag-based raster format.
avif image/avif Input and output High-efficiency next-generation image format.
bmp image/bmp Input only Cannot be specified as an output format. Convert to WEBP or JPEG using ?imop=Convert,format=webp.
ico text/ico, image/ico, image/icon, application/ico, image/x-icon, image/vnd.microsoft.icon Input only Icon container format. Cannot be exported; convert to a supported output format for delivery.
jp2k image/jp2 Input only JPEG 2000 format. Must be explicitly converted using a Convert operation.
heif image/heif Input only High Efficiency Image Format. Must be converted before edge delivery.

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