Tutorial: Create a Traffic Manager Linked Record using Azure CLI

In this tutorial, you create a Traffic Manager Linked Record in Azure DNS using the Azure CLI. A Traffic Manager Linked Record connects a DNS record set directly to an Azure Traffic Manager profile, returning IP addresses to clients without an intermediate CNAME resolution.

Important

Traffic Manager Linked Records is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

For a portal-based walkthrough, see Create a Traffic Manager Linked Record using the Azure portal. For a conceptual overview, see Traffic Manager Linked Records overview.

In this tutorial, you learn how to:

• Create the networking and virtual machine infrastructure.
• Create a Traffic Manager profile with endpoints.
• Create a Traffic Manager Linked Record using Azure CLI.
• Test the Traffic Manager Linked Record.

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

Prerequisites

• An Azure account with an active subscription.

• Azure CLI version 2.60 or later installed locally, or use Azure Cloud Shell. Run az --version to check your version. To install or upgrade, see Install Azure CLI.

• A domain name hosted in Azure DNS. If you don't have an Azure DNS zone, create one and delegate your domain to Azure DNS.

  Note

  In this tutorial, contoso.com is used as an example domain name. Replace contoso.com with your own domain name.

• Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Set environment variables

Set variables for the resource names and locations used throughout this tutorial to avoid repeating them in each command.

RESOURCE_GROUP="test-rg"
LOCATION="eastus"
VNET_NAME="vnet-1"
TM_PROFILE_NAME="tm-profile"
DNS_ZONE="contoso.com"

Create the resource group

az group create \
    --name $RESOURCE_GROUP \
    --location $LOCATION

Create the virtual network

az network vnet create \
    --resource-group $RESOURCE_GROUP \
    --name $VNET_NAME \
    --address-prefix 10.10.0.0/16 \
    --subnet-name subnet-1 \
    --subnet-prefix 10.10.0.0/24

Create web server virtual machines

Create two Ubuntu virtual machines with public IP addresses to use as Traffic Manager endpoints.

Create the public IP addresses

az network public-ip create \
    --resource-group $RESOURCE_GROUP \
    --name public-ip-1 \
    --sku Standard \
    --dns-name vm-1-tmlink

az network public-ip create \
    --resource-group $RESOURCE_GROUP \
    --name public-ip-2 \
    --sku Standard \
    --dns-name vm-2-tmlink

Create the network security group

az network nsg create \
    --resource-group $RESOURCE_GROUP \
    --name nsg-1

az network nsg rule create \
    --resource-group $RESOURCE_GROUP \
    --nsg-name nsg-1 \
    --name AllowHTTP \
    --protocol tcp \
    --priority 100 \
    --destination-port-range 80

az network nsg rule create \
    --resource-group $RESOURCE_GROUP \
    --nsg-name nsg-1 \
    --name AllowHTTPS \
    --protocol tcp \
    --priority 110 \
    --destination-port-range 443

Create the virtual machine NICs

az network nic create \
    --resource-group $RESOURCE_GROUP \
    --name nic-1 \
    --vnet-name $VNET_NAME \
    --subnet subnet-1 \
    --network-security-group nsg-1 \
    --public-ip-address public-ip-1

az network nic create \
    --resource-group $RESOURCE_GROUP \
    --name nic-2 \
    --vnet-name $VNET_NAME \
    --subnet subnet-1 \
    --network-security-group nsg-1 \
    --public-ip-address public-ip-2

Create the virtual machines

Note

Replace <your-ssh-public-key> with the contents of your SSH public key file, or use --generate-ssh-keys to create a new key pair.

az vm create \
    --resource-group $RESOURCE_GROUP \
    --name vm-1 \
    --nics nic-1 \
    --image Ubuntu2404 \
    --admin-username azureuser \
    --generate-ssh-keys \
    --no-wait

az vm create \
    --resource-group $RESOURCE_GROUP \
    --name vm-2 \
    --nics nic-2 \
    --image Ubuntu2404 \
    --admin-username azureuser \
    --generate-ssh-keys

The last command waits for vm-2 to be created. Both VMs are ready when the command returns.

Install NGINX on both VMs

az vm run-command invoke \
    --resource-group $RESOURCE_GROUP \
    --name vm-1 \
    --command-id RunShellScript \
    --scripts "sudo apt-get update && sudo apt-get install -y nginx && echo 'Hello World from vm-1' | sudo tee /var/www/html/index.html"

az vm run-command invoke \
    --resource-group $RESOURCE_GROUP \
    --name vm-2 \
    --command-id RunShellScript \
    --scripts "sudo apt-get update && sudo apt-get install -y nginx && echo 'Hello World from vm-2' | sudo tee /var/www/html/index.html"

Retrieve the public IP addresses

Note the IP addresses for both VMs. You need them when adding Traffic Manager endpoints.

VM1_IP=$(az network public-ip show \
    --resource-group $RESOURCE_GROUP \
    --name public-ip-1 \
    --query ipAddress \
    --output tsv)

