From 071d61fcc3e618772ee609d78b3b48ba03d9c3f2 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Fri, 9 Jan 2026 10:20:15 -0600 Subject: [PATCH 1/6] feat: Add DNS Registrar design decision Create a new design decision document for choosing where to register domains. This consolidates guidance previously scattered across the Service Discovery Domain decision and DNS setup tutorial. The decision presents two main options: AWS Route 53 Registrar (recommended) and existing registrars, with detailed considerations including Cloudflare limitations, enterprise registrar options, and Terraform support constraints. Co-Authored-By: Claude Haiku 4.5 --- .../decide-on-dns-registrar.mdx | 81 +++++++++++++++++++ .../decide-on-service-discovery-domain.mdx | 2 + .../decide-on-vanity-branded-domain.mdx | 2 + 3 files changed, 85 insertions(+) create mode 100644 docs/layers/network/design-decisions/decide-on-dns-registrar.mdx diff --git a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx new file mode 100644 index 000000000..e59c766db --- /dev/null +++ b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx @@ -0,0 +1,81 @@ +--- +title: "Decide on DNS Registrar" +sidebar_label: "DNS Registrar" +description: Choose where to register domains for your AWS infrastructure +tags: + - design-decision +--- + +import Intro from "@site/src/components/Intro"; + +When setting up DNS for the reference architecture, you need to decide where to register your domains. This is separate from where DNS is hosted—Route 53 will host your zones, but the domain registration (the purchase and ownership) can be done through various registrars. + +We recommend registering [dedicated vended domains per stage](/layers/network/design-decisions/decide-on-vanity-branded-domain), such as `acme-prod.com`, `acme-staging.com`, and `acme-dev.com`. This is practical guidance for companies with a simple dev/staging/prod SDLC. If you have a large number of stages or accounts, adapt accordingly. + +## Option 1: Use AWS Route 53 Registrar (Recommended) + +Register domains directly through AWS Route 53 in the `dns` account. This is our recommended approach for most organizations. + +- **Fully AWS-native** — Domain registration and DNS hosting in one place +- **Consolidated billing** — Domain costs appear on your AWS bill (requires a credit card on the account) +- **No lock-in** — Standard domain transfers available if you change your mind later +- **No downsides** — There are no real trade-offs compared to third-party registrars + +The `dns` account (see [Decide on AWS Account Flavors and Organizational Units](/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units)) acts as your centralized registrar. This keeps domain ownership consolidated and simplifies management. + +## Option 2: Use an Existing Registrar + +If you already have a domain portfolio managed elsewhere, you may prefer to keep registration consolidated with your existing registrar. + +Common registrars include: +- **GoDaddy** — Popular general-purpose registrar +- **Squarespace Domains** — Formerly Google Domains +- **Cloudflare** — Registrar with integrated CDN and security features +- **MarkMonitor** — Enterprise-grade registrar for large domain portfolios + +This approach makes sense when you have many existing domains and want to avoid managing registrations in multiple places. + +## Considerations + +### Cloudflare Limitation + +:::caution + +Cloudflare (non-Enterprise plans) cannot delegate top-level NS records. The apex domain NS always remains on Cloudflare. + +::: + +This is problematic if you want a fully AWS-native DNS architecture. Your top-level domain would be managed out-of-band, separately from the rest of your infrastructure. For many organizations this is acceptable, but if you want complete control of NS delegation, use Route 53 or another registrar that supports apex NS delegation. + +### Enterprise Registrars (MarkMonitor) + +Enterprise-scale organizations often use MarkMonitor or similar services to manage large domain portfolios. If your organization uses one of these services: + +- Consult your legal department on domain ownership consolidation +- Consider IP and trademark defense implications +- Follow your organization's existing domain governance policies + +### Terraform Support + +The AWS provider includes an `aws_route53domains_registered_domain` resource, but it has significant limitations: + +- **Cannot register new domains** — Only manages existing registrations +- **Cannot import domains** — No `terraform import` support +- **Limited operations** — Can update nameservers and contact info, but not create or delete registrations + +Domain registration is intentionally ClickOps. The reference architecture does not manage domain registration via Terraform—you must register domains manually through the AWS Console or your chosen registrar. + +### Legal Considerations + +We recommend checking with your legal department on where to consolidate domain ownership. Domain registration has implications for: + +- IP and trademark defense +- Corporate governance requirements +- Regulatory compliance + +## Related + +- [Decide on Vanity (Branded) Domains](/layers/network/design-decisions/decide-on-vanity-branded-domain) +- [Decide on Service Discovery Domain](/layers/network/design-decisions/decide-on-service-discovery-domain) +- [Decide on AWS Account Flavors and Organizational Units](/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units) +- [AWS Route 53 Domain Registration](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html) diff --git a/docs/layers/network/design-decisions/decide-on-service-discovery-domain.mdx b/docs/layers/network/design-decisions/decide-on-service-discovery-domain.mdx index 289f8411d..a152b0504 100644 --- a/docs/layers/network/design-decisions/decide-on-service-discovery-domain.mdx +++ b/docs/layers/network/design-decisions/decide-on-service-discovery-domain.mdx @@ -157,6 +157,8 @@ leveraging delegated zones by account. ## Related +- [Decide on DNS Registrar](/layers/network/design-decisions/decide-on-dns-registrar) + - [Decide on Hostname Scheme for Service Discovery](/layers/network/design-decisions/decide-on-hostname-scheme-for-service-discovery) - [Decide on Vanity (Branded) Domain](/layers/network/design-decisions/decide-on-vanity-branded-domain) diff --git a/docs/layers/network/design-decisions/decide-on-vanity-branded-domain.mdx b/docs/layers/network/design-decisions/decide-on-vanity-branded-domain.mdx index 5fdf3f4a1..1bde5ac6f 100644 --- a/docs/layers/network/design-decisions/decide-on-vanity-branded-domain.mdx +++ b/docs/layers/network/design-decisions/decide-on-vanity-branded-domain.mdx @@ -101,6 +101,8 @@ will work for both `staging.acme.com` and `prod.acme.com`, and that's a bad thin ## Related +- [Decide on DNS Registrar](/layers/network/design-decisions/decide-on-dns-registrar) + - [Decide on Service Discovery Domain](/layers/network/design-decisions/decide-on-service-discovery-domain) - [https://youtu.be/ao-2mfA5OTE](https://youtu.be/ao-2mfA5OTE) From c15551114ac137de167353d33de6797c43b397b3 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Fri, 9 Jan 2026 10:25:04 -0600 Subject: [PATCH 2/6] docs: Clarify domain registration vs DNS delegation Add context explaining the distinction between domain ownership and NS delegation, including patterns for vanity domains (TLD per stage delegated to each account) and service discovery domains (zones delegated to member accounts). Co-Authored-By: Claude Haiku 4.5 --- .../design-decisions/decide-on-dns-registrar.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx index e59c766db..519b4655e 100644 --- a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx +++ b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx @@ -23,6 +23,17 @@ Register domains directly through AWS Route 53 in the `dns` account. This is our The `dns` account (see [Decide on AWS Account Flavors and Organizational Units](/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units)) acts as your centralized registrar. This keeps domain ownership consolidated and simplifies management. +### Domain Registration vs DNS Delegation + +Domain registration (ownership) is different from DNS (nameserver delegation). Organizations often maintain domain portfolios for multiple purposes: marketing domains, SEO, trademark defense, and branded properties. These portfolios can get large. + +Once you own a domain, the NS records can be delegated to any account: + +- **Vanity domains** — We recommend delegating each stage's TLD (e.g., `acme-prod.com`, `acme-staging.com`) to the corresponding account. This lets each environment manage its own TLD, avoiding cross-account complexity. +- **Service discovery domains** — There's typically one domain (e.g., `acme.net`) with zones delegated to each member account (e.g., `prod.acme.net`, `staging.acme.net`). This avoids ambiguity of ownership while enabling account-level DNS management. + +Centralizing registration in the `dns` account while delegating NS records provides clear ownership without operational bottlenecks. + ## Option 2: Use an Existing Registrar If you already have a domain portfolio managed elsewhere, you may prefer to keep registration consolidated with your existing registrar. From 14ea5791c8918e4aa331e6d66516b8d59703d433 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Fri, 9 Jan 2026 10:25:51 -0600 Subject: [PATCH 3/6] docs: Link vanity and service discovery terms to decision docs Co-Authored-By: Claude Haiku 4.5 --- .../network/design-decisions/decide-on-dns-registrar.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx index 519b4655e..d9e2f57f6 100644 --- a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx +++ b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx @@ -29,8 +29,8 @@ Domain registration (ownership) is different from DNS (nameserver delegation). O Once you own a domain, the NS records can be delegated to any account: -- **Vanity domains** — We recommend delegating each stage's TLD (e.g., `acme-prod.com`, `acme-staging.com`) to the corresponding account. This lets each environment manage its own TLD, avoiding cross-account complexity. -- **Service discovery domains** — There's typically one domain (e.g., `acme.net`) with zones delegated to each member account (e.g., `prod.acme.net`, `staging.acme.net`). This avoids ambiguity of ownership while enabling account-level DNS management. +- **[Vanity domains](/layers/network/design-decisions/decide-on-vanity-branded-domain)** — We recommend delegating each stage's TLD (e.g., `acme-prod.com`, `acme-staging.com`) to the corresponding account. This lets each environment manage its own TLD, avoiding cross-account complexity. +- **[Service discovery domains](/layers/network/design-decisions/decide-on-service-discovery-domain)** — There's typically one domain (e.g., `acme.net`) with zones delegated to each member account (e.g., `prod.acme.net`, `staging.acme.net`). This avoids ambiguity of ownership while enabling account-level DNS management. Centralizing registration in the `dns` account while delegating NS records provides clear ownership without operational bottlenecks. From 73b7ca0f417d923b282a33e99844af21c9a48ebc Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Fri, 9 Jan 2026 10:27:02 -0600 Subject: [PATCH 4/6] docs: Add IAM boundaries benefit for centralized registration Co-Authored-By: Claude Haiku 4.5 --- .../layers/network/design-decisions/decide-on-dns-registrar.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx index d9e2f57f6..a962dfd16 100644 --- a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx +++ b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx @@ -32,7 +32,7 @@ Once you own a domain, the NS records can be delegated to any account: - **[Vanity domains](/layers/network/design-decisions/decide-on-vanity-branded-domain)** — We recommend delegating each stage's TLD (e.g., `acme-prod.com`, `acme-staging.com`) to the corresponding account. This lets each environment manage its own TLD, avoiding cross-account complexity. - **[Service discovery domains](/layers/network/design-decisions/decide-on-service-discovery-domain)** — There's typically one domain (e.g., `acme.net`) with zones delegated to each member account (e.g., `prod.acme.net`, `staging.acme.net`). This avoids ambiguity of ownership while enabling account-level DNS management. -Centralizing registration in the `dns` account while delegating NS records provides clear ownership without operational bottlenecks. +Centralizing registration in the `dns` account while delegating NS records provides clear ownership without operational bottlenecks. It also creates clear IAM boundaries—you can grant domain management permissions (e.g., to legal) in the `dns` account while day-to-day DNS operations happen in separate accounts. ## Option 2: Use an Existing Registrar From f6e5b4a1224d05a244e72d07e8c87e4165ee1080 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Fri, 9 Jan 2026 10:28:01 -0600 Subject: [PATCH 5/6] docs: Add procurement to IAM boundaries example Co-Authored-By: Claude Haiku 4.5 --- .../layers/network/design-decisions/decide-on-dns-registrar.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx index a962dfd16..bef36e714 100644 --- a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx +++ b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx @@ -32,7 +32,7 @@ Once you own a domain, the NS records can be delegated to any account: - **[Vanity domains](/layers/network/design-decisions/decide-on-vanity-branded-domain)** — We recommend delegating each stage's TLD (e.g., `acme-prod.com`, `acme-staging.com`) to the corresponding account. This lets each environment manage its own TLD, avoiding cross-account complexity. - **[Service discovery domains](/layers/network/design-decisions/decide-on-service-discovery-domain)** — There's typically one domain (e.g., `acme.net`) with zones delegated to each member account (e.g., `prod.acme.net`, `staging.acme.net`). This avoids ambiguity of ownership while enabling account-level DNS management. -Centralizing registration in the `dns` account while delegating NS records provides clear ownership without operational bottlenecks. It also creates clear IAM boundaries—you can grant domain management permissions (e.g., to legal) in the `dns` account while day-to-day DNS operations happen in separate accounts. +Centralizing registration in the `dns` account while delegating NS records provides clear ownership without operational bottlenecks. It also creates clear IAM boundaries—you can grant domain management permissions (e.g., to legal, procurement) in the `dns` account while day-to-day DNS operations happen in separate accounts. ## Option 2: Use an Existing Registrar From 5e53a885c33fdde7c9ccf01c3724f99a551595ec Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Fri, 9 Jan 2026 15:02:50 -0600 Subject: [PATCH 6/6] docs: Add Route 53 registrar prerequisites consideration Note that dns account must be provisioned first and a credit card is required (separate from regular AWS billing). Co-Authored-By: Claude Haiku 4.5 --- .../network/design-decisions/decide-on-dns-registrar.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx index bef36e714..69988283e 100644 --- a/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx +++ b/docs/layers/network/design-decisions/decide-on-dns-registrar.mdx @@ -76,6 +76,13 @@ The AWS provider includes an `aws_route53domains_registered_domain` resource, bu Domain registration is intentionally ClickOps. The reference architecture does not manage domain registration via Terraform—you must register domains manually through the AWS Console or your chosen registrar. +### Route 53 Registrar Prerequisites + +If you choose AWS Route 53 as your registrar: + +- **The `dns` account must be provisioned first** — You cannot register domains until this account exists +- **A credit card is required** — Route 53 domain registration requires a credit card added to the account, separate from your regular AWS billing arrangement (e.g., invoicing, consolidated billing) + ### Legal Considerations We recommend checking with your legal department on where to consolidate domain ownership. Domain registration has implications for: