Last Reviewed: September 01, 2016

AWS S3 Setup for Drupal

Add the ability to integrate AWS S3 with a Drupal site on Pantheon

Edit this page on GitHub Report an issue with this doc

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.

Note

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.
  Info:
  Note
  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.
  Info:
  Note
  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 default.settings.php file to settings.php or create an empty settings.php file within the sites/default directory 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 sites/all/libraries/awssdk2 directory.

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 (admin/config/media/s3fs/settings).

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

Go to 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)

From /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.