|
| 1 | +--- |
| 2 | +description: Learn about how to configure Amazon S3 cache in imgproxy |
| 3 | +--- |
| 4 | + |
| 5 | +# Cache storage: Amazon S3 |
| 6 | + |
| 7 | +imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, do the following: |
| 8 | + |
| 9 | +1. Set `IMGPROXY_CACHE_USE` environment variable to `s3`. |
| 10 | +2. [Set up the necessary credentials](#set-up-credentials) to grant access to your cache bucket. |
| 11 | +3. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION`. Default: `us-west-1` |
| 12 | +4. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. |
| 13 | +5. _(optional)_ Specify the S3 endpoint with `IMGPROXY_CACHE_S3_ENDPOINT`. You can also set `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint. |
| 14 | +6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`. |
| 15 | +7. _(optional)_ Specify the External ID that needs to be passed in along with the AWS IAM Role to Assume with `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified. |
| 16 | + |
| 17 | +### Configuration |
| 18 | + |
| 19 | +* `IMGPROXY_CACHE_USE`: set to `s3` to enable S3 cache. |
| 20 | +* `IMGPROXY_CACHE_BUCKET`: the S3 bucket name for cache storage. Default: blank |
| 21 | +* `IMGPROXY_CACHE_S3_REGION`: the S3 region for the cache bucket. Default: blank |
| 22 | +* `IMGPROXY_CACHE_S3_ENDPOINT`: a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank |
| 23 | +* `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE`: controls how the S3 bucket endpoint is constructed. When `true`, the endpoint will be constructed using the path style (`https://your-endpoint.com/%bucket`). When `false`, the endpoint will be constructed using the virtual host style (`https://%bucket.your-endpoint.com`). Default: `true` |
| 24 | +* `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`: the ARN of an IAM role to assume for cache access. Default: blank |
| 25 | +* `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`: the external ID required to assume the IAM role for cache access. Default: blank |
| 26 | +* `IMGPROXY_CACHE_PATH_PREFIX`: a path prefix for the cache files. Default: blank |
| 27 | +* `IMGPROXY_CACHE_KEY_HEADERS`: a comma-separated list of HTTP request headers to include in the cache key. Default: blank |
| 28 | +* `IMGPROXY_CACHE_KEY_COOKIES`: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank |
| 29 | +* `IMGPROXY_CACHE_REPORT_ERRORS`: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` |
| 30 | + |
| 31 | +### Set up credentials |
| 32 | + |
| 33 | +There are three ways to specify your AWS credentials. The credentials need to have read/write rights for the cache bucket: |
| 34 | + |
| 35 | +#### IAM Roles |
| 36 | + |
| 37 | +If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to get the security credentials to make calls to AWS S3. |
| 38 | + |
| 39 | +* **Elastic Container Service (ECS):** Assign an [IAM role to a task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html). |
| 40 | +* **Elastic Kubernetes Service (EKS):** Assign a [service account to a pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html). |
| 41 | +* **Elastic Beanstalk:** Assign an [IAM role to an instance](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/iam-instanceprofile.html). |
| 42 | + |
| 43 | +#### Environment variables |
| 44 | + |
| 45 | +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. |
| 46 | + |
| 47 | +```bash |
| 48 | +AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy |
| 49 | + |
| 50 | +# same for Docker |
| 51 | +docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it ghcr.io/imgproxy/imgproxy |
| 52 | +``` |
| 53 | + |
| 54 | +#### Shared credentials file |
| 55 | + |
| 56 | +Alternatively, you can create the `.aws/credentials` file in your home directory with the following content: |
| 57 | + |
| 58 | +```ini |
| 59 | +[default] |
| 60 | +aws_access_key_id = %access_key_id |
| 61 | +aws_secret_access_key = %secret_access_key |
| 62 | +``` |
| 63 | + |
| 64 | +#### Cross-Account Access |
| 65 | + |
| 66 | +Cache S3 access credentials may be acquired by assuming a role using STS. To do so specify the IAM Role arn with the `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN` environment variable. Additionally, if you require an external ID to be passed when assuming a role, specify the `IMGPROXY_CACHE_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. |
| 67 | + |
| 68 | +### Choosing the AWS region |
| 69 | + |
| 70 | +The AWS region specified with the `IMGPROXY_CACHE_S3_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. |
| 71 | + |
| 72 | +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. |
0 commit comments