craftcms / aws-s3
Amazon S3 integration for Craft CMS
Installs: 1 348 645
Dependents: 25
Suggesters: 0
Security: 0
Stars: 61
Watchers: 7
Forks: 28
Open Issues: 17
Type:craft-plugin
Requires
- php: ^8.0.2
- craftcms/cms: ^4.0.0-beta.1|^5.0.0-beta.1
- craftcms/flysystem: ^1.0.0-beta.2|^2.0.0
- league/flysystem-aws-s3-v3: ^3.0.0
Requires (Dev)
- craftcms/ecs: dev-main
- craftcms/phpstan: dev-main
- craftcms/rector: dev-main
- 2.x-dev
- 2.2.1
- 2.2.0
- 2.1.0
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 2.0.0-beta.3
- 2.0.0-beta.2
- 2.0.0-beta.1
- v1.x-dev
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.15
- 1.2.14
- 1.2.13
- 1.2.12
- 1.2.11
- 1.2.10
- 1.2.9
- 1.2.8
- 1.2.7
- 1.2.6
- 1.2.5
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0.1
- dev-dependabot/npm_and_yarn/braces-3.0.3
- dev-dependabot/composer/composer/composer-2.7.7
- dev-fix-invalidations
- dev-fix-web-identity-check
This package is auto-updated.
Last update: 2024-10-24 23:38:16 UTC
README
Amazon S3 for Craft CMS
This plugin provides an Amazon S3 integration for Craft CMS.
Requirements
This plugin requires Craft CMS 4.0.0+ or 5.0.0+.
Installation
You can install this plugin from the Plugin Store or with Composer.
From the Plugin Store
Go to the Plugin Store in your project’s Control Panel and search for “Amazon S3”. Then press Install in its modal window.
With Composer
Open your terminal and run the following commands:
# go to the project directory cd /path/to/my-project.test # tell Composer to load the plugin composer require craftcms/aws-s3 # tell Craft to install the plugin ./craft plugin/install aws-s3
Setup
To create a new Amazon S3 filesystem to use with your volumes, visit Settings → Filesystems, and press New filesystem. Select “Amazon S3” for the Filesystem Type setting and configure as needed.
💡 The Base URL, Access Key ID, Secret Access Key, Bucket, Region, Subfolder, CloudFront Distribution ID, and CloudFront Path Prefix settings can be set to environment variables. See Environmental Configuration in the Craft docs to learn more about that.
AWS IAM Permissions
Setting up IAM permissions for use with this plugin differs from what options you want to be available.
Generally, you'll want an IAM policy that grants the following actions on the resource(s) that you'll use:
s3:GetBucketLocation
s3:ListBucket
s3:PutObject
s3:GetObject
s3:DeleteObject
s3:GetObjectAcl
s3:PutObjectAcl
If you want to allow the site administrator to list and select the bucket to use, you'll also have to add the s3:ListAllMyBuckets
permission to the arn:aws:s3:::
resource and the s3:GetBucketLocation
permission to the specific bucket resource. Please note, that if a bucket lacks the s3:GetBucketLocation
permission, it will not appear in the bucket selection list.
If you use Cloudfront and would like Craft to invalidate files on your behalf you'll also need the following permissions:
cloudfront:ListInvalidations
cloudfront:GetInvalidation
cloudfront:CreateInvalidation
A typical IAM policy that grants the user to choose a bucket can look like this:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:GetObjectAcl",
"s3:PutObjectAcl",
"cloudfront:ListInvalidations",
"cloudfront:GetInvalidation",
"cloudfront:CreateInvalidation"
],
"Resource": [
"arn:aws:s3:::bucketname/*",
"arn:aws:cloudfront::accountid:distribution/distributionid"
]
},
{
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::bucketname"
]
}
]
}
Using automatic focal point detection
This plugin can use the AWS Rekognition service to detect faces in an image and automatically set the focal point accordingly. This requires the image to be either a jpg or a png file. You can enable this feature via Attempt to set the focal point automatically? in the filesystem settings.
⚠️ ️Using this will incur extra cost for each upload, and requires the
rekognition:DetectFaces
action to be allowed.
Assuming Role with OIDC
This plugin also has the ability to assume a role provided to the runtime with the AWS_WEB_IDENTITY_TOKEN_FILE
and AWS_ROLE_ARN
environment variables. If you provide no credentials to AWS and these environment variables exist, then the plugin will attempt to create a connection to AWS using the CredentialProvider::assumeRoleWithWebIdentityCredentialProvider
. This is the ideal way to allow fine-grained access control for hosting Craft CMS in Kubernetes (for example). See the IAM documentation on AWS for more details.
Tasks running in ECS
This plugin is compatible with IAM roles for ECS tasks and will automatically use the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
environment variable, if it’s available. See the IAM Roles for Tasks documentation on AWS for more details.