Move an alternate domain name to a different distribution - Amazon CloudFront
Set up the target distributionFind the source distributionMove the alternate domain name

Move an alternate domain name to a different distribution

When you try to add an alternate domain name to a distribution but the alternate domain name is already in use on a different distribution, you get a CNAMEAlreadyExists error (One or more of the CNAMEs you provided are already associated with a different resource). For example, you get this error when you attempt to add www.example.com to a distribution, but www.example.com is already associated with a different distribution.

In that case, you might want to move the existing alternate domain name from one distribution (the source distribution) to another (the target distribution). The following steps are an overview of the process. For more information, follow the link at each step in the overview.

To move an alternate domain name

  1. Set up the target distribution. This distribution must have an SSL/TLS certificate that covers the alternate domain name that you are moving. For more information, see Set up the target distribution.

  2. Find the source distribution. You can use the AWS Command Line Interface (AWS CLI) to find the distribution that the alternate domain name is associated with. For more information, see Find the source distribution.

  3. Move the alternate domain name. The way you do this depends on whether the source and target distributions are in the same AWS account. For more information, see Move the alternate domain name.

Set up the target distribution

Before you can move an alternate domain name, you must set up the target distribution (the distribution that you are moving the alternate domain name to).

To set up the target distribution

  1. Get an SSL/TLS certificate that includes the alternate domain name that you are moving. If you don’t have one, you can request one from AWS Certificate Manager (ACM), or get one from another certificate authority (CA) and import it into ACM. Make sure that you request or import the certificate in the US East (N. Virginia) (us-east-1) Region.

  2. If you haven’t created the target distribution, create one now. As part of creating the target distribution, associate your certificate (from the previous step) with the distribution. For more information, see Create a distribution.

    If you already have a target distribution, associate your certificate (from the previous step) with the target distribution. For more information, see Update a distribution.

  3. Create a DNS TXT record that associates the alternate domain name with the distribution domain name of the target distribution. Create your TXT record with an underscore (_) in front of the alternate domain name. The following shows an example TXT record in DNS:

    _www.example.com TXT d111111abcdef8.cloudfront.net

    CloudFront uses this TXT record to validate your ownership of the alternate domain name.

Find the source distribution

Before you move an alternate domain name from one distribution to another, you should find the source distribution (the distribution where the alternate domain name is currently in use). When you know the AWS account ID of both the source and target distributions, you can determine how to move the alternate domain name.

To find the source distribution for the alternate domain name

  1. Use the CloudFront list-conflicting-aliases command in the AWS Command Line Interface (AWS CLI) as shown in the following example. Replace www.example.com with the alternate domain name, and EDFDVBD6EXAMPLE with the ID of the target distribution that you set up previously. Run this command using credentials that are in the same AWS account as the target distribution. To use this command, you must have cloudfront:GetDistribution and cloudfront:ListConflictingAlias permissions on the target distribution.

    
aws cloudfront list-conflicting-aliases --alias www.example.com --distribution-id EDFDVBD6EXAMPLE

    The command’s output shows a list of all the alternate domain names that conflict or overlap with the provided one. For example:

    • If you provide www.example.com to the command, the command’s output includes www.example.com and the overlapping wildcard alternate domain name (*.example.com) if it exists.

    • If you provide *.example.com to the command, the command’s output includes *.example.com and any alternate domain names covered by that wildcard (for example, www.example.com, test.example.com, dev.example.com, and so on).

    For each alternate domain name in the command’s output, you can see the ID of the distribution that it’s associated with, and the AWS account ID that owns the distribution. The distribution and account IDs are partially hidden, which allows you to identify the distributions and accounts that you own, but helps to protect the information of ones that you don’t own.

  2. In the command’s output, find the distribution for the alternate domain name that you are moving, and note the source distribution’s AWS account ID. Compare the source distribution’s account ID with the account ID where you created the target distribution, and determine whether these two distribution are in the same AWS account. This helps you determine how to move the alternate domain name.

    To move the alternate domain name, see the following topic.

Move the alternate domain name

Depending on your situation, choose from the following ways to move the alternate domain name:

If the source and target distributions are in the same AWS account

Use the associate-alias command in the AWS CLI to move the alternate domain name. This method works for all same-account moves, including when the alternate domain name is an apex domain (also called a root domain, like example.com). For more information, see Use associate-alias to move an alternate domain name.

