Serving files from Amazon S3
imgproxy can process images from S3 buckets. To use this feature, do the following:
- Set the
IMGPROXY_USE_S3
environment variable to betrue
. - Set up the necessary credentials to grant access to your bucket.
- (optional) Specify the AWS region with
IMGPROXY_S3_REGION
orAWS_REGION
. Default:us-west-1
- (optional) Specify the S3 endpoint with
IMGPROXY_S3_ENDPOINT
. You can also setIMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=false
to use the virtual host style for the endpoint. - (optional) Set the
IMGPROXY_S3_MULTI_REGION
environment variable to betrue
. - (optional) Set the
IMGPROXY_S3_USE_DECRYPTION_CLIENT
environment variable totrue
if your objects are client-side encrypted. - (optional) Specify the AWS IAM Role to Assume with
IMGPROXY_S3_ASSUME_ROLE_ARN
. - (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. - 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
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.
- Elastic Container Service (ECS): Assign an IAM role to a task.
- Elastic Kubernetes Service (EKS): Assign a service account to a pod.
- Elastic Beanstalk: Assign an IAM role to an instance.
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 darthsim/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.
Multi-Region mode
By default, imgproxy allows using S3 buckets located in a single region specified with IMGPROXY_S3_REGION
or AWS_REGION
. If your buckets are located in different regions, set IMGPROXY_S3_MULTI_REGION
environment variable to be true
to enable multi-region mode. In this mode, imgproxy will make an additional request to determine the bucket's region when the bucket is accessed for the first time.
In this mode, imgroxy uses a region specified with IMGPROXY_S3_REGION
or AWS_REGION
to determine the endpoint to which it should send the bucket's region determination request. Thus, it's a good idea to use one of these variables to specify a region closest to the imgproxy instance.
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 thehttp://...
endpoint to disable SSL.