Amazon CloudFront
Developer Guide (API Version 2016-09-29)

Getting Started with the AWS for WordPress Plugin

With the AWS for WordPress plugin, you can set up several AWS services, including Amazon CloudFront. With CloudFront, you can provide visitors to your WordPress website an accelerated viewing experience with content cached in edge locations around the world. When visitors come to your website, CloudFront routes them to the edge location that provides the lowest latency for a faster, more reliable experience.

The AWS for WordPress plugin creates a CloudFront distribution that is optimized for WordPress websites, using multiple cache behaviors to handle the different types of content on your website. The CloudFront features of the plugin work with websites hosted on WordPress.com and with self-hosted WordPress websites on Amazon Lightsail, Amazon EC2, or another web hosting platform.

You can also use the plugin to set up other AWS services like Amazon Polly and Amazon Translate, and then configure CloudFront to accelerate the content generated by those services. For more information about using the plugin to set up Amazon Polly, see WordPress Plugin for Amazon Polly in the Amazon Polly Developer Guide. For more information about using CloudFront to accelerate the content generated by Amazon Polly, see (Optional) Create a CloudFront Distribution for Amazon Polly Content.

Prerequisites

To use the AWS for WordPress plugin, you need an AWS account, an AWS Identity and Access Management (IAM) user, and a WordPress website.

Creating an AWS Account

If you have an AWS account already, you can skip this section. Otherwise, create one.

To create an AWS account

  1. Open https://portal.aws.amazon.com/billing/signup.

  2. Follow the online instructions.

    Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

Creating an IAM User

To use the AWS for WordPress plugin, you must create an IAM user for the plugin. An IAM user is a person or application under an AWS account that has permission to make API calls to AWS services.

Note

If you don't use WordPress.com and instead have a self-hosted WordPress website on Amazon EC2, you can use an IAM role instead of an IAM user. For more information, see IAM Roles for Amazon EC2 in the Amazon EC2 User Guide.

The following procedure contains the steps to create an IAM policy, and then attach it to the IAM user. An IAM policy is a document that defines the permissions that apply to the user.

To create an IAM user

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies. Then choose Create policy.

  3. Choose JSON.

  4. Delete everything in the policy text box, and then paste or enter the following JSON policy into the text box:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "acm:DeleteCertificate", "Resource": "*", "Condition": { "StringEquals": { "aws:RequestedRegion": "us-east-1" } } } ] }
  5. Choose Review policy.

  6. On the Review policy page, do the following:

    1. For Name, enter AWSForWordPressDeleteCert.

    2. Choose Create policy.

  7. In the navigation pane, choose Users. Then choose Add user.

  8. On the Set user details page, do the following:

    1. For User name, enter AWSForWordPressPlugin.

    2. For Access type, choose Programmatic access.

    3. Choose Next: Permissions.

  9. On the Set permissions page, do the following:

    1. Choose Attach existing policies directly.

    2. In the search box, enter WordPress, and then select the check boxes next to AWSForWordPressPolicy and AWSForWordPressDeleteCert. Make sure to select the check boxes for both WordPress policies.

      Note

      The AWSForWordPressPolicy is an AWS managed policy that gives the user permission to use all the features included in the AWS for WordPress plugin. When new features are added to the plugin, AWS will update this policy to include the permissions necessary to use the new features.

    3. Choose Next: Tags.

  10. Choose Next: Review.

  11. Choose Create user.

  12. Choose Download .csv to save the user's credentials (access key ID and secret access key) to your computer. You need them to configure the AWS for WordPress plugin.

    Important

    This is the only time that you can save the user's secret access key, so make sure to save it now.

Protect the IAM User's Credentials

