Adding an Amazon S3 Source

  1. Documentation
  2. Setup
  3. Creating Sources
  4. Adding an Amazon S3 Source

An Amazon S3 Source connects to an existing Amazon S3 bucket. imgix connects using the credentials you supply, so assets don't have to be public.

Setting Up Your S3 Source

Note: When retrieving S3 objects from the us-east-1 region, imgix uses the s3-external-1.amazonaws.com hostname to retrieve assets whenever possible to ensure read-after-write consistency, and will fall back to the default hostname of s3.amazonaws.com if necessary.

  1. Go to the Sources page in the imgix dashboard and click the New Source button.

  2. Select Amazon S3 from the Source Type dropdown. Screenshot-Amazon S3 source setup

  3. Fill in the details for the Amazon S3 Source (see the security notice below about access/secret keys). The parameters are:

    • Access Key ID: The access key of the credentials you want imgix to connect with.
    • Secret Access Key: The secret key of the credentials you want imgix to connect with.
    • Bucket: The name of the bucket containing the assets you want imgix to connect to.
    • Prefix: The folder prefix you want to resolve to. The prefix is prepended to the asset path before resolving the asset in S3. By default the asset path is /.

  4. Name the Subdomain you'd like to use as the base URL for your assets.

    Note: The subdomain name you choose is unique to your Source and can't be re-used. If you're setting up a Source with a lot of customization (particularly a Custom Domain), choose the name you plan to use going forward.

    • If you are editing an existing Source and the Video API is enabled, the imgix Video Subdomain field will be visible. This field automatically inherits the value from your imgix Image Subdomain and cannot be modified without changing the Image Subdomain.

  5. Set your Asset Processing Rules for the Asset Manager. This setting does not affect which assets can be served through the Rendering API. Instead, it will only impact which assets appear in the Asset Manager based on the path prefix configuration. You can choose to either:

    • Include all paths (default setting)
    • Include one or many user defined paths
    • Exclude all paths
    • Exclude one or many user defined paths

  6. Click the Save button. Your Source will be queued for deployment. Screenshot-Amazon S3 source setup

Security

We strongly recommend creating an Amazon IAM account specifically for imgix to access your S3 bucket with. All Amazon credentials are stored using industry standard cryptographic best practices.

Easy & Secure

The "Amazon S3 Read Only Access" policy template for your IAM account provides the best mix of ease, protection, and imgix feature future-proofing.

  1. Go to your AWS IAM Dashboard
  2. Click Users on the left navigation
  3. Click Add User or select an existing user
  4. If adding a User, give them a User Name and enable Programamtic access. Select Next: Permissions
  5. Click the Permissions tab and then the Add Permissions button
  6. Select the Attach existing policies directly tab
  7. You will be presented with a list of policy templates. Scroll down or search until you see “Amazon S3 Read Only Access” then click the Select button next to it.
  8. Click Next: Review and then Add Permissions

Advanced

imgix only needs a few read-only permissions to properly fetch assets. To add an additional layer of security, use a limited-permissions IAM account that is only used for imgix and only for the bucket containing your assets.

The specific S3 permissions imgix requires are:

  • ListBucket
  • GetBucketLocation
  • GetObject

Advanced Policy Example

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket/*",
        "arn:aws:s3:::your-bucket"
      ]
    }
  ]
}

Note: If you decide to manually build your policy, please double-check it with the Amazon IAM Policy Simulator.

Advanced Settings

See the Advanced Source Settings for information about setting up custom domains, defaults, and cache TTL options.

Next: Serving Assets

Setup
Related Guides