CloudFront configs allow for alternate domain names if you’d like to use a custom domain for your CDN distribution. You likely want that.

The alternate domain list can include wildcard subdomains, like *.example.com – see the docs. This is handy for dev and experiment environments so you don’t have to be constantly updating the config.

Imagine you have a scenario where you have a Route53 (DNS) & CloudFront config that looks like:

example.com - ALIAS - CloudFrontDistroA 
(where example.com is defined as an alias)

www.example.com - CNAME - example.com

random.example.com - ALIAS - CloudFrontDistroB 
(where *.example.com is defined as an alias)

What would you expect would happen when traffic went to www.example.com ?

If you’re not an insane person, you’d likely expect it to be directed to example.com, because that’s how DNS CNAMEs work.

You’ve probably guessed by now that this isn’t what actually happens.

Per AWS support, when traffic is routed to a CloudFront point of presence (POP), it will ignore the DNS config and route to the most specific rule across the CloudFront distributions in your account.

So, *.example.com will not only catch ANY example.com CNAME that doesn’t have an explicit mapping across all of your distributions’ alternate domain lists. It will also route ANY example.com CNAME there taht doesn’t have an explicit mapping. That makes a sort of sense if you’re thinking about a wildcard’s behavior in isolation. The first part at least, the second part is rubbish.

What this means in practice though is that one distribution’s configuration may affect another distribution in unexpected ways.

To AWS’ credit, this is documented… barely and for the inverse scenario.

If you have overlapping alternate domain names in two distributions, CloudFront sends the request to the distribution with the more specific name match, regardless of the distribution that the DNS record points to. For example, marketing.domain.com is more specific than *.domain.com.

I could see a use case for wanting an optional catch-all. I cannot fathom why anyone would desire this as the hard-coded default behavior. It completely fails the Principal of Least Surprise.

So my friends, do not use wildcard subdomains in your CloudFront Alternate Domain config. Learn from my mistakes. I was a fool for believing we could have nice things.