# Move an alternate domain name If you try to add an alternate domain name to a standard distribution or distribution tenant, and the alternate domain name is already associated with a different resource, you will get an error message. For example, you will get the `CNAMEAlreadyExists` error message (One or more of the CNAMEs you provided are already associated with a different resource) when you try to add www.example.com to a standard distribution or distribution tenant, but that alternate domain name is already associated with a different resource. In that case, you might want to move the existing alternate domain name from one resource to another. This is the *source distribution* and the *target distribution*. You can move alternate domain names between either standard distributions and/or distribution tenants. To move the alternate domain name, see the following topics: **Topics** + [ # Set up the target standard distribution or distribution tenant ](alternate-domain-names-move-create-target.md) + [ # Find the source standard distribution or distribution tenant ](alternate-domain-names-move-find-source.md) + [ # Move the alternate domain name ](alternate-domain-names-move-options.md) # Set up the target standard distribution or distribution tenant Before you can move an alternate domain name, you must set up the target resource. This is the target standard distribution or distribution tenant that you're moving the alternate domain name to. ------ #### [ Standard distribution ] **To set up a target standard distribution** 1. Request a TLS certificate. This certificate includes the alternate domain name as the Subject or Subject Alternative Domain (SAN), or a wildcard (\$1) that covers the alternate domain name that you’re moving. If you don’t have one, you can request one from AWS Certificate Manager (ACM) or from another certificate authority (CA) and import it into ACM. **Note** You must request or import the certificate in the US East (N. Virginia) (`us-east-1`) Region. For more information, see [Request a public certificate using the console](https://docs.aws.amazon.com/acm/latest/userguide/acm-public-certificates.html#request-public-console) and [Import a certificate](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate-api-cli.html) in the AWS Certificate Manager in the *AWS Certificate Manager User Guide*. 1. If you haven’t created the target standard distribution, create one now. As part of creating the standard distribution, associate the certificate with this standard distribution. For more information, see [Create a distribution](distribution-web-creating-console.md). If you already have a target standard distribution, associate the certificate with the standard distribution. For more information, see [Update a distribution](HowToUpdateDistribution.md). 1. **If you’re moving alternate domain names within the same AWS account, skip this step.** To move an alternate domain name from one AWS account to another, you must create a TXT record in your DNS configuration. This verification step helps prevent unauthorized domain transfers. CloudFront uses this TXT record to validate your ownership of the alternate domain name. In your DNS configuration, create a DNS TXT record that associates the alternate domain name with the target standard distribution. The TXT record format can vary, depending on the domain type. + For subdomains, specify an underscore (`_`) in front of the alternate domain name. The following shows an example TXT record. `_www.example.com TXT d111111abcdef8.cloudfront.net` + For an apex (or root domain), specify an underscore and period ( `_.`) in front of the domain name. The following shows an example TXT record. `_.example.com TXT d111111abcdef8.cloudfront.net` ------ #### [ Distribution tenant ] **To set up the target distribution tenant** 1. Request a TLS certificate. This certificate includes the alternate domain name as the Subject or Subject Alternative Domain (SAN), or a wildcard (\$1) that covers the alternate domain name that you’re moving. If you don’t have one, you can request one from AWS Certificate Manager (ACM) or from another certificate authority (CA) and import it into ACM. **Note** You must request or import the certificate in the US East (N. Virginia) (`us-east-1`) Region. For more information, see [Request a public certificate using the console](https://docs.aws.amazon.com/acm/latest/userguide/acm-public-certificates.html#request-public-console) and [Import a certificate](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate-api-cli.html) in the AWS Certificate Manager in the *AWS Certificate Manager User Guide*. 1. If you haven’t created the target distribution tenant, create one now. As part of creating the distribution tenant, associate the certificate with the distribution tenant. For more information, see [Create a distribution](distribution-web-creating-console.md). If you already have a target distribution tenant, associate the certificate with the distribution tenant. For more information, see [Add a domain and certificate (distribution tenant)](managed-cloudfront-certificates.md#vanity-domain-tls-tenant). 1. **If you’re moving alternate domain names within the same AWS account, skip this step.** To move an alternate domain name from one AWS account to another, you must create a TXT record in your DNS configuration. This verification step helps prevent unauthorized domain transfers, and CloudFront uses this TXT record to validate your ownership of the alternate domain name. In your DNS configuration, create a DNS TXT record that associates the alternate domain name with the target distribution tenant. The TXT record format can vary, depending on the domain type. + For subdomains, specify an underscore (`_`) in front of the alternate domain name. The following shows an example TXT record. `_www.example.com TXT d111111abcdef8.cloudfront.net` + For an apex (or root domain), specify an underscore and period ( `_.`) in front of the domain name. The following shows an example TXT record. `_.example.com TXT d111111abcdef8.cloudfront.net` ------ Next, see the following topic to find the source standard distribution or distribution tenant that is already associated with the alternate domain name. # Find the source standard distribution or distribution tenant Before you can move an alternate domain name from one distribution (standard or tenant) to another, find the *source distribution*. This is the resource that the alternate domain name is already associated with. When you know the AWS account ID of both the source and target distribution resources, you can determine how to move the alternate domain name. **Notes** We recommend that you use the [ListDomainConflicts](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListDomainConflicts.html) API operation, because it supports both standard distributions and distribution tenants. The [ListConflictingAliases](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListConflictingAliases.html) API operation only supports standard distributions. Follow these examples to find the source distribution (standard or tenant). ------ #### [ list-domain-conflicts ] **Tip** For a standard distribution, you must have the `cloudfront:GetDistribution` and `cloudfront:ListDomainConflicts` permissions. For a distribution tenant, you must have the `cloudfront:GetDistributionTenant` and `cloudfront:ListDomainConflicts` permissions. **To use `list-domain-conflicts` to find the source standard distribution or distribution tenant** 1. Use the `list-domain-conflicts` command as shown in the following example. 1. Replace *www.example.com* with the domain name. 1. For the `domain-control-validation-resource`, specify the ID of the target standard distribution or distribution tenant [that you set up previously](alternate-domain-names-move-create-target.md). You must have a standard distribution or distribution tenant that is associated with a certificate that covers the specified domain. 1. Run this command using the credentials that are in the same AWS account as the target standard distribution or distribution tenant. **Request** This example specifies a distribution tenant. ``` aws cloudfront list-domain-conflicts \ --domain www.example.com \ --domain-control-validation-resource "DistributionTenantId=dt_2x9GhoK0TZRsohWzv1b9It8JABC" ``` **Response** For each domain name in the command’s output, you can see the following: + The resource type that the domain is associated with + The resource ID + The AWS account ID that owns the resource The resource ID and the account ID are partially hidden. This allows you to identify the standard distribution or distribution tenant that belongs to your account, and helps to protect the information of ones that you don’t own. ``` { "DomainConflicts": [ { "Domain": "www.example.com", "ResourceType": "distribution-tenant", "ResourceId": "***************ohWzv1b9It8JABC", "AccountId": "******112233" } ] } ``` The response lists all the domain names that conflict or overlap with the one that you specified. **Example** + If you specify *tenant1.example.com*, the response includes tenant1.example.com and the overlapping wildcard alternate domain name (\$1.example.com if it exists). + If you specify *\$1.tenant1.example.com*, the response includes \$1.tenant1.example.com and any alternate domain names covered by that wildcard (for example, test.tenant1.example.com, dev.tenant1.example.com, and so on). 1. In the response, find the source standard distribution or distribution tenant for the alternate domain name that you're moving, and note the AWS account ID. 1. Compare the account ID of the *source* standard distribution or distribution tenant with the account ID where you created the *target* standard distribution or distribution tenant in the [previous step](alternate-domain-names-move-create-target.md). You can then determine whether the source and target are in the same AWS account. This helps you determine how to move the alternate domain name. For more information, see the [https://docs.aws.amazon.com/cli/latest/reference/cloudfront/list-domain-conflicts.html](https://docs.aws.amazon.com/cli/latest/reference/cloudfront/list-domain-conflicts.html) command in the *AWS Command Line Interface Reference*. ------ #### [ list-conflicting-aliases (standard distributions only) ] **Tip** You must have the `cloudfront:GetDistribution` and `cloudfront:ListConflictingAliases` permissions on the target standard distribution. **To use `list-conflicting-aliases` to find the source standard distribution** 1. Use the `list-conflicting-aliases` command as shown in the following example. 1. Replace *www.example.com* with the alternate domain name, and *EDFDVBD6EXAMPLE* with the ID of the target standard distribution [that you set up previously](alternate-domain-names-move-create-target.md). 1. Run this command using credentials that are in the same AWS account as the target standard distribution. **Request** This example specifies a standard distribution. ``` aws cloudfront list-conflicting-aliases \ --alias www.example.com \ --distribution-id EDFDVBD6EXAMPLE ``` **Response** For each alternate domain name in the command’s output, you can see the ID of the standard distribution that it’s associated with, and the AWS account ID that owns the standard distribution. The standard distribution and account IDs are partially hidden, which allows you to identify the standard distributions and accounts that you own, and helps to protect the information of ones that you don’t own. ``` { "ConflictingAliasesList": { "MaxItems": 100, "Quantity": 1, "Items": [ { "Alias": "www.example.com", "DistributionId": "*******EXAMPLE", "AccountId": "******112233" } ] } } ``` The response lists the alternate domain names that conflict or overlap with the one that you specified. **Example** + If you specify *www.example.com*, the response includes www.example.com and the overlapping wildcard alternate domain name (\$1.example.com) if it exists. + If you specify *\$1.example.com*, the response includes \$1.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). 1. Find the standard distribution for the alternate domain name that you're moving, and note the AWS account ID. Compare this account ID with the account ID where you created the target standard distribution in the [previous step](alternate-domain-names-move-create-target.md). You can then determine whether these two standard distributions are in the same AWS account and how to move the alternate domain name. For more information, see the [https://docs.aws.amazon.com//cli/latest/reference/cloudfront/list-conflicting-aliases.html](https://docs.aws.amazon.com//cli/latest/reference/cloudfront/list-conflicting-aliases.html) command in the *AWS Command Line Interface Reference*. ------ Next, see the following topic to move the alternate domain name. # Move the alternate domain name Depending on your situation, choose from the following ways to move the alternate domain name: **The source and target distributions (standard or tenant) are in the same AWS account** Use the **update-domain-association** command in the AWS Command Line Interface (AWS CLI) to move the alternate domain name. This command works for all same-account moves, including when the alternate domain name is an apex domain (also called a *root domain*, like example.com). **The source and target distributions (standard or tenant) are in different AWS accounts** If you have access to the source standard distribution or distribution tenant, the alternate domain name is *not* an apex domain, 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](#alternate-domain-names-move-use-wildcard). If you don’t have access to the AWS account that has the source standard distribution or distribution tenant, you can try using the **update-domain-association** command to move the alternate domain name. The source standard distribution or distribution tenant must be disabled before you can move the alternate domain name. For additional help, see [Contact AWS Support to move an alternate domain name](#alternate-domain-names-move-contact-support). **Note** You can use the **associate-alias** command, but this command only supports standard distributions. See [AssociateAlias](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_AssociateAlias.html) in the *Amazon CloudFront API Reference*. ------ #### [ update-domain-association (standard distributions and distribution tenants) ] **To use `update-domain-association` to move an alternate domain name** 1. Use the `update-domain-association` command, as shown in the following example. 1. Replace *example.com* with the alternate domain name, and specify the ID of the target standard distribution or distribution tenant. 1. Run this command using credentials that are in the same AWS account as the target standard distribution or distribution tenant. **Note the following restrictions** In addition to the `cloudfront:UpdateDomainAssociation` permission, you must have the `cloudfront:UpdateDistribution` permission to update a standard distribution. To update a distribution tenant, you must have the `cloudfront:UpdateDistributionTenant` permission. If the source and target distributions (standard or tenant) are in different AWS accounts, the source must be disabled before you can move the domain. The target distribution must be set up as described in [Set up the target standard distribution or distribution tenant](alternate-domain-names-move-create-target.md). **Request** ``` aws cloudfront update-domain-association \ --domain "www.example.com" \ --target-resource DistributionTenantId=dt_9Fd3xTZq7Hl2KABC \ --if-match E3UN6WX5ABC123 ``` **Response** ``` { "ETag": "E7Xp1Y3N9DABC", "Domain": "www.example.com", "ResourceId": "dt_9Fd3xTZq7Hl2KABC" } ``` This command removes the alternate domain name from the source standard distribution or distribution tenant and adds it to the target standard distribution or distribution tenant. 1. After the target distribution is fully deployed, update your DNS configuration to point your domain name to the CloudFront routing endpoint. For example, your DNS record would point your alternate domain name (`www.example.com`) to the CloudFront provided domain name d111111abcdef8.cloudfront.net. If the target is a distribution tenant, specify the connection group endpoint. For more information, see [Point domains to CloudFront](managed-cloudfront-certificates.md#point-domains-to-cloudfront). ------ #### [ associate-alias (standard distributions only) ] **To use `associate-alias` to move an alternate domain name** 1. Use the `associate-alias` command, as shown in the following example. 1. Replace *www.example.com* with the alternate domain name, and *EDFDVBD6EXAMPLE* with the target standard distribution ID. 1. Run this command using credentials that are in the same AWS account as the target standard distribution. **Note the following restrictions** You must have `cloudfront:AssociateAlias` and `cloudfront:UpdateDistribution` permissions on the target standard distribution. If the source and target standard distribution are in the same AWS account, you must have `cloudfront:UpdateDistribution` permission on the source standard distribution. If the source standard distribution and target standard distribution are in different AWS accounts, you must disable the source standard distribution first. The target standard distribution must be set up as described in [Set up the target standard distribution or distribution tenant](alternate-domain-names-move-create-target.md). **Request** ``` aws cloudfront associate-alias \ --alias www.example.com \ --target-distribution-id EDFDVBD6EXAMPLE ``` This command removes the alternate domain name from the source standard distribution and moves it to the target standard distribution. 1. After the target standard 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 standard distribution. For example, your DNS record would point your alternate domain name (`www.example.com`) to the CloudFront provided domain name d111111abcdef8.cloudfront.net. For more information, see the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudfront/associate-alias.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudfront/associate-alias.html) command in the *AWS CLI Command Reference*. ------ ## 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 Support. For more information, see [Contact AWS Support to move an alternate domain name](#alternate-domain-names-move-contact-support). **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 \$1.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](HowToUpdateDistribution.md). 1. 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. 1. Update the source distribution to remove the alternate domain name. For more information, see [Update a distribution](HowToUpdateDistribution.md). 1. Update the target distribution to add the alternate domain name. For more information, see [Update a distribution](HowToUpdateDistribution.md). 1. 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. 1. (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 Support to move the alternate domain name. **To contact 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 standard distribution or distribution tenant](alternate-domain-names-move-create-target.md). 1. [Contact Support](https://console.aws.amazon.com/support/home) to request that they verify that you own the domain, and move the domain to the new CloudFront distribution for you. 1. 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.