Skip to main content

Task 05: Configure DNS Servers

The automated run does this task for you

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.

Runbook Azure Dell

DOCUMENT CATEGORY: Runbook
SCOPE: DNS client configuration
PURPOSE: Set DNS server addresses on the management NIC of all nodes using explicit values from infrastructure.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.

Run AFTER Task 04

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.

DNS decisions are permanent

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):

  1. The DNS servers must be the same on every node of the instance.
  2. 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.
  3. 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.
  4. 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.
  5. For Active Directory deployments the DNS server must resolve the Active Directory domain and the public internet endpoints.
  6. The DNS server IPs must not fall in the Azure Resource Bridge ranges (10.96.0.0/24 for deployments created from 2610, 10.96.0.0/12 for earlier deployments, and 10.244.0.0/16 for all). Use the wider 10.96.0.0/12 as 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.
  7. 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.
  8. 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:

  1. Reads the DNS servers of the management port on each node
  2. Changes nothing when they already equal networking.management.dns_servers
  3. Otherwise sets them with Set-DnsClientServerAddress
  4. Reads them back at the end of the run and compares them with the file

Prerequisites​

RequirementDescriptionSource
Task 04 completeDHCP disabled on all adaptersTask 04: Disable DHCP
DNS IPs confirmedValidated DNS server addressesinfrastructure.yml: networking.management.dns_servers
NIC name confirmedManagement adapter nameinfrastructure.yml: nodes[].network_adapters[].name

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​

Configure DNS interactively on each node via console, KVM, or RDP.

Use the Orchestrated Script tab when running multiple nodes

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:

  1. Open SConfig (if not already running, type sconfig in PowerShell)
  2. Select option 8 — Network settings
  3. Select the management adapter (the one configured with a static IP in Task 03)
  4. Select option 2 — Set DNS Servers
  5. Enter the Primary DNS IP from infrastructure.yml → networking.management.dns_servers
  6. Enter the Secondary DNS IP from infrastructure.yml → networking.management.dns_servers
  7. 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

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:

CheckExpectedStatus
Primary DNS on management NICnetworking.management.dns_servers from infrastructure.yml☐
Secondary DNS on management NICnetworking.management.dns_servers from infrastructure.yml☐
No other DNS entries on management NICOnly 2 servers listed☐
DNS resolution test

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​

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 validation fails (post-set mismatch)Transient WMI delayWait 5 seconds and re-run the validation query manually
DNS not resolving names (verified in Task 06)DNS servers unreachableVerify DNS server IPs are reachable from node; check routing and firewall
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 04: Disable DHCP↑ Phase 03: OS ConfigurationTask 06: Verify DNS →

Version Control​

VersionDateAuthorChanges
1.02026-01-31Azure Local CloudInitial document
2.02026-03-05Azure Local CloudFull 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