search

18F / dns

DNS configuration for domains managed by GSA TTS
https://github.com/18F/dns/blob/master/doc/architecture.md
Other
45 stars 60 forks source link

readme

TTS DNS configuration

CircleCI

This repository holds the source code for configuring DNS for domains managed by GSA TTS, including 18F and the Presidential Innovation Fellows. See also:

Making changes

Assuming you're TTS staff, it's recommended that you make the change in a branch on this repository itself, rather than on a fork, because the credentials aren't shared with forks. (The main branch is protected to limit write access only to certain staff, and to ensure history doesn't get overwritten, etc.) For major changes, it is recommended to keep the TTL value low just before and during the change period in order to make it easier to verify the changes went through as expected.

  1. Is the domain pointing to the right nameservers? In other words, is there a file for the domain under terraform/ already?
    • Yes: Continue to next step.
    • No:
      1. Add a file for the domain (or subdomain, if the second-level domain isn't being added), to create the public hosted zone.
        • analytics.usa.gov is a good example to copy from.
        • You'll be using Terraform's aws_route53_zone.
        • If it's an existing domain, you'll want to make sure all existing records are copied over, so that they don't break when the cutover happens. You can ask the existing DNS managers for a list of records or a zone file for the domain and all subdomains.
      2. After the pull request is merged, to get the name servers for your domain check the output for your build in CircleCI. If you need further assistance, check with #admins-dns.
      3. Change the nameservers for the domain to point to AWS.
  2. Add the relevant additional record sets. In Terraform, these are known as aws_route53_records.

It's worth noting that if you are pointing to a CloudFront distro, you should use Route 53's own alias and not a CNAME record. In fact, CNAMEing a top-level domain (or the top level of a delegated subdomain) is not allowed in DNS. See the various examples in the repo, such as this one.

On merge, changes are deployed to an AWS account hosting the Route53 records automatically by a CircleCI job.

Please note: only production systems with an ATO that are categorized as Low impact should have their DNS configuration here.

Redirects

We are moving from pages-redirects to fully configuring them in this repository. See the 18f_gov__join_18f_gov_redirect example.

Leave the trailing slash off the destination domain.

If the redirecting domain is assigned to any CloudFront distribution in any AWS account, it will need to be unassociated before the module above can be successfully deployed.

Stubbing files

We keep a Terraform file for every TTS domain, even if it's just a comment referencing DNS managed elsewhere.

Public domain

This project is in the worldwide public domain. As stated in the license:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.