Task 05: Configure DNS Servers
The automated OS configuration run covers this task in the Dns step (DNS servers on the management port). 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 configuration
PURPOSE: Set DNS server addresses on the management NIC of all nodes using explicit values frominfrastructure.yml— adapter resolved by exact name, not auto-detected MASTER REFERENCE: Phase 03: OS Configuration
Status: Active
Overview
Configure the primary and secondary DNS server addresses on the management network adapter of each Azure Local node. DNS must be set before Active Directory operations, Azure Arc registration, and any hostname resolution required later in the deployment.
Task 04 (disable DHCP) must be complete. Setting DNS before DHCP is disabled has no harmful effect, but the standard sequence is Tasks 03 → 04 → 05.
Once the deployment completes, it isn't supported to change the DNS server IPs, and the addresses can't be updated across the Azure Local platform stack. Get them right now. Per Learn (Azure Local 2610, Network considerations for cloud deployments, DNS server considerations):
- The DNS servers must be the same on every node of the instance.
- The DNS servers of the infrastructure IP address range (set in the deployment wizard or template) must be the same ones the nodes use. The Azure Resource Bridge control plane VM and the AKS control plane use those servers.
- At least one configured DNS server must run outside the Azure Local instance. Running all of them as VMs on the instance that depends on them isn't supported, because name resolution is needed during boot, shutdown, restart and recovery.
- Every configured DNS server must resolve the on-premises domains the infrastructure needs. Public DNS servers such as 8.8.8.8 aren't supported as the configured servers.
- For Active Directory deployments the DNS server must resolve the Active Directory domain and the public internet endpoints.
- The DNS server IPs must not fall in the Azure Resource Bridge ranges (
10.96.0.0/24for deployments created from 2610,10.96.0.0/12for earlier deployments, and10.244.0.0/16for all). Use the wider10.96.0.0/12as the planning rule unless you are sure the instance is new on 2610. If AKS uses these DNS servers, also avoid its service and pod ranges. - Learn recommends assigning only one management IP for the default gateway and for the configured DNS servers across the physical network adapters of the node, so it doesn't change once the management intent is created. Network validation fails when it finds more than one physical adapter with a default gateway.
- In an ARM template, write multiple DNS servers as quoted strings separated by commas, for example
"dnsServers": ["192.0.2.4", "192.0.2.5"].
What the Dns step of the OS configuration does:
- Reads the DNS servers of the management port on each node
- Changes nothing when they already equal
networking.management.dns_servers - Otherwise sets them with
Set-DnsClientServerAddress - Reads them back at the end of the run and compares them with the file
Prerequisites
| Requirement | Description | Source |
|---|---|---|
| Task 04 complete | DHCP disabled on all adapters | Task 04: Disable DHCP |
| 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 |
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
- SConfig Utility
- Orchestrated Script
Configure DNS interactively on each node via console, KVM, or RDP.
SConfig requires repeating these steps on every node individually. For multi-node deployments, the Orchestrated Script tab (the OS configuration) is faster and less error-prone.
Steps — for each node:
- Open SConfig (if not already running, type
sconfigin PowerShell) - Select option
8— Network settings - Select the management adapter (the one configured with a static IP in Task 03)
- Select option
2— Set DNS Servers - Enter the Primary DNS IP from
infrastructure.yml→networking.management.dns_servers - Enter the Secondary DNS IP from
infrastructure.yml→networking.management.dns_servers - Press Enter to confirm
Verify in SConfig:
After setting DNS, return to the Network settings menu and confirm the DNS servers shown
match the values from infrastructure.yml.
Alternatively, verify in PowerShell:
# Run on the node after SConfig configuration
Get-DnsClientServerAddress -AddressFamily IPv4 |
Where-Object { $_.ServerAddresses.Count -gt 0 } |
Select-Object InterfaceAlias, ServerAddresses |
Format-Table -AutoSize
PowerShell
No script in this task folder. The folder
scripts/deploy/04-cluster-deployment/phase-03-os-configuration/task-05-configure-dns-serversholds only a placeholder. A placeholder printsNOT IMPLEMENTED, changes nothing and exits with code 3. The earlierSet-DnsServers.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 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
Verify DNS server configuration on each node:
# Run on each node (or via PSRemoting)
Get-DnsClientServerAddress -AddressFamily IPv4 |
Where-Object { $_.ServerAddresses.Count -gt 0 } |
Select-Object InterfaceAlias, ServerAddresses |
Format-Table -AutoSize
Validation checklist:
| Check | Expected | Status |
|---|---|---|
| Primary DNS on management NIC | networking.management.dns_servers from infrastructure.yml | ☐ |
| Secondary DNS on management NIC | networking.management.dns_servers from infrastructure.yml | ☐ |
| No other DNS entries on management NIC | Only 2 servers listed | ☐ |
Task 06 performs a full DNS resolution validation. Basic resolution testing at this stage is optional — proceed to Task 06 for a comprehensive verification.
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 validation fails (post-set mismatch) | Transient WMI delay | Wait 5 seconds and re-run the validation query manually |
| DNS not resolving names (verified in Task 06) | DNS servers unreachable | Verify DNS server IPs are reachable from node; check routing and firewall |
| 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 04: Disable DHCP | ↑ Phase 03: OS Configuration | Task 06: Verify DNS → |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-01-31 | Azure Local Cloud | Initial document |
| 2.0 | 2026-03-05 | Azure Local Cloud | Full rewrite to standards — complete frontmatter, 3-tab structure (SConfig, Direct, Orchestrated), Standalone tab removed, full embedded scripts, explicit NIC name from infrastructure.yml, infrastructure.yml integration in orchestrated script |