Home

CloudFront

Create and manage CloudFront web distributions and run invalidations

Overview

Cumulus makes using CloudFront easier and cleaner! Easily configure web distributions and update cache behaviors! Run commonly used invalidations! Read the following sections to learn about configuring your CloudFront environment with Cumulus. Example configuration can be found in the Cumulus repo.

Distribution Definition

Cumulus currently only supports managing CloudFront Web Distributions because these are the only distributions we use at this time at Lucid. If you have additional needs, submit a pull request!

Each distribution is defined in its own file, and the folder distributions are located in is configurable. In other Cumulus modules, you’ve probably seen that managed assets get their names from the names of the files in which they are defined. However, because CloudFront distributions are only identifiable by their ID in AWS, file names for distributions are arbitrary. The only thing to note is that the file name is the name that Cumulus will use to refer to your distribution in its output, and as input into its command line interface (minus the .json, of course). Distributions are JSON objects with the following attributes:

Here is an example of a distribution with a custom origin:

{
  "id": "DistributionID",
  "origins": [
    {
      "id": "Custom-www.example.com",
      "domain-name": "www.example.com",
      "origin-path": "/cloudfronted",
      "custom-origin-config": {
        "http-port": 80,
        "https-port": 443,
        "protocol-policy": "https-only",
        "origin-ssl-protocols": [
          "TLSv1",
          "TLSv1.1",
          "TLSv1.2"
        ]
      }
    }
  ],
  "default-cache-behavior": {...},
  "comment": "Created with Cumulus",
  "enabled": false
}

Cache Behaviors

A cache behavior controls how itemes accessed using the distribution are cached. Cache Behaviors have the following properties:

Here is an example cache behavior configuration that could be used for the default-cache-behavior:

{
  "target-origin-id": "Custom-www.example.com",
  "forward-query-strings": true,
  "forwarded-cookies": "whitelist",
  "forwarded-cookies-whitelist": [
    "SESSION",
  ],
  "forward-headers": [
    "Origin"
  ],
  "trusted-signers": [
    "self"
  ],
  "viewer-protocol-policy": "https-only",
  "min-ttl": 0,
  "max-ttl": 31536000,
  "default-ttl": 86400,
  "smooth-streaming": false,
  "allowed-methods": [
    "HEAD",
    "GET",
    "OPTIONS"
  ],
  "cached-methods": [
    "HEAD",
    "GET"
  ],
  "compressed": true
}

Here is a full example of a distribution config with an S3 origin and another cache behavior which caches all .PNG requests for a year, and other requests for a day

{
  "id": "DistributionID",
  "origins": [
    {
      "id": "S3-bucket-name-1",
      "domain-name": "bucket-name-1.s3.amazonaws.com",
      "origin-path": ""
    }
  ],
  "default-cache-behavior": {
    "target-origin-id": "S3-bucket-name-1",
    "forward-query-strings": false,
    "forwarded-cookies": "none",
    "forward-headers": [],
    "trusted-signers": [],
    "viewer-protocol-policy": "https-only",
    "min-ttl": 86400,
    "max-ttl": 86400,
    "default-ttl": 86400,
    "smooth-streaming": false,
    "allowed-methods": [
      "HEAD",
      "GET",
      "OPTIONS"
    ],
    "cached-methods": [
      "HEAD",
      "GET"
    ],
    "compressed": true
  },
  "cache-behaviors": [
    {
      "target-origin-id": "S3-bucket-name-1",
      "path-pattern": "*.png",
      "forward-query-strings": false,
      "forwarded-cookies": "none",
      "forward-headers": [],
      "trusted-signers": [],
      "viewer-protocol-policy": "https-only",
      "min-ttl": 31536000,
      "max-ttl": 31536000,
      "default-ttl": 31536000,
      "smooth-streaming": false,
      "allowed-methods": [
        "HEAD",
        "GET",
        "OPTIONS"
      ],
      "cached-methods": [
        "HEAD",
        "GET",
        "OPTIONS"
      ],
      "compressed": false
    }
  ],
  "comment": "Created with Cumulus",
  "enabled": false
}

It should be noted that Cumulus will create a new CloudFront distribution if you omit the "id" parameter the next time the configuration is synced. After creation, the configuration used to create the distribution will be updated with the id of the created distribution to prevent it from being created again on accident.

There are some configuration options for web distributions that Cumulus does not handle because we do not use them at Lucid or do not want them managed by Cumulus at this time. These include:

If you would like these added to Cumulus, please submit a pull request.

Diffing and Syncing CloudFront

Cumulus’s CloudFront module has the following usage:

cumulus cloudfront [diff|help|invalidate|list|migrate|sync] <asset>

Distributions can be diffed, listed, and synced, and invalidated (migration is covered in the following section). The four actions do the following:

Migration

If your environment is anything like ours, you have dozens of distributions, and would rather not write Cumulus configuration for them by hand. Luckily, Cumulus provides a migrate task that will pull down your web distributions and produce configuration for them.

Invalidation

Cumulus supports creating CloudFront invalidations using files in the configurable invalidations directory. Invalidations use a combination of the current time, name of the file, and md5 of the specified paths to ensure that an invalidation on a distribution is not ran more than once in a 5 minute window. This is to prevent accidentally creating invalidations in quick succession, and can be easily overridden by changing the name of the file containing the invalidation config, changing the paths to invalidate, or waiting for the next 5 minute window. For example, if an invalidation was run at 1:49, it could not be ran again until 1:50 unless you changed the paths or renamed it.

Invalidation configurations are JSON objects with the following attributes: * distribution-id - the id of the cloudfront distribution to run an invalidation on * paths - an array of paths to invalidate on the distribution. Items must start with a / and may contain the wildcard * e.g. ["/*.jpg", "/index.html"]

To run an invalidation that has been saved under invalidations/invalidate-bucket-2.json you would run the command:

cumulus cloudfront invalidate invalidate-bucket-2

Configuration

Cumulus reads configuration from a configuration file, conf/configuration.json (the location of this file can also be specified by running cumulus with the --config option). The values in configuration.json can be changed to customized to change some of Cumulus’s behavior. The following is a list of the values in configuration.json that pertain to the CloudFront module:

➜