New APIs and functionality for managing Amazon CloudFront CNAMEs

Today, Amazon CloudFront announced the release of two new APIs, ListConflictingAliases and AssociateAlias. These APIs are useful when you need to locate or move Alternate Domain Names (CNAMEs) when you encounter the CNAMEAlreadyExists error code. In addition, more use cases have been enabled when you are working with wildcard CNAMEs across accounts. Before diving into the APIs, this blog first sets a bit of context for the CNAMEAlreadyExists error code and discusses ways that AWS gives you more freedom to manage CNAMEs in your CloudFront distributions.

Enabling new use cases

Historically, when trying to add a CNAME (such as test.example.com) to a distribution, the CNAMEAlreadyExists error code was returned in two scenarios. First, either that exact CNAME (test.example.com) exists on another distribution; or second, a wildcard CNAME at that same level (*.example.com) exists in a distribution in a different AWS account. Before domain validation was introduced, when adding a CNAME to a distribution, you sometimes used a second behavior, the cross-account wildcard restriction, to ensure none of your domain CNAMEs were added by a different account. With domain validation in place, this practice is no longer necessary as CNAMEs are only added when you prove a degree of ownership over that domain with a valid and trusted certificate.

As of today, you can now use a wildcard CNAME in one account, and a specific CNAME in another account. This change opens up several new capabilities that allow you to work with, delegate, and manage these CNAMEs. For example, large organizations with teams using multiple accounts for different aspects of their application can use a specific domain (such as api.example.com) in account A, and use a wildcard (*.example.com) to direct all other traffic to Account B. Alternatively, you can delegate the use of a specific CNAME (such as saas.example.com) to a SaaS provider’s account where you might already be using *.example.com in your own account. And lastly, you can use a wildcard to transition a non-apex CNAME that is actively serving traffic between distributions in two different accounts.

In addition to this new functionality, two new APIs further facilitate the CNAME management process – ListConflictingAliases and AssociateAlias. In summary, if you encounter the CNAMEAlreadyExists error code, these APIs show you which distribution has the CNAME, and let you atomically move the CNAME to a target distribution in a single update, under certain conditions. Now let’s look at the key details of each API.

Introducing ListConflictingAliases

Let’s start with the ListConflictingAliases API. This API identifies a given CNAME, either a specific subdomain or a wildcard, and returns a list of CNAMEs that exist on a CloudFront distribution and either match or overlap the CNAME. In addition, the API also returns information about the distribution ID and account ID where any of these CNAMEs are located. It is important to note that the distribution ID and account ID in the API response are partially obfuscated to balance the need to protect the identity of AWS accounts and resources, with the need to provide sufficient information to conduct follow-up investigations or discussions. To use this API, your IAM role must have permissions to GetDistribution and ListConflictingAliases.

Introducing AssociateAlias

The second API is AssociateAlias. This API moves a given CNAME from a source distribution to a target distribution in a single atomic update, without disrupting your traffic. If you are moving CNAMEs within the same account, the process is straightforward. Moving a CNAME across accounts is more nuanced, depending on the state of the distribution and whether or not you have access to both accounts.

CNAME moves within the same account
When you are trying to move a CNAME between two distributions in the same account, you can use this API to move the CNAME with full control. Your IAM role must have UpdateDistribution permission on both the source and target distribution, and AssociateAlias permission on the target distribution. In addition, CloudFront confirms that the target distribution’s certificate passes the domain validation criteria and does a DNS dig to find the required TXT record confirm domain ownership. For more on this, see Set up the target distribution in the CloudFront Developer Guide.

CNAME moves across accounts
If the source distribution is in a disabled state, you can use the API to move the CNAME to your target distribution just like above. However, in this scenario your IAM role only needs UpdateDistribution and AssociateAlias permissions on the target distribution. CloudFront does same domain validation and DNS checks as previously described.

If the source distribution is still in an active state, there are two approaches outside the AssociateAlias. First, if the CNAME is not an apex domain (such as example.com) and you have access to both accounts, you can now use a wildcard to move an alternate domain name between the two accounts now that the cross-account wildcard restriction has been removed. However, if the CNAME is an apex domain, or you don’t have access to the source account, the second approach is to follow the steps in the Contact AWS Support to move an alternate domain name section of the CloudFront Developer Guide.

Looking forward

I hope you find these new capabilities useful in managing CNAME migrations. As AWS looks forward, we’re evaluating ways that we can validate requests to move a CNAME across accounts from a source distribution that is active. As part of this, we’re always working to strike the right balance between providing more flexibility and control against maintaining our operational bar for the security and availability of your workloads. Stay tuned for more details to come in the future.

For more information on this new functionality and APIs, see Moving an alternate domain name to a different distribution in the CloudFront Developer Guide as well the API References for ListConflictingAlias and AssociateAlias.