Skip to main content

Task 06: Verify DNS Client Configuration

The automated run does this task for you

The automated OS configuration run covers this task in the Dns step and the verification pass at the end of the run, which read the DNS servers back and compare them with the file. Use the manual steps below when you can't use the run, or to understand or troubleshoot what it does. See how the run works.

Runbook Azure Dell

DOCUMENT CATEGORY: Runbook
SCOPE: DNS client verification
PURPOSE: Confirm DNS configuration matches infrastructure.yml and that Azure endpoints resolve from each node — prerequisite for Arc registration and AD operations MASTER REFERENCE: Phase 03: OS Configuration

Status: Active

Overview​

Verify that primary and secondary DNS servers are correctly configured on the management NIC of every Azure Local node, and that each node can resolve the Azure endpoints required for Arc registration and Azure Resource Manager communication.

This task does not change any configuration — it is a read-only validation step.

Verify, because DNS can't be changed after deployment

The servers verified here become the permanent DNS servers of the instance. Before you pass this task, confirm they are the same on all nodes, that at least one runs outside the instance, that none is a public resolver such as 8.8.8.8, and that none is in the Azure Resource Bridge ranges (see the list in Task 05).

What the checks do:

  1. Read the configured DNS servers of each node and compare them with networking.management.dns_servers
  2. Test that each node resolves the domain and the Azure endpoints
  3. Report the result per node

Prerequisites​

RequirementDescriptionSource
Task 05 completeDNS servers configured on management NICTask 05: Configure DNS
DNS IPs confirmedValidated DNS server addressesinfrastructure.yml: networking.management.dns_servers
NIC name confirmedManagement adapter nameinfrastructure.yml: nodes[].network_adapters[].name
Network reachabilityDNS servers reachable from nodesSite network configuration

Configuration Reference​

infrastructure.yml pathScript variableExample
nodes[].network_adapters[].nameThe management adapterEmbedded NIC 1
networking.management.dns_serversPrimary DNS server192.0.2.4
networking.management.dns_serversSecondary DNS server192.0.2.5
nodes[].management.ip_addressThe address the OS configuration connects to192.0.2.11

Execution Options​

Run the check on each node (console, KVM or RDP). The earlier toolkit script Test-DnsConfiguration.ps1 is removed.

Valueinfrastructure.yml key
The expected DNS serversnetworking.management.dns_servers
The domainidentity.active_directory.domain_fqdn
# The DNS servers of every adapter that has one. Compare them with networking.management.dns_servers.
Get-DnsClientServerAddress -AddressFamily IPv4 |
Where-Object { $_.ServerAddresses.Count -gt 0 } |
Select-Object InterfaceAlias, ServerAddresses

# The domain and an Azure endpoint must resolve
Resolve-DnsName improbability.cloud
Resolve-DnsName management.azure.com

The check fails when a node has other DNS servers than the file or cannot resolve a name.


Validation Checklist​

  • Primary DNS server matches infrastructure.yml: networking.management.dns_servers
  • Secondary DNS server matches infrastructure.yml: networking.management.dns_servers
  • Configuration confirmed on all nodes
  • The same DNS servers on every node, at least one outside the instance, none a public resolver, none in the Azure Resource Bridge ranges
  • management.azure.com resolves from all nodes
  • login.microsoftonline.com resolves from all nodes
  • guestnotificationservice.azure.com resolves from all nodes
  • dp.kubernetesconfiguration.azure.com resolves from all nodes

Values from infrastructure.yml​

The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.


Troubleshooting​

IssueRoot CauseRemediation
Adapter not found errorNIC name in config doesn't matchRun Get-NetAdapter on the node; update nodes[].network_adapters[].name in infrastructure.yml
DNS mismatch — wrong IPs returnedTask 05 not completed or used incorrect valuesRe-run Task 05 with correct values from infrastructure.yml
Azure endpoints fail to resolveDNS servers unreachable or missing forwardersVerify DNS servers are online; check forwarder configuration on DNS server
Endpoints resolve internally but not externallyDNS forwarder not configured for internetAdd an internet forwarder on the customer DNS server. The forwarder belongs on the DNS server; do not configure a public resolver such as 8.8.8.8 as one of the DNS servers of the nodes (not supported)
OS configuration: the node is Blocked in the plannetworking.management.dns_servers is missingAdd the DNS servers to infrastructure.yml, then run the plan again
Node unreachable via PSRemotingWinRM not configured or firewall blockingVerify Task 01 (WinRM) completed; check firewall rules


Alternatives​

The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.

← Task 05: Configure DNS↑ Phase 03: OS ConfigurationTask 07: Configure NTP →

Version Control​

VersionDateAuthorChanges
1.02026-01-31Azure Local CloudInitial document
2.02026-03-04Azure Local CloudFull rewrite to standards — complete frontmatter, bare-node 2-tab structure (Direct, Orchestrated), Standalone tab removed, full embedded scripts, explicit NIC and DNS values from infrastructure.yml, Assert-ConfigValues hard-fail, Azure endpoint resolution test