Home

Route53

Create and manage Route53 hosted zones and records.

Overview

Cumulus makes using Route53 easier and cleaner! Create files containing common records to be included in multiple hosted zones! Reference AWS resources by name in alias records! Read the following sections to learn about configuring your Route53 environment with Cumulus. Example configuration can be found in the Cumulus repo.

Zone Definition

Each hosted zone is defined in its own file, and the folder zones 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 you can have two hosted zones that share a name and differ by their privacy settings, file names for hosted zones are arbitrary. The only thing to note is that the file name is the name that Cumulus will use to refer to your hosted zone in its output, and as input into its command line interface (minus the .json, of course). Zone definitions are JSON objects with the following attributes:

Here’s an example of a public zone definition:

{
  "domain": "example.com",
  "zone-id": "Z23N6K3FTHCHPS",
  "private": false,
  "comment": "An example comment",
  "records": {
    "ignored": [ ... ],
    "includes": [ ... ],
    "inlines": [ ... ]
  }
}

And here’s another example, this time of a private zone definition:

{
  "domain": "example.com",
  "zone-id": "Z23N6K3FTHCHPS",
  "private": true,
  "comment": "An example comment",
  "vpc": [
    {
      "id": "vpc-5f019b3a",
      "region": "us-east-1"
    },
    ...
  ],
  "records": { ... }
}

It should be noted that Cumulus will not create hosted zones for you, because you need to manually configure any zone you create in Route53 with your domain registrar. As such, your zone definitions are only used to sync your Route53 configuration.

Record Definition

Cumulus allows you to define two different types of records: basic and alias records. The following sections describe how to configure both types of records.

Currently Cumulus only supports Route53 basic resource record sets and alias resource record sets because those are the record types that are used at Lucid. If you have additional needs, please submit a pull request!

Basic

Basic records are just JSON objects with the following attributes:

Here are a couple examples:

[
  {
    "name": "sub",
    "type": "A",
    "ttl": 300,
    "value": [
      "127.0.0.1",
      "123.4.5.6"
    ]
  },
  {
    "name": "a",
    "type": "TXT",
    "ttl": 300,
    "value": [
      "Sample Text"
    ]
  }
]

Aliases

Alias records are records that point to other AWS resources. Route53 allows you to point records at ELBs, S3 websites, CloudFront distributions, or other records within the Route53 zone. Alias records contain the following attributes:

The alias name differs a little for each of the alias types:

Here are examples of each type:

[
  {
    "name": "a",
    "type": "A",
    "alias": {
      "type": "elb",
      "name": "elb-name"
    }
  },
  {
    "name": "b",
    "type": "A",
    "alias": {
      "type": "s3"
    }
  },
  {
    "name": "c",
    "type": "A",
    "alias": {
      "type": "cloudfront"
    }
  },
  {
    "name": "d",
    "type": "A",
    "alias": {
      "type": "record",
      "name": "sub.example.com"
    }
  }
]

Includes

Sometimes you have multiple zones that contain the same records. In order to prevent someone from only changing records in one place and forgetting about the others (and thereby messing up your environment!), Cumulus allows you to define a file filled with common records that can be included in multiple zone definitions. The folder the includes are located in is configurable, but each file should contain a JSON array of record definitions.

To use includes, add the names of the files you’d like to include into the includes array of your zone definition (minus the .json extension). For example:

{
  ...
  "records": {
    "includes": [
      "example-included"
    ],
    ...
  }
}

In this example, the records in example-included.json, which should look something like

[
  {
    "name": "a",
    "type": "TXT",
    "ttl": 300,
    "value": [
      "Sample Text"
    ]
  },
  ...
]

Ignores

At Lucid, parts of our infrastructure automatically create Route53 records. We didn’t want to manage these records as they are variable, so we wanted Cumulus to ignore those records. Perhaps you have something similar in your environment. To ignore records, add a regex string that will match the records you want to ignore to the ignored array of the zone definition. For example, if we wanted to ignore any records that have names that look like example-1.domain.com, example-2.domain.com, etc., we could use the following:

{
  ...
  "records": {
    "ignored": [
      "^example-",
      ...
    ],
    ...
  }
}

Diffing and Syncing Route53

Cumulus’s Route53 module has the following usage:

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

Hosted zones can be diffed, listed, and synced (migration is covered in the following section). The three actions to the following:

Migration

If your environment is anything like ours, you have hundreds of records, and would rather not write Cumulus configuration for them by hand. Luckily, Cumulus provides a migrate task that will pull down your zones and produce configuration for them. Unfortunately, it won’t pull records into common files for includes or produce ignores for you, so you’ll still have to do that by hand, but it should be far less work.

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 Route53 module:

➜