Resolve private domain names in Azure SQL Managed Instance

Applies to: Azure SQL Managed Instance

In this article, learn how Azure SQL Managed Instance resolves private domain names.


In certain situations, it's necessary for the SQL Server database engine to resolve domain names that don't exist in public DNS records. For example, the following scenarios are likely to involve private domain names:

Azure SQL Managed Instance is deployed in an Azure virtual network and uses Azure-provided name resolution by default to resolve Internet addresses.

To change the default name resolution behavior and enable the resolution of private domain names, you can:


When you change a virtual network's DNS server from Azure to custom or vice versa, SQL Managed Instances in that virtual network must also be notified of the change. This is described in the section Update SQL Managed Instances.

You don't need to do this when you only attach or update Azure private DNS zones to the managed instances' virtual network. Those changes automatically propagate to the managed instances.


  • Be careful not to override or disable the resolution of domain names that Azure SQL Managed Instance uses internally, as listed in Networking constraints. Always configure your custom DNS server so that it can resolve public domain names.
  • Always use a fully qualified domain name (FQDN) for the services that you want Azure SQL Managed Instance to resolve, such as your mail server or an on-premises SQL Server instance. Use FQDNs even if those services are within your private DNS zone. For example, use Creating a linked server or configuring replication that reference SQL Server VMs inside the same virtual network also require an FQDN and a default DNS suffix; for example,

Update SQL Managed Instances

If the DNS server setting is changed in a virtual network with existing SQL managed instances, then the virtual cluster that hosts those instances, and the underlying machine groups, need to synchronize with the changes in the DNS configuration. Updating a virtual cluster affects all SQL Managed Instances hosted in it.

When you update a virtual cluster's DNS server settings, the custom DNS server IP addresses set on the virtual network become the preferred DNS servers for the instances in that cluster. The instances still retain Azure's DNS resolver address as a backup, but now resolve addresses using the custom DNS servers first.

Use the Azure portal to update the DNS server settings for an existing virtual cluster.

  1. Open the Azure portal.
  2. Open the resource group with a managed instance in the subnet you're configuring, and select the SQL managed instance that you want to update the DNS server settings for.
  3. In Overview, select the Virtual cluster the instance belongs to.
  4. Select Synchronize DNS server settings to update the cluster.

Screenshot showing the Synchronize DNS server settings action on the virtual cluster's overview page.

Verify the configuration

After you update the DNS server settings on the virtual cluster, you can verify that it's now in effect for the managed instances in that cluster. One way to do so is to create and run a SQL Server Agent job that outputs a list of DNS servers currently configured on the network interface.

To view the list of DNS servers configured on the managed instance's network interface:

  1. Start SQL Server Management Studio.
  2. Connect to a managed instance in the cluster you updated the DNS settings for.
  3. In Object Explorer, expand SQL Server Agent.
  4. Right-click Jobs and select New Job....
  5. In General, write the name of the job; for example "Verify DNS settings".
  6. In Steps, select New....
  7. Write the name of the step; for example, "run".
  8. Set Type to PowerShell.
  9. In Command, paste the following command: Get-DnsClientServerAddress
  10. Select OK, then OK to close both dialog windows.
  11. In Object Explorer, right-click the job you created and select Start Job at Step.... The job will run.
  12. When the job finishes, right-click it again and select View History.
  13. In Log file summary, expand the job and select its first and only step underneath it.
  14. In Selected row details:, review the output of the command and confirm that it contains your DNS server IP address(es).


A user that is synchronizing DNS server configurations across a virtual network:

  • Should be a member of the Subscription Contributor role, or
  • Have a custom role with the Microsoft.Sql/virtualClusters/updateManagedInstanceDnsServers/action permission.

Next steps