Skip to main content
Version: 4-preview

Serving files from Google Cloud Storage

imgproxy can process images from Google Cloud Storage buckets. To use this feature, do the following:

  1. Set the IMGPROXY_USE_GCS environment variable to true.
  2. Set up credentials to grant access to your bucket.
  3. (optional) Specify the Google Cloud Storage endpoint with IMGPROXY_GCS_ENDPOINT.
  4. Use gs://%bucket_name/%file_key as the source image URL.

If you need to specify generation of the source object, you can use the query string of the source URL:

gs://%bucket_name/%file_key?%generation
tip

If filenames in your Google Cloud Storage may contain ?, you may want to set IMGPROXY_SOURCE_URL_QUERY_SEPARATOR to another string that is not used in filenames or set it to blank to disable query string extraction.

For example, if you set IMGPROXY_SOURCE_URL_QUERY_SEPARATOR to ?generation=, you can specify the generation like this:

gs://%bucket_name/%file_key?generation=%generation

Setup credentials​

If you run imgproxy inside Google Cloud infrastructure (Compute Engine, Kubernetes Engine, App Engine, and Cloud Functions, etc), and you have granted access to your bucket to the service account, you probably don't need to do anything here. imgproxy will try to use the credentials provided by Google.

Otherwise, set IMGPROXY_GCS_KEY environment variable to the content of Google Cloud JSON key. Get more info about JSON keys: https://cloud.google.com/iam/docs/creating-managing-service-account-keys.

warning

For security reasons, imgproxy accepts only service account keys for Google Cloud Storage integration.

Restricting bucket access​

Restrict which GCS buckets imgproxy can access for security:

  • IMGPROXY_GCS_ALLOWED_BUCKETS: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed)
  • IMGPROXY_GCS_DENIED_BUCKETS: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank
tip

Use IMGPROXY_GCS_ALLOWED_BUCKETS to allow trusted buckets. Use IMGPROXY_GCS_DENIED_BUCKETS to block specific ones. If both are set, allowed buckets override denied ones.