External DNS
This document describes how to setup external DNS services to work with Release.

How Release Routes Traffic to Your Environments

Release creates dynamic routing entries in our proprietary [email protected] routing infrastructure for every environment. When new ephemeral or permanent environments are created by Release, we update a routing table stored in DynamoDB which is then checked on every request made to Cloudfront with a [email protected] program. In this way we can instantly route and (possibly) re-route traffic without waiting for propagation delays or TTLs to expire.
In order to correctly create a hostname for a dynamic service, Release talks to the ALB ingress controller in AWS to create the correct routing entry and point requests to the correct environment. For static sites, Release grabs the bucket hostname and path, including a list of any assets written to S3 for the version being deployed, and adds those entries to our routing table.
For self-hosted customers, we use the following pattern to create ephemeral hostnames:
Here is an example ephemeral hostname for an app called Example and a service called Test
Permanent environment hostnames are usually static and could be something like the following examples show:
For hosted customers, all of the cluster communication, routing, and DNS traffic occur inside Release's customer account in AWS. For self-hosted (but Release-managed) customers, all of the cluster communication, routing, and DNS traffic occurs inside their own AWS account(s). For customers who might have a third-party DNS requirement or existing deployment, we still require an AWS Route53 zone, but we can integrate as shown in the next sections.

Required setup for all externally hosted DNS providers

Before setting up your external DNS provider, you must create a subdomain on a hosted zone in AWS where you'd like your environments to be accessible.
Navigate to the Route53 service in AWS by searching for it in the Services drop-down.
Click "Hosted Zones"
Click "Create Hosted Zone" then fill in "Domain name" and leave the type set to "Public Hosted Zone", then click "Create"
Fill in the details of which subdomain you want your Release apps to run on. In this example, ephemeral environments will be hosted on the subdomain. In our prior example, setting this would result in an ephemeral environment running here:

Setup Cloudflare

For users who have DNS routed through Cloudflare, a few steps must be taken to configure things to work correctly with Release.

Create NS records to point to your Route 53 subdomain/hosted zone

You will need to know the nameservers that were created for your hosted zone before finishing this setup. You can find your nameservers for your hosted zone by selecting the zone and viewing the details from your Route53 console.
View the nameservers you'll need for your subdomain/hosted zone when setting up Cloudflare
Navigate to the "DNS" section in the CloudFlare menu and create NS records that point to your Route53 hosted zone/subdomain.
In this example the subdomain where Release environments will be run is "releasehub". Set the Name* field to the subdomain/hosted zone you created in "Setup external DNS to work with Ephemeral Environments" section. For every nameserver for that hosted zone, create an NS record. Leave the TTL field set to "auto"
Create NS records for your subdomain
Release will handle all the certificate creation, Cloudfront (via [email protected]) routing table updates, and DNS entries for you.