If the source and target distributions are in different AWS accounts

If you have access to the source distribution, the alternate domain name is not an apex domain (also called a root domain, like example.com), and you are not already using a wildcard that overlaps with that alternate domain name, use a wildcard to move the alternate domain name. For more information, see Use a wildcard to move an alternate domain name.

If you don’t have access to the source distribution’s AWS account, you can try using the associate-alias command in the AWS CLI to move the alternate domain name. If the source distribution is disabled, you can move the alternate domain name. For more information, see Use associate-alias to move an alternate domain name. If the associate-alias command doesn’t work, contact AWS Support. For more information, see Contact AWS Support to move an alternate domain name.

Use associate-alias to move an alternate domain name

If the source distribution is in the same AWS account as the target distribution, or if it’s in a different account but disabled, you can use the CloudFront associate-alias command in the AWS CLI to move the alternate domain name.

To use associate-alias to move an alternate domain name

  1. Use the AWS CLI to run the CloudFront associate-alias command, as shown in the following example. Replace www.example.com with the alternate domain name, and EDFDVBD6EXAMPLE with the target distribution ID. Run this command using credentials that are in the same AWS account as the target distribution. Note the following restrictions for using this command:

    • You must have cloudfront:AssociateAlias and cloudfront:UpdateDistribution permissions on the target distribution.

    • If the source and target distributions are in the same AWS account, you must have cloudfront:UpdateDistribution permission on the source distribution.

    • If the source and target distributions are in different AWS accounts, the source distribution must be disabled.

    • The target distribution must be set up as described in Set up the target distribution.

    
aws cloudfront associate-alias --alias www.example.com --target-distribution-id EDFDVBD6EXAMPLE

    This command updates both distributions by removing the alternate domain name from the source distribution and adding it to the target distribution.

  2. After the target distribution is fully deployed, update your DNS configuration to point the alternate domain name’s DNS record to the distribution domain name of the target distribution.

Use a wildcard to move an alternate domain name

If the source distribution is in a different AWS account than the target distribution, and the source distribution is enabled, you can use a wildcard to move the alternate domain name.

Note

You can’t use a wildcard to move an apex domain (like example.com). To move an apex domain when the source and target distributions are in different AWS accounts, contact AWS Support. For more information, see Contact AWS Support to move an alternate domain name.

To use a wildcard to move an alternate domain name
Note

This process involves multiple updates to your distributions. Wait for each distribution to fully deploy the latest change before proceeding to the next step.

  1. Update the target distribution to add a wildcard alternate domain name that covers the alternate domain name that you are moving. For example, if the alternate domain name that you’re moving is www.example.com, add the alternate domain name *.example.com to the target distribution. To do this, the SSL/TLS certificate on the target distribution must include the wildcard domain name. For more information, see Update a distribution.

  2. Update the DNS settings for the alternate domain name to point to the domain name of the target distribution. For example, if the alternate domain name that you’re moving is www.example.com, update the DNS record for www.example.com to route traffic to the domain name of the target distribution (for example d111111abcdef8.cloudfront.net).

    Note

    Even after you update the DNS settings, the alternate domain name is still served by the source distribution because that’s where the alternate domain name is currently configured.

  3. Update the source distribution to remove the alternate domain name. For more information, see Update a distribution.

  4. Update the target distribution to add the alternate domain name. For more information, see Update a distribution.

  5. Use dig (or a similar DNS query tool) to validate that the DNS record for the alternate domain name resolves to the domain name of the target distribution.

  6. (Optional) Update the target distribution to remove the wildcard alternate domain name.

Contact AWS Support to move an alternate domain name

If the source and target distributions are in different AWS accounts, and you don’t have access to the source distribution’s AWS account or can’t disable the source distribution, you can contact AWS Support to move the alternate domain name.

To contact AWS Support to move an alternate domain name

  1. Set up a target distribution, including the DNS TXT record that points to the target distribution. For more information, see Set up the target distribution.

  2. Contact AWS Support to request that they verify that you own the domain, and move the domain to the new CloudFront distribution for you.

  3. After the target distribution is fully deployed, update your DNS configuration to point the alternate domain name’s DNS record to the distribution domain name of the target distribution.