DNS: can we use subdomains for each account? Or do we need different domains?

[zackproser]

A customer asked:

The domain organization recommended in the reference architecture allows to have a domain structure like api.dev.domain.com, api.staging.domain.com, api.domain.com. Will this work, or do we need to use separate domains for each account?

[zackproser]

Our Ref Arch supports both approaches:

• You can use a single domain, and assign unique subdomains to each account, e.g.; dev.example.com, stage.example.com, prod.example.com
• You can use a different domain for each account, if you so wish, e.g.; example.net, example.com, example.io

We have automated DNS checks built into our tooling that will ensure your DNS setup is resolving correctly prior to a deployment.

[brikis98]

A few notes to add here:

Reference Architecture requirements

The technical requirement in the Reference Architecture is that you have a properly configured Route 53 Public Hosted Zone in each of your dev, stage, prod, and shared-services account. The code in the Reference Architecture will look up these Public Hosted Zones and add DNS records to them, such as an A record for the sample apps deployed with the Reference Architecture, so you can see examples of how to use Terraform to manage DNS. We'll cover how to create these Route 53 Public Hosted Zones below.

Security requirements

As long as you have Route 53 Public Hosted Zones in each account, the Reference Architecture will work, but not all approaches for managing domain names are equally secure. Some trade-offs to consider:

1. Cookies. If you use subdomains for each environment (e.g., dev.your-company.com, stage.your-company.com, etc), there is a higher risk of accidentally issuing a cookie that works across all of those sub-domains (*.your-company.com), even though you only wanted that cookie to work with one sub-domain. For example, you might create an auth cookie in dev that accidentally works in prod too, which could be a huge security problem. This is less likely to happen if you use totally separate domain names for each environment (e.g., your-company-dev.com, your-company-stage.com, etc).
2. TLS certificates. Similar to cookies, if you use subdomains for each environment, there is a higher risk of accidentally issuing a TLS certificate that is accepted across all of those sub-domains, even though you only wanted that TLS certificate to work with one sub-domain. Again, this is less likely to happen if you use totally separate domain names for each environment.
3. Accidental delegation. If the domains for all your environments are all registered in a single place, and you delegate the management of the domains for each environment to that environment, there is a higher risk of accidentally giving an environment too much power. E.g., Perhaps you tried to delegate dev.your-company.com to the dev account and prod.your-company.com to the prod account, but you accidentally delegated both to the dev account, which is problematic, as most dev accounts are not as locked down and monitored as prod accounts. With totally separate domains for each environment, and those domains solely defined and managed in those environments, there's no delegation at all to worry about and accidentally get wrong.
4. Blast radius. If all the domains for all your environments are registered in a single place, then mistakes are more likely to cause problems across all environments (a larger "blast radius"). For example, perhaps you were trying to make some simple changes in dev—e.g., delegate dev.your-company.com to the dev account—but due to a typo or accidentally messed up command, you end up causing problems in stage and prod too. With totally separate domains for each environment, and those domains solely defined and managed in those environments, there's little-to-no chance of causing a problem in prod while you're working in the dev account.

How to create Route 53 Public Hosted Zones

There are several ways to create these Route 53 Public Hosted Zones:

1. Buy one domain in each of the AWS accounts [RECOMMENDED]. E.g., Use Route 53 to buy your-company-dev.com in the dev account, your-company-stage.com in the stage account, and so on. When you register a domain using Route 53, it creates the public hosted zone for you automatically. This is our recommended option, both as it's the simplest, and the most secure.
2. Buy one domain for each account, but buy them outside of those accounts. Perhaps you use some other registrar (e.g., GoDaddy or CloudFlare) and you use it to buy your-company-dev.com, your-company-stage.com, and so on. If you do this, you'll then need to create a Route 53 Public Hosted Zone in each of those accounts (dev, stage, etc), copy the name servers that AWS automatically assigns to that Public Hosted Zone, and configure your registrar (e.g., GoDaddy or CloudFlare) to use those name servers for that domain. This allows the domains to all live in that one registrar, but for the DNS entries for that domain to be managed in each of your AWS accounts.
3. Buy one domain and use sub-domains in each account. E.g., You buy your-company.com in some registrar (e.g., GoDaddy or CloudFlare) and you want to use dev.your-company.com in dev, stage.your-company.com in stage, and so on. Making this work is similar to the previous item: you create a Route 53 Public Hosted Zone in each account, grab the name servers for it, and configure your registrar to delegate management of those subdomains to those name servers.

[zackproser]

If you're bootstrapping your Reference Architecture to prepare for deployment, you can use the gruntwork command line interface (CLI) to bootstrap the domain names within route53 for you.