Private bucket origin · Google Cloud Storage

Serve images from a private Google Cloud Storage bucket

Fetch and resize originals from a private Google Cloud Storage bucket. Edge nodes sign requests with GCS interoperability HMAC keys and deliver AVIF or WebP.

How it works

Google Cloud Storage offers an XML API compatible with AWS Signature Version 4 at https://storage.googleapis.com/<bucket>/. With an HMAC key for a service account that has Storage Object Viewer on the bucket, edge nodes sign each GET request without making the bucket public and without loading a Google Cloud SDK.

# Public delivery URL
https://a3f9c21b.zwcld.net/v1/products/sofa.jpg?w=800&f=auto&q=auto
# Signed fetch by the edge node
GET https://storage.googleapis.com/my-images/products/sofa.jpg

Signing: AWS Signature Version 4 (HMAC-SHA256) for service s3 with region auto against https://storage.googleapis.com/<bucket>/.

What the console asks for

Field What to give
Bucket The Google Cloud Storage bucket name, such as my-images.
Folder (optional) A prefix inside the bucket, such as images/originals.
Access key id and secret An HMAC key (Access ID and Secret) from Cloud Storage → Settings → Interoperability, for a service account with roles/storage.objectViewer on the bucket.

The secret is sealed at rest with the Data Protection key ring and never shown back in the console. Rotating credentials means entering a new key on the bucket row; edge nodes pick it up within a minute.

Setting it up, step by step

  1. In Google Cloud Console, create a service account granted Storage Object Viewer on your image bucket.
  2. Open Cloud Storage → Settings → Interoperability and generate an HMAC key for that service account.
  3. In the ZawCloud console, open the Domains tab → Add a private bucket, choose Google Cloud Storage, and enter the bucket name and HMAC key.
  4. Set the bucket as your account's or custom domain's origin.

Details worth knowing

  • Uses GCS XML API interoperability (HMAC access id and secret); service-account JSON private keys (GOOG4-RSA-SHA256) are not used.
  • Bucket names with dots or underscores work as usual because requests use path style on storage.googleapis.com.
  • When an original is updated in the bucket, purge its path from the console's Cache tab or via POST /v1/purge.

Connect your bucket

An account can configure up to 10 private buckets and point the account origin or individual custom hostnames at them.

Other private bucket origins: Amazon S3 & S3-compatible , Cloudflare R2 , Azure Blob Storage .