ember-cli-deploy-cloudfront

An ember-cli-deploy plugin to invalidate cached files on AWS CloudFront

This plugin invalidates one or more files in an Amazon CloudFront distribution. It is primarily useful for invalidating an outdated index.html, but can be configured to invalidate any other files as well.

What is an ember-cli-deploy plugin?

A plugin is an addon that can be executed as a part of the ember-cli-deploy pipeline. A plugin will implement one or more of the ember-cli-deploy's pipeline hooks.

For more information on what plugins are and how they work, please refer to the Plugin Documentation.

Quick Start

To get up and running quickly, do the following:

1. Install this plugin

   $ ember install ember-cli-deploy-cloudfront

2. Place the following configuration into config/deploy.js

   ENV.cloudfront = {
     accessKeyId: '<your-aws-access-key>',
     secretAccessKey: '<your-aws-secret>',
     distribution: '<your-cloudfront-distribution-id>'
   }

3. Run the pipeline with the activation flag

   $ ember deploy production --activate

Installation

Run the following command in your terminal:

ember install ember-cli-deploy-cloudfront

ember-cli-deploy Hooks Implemented

For detailed information on what plugin hooks are and how they work, please refer to the Plugin Documentation.

• configure
• didActivate

Configuration Options

For detailed information on how configuration of plugins works, please refer to the Plugin Documentation.

accessKeyId

The AWS access key for the user that has the ability to upload to the bucket. If this is left undefined, the normal AWS SDK credential resolution will take place.

Default: undefined

secretAccessKey

The AWS secret for the user that has the ability to upload to the bucket. This must be defined when accessKeyId is defined.

Default: undefined

profile

The AWS profile as definied in ~/.aws/credentials. If this is left undefined, the normal AWS SDK credential resolution will take place.

Default: undefined

sessionToken

The AWS session token for the user that has the ability to manage the CloudFront distribution. This may be required if you are using the AWS Security Token Service. This requires both accessKeyId and secretAccessKey to be defined.

Default: undefined

distribution (required)

The CloudFront distribution ID that should be invalidated. May be specified as a string for a single distribution (most common) or as an array of strings for multiple distributions.

Default: undefined

region

The AWS region to send service requests to.

Default: us-east-1

objectPaths

CloudFront object paths contained in this array will be invalidated on CloudFront. Each object path must be relative to the CloudFront distribution root and begin with /.

Default: ['/index.html']

invalidationClient

The client used to create the invalidation. This allows the user the ability to use their own client for invalidating instead of the one provided by this plugin.

The client specified MUST implement a function called invalidate.

Default: the upload client provided by ember-cli-deploy-cloudfront

cloudfrontClient

The underlying CloudFront library used to create the invalidation with CloudFront. This allows the user to use the default invalidation client provided by this plugin but switch out the underlying library that is used to actually create the invalidation.

The client specified MUST implement a function called createInvalidation.

Default: the default CloudFront library is aws-sdk

waitForInvalidation

If set to true the deployment will wait until AWS reports invalidation complete state. This ensures new version is available online after the pipeline is finished. This can be useful to know, for example before running further tests against deployed production. Note that it may take several minutes or more for the invalidation to fully complete, so only use this option if you really need to wait for the invalidation to complete. Note that to use this option you'll need to have IAM permissions for "cloudfront:GetInvalidation". See Minimum CloudFront Permissions below.

Default: false

Disable in Selected Environments

If your application doesn't need CloudFront invalidation in an environment where you do need to run other activation hooks, it is possible to whitelist the plugins that you do want ember-cli-deploy to run. For an application using the ember-cli-deploy-aws-pack for example, the whitelist would look like this when excluding ember-cli-deploy-cloudfront:

ENV.plugins = ['build', 'gzip', 's3', 'manifest'];

While this may not be ideal for complicated deploy processes with many plugins, there is an effort currently underway to add per-plugin disabling to ember-cli-deploy: ember-cli-deploy/ember-cli-deploy#349

Configuring AWS

Minimum CloudFront Permissions

Ensure you have the minimum required permissions configured for the user (accessKeyId). A bare minimum policy should have the following permissions:

{
   "Version": "2012-10-17",
   "Statement":[{
      "Effect":"Allow",
      "Action":["cloudfront:CreateInvalidation"],
      "Resource":"*"
      }
   ]
}

If you have enabled the waitForInvalidation option above you'll need to ensure you have the following permissions as a minimum:

{
   "Version": "2012-10-17",
   "Statement":[{
      "Effect":"Allow",
      "Action":[
        "cloudfront:CreateInvalidation",
        "cloudfront:GetInvalidation"
       ],
      "Resource":"*"
      }
   ]
}

The cloudfront:CreateInvalidation action is the only one necessary for this addon (unless you've enabled the waitForInvalidation option above), though the more permissive cloudfront:* permission will also work. AWS does not currently allow CloudFront permissions to be limited by distribution, so the only accepted value for Resource is * (all distributions).

Why ember build and ember test don't work

Since this is a node-only ember-cli addon, this package does not include many files and dependencies which are part of ember-cli's typical ember build and ember test processes.