DNS Conditional Forwarder (Add a Forwarding Rule)

Standard change: Add DNS conditional forwarder(s).

Effect: the Azure environment can resolve names of a domain that is hosted on DNS servers outside Azure (for example on-premises). The Private DNS Resolver forwards queries for that domain to those servers. Only the connectivity layer changes, and the firewall layer if the DNS servers are added to an IP group.

Background on the resolver and the direction of forwarding: DNS design. The other direction (on-premises to Azure) is a conditional forwarder on the on-premises DNS servers and is not part of this change.

Request fields

Field	Use
Domain name(s)	The domain(s) that the DNS servers are authoritative for, for example contoso.example
DNS server IP address(es)	The servers that should answer for the domain, for example 10.50.10.10 and 10.50.10.11
Rationale	pull request
Environment	Platform environment and region(s)

Example of a request: "We would like conditional forwarders from Azure to our datacenter for contoso.example. Point them to 10.50.10.10 and 10.50.10.11."

Steps

1. Create a branch in the configuration repository (Making a change safely).

2. Add the forwarding rule in <env-folder>/<region>/connectivity.auto.tfvars. Find private_dns_resolver_forwarding_rules. If there are no rules yet, the value is null. Add or extend the object with one entry per domain:

   private_dns_resolver_forwarding_rules = {
     contoso-example = {
       dns_forwarding_ruleset_id = null
       domain_name               = "contoso.example."
       enabled                   = true
       metadata                  = null
       target_dns_servers = {
         server1 = {
           ip_address = "10.50.10.10"
           port       = 53
         }
         server2 = {
           ip_address = "10.50.10.11"
           port       = 53
         }
       }
     }
   }
   

   The trailing dot is required

   domain_name must end with a dot (contoso.example.).

3. Allow the traffic to the DNS servers. Add the DNS server addresses to the IP group for DNS servers in <env-folder>/<region>/ip_groups/ (in the platform this group was named ipgrp-dns-servers), if they are not in it yet, and check that a firewall rule allows DNS (port 53) from the hub to that group (Firewall rules).

4. Repeat in every environment folder that needs it. Canary and prod stay identical for this change. If a platform has no canary, skip it.
5. Plan with hub in Plan (or ApproveModifications) mode. Expect:
   • connectivity: the new or changed forwarding rule(s) on the DNS forwarding ruleset;
   • firewall: the IP group update, when you added addresses.
6. Apply to canary, check, then prod.
7. Merge the pull request after review.

Verify

• Azure portal: Private DNS Resolver > DNS Forwarding Rulesets, and check the new rule(s). Check the IP group in the firewall policy.
• From a VM in a test spoke, resolve a name of the domain without naming a DNS server, for example with nslookup or dig. The query uses the DNS server of the virtual network (the hub path).

If resolution fails

Resolve the name again, naming a DNS server, in this order, to find where it breaks:

1. the private IP address of the Azure Firewall (DNS proxy);
2. the inbound endpoint of the Private DNS Resolver;
3. the on-premises DNS server from the request.

If none works, DNS traffic is blocked on the path: a network security group, a firewall rule, or the on-premises firewall or routing. Check the Azure Firewall logs for blocked DNS traffic and for queries forwarded to the on-premises servers (Where to look first).

For domains that end in .local, many operating systems use multicast DNS (mDNS) and never ask the configured DNS server. Test with another name, or change the client.

Roll back

Remove the rule from private_dns_resolver_forwarding_rules (and the IP group entries, if nobody else uses them) and run hub.