Skip to main content
Sponsor @cloudposse

Decide on Vanity (Branded) Domains

Problem​

We need a domain that represents your branded domain in the live environment. This will be our synthetic production domain since we do not want to interfere with any current production environments. Also, we do not want to use any domains currently in use for any other purpose.

IMPORTANT

This is not the same as Decide on Service Discovery Domain.

  • These domains are for public-facing endpoints

  • Prevent devs from using logic jumps based on the domain instead of using feature flags

  • Maintain symmetry with production (e.g. if we have acme.com in production redirect to www.acme.com, we should be able to test/validate identical behavior with a top-level domain in staging and dev)

  • CNAME is not possible with a zone-apex, only A records. (If we used staging.acme.com, we would technically want to use www.staging.acme.com for zone-apex parity and that just gets too long)

  • Cookie domain scope should only be for staging or production but not both. Separate domains prevent this from happening. For example, if you set Domain=acme.com, cookies are available on subdomains like staging.acme.com and www.acme.com. Therefore, we want to avoid this possibility. We have seen this affect the ability to properly QA features.

  • CORS headers should prevent cross-origin requests from staging and product. We want to prevent wildcards from permitting cross-staging requests which could lead to staging hammering production (vise versa)

Access-Control-Allow-Origin: https://*.acme.com

Considerations​

Use one domain for each stage (prod, staging, dev, sandbox, etc)

  • This top-level domain will be delegated to each account as necessary. Typically including prod, staging, dev, and optionally sandbox.
  • Our standard recommendation is to acquire a new domain with a regular TLD.
  • One good convention is to use your namespace suffixed with -prod or -staging. e.g. $namespace-$stage.com would become cpco-prod.com, cpco-staging.com, cpco-dev.com
info

Remember, these are for synthetic testing of branded domain functionality, and not the actual domains your customers will be using.

FAQ​

What are examples of vanity domains?​

Think of vanity domains as all of your publicly branded properties. E.g. apple.com and www.apple.com and store.apple.com.

Why do we differentiate between vanity domains and service discovery domains?​

It’s not uncommon that vanity domains are controlled by a different entity in the organization and may not even be controlled using terraform or other IaC. Of course, we prefer to manage them with terraform using our dns-primary component, it’s not a technical requirement.

What’s the difference between vanity domains and service discovery domains?​

Vanity domains are typically fronted by a CDN and then upstream to some load balancer (e.g. ALB). The load balancer on the other hand will typically have a service discovery domain associated with it (e.g. lb.uw2.prod.acme.org). The service discovery domain is a domain whose conventions we (operations teams) control (e.g. totally logical and hierarchical with multiple zone delegations). While the vanity domains are governed by a different set of stakeholders such as marketing, sales, legal, and SEO. You might have hundreds or thousands of vanity domains pointed to a single service discovery domain.

Why don’t we just use staging.acme.com and dev.acme.com as our vanity domains?​

We want symmetry and this is not symmetrical to what you use currently in production. E.g. your production traffic doesn’t go to prod.acme.com. It goes to acme.com or www.acme.com; so for the same reason, we want to have something that symmetrical to acme.com for dev and staging purposes. Another example is a cookie set on .acme.com will work for both staging.acme.com and prod.acme.com, and that's a bad thing from a testing perspective.