The IAM user that you created in the preceding section can do the following in your AWS account:

  • Create, modify, tag, list, and delete CloudFront distributions with the tag "createdBy" : "AWSForWordPressPlugin", and create and list invalidations in those distributions.

  • Request, tag, list, and delete AWS Certificate Manager certificates in the US East (N. Virginia) Region.

  • Create AWS CloudFormation stacks in the US East (N. Virginia) Region, and modify, list, and delete stacks with the tag "createdBy" : "AWSForWordPressPlugin".

  • Use Amazon Polly to convert text into speech, and list the Amazon Polly voices that are available.

  • Use Amazon Translate to translate text from one language to another.

  • Determine whether a particular Amazon S3 bucket exists.

  • Create Amazon S3 buckets whose names begins with audio_for_wordpress or audio-for-wordpress, and create, delete, and list objects in those buckets.

Important

To prevent unauthorized users from gaining these permissions, protect the IAM user's credentials. Treat the secret access key like a password; store it in a safe place, and don't share it with anyone. Like a password, rotate the access key periodically. If the secret access key is accidentally leaked, delete it immediately. Then you can create a new access key to use with the AWS for WordPress plugin.

Creating a WordPress Website

If you have a WordPress website already, you can skip ahead to Step 1: Install the Plugin.

If you don't have a WordPress website, you can create one using WordPress.com. To use the AWS for WordPress plugin, you need a WordPress.com Business or eCommerce plan.

You can also install the WordPress software on your own web server, using Amazon Lightsail, Amazon EC2, or another web hosting platform. Hosting your own WordPress website involves more steps than using WordPress.com, and requires the ability to configure and manage a web server, a load balancer, DNS records, and web server certificates.

Regardless of how you set up your WordPress website, you need the following before you can use the AWS for WordPress plugin:

  • Your website must have its own domain name. A domain name, also known as a web address or a URL (uniform resource locator), is the address that visitors use to go to your website. For example, Amazon's domain name is amazon.com. In this topic, we use example.com as a generic example domain name, but you need a custom domain name for your website.

  • Your website must work using HTTPS. This is a security best practice, and the plugin assumes that your website works using HTTPS. To check, go to your website's address using HTTPS (for example, https://example.com) and make sure that your website displays correctly.

When your website has a domain name and works using HTTPS, proceed to the following section.

Step 1: Install the Plugin

Before you install the plugin, make sure to complete the prerequisites.

