AWS S3 Setup for Drupal
Add the ability to integrate AWS S3 with a Drupal site on PantheonDiscuss in our Forum Discuss in Slack
Amazon Web Services (AWS) offers Simple Storage Service (S3) for scalable storage and content distribution, which can be integrated with Drupal sites running on Pantheon.
Before You Begin
Be sure that you have:
- An existing Drupal site or create one
- Set up an account with Amazon Web Services (AWS). Amazon offers free access to most of their services for the first year.
When creating an AWS account, you will have to enter credit card information. This is required, but you will not be charged unless you exceed the usage limits of their free tier.
Configure S3 within the AWS Console
Before integrating S3 with Drupal, you'll need to configure the service within your AWS Management Console.
Create a New AWS S3 Bucket
If you do not have an existing bucket for your Drupal site, create one:
From your AWS Console, click S3.
Click Create Bucket.
Enter a bucket name. The bucket name you choose must be unique across all existing bucket names in Amazon S3.
After you create a bucket, you cannot change its name. The bucket name is visible in the URL that points to the objects stored in the bucket. Ensure that the bucket name you choose is appropriate.
Select a region and click Create.
Select Permissions within the bucket properties and click Add more permissions.
Choose a user and tick the boxes for Read and Write access for both Objects and Permissions, then click Save.
Create an Identity and Access Management Policy
Identity and Access Management (IAM) allows you to manage all user access to AWS resources and services. Creating a policy allows you to explicitly set limited privileges on your specific bucket. This strategy offers long-term flexibility for organizing and managing users and their privileges.
From your AWS Console, click the IAM link.
Go to Policies and click Create Policy.
Select Create your Own Policy.
Give it a name and use the code example code provided in Amazon's Policy Documentation.
Choose Amazon S3 for the AWS Service and select All Actions. Provide the Amazon Resource Name for your bucket, and click Next Step.
Edit the policy name and description (optional).
Click Create Policy.
For details, see Example Policies for Administering AWS Resources.
Create an Identity and Access Management Group
We recommend that you do not access an S3 bucket using your AWS root user credentials. Instead, create an IAM group and user:
From your AWS Console, click Identity & Access Management.
Click Groups, then Create New Group.
Enter a descriptive group name and click Next Step.
Filter policies by Customer Managed Policies and select your recently created policy.
Click Next Step, then Create Group.
Go to Users and click Create New Users.
Provide a user name and click Create, then view the new user security credentials by clicking Show User Security Credentials.
You can only view or download a user's secret access key immediately after the user has been created. This information cannot be accessed at a later point in time. You will need the access keys when configuring the S3 File System module
Click Download Credentials. Make sure you save the credentials in a secure location before leaving this page.
Go to the group created in step 5 and select Add Users to Group.
Select your newly created user and click Add Users.
Integrate S3 with Drupal
You will need to install the appropriate Drupal module(s) and the AWS SDK library.
The following instructions use Drupal and Terminus, Pantheon's CLI which allows you to call Drush remotely without using a local installation.
These steps require Drush 8, which is run by default on Pantheon for newly created Drupal sites. Sites created prior to November 4, 2015 run 5.x by default.
Before you begin:
Set your site’s Drush version to Drush 8 if needed.
Either copy the
settings.phpor create an empty
settings.phpfile within the
sites/defaultdirectory if you have not done so already.
Set the site's connection mode to SFTP within the site Dashboard or via Terminus:
terminus connection:set <site>.<env> sftp
Install Required and Recommended Modules
S3 File System
Install the Libraries API and S3 File System modules:
terminus drush <site>.<env> -- en libraries s3fs -y
Get the AWS SDK Library 2.x:
terminus drush <site>.<env> -- make --no-core sites/all/modules/s3fs/s3fs.make -y //or if you have a contrib subfolder for modules use: //terminus drush <site>.<env> -- make --no-core sites/all/modules/contrib/s3fs/s3fs.make -y
The above command will add the AWS SDK version 2.x library into the
S3 File System CORS
Use the S3 File System CORS Upload module to enhance your Drupal media handling and interface with your S3 bucket by having your file uploads go directly to your S3 bucket.
Install s3fs_cors module using Drush:
terminus drush <site≥.<env> -- en jquery_update s3fs_cors -y
Drupal Module Configuration
S3 File System User Credentials
You can configure the settings for the S3 File System module via the Drupal admin after the installation (
Enter credentials created for the user in the previous section and your bucket name.
You can optionally use a CNAME to serve files from a custom domain if desired. However, you will need to create a corresponding CNAME record with your DNS host.
Configure Download and Upload Destinations
admin/config/media/file-system and set Default download method to Amazon Simple Storage Service. You can set the Upload destination to S3 File System within the Field Settings tab.
S3 File System CORS Upload (s3fs_cors)
/admin/config/media/s3fs/cors, set CORS Origin to your domain. There's an individual max file path length of 250 characters.
Synchronizing the S3 Bucket and Drupal Files
Periodically, you'll need to run Actions provided by the S3 File System module either via the admin or Terminus to sync Drupal with your S3 bucket.
If you have files on S3 already that are not known to Drupal, refresh the files metadata cache:
terminus drush <site>.<env> -- s3fs-refresh-cache
If you have files in Drupal that need inclusion with S3 run:
terminus drush <site>.<env> -- s3fs-copy-local
If you receive an access denied error message from Amazon, check the permissions on your bucket and policies. Verify all your configuration settings in Drupal are complete and accurate.