How do I resolve the CNAMEAlreadyExists error when I set up a CNAME alias for my CloudFront distribution?

6 minute read
0

When I set up a Canonical Name record (CNAME) alias for my Amazon CloudFront distribution, I get a "CNAMEAlreadyExists" error.

Short description

You can't use the same CNAME alias for more than one CloudFront distribution. When the CNAME alias that you want to add is already associated with another CloudFront distribution, you receive the following error:

"One or more of the CNAMEs you provided are already associated with a different resource. (Service: AmazonCloudFront; Status Code: 409; Error Code: CNAMEAlreadyExists; Request ID: a123456b-c78d-90e1-23f4-gh5i67890jkl*"

If you have access to both source and target distributions, then manually remove the CNAME association from the existing CloudFront distribution. Then, associate the CNAME with the new CloudFront distribution.

Note: To manually associate the CNAME, you might need to wait until the old distribution's status is Deployed before you proceed.

If you don't know the distribution ID, then use the ListConflictingAliases CloudFront API. This lets you find partial information about the distribution and the AWS account ID for the conflicting CNAME alias. Then, use the AssociateAlias API to move your CNAME from the existing distribution (source distribution) to the new distribution (target distribution).

Use one of the following resolutions based on your scenario:

  • For source and target distributions that are in the same account, refer to the Use the AssociateAlias API to move your CNAME section.
  • For cross-account source and target distributions, refer to the Deactivate source distribution with the conflicting CNAME section.
  • If you can't deactivate the source distribution because of the downtime to existing traffic, then refer to Use a wildcard to move the alternate domain name.
    Note: You can't use a wildcard to move an apex domain (example.com). To move an apex domain when the source and target distributions are in different accounts, see Contact AWS Support to move an alternate domain name.

Resolution

Use the AssociateAlias API to move your CNAME

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

To move your CNAME, complete the following steps:

  1. In the AWS Identity and Access Management (IAM) policy of the user or role that makes the API request, add the following resource-level permissions:
    Note: Replace SourceAcccount with the account number of the source distribution. Replace SourceDistroID with the source distribution ID. Replace TargetAccountID with the account number of the target distribution. Replace TargetDistroID with target distribution ID.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "CloudFrontCnameSwapSameAcc",
          "Effect": "Allow",
          "Action": [
            "cloudfront:GetDistribution",
            "cloudfront:ListConflictingAliases",
            "cloudfront:AssociateAlias",
            "cloudfront:UpdateDistribution"
          ],
          "Resource": [
            "arn:aws:cloudfront::SourceAcccount:distribution/SourceDistroID",
            "arn:aws:cloudfront::TargetAccount:distribution/TargetDistroID"
          ]
        }
      ]
    }

    Important: The IAM user or role that makes the request must have the resource-level permissions in both the source distribution and target distribution.

  2. Identify the distribution with the conflicting CNAME. If you don't know which distribution has the conflicting CNAME, then use the ListConflictingAliases API to find the distribution:
    Note: Replace YourDistributionID with your distribution's ID and YourCNAME with the conflicting CNAME alias.

    $ aws cloudfront list-conflicting-aliases --distribution-id YourDistributionID --alias YourCNAME
  3.  To verify ownership of the domain, you must have read access to YourDistributionID. You must also have an SSL/TLS certificate that's associated with the CloudFront distribution that secures the conflicting CNAME.
    When you're ready to verify ownership, create a DNS TXT record for the CNAME that resolves to the target distribution's canonical name. Your TXT record must include an underscore before the CNAME, apex, or wildcard:

    _.example.com.         900   IN   TXT     "dexample123456.cloudfront.net"
    _cname.example.com.    900   IN   TXT     "dexample123456.cloudfront.net"
    _*.example.com.        900   IN   TXT     "dexample123456.cloudfront.net"
  4. Verify that the target distribution has a valid SSL/TLS certificate.
    Note: The subject name or subject alternative name must match or overlap with the CNAME alias. It's a best practice to have a valid certificate that's issued from AWS Certificate Manager or a trusted CA that's listed in Mozilla's CA certificate list.

  5. Run the AssociateAlias API request from the account that owns the target distribution:

    $ aws cloudfront associate-alias --target-distribution-id YourTargeDistributiontID --alias your_cname.example.com

