Prepare AWS Account - Set Up DNS for Cages Defined Within Your Account

How to set up external DNS to route to the Nucleator Cages that you have defined

Configure DNS

account setup creates Hosted Zones in AWS Route53 for each of the Cages listed in the customer configuration file (~/.nucleator/siteconfig/<customer_name>.yml) for the specified Customer. To support easy external DNS name resolution of instances that Stacksets define to be externally resolvable, the DNS nameservers for the domain that you've specified for customer_domain must delegate to the Nucleator created hosted zone(s) responsibility for name resolution for servers within each defined Nucelator Cage. Because different Customers may user different DNS services to manage their specified customer_domain, Nucleator does not attempt to automate this step. Connection of each defined Cage to DNS resolution services needs to occurs manually immediately after the account setup process, and remains available to each defined Cage as the Cage is repeatedly provisioned and destroyed. Nucleator Stacksets manage the provisioning of DNS records within the hosted zone provisioned by the Cage. In order for these records to be resolvable, manual setup of DNS to delegate from the customer_domain to each defined Cage's hosted zone is required to complete account setup.

Example DNS Resolution Path

We'll use resolution of the bastion server for a customer's build Cage as an example and assume that the customer_domain is one level below your top level domain. A typical DNS resolution path for this case is:

We will describe the process of delegating from customer_domain to each Cage's hosted zone in three scenarios:

Customer DNS in Route 53. customer_domain is managed in AWS Route53, most likely in an Account that is unrelated to Nucleator usage.
Customer DNS outside AWS. customer_domain is managed using a DNS system outside of AWS.
Customer Domain from free provider. I don't own a domain where I can control NS records and would like to establish a no-cost subdomain so I can try out Nucleator.

Customer Domain is Managed in AWS Route53

If you are using AWS Route53 to manage DNS for your specified customer_domain, you just need to add an NS record to the hosted zone that is authoritative for customer_domain for each of the Cages that you've defined for the specified Customer. The NS record for each Cage should include all of the nameservers that are specified in the Hosted Zone that was created for that Cage by nucleator account setup.

Add NS Record for each defined Cage in Route53

Icon

In your target Account:

In your target Account, use the AWS Management Console to navigate to the Route53 hosted zone created for each Cage that you've defined for your customer. The hosted zone will be named <cage_name>.<customer_domain>. In the example above, the hosted zone would be named build.department.example.com. Select the hosted zone and "Go to Record Sets".
Choose the single NS record within the hosted zone for the selected Cage with name <cage_name>.<customer_domain>.
Copy the values of the four nameservers from the record detail in the right pane.

In the Account which you or your organization uses to manage authoritative DNS records for <customer_domain>:

Use the AWS Management Console to navigate to the Route53 hosted zone that includes authoritative records for <customer_domain>
Add a NS record with the name <cage_name>.<customer_domain>. In the example above, the NS record would be named build.department.example.com. Paste the four nameservers copied above into the value of the NS record.

After a brief delay, the hosted zone for your Cage should begin to resolve in the global DNS system. You can test this to validate that it is working:

dig +short NS <cage_name>.<customer_domain> # returns nameservers for the hosted zone created for your Cage
 
dig +short SOA <cage_name>.<customer_domain> # returns Source of Authority for the hosted zone created for your Cage

Customer Domain is Managed Externally

Customer DNS setups can vary dramatically. While Route53 is performant and convenient, you do not need to use Route53 as the DNS Service for your specified customer_domain in order to use Nucleator. You do need to be able to add NS records for each Cage to the zone file that is authoritative for customer_domain.

Add NS Record for each defined Cage in Route53

Icon

In your target Account: (same steps as above)

In your target Account, use the AWS Management Console to navigate to the Route53 hosted zone created for each Cage that you've defined for your customer. The hosted zone will be named <cage_name>.<customer_domain>. In the example above, the hosted zone would be named build.department.example.com. Select the hosted zone and "Go to Record Sets".
Choose the single NS record within the hosted zone for the selected Cage with name <cage_name>.<customer_domain>.
Copy the values of the four nameservers from the record detail in the right pane.

With the DNS Service Provider for <customer_domain>:

Navigate to the zone file or other mechanism provided by your DNS service provider for managing authoritative records for <customer_domain>
Add a NS record with the name <cage_name>.<customer_domain>. In the example above, the NS record would be named build.department.example.com. Specify the four nameservers copied above within the NS record.

After a brief delay, the hosted zone for your Cage should begin to resolve in the global DNS system. You can test this to validate that it is working using the same method as described above.

Customer Domain is Provided by a Free Subdomain Provider

To illustrate this case we will use a free hosted subdomain service from freedns.afraid.org.

The following example will create and use a free hosted subdomain from http://freedns.afraid.org to establish a subdomain that can be used as Nucleator's customer_domain. In this example we will create a subdomain at freedns.afraid.org, and a manually created hosted zone within Route53 that together will provide a resolvable customer_domain to which we can add authoritative DNS records. In this example we will use customer_domain of fredco.mooo.com, and configure DNS resolution for a defined Nucleator build Cage. If you do not own a domain where you can create NS records, this approach will also allow you to try out Nucleator without needing to purchase one.

Icon

Sign-up for a free account at http://freedns.afraid.org - instructions on their web-site
Create a subdomain for any of their available top domains - mooo.com in this example
1. Create an NS record for your customer - fredco in this example
2. Leave your browser window open for the addition of the nameserver info
In your target AWS Account, manually create a new external Hosted Zone in Route53 (new browser tab) for fredco.mooo.com
Copy name server information to freedns.afraid.com
1. Enter detail page for the hosted zone created in the prior step by clicking on "fredco.mooo.com" in route53
2. Choose the single NS record within the hosted zone for "fredco.moo.com" and copy one of the name server names (.com) into your cut buffer (without the trailing '.')
3. Paste the name server name into the "Destination" field of the free hosted subdomain on freedns.afraid.com and save
4. Your DNS record at freedns.afraid.org should look similar to :
  
  You now have an externally resolvable subdomain at fredco.mooo.com to which you can add authoritative DNS records though the fredco.mooo.com Route53 hosted zone that you created.
Delegate to the hosted zone for the build Cage from fredco.mooo.com
1. In the Route53 hosted zone page select build.fredco.mooo.com and "Go to Hosted Zone"
2. Choose the single NS record within the hosted zone with name build.fredco.mooo.com.
3. Copy the values of the four nameservers from the record detail in the right pane.
4. In the Route53 hosted zone page select fredco.mooo.com and "Go to Hosted Zone"
5. Create Record Set, Set type to NS, paste the build cage nameservers into the destination and save record
6. The new hosted zone for fredco.mooo.com should look like:
  
  where the NS records for the build.fredco.mooo.com come from the cage hosted zone information created by Nucleator also within route53
Repeat step 5 for all the Nucleator cages defined in the customer configuration file (~/.nucleator/siteconfig/<customer_name>.yml)

Once complete:

the mooo.com name servers are delegating references to fredco.mooo.com to the nameserver within the manually created Route53 Hosted Zone fredco.mooo.com.
This nameserver in turn is delegating references to build.fredco.mooo.com to the nameservers within the build Cage Route53 Hosted Zone build.fredco.mooo.com that were automatically created by nucleator account setup .
These nameservers, established by nucleator account setup, will include DNS records for any externally resolvable instances provisioned within the Nucleator build Cage, for example bastion.build.fredco.mooo.com.

Next: Prepare AWS Account - Set Up Billing and Reporting