Task 06: Verify DNS Client Configuration
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.
DOCUMENT CATEGORY: Runbook
SCOPE: DNS client verification
PURPOSE: Confirm DNS configuration matchesinfrastructure.ymland 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.
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:
- Read the configured DNS servers of each node and compare them with
networking.management.dns_servers - Test that each node resolves the domain and the Azure endpoints
- Report the result per node
Prerequisites
| Requirement | Description | Source |
|---|---|---|
| Task 05 complete | DNS servers configured on management NIC | Task 05: Configure DNS |
| DNS IPs confirmed | Validated DNS server addresses | infrastructure.yml: networking.management.dns_servers |
| NIC name confirmed | Management adapter name | infrastructure.yml: nodes[].network_adapters[].name |
| Network reachability | DNS servers reachable from nodes | Site network configuration |
Configuration Reference
infrastructure.yml path | Script variable | Example |
|---|---|---|
nodes[].network_adapters[].name | The management adapter | Embedded NIC 1 |
networking.management.dns_servers | Primary DNS server | 192.0.2.4 |
networking.management.dns_servers | Secondary DNS server | 192.0.2.5 |
nodes[].management.ip_address | The address the OS configuration connects to | 192.0.2.11 |
Execution Options
- Direct Script (On Node)
- Orchestrated Script
Run the check on each node (console, KVM or RDP). The earlier toolkit script Test-DnsConfiguration.ps1 is removed.
| Value | infrastructure.yml key |
|---|---|
| The expected DNS servers | networking.management.dns_servers |
| The domain | identity.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.
PowerShell
No script in this task folder. The folder
scripts/deploy/04-cluster-deployment/phase-03-os-configuration/task-06-verify-dns-client-configurationholds only a placeholder. A placeholder printsNOT IMPLEMENTED, changes nothing and exits with code 3. The earlierTest-DnsConfiguration.ps1is removed. The OS configuration does this task in its Dns step.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-03-os-configuration/Invoke-AzureLocalOsConfiguration.ps1 | The one entry point of the OS configuration. It runs Set-AzureLocalNodeConfiguration.ps1 for each node: it reads the node, changes only what differs from infrastructure.yml, and reports. -Step limits the run to one step. |
The Plan mode is read only: it reads the DNS servers back and lists any difference. The pre-cluster verification checks them again before the deployment (check ND-006).
The nodes' local administrator comes from identity.local_admin of infrastructure.yml (the password is a secret reference), or from -Credential. The script never prompts. Run settings go in a JSON file given with -SettingsFile.
Run
# Plan (the default): read every node and list what would change
./Invoke-AzureLocalOsConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -Step Dns
# Apply
./Invoke-AzureLocalOsConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -Step Dns -Mode Apply
See how the run works.
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.comresolves from all nodes -
login.microsoftonline.comresolves from all nodes -
guestnotificationservice.azure.comresolves from all nodes -
dp.kubernetesconfiguration.azure.comresolves 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
| Issue | Root Cause | Remediation |
|---|---|---|
Adapter not found error | NIC name in config doesn't match | Run Get-NetAdapter on the node; update nodes[].network_adapters[].name in infrastructure.yml |
| DNS mismatch — wrong IPs returned | Task 05 not completed or used incorrect values | Re-run Task 05 with correct values from infrastructure.yml |
| Azure endpoints fail to resolve | DNS servers unreachable or missing forwarders | Verify DNS servers are online; check forwarder configuration on DNS server |
| Endpoints resolve internally but not externally | DNS forwarder not configured for internet | Add 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 plan | networking.management.dns_servers is missing | Add the DNS servers to infrastructure.yml, then run the plan again |
| Node unreachable via PSRemoting | WinRM not configured or firewall blocking | Verify 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.
Navigation
| ← Task 05: Configure DNS | ↑ Phase 03: OS Configuration | Task 07: Configure NTP → |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-01-31 | Azure Local Cloud | Initial document |
| 2.0 | 2026-03-04 | Azure Local Cloud | Full 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 |