Deactivate the source distribution with the conflicting CNAME

For source and target distributions that are in different accounts, turn off the source distribution that's associated with the conflicting domain. Then, use the AssociateAlias API to move the CNAME.

Use the associate-alias command to move apex domains between different accounts:

  1. Open the CloudFront console.
  2. On the navigation pane, choose Distributions.
  3. Select the source distribution, and then choose Disable.
    Note: If you don't know which distribution has the conflicting CNAME, then use the ListConflictingAliases API to find the distribution. Replace YourDistributionID with the ID of your distribution and YourCNAME with the name of the conflicting CNAME:
    $ aws cloudfront list-conflicting-aliases --distribution-id YourDistributionID --alias YourCNAME
    Note: The ListConflictingAliases API requires the GetDistribution and ListConflictingAliases permissions.

After you deactivate the source distribution, follow the steps in the Use the AssociateAlias API to move your CNAME section.

If you don't have access to the account that contains the source distribution or you can't deactivate the source distribution, then contact AWS Support.

Use a wildcard to move the alternate domain name

If your source and target distributions are in different accounts but you can't deactivate the source distribution, then use a wildcard to move the CNAME. You must have access to both the source distribution and target distribution to move the CNAME.

This process involves multiple updates to both source and target distributions. Wait for each distribution to fully deploy the latest change before you proceed to the next step.

To move the alternate domain name, complete the following steps:

  1. Update the target distribution to add a wildcard CNAME that covers the alternate domain name that you want to move. If your domain is www.example.com, then add the wildcard alternate domain name *.example.com to the target distribution.
    Note: You must have an SSL/TLS certificate on the target distribution that secures the wildcard domain name.

  2. Update the DNS settings for the CNAME to point to the target distribution's canonical name. For example, if your domain is www.example.com, then update the DNS record for www.example.com to route traffic to the target distribution's canonical name:

    www.example.com.         86400   IN   CNAME     "dexample123456.cloudfront.net"

    Note: Because the alternate domain name is still associated to the source distribution, the source distribution still requests that you use the alternate domain name.

  3. Update the source distribution to remove the alternate domain name.
    Note: In this step, there's no interruption to the live traffic. Because the requested domain name matches the wildcard domain that's added to the target distribution, live traffic uses the target distribution settings.

  4. To add the alternate domain name that you want to move, update the target distribution.

  5. To validate the DNS record for the CNAME, use dig or a similar DNS query tool:

    dig CNAME www.example.com +short
    nslookup example.com
  6. (Optional) To remove the wildcard alternate domain name, update the target distribution.

AWS OFFICIAL
AWS OFFICIALUpdated 2 months ago
6 Comments

Hi, I want to ask if something needs to be changed in the action list when I have the apex domain. In my case source and target distributions are in different AWS accounts but the source distribution can't be deactivated (production environment).

replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied a year ago

What do I do when the list-conflicting-aliases command doesn't list any other distributions other than the one I'm running the command for?

replied 7 months ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied 7 months ago

I followed the "Use a wildcard to move the alternate domain name" section and was able to perform a no-downtime cutover from one distribution to another.

However, this guide could be clearer in a number of areas:

  • Make it clear that traffic does not cut over until step 3 (when the alternate domain name is removed from the source distribution)
  • Clarify whether two (or more) distributions can share the same wildcard-based alternate domain name in parallel

It's surprising to me that the user-managed DNS record(s) that point the alternate domain name to the Cloudfront distribution don't actually control where traffic goes. It seems like Cloudfront implements some additional routing logic, such that the distribution your traffic gets routed to is primarily a function of where the alternate domain name is associated. While that makes sense given Cloudfront's global design, I would love to see some documentation that explains this behavior in more detail.

replied 5 days ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied 4 days ago