Tutorial: Add a custom domain to your endpoint

This tutorial shows how to add a custom domain to an Azure Content Delivery Network (CDN) endpoint.

The endpoint name in your CDN profile is a subdomain of azureedge.net. By default when delivering content, the CDN profile domain gets included in the URL.

For example, https://contoso.azureedge.net/photo.png.

Azure CDN provides the option of associating a custom domain with a CDN endpoint. This option delivers content with a custom domain in your URL instead of the default domain.

In this tutorial, you learn how to:

  • Create a CNAME DNS record.
  • Add a custom domain with your CDN endpoint.
  • Verify the custom domain.

If you don't have an Azure subscription, create an Azure free account before you begin.

Prerequisites

Create a CNAME DNS record

Before you can use a custom domain with an Azure CDN endpoint, you must first create a canonical name (CNAME) record with Azure DNS or your DNS provider to point to your CDN endpoint.

A CNAME record is a DNS record that maps a source domain name to a destination domain name.

For Azure CDN, the source domain name is your custom domain name and the destination domain name is your CDN endpoint hostname.

Azure CDN routes traffic addressed to the source custom domain to the destination CDN endpoint hostname after it verifies the CNAME record.

A custom domain and its subdomain can only get added to a single endpoint at a time.

Use multiple CNAME records for different subdomains from the same custom domain for different Azure services.

You can map a custom domain with different subdomains to the same CDN endpoint.

Note

  • This tutorial uses the CNAME record type for multiple purposes:
    • Traffic routing can be accomplished with a CNAME record as well as A or AAAA record types in Azure DNS. To apply, use the following steps to replace the CNAME record with the record type of your choice.
    • A CNAME record is required for custom domain ownership validation and must be available when adding the custom domain to a CDN Endpoint. More details in the following section.

Azure DNS uses alias records for Azure resources within the same subscription.

To add an alias record for your Azure CDN endpoint:

  1. Sign in to the Azure portal.

  2. In the left-hand menu, select All resources then the Azure DNS zone for your custom domain.

  3. In the DNS zone for your custom domain, select + Record set.

  4. In Add record set enter or select the following information:

    Setting Value
    Name Enter alias you want to use for your CDN endpoint. For example, www.
    Type Select CNAME.
    Alias record set Select Yes.
    Alias type Select Azure resource.
    Choose a subscription Select your subscription.
    Azure resource Select your Azure CDN endpoint.
  5. Change the TTL for the record to your value.

  6. Select OK.

Add a custom domain to your CDN endpoint

After you've registered your custom domain, you can then add it to your CDN endpoint.


  1. Sign in to the Azure portal and browse to the CDN profile containing the endpoint that you want to map to a custom domain.

  2. On the CDN profile page, select the CDN endpoint to add the custom domain.

    CDN endpoint selection

  3. Select + Custom domain.

    Add custom domain button

  4. In Add a custom domain, Endpoint hostname, gets generated and pre-filled from your CDN endpoint URL: <endpoint-hostname>.azureedge.net. You can't change this value.

  5. For Custom hostname, enter your custom domain, including the subdomain, to use as the source domain of your CNAME record.

    1. For example, www.contoso.com or cdn.contoso.com. Don't use the cdnverify subdomain name.

    Add custom domain

  6. Select Add.

    Azure verifies that the CNAME record exists for the custom domain name you entered. If the CNAME is correct, your custom domain gets validated.

    It can take some time for the new custom domain settings to propagate to all CDN edge nodes:

    • For Azure CDN Standard from Microsoft profiles, propagation usually completes in 10 minutes.
    • For Azure CDN Standard from Akamai profiles, propagation usually completes within one minute.
    • For Azure CDN Standard from Edgio and Azure CDN Premium from Edgio profiles, propagation usually completes in 10 minutes.

Verify the custom domain

After you've completed the registration of your custom domain, verify that the custom domain references your CDN endpoint.

  1. Ensure that you have public content that you want cached at the endpoint. For example, if your CDN endpoint is associated with a storage account, Azure CDN caches the content in a public container. Set your container to allow public access and it contains at least one file to test the custom domain.

  2. In your browser, navigate to the address of the file by using the custom domain. For example, if your custom domain is www.contoso.com, the URL to the cached file should be similar to the following URL: http://www.contoso.com/my-public-container/my-file.jpg. Verify that the result is that same as when you access the CDN endpoint directly at <endpoint-hostname>.azureedge.net.

Clean up resources


If you no longer want to associate your endpoint with a custom domain, remove the custom domain by doing the following steps:

  1. Go to your DNS provider, delete the CNAME record for the custom domain, or update the CNAME record for the custom domain to a non-Azure CDN endpoint.

    Important

    To prevent dangling DNS entries and the security risks they create, starting from April 9th 2021, Azure CDN requires removal of the CNAME records to Azure CDN endpoints before the resources can be deleted. Resources include Azure CDN custom domains, Azure CDN profiles/endpoints or Azure resource groups that has Azure CDN custom domain(s) enabled.

  2. In your CDN profile, select the endpoint with the custom domain that you want to remove.

  3. From the Endpoint page, under Custom domains, right-click the custom domain that you want to remove, then select Delete from the context menu. Select Yes.

    The custom domain gets removed from your endpoint.

Next steps

In this tutorial, you learned how to:

  • Create a CNAME DNS record.
  • Add a custom domain with your CDN endpoint.
  • Verify the custom domain.

Advance to the next tutorial to learn how to configure HTTPS on an Azure CDN custom domain.