VM2_IP=$(az network public-ip show \
    --resource-group $RESOURCE_GROUP \
    --name public-ip-2 \
    --query ipAddress \
    --output tsv)

echo "vm-1 IP: $VM1_IP"
echo "vm-2 IP: $VM2_IP"

Create the Traffic Manager profile

az network traffic-manager profile create \
    --resource-group $RESOURCE_GROUP \
    --name $TM_PROFILE_NAME \
    --routing-method Priority \
    --unique-dns-name tm-profile-$RANDOM

Add endpoints to the Traffic Manager profile

az network traffic-manager endpoint create \
    --resource-group $RESOURCE_GROUP \
    --profile-name $TM_PROFILE_NAME \
    --name tmendpoint-1 \
    --type externalEndpoints \
    --target $VM1_IP \
    --priority 1

az network traffic-manager endpoint create \
    --resource-group $RESOURCE_GROUP \
    --profile-name $TM_PROFILE_NAME \
    --name tmendpoint-2 \
    --type externalEndpoints \
    --target $VM2_IP \
    --priority 2

Get the full resource ID of the Traffic Manager profile. You need it when creating the linked record.

TM_PROFILE_ID=$(az network traffic-manager profile show \
    --resource-group $RESOURCE_GROUP \
    --name $TM_PROFILE_NAME \
    --query id \
    --output tsv)

echo "Traffic Manager profile ID: $TM_PROFILE_ID"

Create the Traffic Manager Linked Record

Use az network dns record-set a create with the --traffic-management-profile parameter to create the Traffic Manager Linked Record. The following command creates an A record at the zone apex (@).

Note

The --traffic-management-profile parameter is available in Azure CLI version 2.60 and later, and requires the Traffic Manager Linked Records preview API (2024-06-01-preview or later).

az network dns record-set a create \
    --resource-group <dns-zone-resource-group> \
    --zone-name $DNS_ZONE \
    --name "@" \
    --traffic-management-profile $TM_PROFILE_ID

Note

Replace <dns-zone-resource-group> with the resource group that contains your Azure DNS zone. This may differ from the resource group that contains the Traffic Manager profile.

To create a Traffic Manager Linked Record for a subdomain instead of the zone apex, replace "@" with the subdomain name, for example "www":

az network dns record-set a create \
    --resource-group <dns-zone-resource-group> \
    --zone-name $DNS_ZONE \
    --name "www" \
    --traffic-management-profile $TM_PROFILE_ID

Verify the linked record

az network dns record-set a show \
    --resource-group <dns-zone-resource-group> \
    --zone-name $DNS_ZONE \
    --name "@"

The output includes a trafficManagementProfile property with the Traffic Manager profile resource ID, confirming the link is established:

{
  "name": "@",
  "properties": {
    "trafficManagementProfile": {
      "id": "/subscriptions/.../resourceGroups/test-rg/providers/Microsoft.Network/trafficManagerProfiles/tm-profile"
    },
    "TTL": 30,
    ...
  }
}

Note

The TTL value shown in the output is inherited from the Traffic Manager profile's DNS configuration. Any TTL value specified during record creation is ignored.

Test the Traffic Manager Linked Record

To test name resolution, query one of the Azure DNS name servers for your zone directly. First, list your zone's name servers:

az network dns record-set ns show \
    --resource-group <dns-zone-resource-group> \
    --zone-name $DNS_ZONE \
    --name "@" \
    --query "nsRecords[0].nsdname" \
    --output tsv

Use the returned name server with nslookup to test resolution:

nslookup contoso.com <name-server-from-above>

The response contains the IP address of the highest-priority healthy Traffic Manager endpoint—without any CNAME records in the answer. This confirms that Traffic Manager Linked Records return IP addresses directly.

Test failover

1. Browse to your domain. You should see the NGINX page for vm-1.

2. Stop the vm-1 VM:

   az vm stop --resource-group $RESOURCE_GROUP --name vm-1
   

3. Wait a few minutes for Traffic Manager to detect the endpoint as unhealthy.

4. Flush your local DNS cache (ipconfig /flushdns on Windows, sudo dscacheutil -flushcache on macOS) and browse to your domain again. You should now see the page for vm-2.

5. Restart vm-1 to restore the original configuration:

   az vm start --resource-group $RESOURCE_GROUP --name vm-1
   

Clean up resources

When you no longer need the resources created in this tutorial, delete the resource group and the DNS record:

# Delete the resource group and all resources within it
az group delete --name $RESOURCE_GROUP --yes --no-wait

# Delete the Traffic Manager Linked Record from the DNS zone
az network dns record-set a delete \
    --resource-group <dns-zone-resource-group> \
    --zone-name $DNS_ZONE \
    --name "@" \
    --yes

Next steps

In this tutorial, you created a Traffic Manager Linked Record using Azure CLI. The record links your DNS zone apex to a Traffic Manager profile, returning IP addresses directly to clients.

• Learn more about Traffic Manager Linked Records.
• Create a Traffic Manager Linked Record using Azure PowerShell or the Azure portal.
• Learn more about Traffic Manager routing methods.
• Learn more about Strictly Typed Profiles.