DNS Design¶

Name resolution decides whether traffic to a PaaS service stays on the private network or goes over the internet. This page explains the DNS design of the platform and the pitfalls when connecting it to an on-premises DNS. For the settings, see feature flags (private DNS zones, private DNS resolver).

Components¶

Component	Role
Spoke virtual network	Uses a custom DNS server: the hub DNS server of its region (the spoke setting `dnsServerOverwrite` is empty by default, see Spoke JSON reference)
Hub DNS entry point	Typically the Azure Firewall acting as DNS proxy. It forwards queries to the resolver.
Azure Private DNS Resolver	Inbound endpoint: receives queries from the firewall and from on-premises. Outbound endpoint: forwards queries for selected domains (for example an internal Active Directory domain) to DNS servers elsewhere.
Central private DNS zones	One zone per Private Link service (for example `privatelink.blob.core.windows.net`). An Azure Policy initiative registers private endpoint records in them.
On-premises DNS	Domain controllers or other DNS servers. They answer for the internal namespace and, with conditional forwarders, send Azure names to the resolver's inbound endpoint.
Public DNS	Managed outside the platform, by the registrar or DNS provider

Resolution paths¶

flowchart LR
    vm["VM in a spoke"] --> fw["Hub firewall (DNS proxy)"]
    fw --> in["Private DNS Resolver (inbound)"]
    in --> pz["Central private DNS zones"]
    out["Private DNS Resolver (outbound)"] -- "forwarding rule" --> ad["Internal DNS / AD servers"]
    in --> out
    onprem["On-premises client"] --> opdns["On-premises DNS"]
    opdns -- "conditional forwarder" --> in

From	To	Path
Spoke	A name in a private DNS zone (private endpoint)	Spoke DNS setting, firewall DNS proxy, resolver inbound endpoint, private DNS zone
Spoke	An internal domain hosted on-premises or on domain controllers in Azure	The same path, then a forwarding rule on the resolver sends the query out through the outbound endpoint
On-premises	The internal domain	Answered by the on-premises DNS
On-premises	A name in an Azure private DNS zone	A conditional forwarder on the on-premises DNS sends the query over the VPN or ExpressRoute link to the resolver's inbound endpoint

How a private endpoint name resolves¶

A resource in the virtual network looks up example.azurewebsites.net.
The Azure-provided DNS (168.63.129.16) sees that Private Link is enabled for the service and returns a CNAME to example.privatelink.azurewebsites.net.
The private DNS zone privatelink.azurewebsites.net is linked to the network and holds an A record with the private endpoint's IP address.
The resource connects to that private IP. The traffic stays on the Azure backbone.

For on-premises clients to get the private IP, their DNS must forward the query to the resolver. Without that, they get the public IP and the traffic goes over the internet.

Enabling conditional forwarding: do it in order¶

Switching on conditional forwarding changes where on-premises traffic goes. Existing workloads that reach a PaaS service over its public address today will start to use the private IP address. If the firewalls do not allow that, they stop working.

List the private DNS zones that you will forward. Create a conditional forwarder per zone on the on-premises DNS servers, pointing to the resolver's inbound endpoint.
First allow the traffic from on-premises to the private endpoint addresses, in the on-premises firewall and in the Azure Firewall.
Make sure every site that uses the DNS servers has private connectivity to Azure. A remote site or subsidiary without a private link would get a private IP it cannot reach. Enable forwarding for them after the link is live.
Enable the forwarders, one zone at a time, and test.

Runbook for adding a forwarding rule: DNS conditional forwarder.

Pitfalls¶

Pitfall	What happens	What to do
Split DNS: the same zone exists in the internal DNS and in the public DNS	A record that only exists in the public zone cannot be resolved inside the network, because the internal DNS is authoritative for the whole zone and returns name not found	Create each record in both places, or avoid hosting the same zone in both
Manual record management	Slow, error-prone and only a few people can do it	Manage records as code in a repository, or delegate a subdomain to the teams (DNS subdomain delegation)
Unclear ownership	Nobody knows who owns a zone	Name zones after the workload and environment

Verify against your configuration

This page describes the usual design. Check which address the spokes use as DNS server and whether the firewall DNS proxy is enabled in your platform configuration (virtual_network_dns_servers, firewall_policy_dns.proxy_enabled).