To install the plugin

  1. Log in to the admin dashboard for your WordPress website, also known as WP Admin.

  2. Choose Plugins.

    • If you already have the Amazon AI (the plugin's previous name) or AWS for WordPress plugin:

      1. Select the check box next to Amazon AI or AWS for WordPress.

      2. In the Bulk Action menu, choose Update, and then choose Apply.

    • If you don't have the Amazon AI or AWS for WordPress plugin:

      1. Choose Add New.

      2. In the search box, enter AWS for WordPress.

      3. Find the AWS for WordPress plugin. Choose Install Now, and then choose Activate.

After you activate the plugin, proceed to the following section to configure and use it.

Step 2: Configure and Use CloudFront with the Plugin

When you use CloudFront with the AWS for WordPress plugin for site acceleration, the plugin uses a subdomain, also known as an alternate domain name or CNAME, to send your website's traffic through CloudFront. This can reduce latency and improve the viewing experience by loading resources faster.

Without the plugin's site acceleration, all the traffic of your website's viewers goes to the server that hosts your WordPress website. After completing the steps in the following procedure, you can enable the plugin's site acceleration, which gives viewers two options for visiting your website:

  • When viewers use your website's domain name, such as example.com, all the traffic goes through CloudFront, except for the website's index page and a few small image files.

  • When viewers use your website's alternate domain name, such as www.example.com, all the traffic goes through CloudFront.

Using either domain, your website's viewers get lower latency and a faster, more reliable viewing experience. We recommend telling viewers to use your website's alternate domain name. The following diagrams show your viewers' traffic with and without the plugin's site acceleration.


					Diagram of a website viewer's traffic going to the WordPress website
						host.

Without the plugin's site acceleration


					Diagram of a website viewer's traffic going to the CloudFront edge
						locations.

With the plugin's site acceleration

To configure and use CloudFront with the plugin (enable site acceleration)

  1. Log in to the admin dashboard for your WordPress website, also known as WP Admin.

  2. In the left navigation, choose AWS.

  3. Paste or enter the access key ID and secret access key that you saved previously, and then choose Save Changes.

    Note

    If you host WordPress on Amazon EC2, you can skip this step and use an IAM role instead of an IAM user. In that case, keep these two fields blank. For more information about IAM roles, see IAM Roles for Amazon EC2 in the Amazon EC2 User Guide.

    Note

    Regardless of what you choose for AWS Region, the plugin's CloudFront feature creates all resources in the US East (N. Virginia) Region.

  4. In the navigation pane, choose CloudFront.

  5. On the CloudFront Setup page, do the following:

    1. If necessary, for Origin Domain Name, enter your website's domain name, for example, example.com.

    2. For CloudFront Alternate Domain Name, enter a subdomain that viewers will use for your website's accelerated experience. We recommend using www in front of your website's domain name, for example, www.example.com.

    3. Choose Initiate Setup.

  6. CloudFront uses AWS Certificate Manager to create a certificate for your alternate domain name, and you must validate the certificate within 72 hours of the request. Do this by adding the DNS record that the plugin shows on the setup page. The process for adding this validation record varies depending on your DNS service provider. If you use WordPress.com hosting services, see their documentation for information about how to update DNS records with a custom entry. If you use Amazon Route 53 for DNS, see Creating Records by Using the Amazon Route 53 Console in the Amazon Route 53 Developer Guide.

    After you add the DNS record, return to the setup page and choose Check status of SSL certificate.

    When you complete this step, CloudFront sets up a distribution that is optimized for WordPress. This process can take some time to deploy globally. The setup page automatically refreshes every ten seconds to keep you updated while the deployment is in progress.

  7. After the deployment is complete, create a DNS record to point your alternative domain name (for example, www.example.com) to your new CloudFront distribution. Do this by adding the DNS record that the plugin shows on the setup page. The process for adding this validation record varies depending on your DNS service provider. If you use WordPress.com hosting services, see their documentation for information about how to update DNS records with a custom entry. If you use Amazon Route 53 for DNS, see Creating Records by Using the Amazon Route 53 Console in the Amazon Route 53 Developer Guide.

    After you add the DNS record, return to the setup page and choose Check status of CloudFront DNS record.

  8. Choose Activate Site Acceleration, and then choose Save Changes.

When you activate site acceleration, the AWS for WordPress plugin configures your website to serve the website's resources—for example, CSS and JavaScript files, and images—from your CloudFront distribution. You can verify that the plugin accelerates your website for viewers by viewing your website from a private browsing window, or by using a different browser outside of WordPress's admin mode. Make sure that you navigate to your website using the alternate domain name, for example, www.example.com.

(Optional) Deactivate Site Acceleration

You can deactivate site acceleration to serve all of your website's resources from your web server host, bypassing the CloudFront distribution. This leaves your distribution intact and available for use when you choose to reactivate the plugin's site acceleration.

Warning

Before you deactivate site acceleration, edit the DNS record for your alternative domain name (such as www.example.com) so that it points to your website's domain (such as example.com). If you don't do this first, you might experience downtime or problems with your website. After you edit the DNS record, wait longer than the record's time to live (TTL) value before deactivating site acceleration.

If you use WordPress.com hosting services, see their documentation for information about how to edit DNS records. If you use Amazon Route 53 for DNS, see Editing Records in the Amazon Route 53 Developer Guide.

To deactivate site acceleration

  1. Log in to your WordPress website, and then choose WP Admin.

  2. In the navigation pane, choose AWS.

  3. In the navigation pane, choose CloudFront.

  4. Clear the Activate Site Acceleration check box, and then choose Save Changes.

Deactivating site acceleration is reversible. To reactivate it, select the Activate Site Acceleration check box, and then choose Save Changes.

(Optional) Remove Site Acceleration and Delete the CloudFront Distribution

You can use the AWS for WordPress plugin to delete your CloudFront distribution. This is not reversible. To use the AWS for WordPress plugin for site acceleration again, you must reconfigure the plugin, which creates a new CloudFront distribution.

Warning

Before you delete your CloudFront distribution, edit the DNS record for your alternative domain name (such as www.example.com) so that it points to your website's domain (such as example.com). If you don't do this first, you might experience downtime or problems with your website. After you edit the DNS record, wait longer than the record's time to live (TTL) value before deleting your CloudFront distribution.

If you use WordPress.com hosting services, see their documentation for information about how to edit DNS records. If you use Amazon Route 53 for DNS, see Editing Records in the Amazon Route 53 Developer Guide.

To remove site acceleration and delete your CloudFront distribution

  1. Log in to your WordPress website, and then choose WP Admin.

  2. In the navigation pane, choose AWS.

  3. In the navigation pane, choose CloudFront.

  4. Choose Remove Site Acceleration, and then choose OK.

When you complete these steps, the AWS for WordPress plugin deletes your CloudFront distribution. This can take several minutes to complete. After the process is complete, you can optionally open the AWS Management Console to verify that the CloudFront, AWS Certificate Manager, and AWS CloudFormation resources created by the plugin are deleted.

(Optional) Deactivate and Remove the Plugin

You can deactivate the AWS for WordPress plugin to stop using all of its features for CloudFront and other AWS services. You can also delete the plugin to remove it from your WordPress website completely.

Warning

Before you deactivate and delete the plugin, edit the DNS record for your alternative domain name (such as www.example.com) so that it points to your website's domain (such as example.com). If you don't do this first, you might experience downtime or problems with your website. After you edit the DNS record, wait longer than the record's time to live (TTL) value before deactivating and deleting the plugin.

If you use WordPress.com hosting services, see their documentation for information about how to edit DNS records. If you use Amazon Route 53 for DNS, see Editing Records in the Amazon Route 53 Developer Guide.

Note

If you deactivate and delete the plugin without first removing site acceleration, the plugin does not delete the CloudFront, AWS Certificate Manager, and AWS CloudFormation resources that it created. These resources remain in your AWS account, and you are charged for any usage that exceeds the AWS Free Tier. To delete these resources before deleting the plugin, see (Optional) Remove Site Acceleration and Delete the CloudFront Distribution.

To deactivate the AWS for WordPress plugin

  1. Log in to your WordPress website, and then choose WP Admin.

  2. Choose Plugins.

  3. Locate the AWS for WordPress plugin, and then choose Deactivate.

    Deactivating the plugin is reversible. To reactivate it, choose Activate.

  4. To completely remove the AWS for WordPress plugin, choose Delete.

(Optional) Create a CloudFront Distribution for Amazon Polly Content

If you use the AWS for WordPress plugin with Amazon Polly, you can create a CloudFront distribution to accelerate the audio content generated by Amazon Polly. For more information about using the plugin with Amazon Polly, see WordPress Plugin for Amazon Polly in the Amazon Polly Developer Guide.

To create a CloudFront distribution for Amazon Polly audio

  1. Log in to the admin dashboard for your WordPress website, also known as WP Admin.

  2. In the left navigation, choose AWS.

  3. In the Cloud Storage section, make note of your S3 bucket name. It will begin with audio-for-wordpress or audio_for_wordpress. You need this bucket name to complete the following steps.

  4. Sign in to the AWS Management Console and open the CloudFront console at https://console.aws.amazon.com/cloudfront/.

  5. Choose Create Distribution.

  6. Choose Get Started for a Web distribution.

  7. For Origin Domain Name, choose the Amazon S3 bucket whose name you noted in a previous step.

  8. Scroll to the bottom of the page, and then choose Create Distribution.

  9. Choose the distribution that you created in the previous step, and then make note of the distribution's Domain Name. You need this domain name to complete the following steps.

  10. Log in to the admin dashboard for your WordPress website, also known as WP Admin.

  11. In the left navigation, choose AWS.

  12. For Amazon CloudFront (CDN) domain name, enter the domain name that you noted in a previous step.

  13. Choose Save Changes.

Troubleshooting

If you encounter problems with the AWS for WordPress plugin, the following topics can help you solve them. To report bugs or to get help with other problems that are not covered by these topics, open an issue on GitHub.

Can't Connect to AWS

The plugin might display the following error: Can't connect to AWS. Check your credentials and make sure your AWS account is active. If you see this error, try the following:

User Is Not Authorized

The plugin might display the following error messages:

  • Error in Setup

  • AccessDenied

  • User: <user ARN> is not authorized to perform <action>

If you see one of these errors, make sure that the IAM user that you created for the plugin has the correct permissions. For more information, see Creating an IAM User.

CloudFront Settings Page Is Blank

When you navigate to the plugin's CloudFront settings page, the page might be blank. This means that you haven't entered your AWS access key and AWS secret key in the plugin's General configuration page. For more information, see Step 2: Configure and Use CloudFront with the Plugin.

DescribeCertificate Error

The plugin might display the following error messages:

  • Error in Setup

  • Found 1 error while validating the input provided for the DescribeCertificate operation: [CertificateArn] expected string length to be >= 20, but found string length of 0

If you see one of these errors, choose Restart Setup, and then make sure that you enter a domain name, not an IP address, for Origin Domain Name and CloudFront Alternate Domain Name. For more information, see Step 2: Configure and Use CloudFront with the Plugin.

AWS CloudFormation Error

The plugin might display the following error messages:

  • Caught exception in method AmazonAI_Cloudformation

  • Stack is in an unexpected state. CloudFront Distribution state is: <distribution state> and Stack state is: stack state

If you see one of these errors, choose Restart Setup to try again. If you're comfortable diagnosing errors using the AWS CloudFormation console, you can open the console to see what went wrong.

CloudFront Distribution Deployment Seems Stuck

When setting up site acceleration, the plugin might show the CloudFront Distribution Deployment step for a long time, and it might seem like the plugin is stuck at this step. This step can take several minutes to complete. The plugin refreshes every ten seconds during this step, and displays a message like this: Last updated at <date and time of last update>. Look for this message to see when the plugin last refreshed the page. If it was within the last minute, we recommend that you continue to wait for this step to complete. If the plugin has not refreshed in a while, you can try reloading the page.

Alternate Domain Isn't Working

If you finished setting up CloudFront with the plugin but your alternate domain name (for example, www.example.com) isn't working, make sure that you added a CNAME record to your DNS records. If you use WordPress.com hosting services, see their documentation for information about how to update DNS records with a custom entry. If you use Amazon Route 53 for DNS, see Creating Records by Using the Amazon Route 53 Console in the Amazon Route 53 Developer Guide.

If you used the plugin to delete your CloudFront distribution and your alternate domain name (for example, www.example.com) isn't working, make sure that you updated your DNS records to repoint the alternate domain name to your website's apex domain (for example, example.com) and that you've waited longer than the DNS record's time to live (TTL) value. If you use WordPress.com hosting services, see their documentation for information about how to update DNS records with a custom entry. If you use Amazon Route 53 for DNS, see Creating Records by Using the Amazon Route 53 Console in the Amazon Route 53 Developer Guide.

Can't Find AWS Resources

The CloudFront feature of the plugin creates resources in several AWS services, including CloudFront, AWS Certificate Manager, and AWS CloudFormation. If you're looking for these resources in the AWS Management Console or listing them using an API, make sure that you use the US East (N. Virginia) Region (us-east-1).