Skip to main content
Version: 4-preview

Internal cache: Azure Blob Storage

imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, do the following:

  1. Set the IMGPROXY_CACHE_USE environment variable to abs.
  2. Set IMGPROXY_CACHE_ABS_NAME to your Azure account name.
  3. Set up the necessary credentials.
  4. Specify the cache container name with IMGPROXY_CACHE_BUCKET.
  5. (optional) Specify the Azure Blob Storage endpoint with IMGPROXY_CACHE_ABS_ENDPOINT.

Configuration​

  • IMGPROXY_CACHE_USE: set to abs to enable Azure Blob Storage cache.
  • IMGPROXY_CACHE_ABS_NAME: the Azure account name for cache storage. Default: blank
  • IMGPROXY_CACHE_BUCKET: the Azure container name for cache storage. Default: blank
  • IMGPROXY_CACHE_ABS_KEY: the Azure account key for cache storage. Default: blank
  • IMGPROXY_CACHE_ABS_ENDPOINT: a custom Azure Blob Storage endpoint for cache. Default: blank
  • IMGPROXY_CACHE_PATH_PREFIX: a path prefix for the cache files. Default: blank
  • IMGPROXY_CACHE_KEY_HEADERS: a comma-separated list of HTTP request headers to include in the cache key. Default: blank
  • IMGPROXY_CACHE_KEY_COOKIES: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank
  • IMGPROXY_CACHE_REPORT_ERRORS: when true, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: false

Set up credentials​

Leverage Azure Managed Identity or Service Principal​

Microsoft recommends using a Managed Identity or Service Principal when accessing resources in an Azure Storage Account. Both of these authentication pathways are supported out of the box.

Managed Identity​

No additional configuration is required so long as the resource running imgproxy has a Managed Identity assigned.

Service Principal​

Please refer to the following documentation on creating a service principal before proceeding.

Once that step is complete, the following environment variables must be configured based on the chosen option.

For secret authentication:

  • AZURE_CLIENT_ID: the client ID for your application registration
  • AZURE_TENANT_ID: the tenant ID for your application registration
  • AZURE_CLIENT_SECRET: the client secret for your application registration

For certificate authentication:

  • AZURE_CLIENT_ID: the client ID for your application registration
  • AZURE_TENANT_ID: the tenant ID for your application registration
  • AZURE_CLIENT_CERTIFICATE_PATH: the path to a PFX or PEM-encoded certificate including private key
  • AZURE_CLIENT_CERTIFICATE_PASSWORD: (optional) the password protecting the certificate file (PFX (PKCS12))
  • AZURE_CLIENT_CERTIFICATE_CHAIN: (optional) send certificate chain in x5c header to support subject name / issuer-based authentication

Using Storage Account Key​

Alternatively, you can set IMGPROXY_CACHE_ABS_KEY to your Azure Blob Storage account key. See the Manage storage account access keys guide for more info.