Skip to content

amazon_s3.mdx

Latest commit

 

History

History
99 lines (65 loc) · 5.69 KB

amazon_s3.mdx

File metadata and controls

99 lines (65 loc) · 5.69 KB
description Learn about how to connect your Amazon S3 buckets to imgproxy

Serving files from Amazon S3

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

  1. Set the IMGPROXY_USE_S3 environment variable to be true.
  2. Set up the necessary credentials to grant access to your bucket.
  3. (optional) Specify the AWS region with IMGPROXY_S3_REGION or AWS_REGION. Default: us-west-1
  4. (optional) Specify the S3 endpoint with IMGPROXY_S3_ENDPOINT. You can also set IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=false to use the virtual host style for the endpoint.
  5. (optional) Set the IMGPROXY_S3_USE_DECRYPTION_CLIENT environment variable to true if your objects are client-side encrypted.
  6. (optional) Specify the AWS IAM Role to Assume with IMGPROXY_S3_ASSUME_ROLE_ARN.
  7. (optional) Specify the External ID that needs to be passed in along with the AWS IAM Role to Assume with IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID. This will have no effect if the assume role ARN is not specified.
  8. Use s3://%bucket_name/%file_key as the source image URL.

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

s3://%bucket_name/%file_key?%version_id

:::tip If filenames in your S3 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 ?version=, you can specify the version like this:

s3://%bucket_name/%file_key?version=%version_id

:::

Set up credentials

There are three ways to specify your AWS credentials. The credentials need to have read rights for all of the buckets given in the source URLs:

IAM Roles

If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to to get the security credentials to make calls to AWS S3.

Environment variables

You can specify an AWS Access Key ID and a Secret Access Key by setting the standard AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy

# same for Docker
docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it ghcr.io/imgproxy/imgproxy

Shared credentials file

Alternatively, you can create the .aws/credentials file in your home directory with the following content:

[default]
aws_access_key_id = %access_key_id
aws_secret_access_key = %secret_access_key

Cross-Account Access

S3 access credentials may be acquired by assuming a role using STS. To do so specify the IAM Role arn with the IMGPROXY_S3_ASSUME_ROLE_ARN environment variable. Additionally, if you require an external ID to be passed when assuming a role, specify the IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID environment variable. This approach still requires you to provide initial AWS credentials by using one of the ways described above. The provided credentials role should allow assuming the role with provided ARN.

Choosing the AWS region

The AWS region specified with the IMGPROXY_S3_REGION or AWS_REGION environment variable determines the S3 endpoint used by imgproxy for the initial request to the bucket. If AWS reports that the bucket is in a different region, imgproxy will remember this, retry the request, and use the new region for all subsequent requests for this bucket.

This allows imgproxy to access buckets in any region. However, the initial request to the bucket in a different region than the one specified in the environment variable may add some latency. Thus, the rule of thumb for the best performance is the following:

  • If you are going to use only one bucket, set the region to the one where the bucket is located.
  • If your most frequently used buckets are in the same region, set the region to that one.
  • If your buckets are spread across multiple regions, set the region to the closest one to your imgproxy instance.

Restricting bucket access

For security purposes, you can restrict which S3 buckets imgproxy is allowed to access:

  • IMGPROXY_S3_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_S3_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_S3_ALLOWED_BUCKETS to create an allowlist of trusted buckets, or use IMGPROXY_S3_DENIED_BUCKETS to block specific buckets. If both are set, allowed buckets take precedence. :::

MinIO

MinIO is an object storage server released under Apache License v2.0. It is compatible with Amazon S3, so it can be used with imgproxy.

To use MinIO as source images provider, do the following:

  • Set up Amazon S3 support as usual using environment variables or a shared config file.
  • Specify an endpoint with IMGPROXY_S3_ENDPOINT. Use the http://... endpoint to disable SSL.