From 26dae6b490802932d1cb4fede55d7da58e525528 Mon Sep 17 00:00:00 2001 From: John Neemes Date: Wed, 15 Jul 2026 09:43:16 -0400 Subject: [PATCH 1/3] DNS External Resolution TSG: quick-fix, full admin-surface discoverability, validator table - Add a 'Quick fix (start here)' block: auto-identify the management adapter and give the exact reversible Set-DnsClientServerAddress command, gated by 'do not guess DNS servers', so the ~90% case is unblocked in one screen without reading the full decision tree first. - Add a 'Where it appears across the admin surfaces' subsection covering all eight admin surfaces (node PowerShell, event log, portal, on-disk result JSON = shown; Get-ClusterLog, Failover Cluster Manager, WAC standalone, WAC-in-portal = explicitly not evident), so admins do not hunt in the wrong place. - Add a validator metadata table (Name / Validator-test / Component / Severity) under the H1. No change to the diagnosis or remediation logic; documentation completeness and time-to-fix only. --- ...bleshooting-DNS-External-DNS-Resolution.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md b/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md index 516e36c2..10d620ef 100644 --- a/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md +++ b/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md @@ -1,5 +1,12 @@ # AzStackHci_DNS_ExternalDnsResolution +| | | +|---|---| +| **Name** | `AzStackHci_DNS_ExternalDnsResolution` | +| **Validator / test** | `Invoke-AzStackHciDNSValidation -Include Test-ExternalDnsResolution` | +| **Component** | Environment Validator (DNS) | +| **Severity** | Critical | + > **At a glance** > - **Owner:** the customer's network or DNS administrator. This is not a Microsoft software defect and not an OEM hardware or firmware issue. > - **Impact:** Critical. It blocks Azure Local deployment and updates until external DNS resolution works on every node. @@ -55,6 +62,40 @@ intended DNS rather than a stale value carried over from imaging. > in-progress supportability PR, so this guide does not depend on it: > [Troubleshooting AzStackHci_Connectivity_Test_Dns](./Troubleshooting-Connectivity-Test-Dns.md). +## Quick fix (start here) + +If external DNS resolution is failing and you already have the cluster's intended DNS +server addresses (from your deployment's management-network configuration), this resolves +the most common case: a node pointed at a DNS server that cannot resolve external names. + +> **Do not guess DNS server IP addresses.** If you do not have the cluster's correct DNS +> servers, stop here and use the full decision tree under [Remediation](#remediation) after +> identifying the failing server. Guessing can break name resolution for the whole node. + +On each affected node, identify the management adapter and re-point it at DNS servers that +resolve external names (per node, applies immediately, no reboot, reversible): + +```powershell +# 1. Identify the management adapter (the up adapter holding the node's management IP) +$mgmt = (Get-NetIPConfiguration | Where-Object { $_.IPv4Address -and $_.NetAdapter.Status -eq 'Up' } | + Select-Object -First 1).InterfaceAlias +"Management adapter: $mgmt" + +# 2. Record the current DNS servers FIRST so the change can be rolled back +Get-DnsClientServerAddress -InterfaceAlias $mgmt -AddressFamily IPv4 + +# 3. Set the correct servers (replace with YOUR deployment's documented management DNS servers) +Set-DnsClientServerAddress -InterfaceAlias $mgmt -ServerAddresses '','' + +# 4. Confirm external resolution now works on this node +Resolve-DnsName -Name management.azure.com -Type A +``` + +If that does not resolve it (the server is correct but internal-only, a forwarder is +missing, a firewall blocks port 53, or a proxy is in use), work the full decision tree in +[Remediation](#remediation), then re-run the validator as shown in +[Verify the fix](#verify-the-fix). + ## Requirements - Administrative (local administrator) access to each Azure Local node, or a remote @@ -115,6 +156,33 @@ same record is written to `AzStackHciEnvironmentChecker` as Event ID 17205; filt and read `AdditionalData.Detail`. In the Azure portal, open the Azure Local cluster then the **Updates** tab; a failing pre-update health check names the failing validator there. +### Where it appears across the admin surfaces + +This is an Environment Validator (pre-update health check) result, so it surfaces on some +admin tools and deliberately does **not** on others. Knowing which is which stops you from +hunting in the wrong place: + +- **PowerShell on an Azure Local node** (shown): the queries in this section + (`Get-DnsClientServerAddress`, `Resolve-DnsName -Server`, and the per-node fan-out below) + reproduce and localize the failure. +- **Windows event logs** (shown): the `AzStackHciEnvironmentChecker` channel writes the same + record as **Event ID 17205**, with the failing `Name` and `AdditionalData.Detail`. +- **Azure portal** (shown): the Azure Local cluster **Updates** tab flags the failing + validator on a pre-update health check. +- **Component / tool log files (on disk)** (shown): the cluster-wide + `HealthCheckResult.EnvironmentChecker.*.json` on the infrastructure share, and the + `%USERPROFILE%\.AzStackHci\AzStackHciEnvironmentChecker.log` on the node that ran the + check, both record the result. +- **Cluster logs (`Get-ClusterLog`)** (not evident): this DNS readiness failure is **not** + written to the failover-cluster log, so do not look there. +- **Windows Failover Cluster Manager** (not evident): it does **not** show up as a failed + cluster role, resource, or node. The cluster stays healthy; this is a readiness check, not + a clustering fault. +- **Windows Admin Center (standalone host)** (not evident): WAC does **not** surface the + Environment Validator result; use the portal **Updates** tab or the result JSON above. +- **Windows Admin Center in the Azure portal** (not evident): the readiness failure appears + through the cluster **Updates** tab (above), **not** in the WAC-in-portal node view. + ### What it looks like: example failure signature The dedicated validator lists each failing node as its own bullet and adds an From b0b170e37da102bc99231b35166fe5dac2d956ea Mon Sep 17 00:00:00 2001 From: John Neemes Date: Wed, 15 Jul 2026 10:22:55 -0400 Subject: [PATCH 2/3] Address PR review: scope quick-fix to deployment-time, safe adapter select, per-server verify, template table - Quick fix now distinguishes deployment/add-node (node DNS-client change OK) from an already-deployed cluster, where changing DNS servers is UNSUPPORTED post-deployment; deployed clusters are directed to the supported upstream DNS/forwarder fix. - Management adapter is selected by the node's known management IP and fails closed unless exactly one up adapter owns it (multihomed nodes: no enumeration-order guessing). - Verify step now queries every configured server with -Server, matching the validator, so a working default resolver cannot mask a still-failing server. - Metadata block converted to the Troubleshoot-Template HTML table with Applicable Scenarios and Affected Versions. --- ...bleshooting-DNS-External-DNS-Resolution.md | 85 ++++++++++++++----- 1 file changed, 63 insertions(+), 22 deletions(-) diff --git a/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md b/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md index 10d620ef..7365847b 100644 --- a/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md +++ b/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md @@ -1,11 +1,31 @@ # AzStackHci_DNS_ExternalDnsResolution -| | | -|---|---| -| **Name** | `AzStackHci_DNS_ExternalDnsResolution` | -| **Validator / test** | `Invoke-AzStackHciDNSValidation -Include Test-ExternalDnsResolution` | -| **Component** | Environment Validator (DNS) | -| **Severity** | Critical | + + + + + + + + + + + + + + + + + + + + + + + + + +
NameAzStackHci_DNS_ExternalDnsResolution
Validator / testInvoke-AzStackHciDNSValidation -Include Test-ExternalDnsResolution
ComponentEnvironment Validator (DNS)
SeverityCritical
Applicable ScenariosDeployment, AddNode, Update (pre-update health check)
Affected VersionsAll versions
> **At a glance** > - **Owner:** the customer's network or DNS administrator. This is not a Microsoft software defect and not an OEM hardware or firmware issue. @@ -64,31 +84,52 @@ intended DNS rather than a stale value carried over from imaging. ## Quick fix (start here) -If external DNS resolution is failing and you already have the cluster's intended DNS -server addresses (from your deployment's management-network configuration), this resolves -the most common case: a node pointed at a DNS server that cannot resolve external names. +First decide which situation you are in, because the **supported** fix differs: + +- **Deploying, or adding a node (the node is not yet a deployed cluster member):** you may + re-point that node's management-adapter DNS client at DNS servers that resolve external + names (steps below). +- **An already-deployed cluster (this failed at a pre-update health check):** do **not** + change the node's DNS client. **Azure Local does not support modifying DNS server settings + post-deployment** (see + [Test-ManagementAdapterReadiness](./Networking/Troubleshoot-Network-Test-ManagementAdapterReadiness.md)). + Fix it **upstream** instead: make the currently-configured DNS server resolve external + names (add a forwarder or conditional forwarder, or otherwise unblock external resolution), + as in [Remediation](#remediation) step 3, second option. Then re-run the validator per + [Verify the fix](#verify-the-fix). > **Do not guess DNS server IP addresses.** If you do not have the cluster's correct DNS -> servers, stop here and use the full decision tree under [Remediation](#remediation) after -> identifying the failing server. Guessing can break name resolution for the whole node. +> servers, use the full decision tree under [Remediation](#remediation) after identifying the +> failing server. Guessing can break name resolution for the whole node. -On each affected node, identify the management adapter and re-point it at DNS servers that -resolve external names (per node, applies immediately, no reboot, reversible): +**Deployment-time only** (do not run on a deployed cluster): re-point the management +adapter's DNS client (per node, applies immediately, no reboot, reversible): ```powershell -# 1. Identify the management adapter (the up adapter holding the node's management IP) -$mgmt = (Get-NetIPConfiguration | Where-Object { $_.IPv4Address -and $_.NetAdapter.Status -eq 'Up' } | - Select-Object -First 1).InterfaceAlias -"Management adapter: $mgmt" +# 1. Identify the management adapter by the node's KNOWN management IP (from your deployment +# config). Azure Local nodes are multihomed, so never pick by enumeration order -- fail +# closed unless exactly one up adapter owns that IP. +$ManagementIp = '' +$mgmt = @(Get-NetIPConfiguration | Where-Object { + $_.NetAdapter.Status -eq 'Up' -and ($_.IPv4Address.IPAddress -contains $ManagementIp) }) +if ($mgmt.Count -ne 1) { + throw "Expected exactly one up adapter owning $ManagementIp; found $($mgmt.Count). Confirm the management IP and adapter first -- do not proceed." +} +$mgmtAlias = $mgmt[0].InterfaceAlias +"Management adapter: $mgmtAlias" # 2. Record the current DNS servers FIRST so the change can be rolled back -Get-DnsClientServerAddress -InterfaceAlias $mgmt -AddressFamily IPv4 +Get-DnsClientServerAddress -InterfaceAlias $mgmtAlias -AddressFamily IPv4 -# 3. Set the correct servers (replace with YOUR deployment's documented management DNS servers) -Set-DnsClientServerAddress -InterfaceAlias $mgmt -ServerAddresses '','' +# 3. Set the correct servers (your deployment's documented management DNS servers) +Set-DnsClientServerAddress -InterfaceAlias $mgmtAlias -ServerAddresses '','' -# 4. Confirm external resolution now works on this node -Resolve-DnsName -Name management.azure.com -Type A +# 4. Verify EVERY configured server resolves the external name, the way the validator does +# (a working default resolver can hide another configured server that still returns none) +foreach ($dns in ((Get-DnsClientServerAddress -InterfaceAlias $mgmtAlias -AddressFamily IPv4).ServerAddresses | Sort-Object -Unique)) { + $count = (Resolve-DnsName -Name management.azure.com -Server $dns -Type A -DnsOnly -QuickTimeout -ErrorAction SilentlyContinue).Count + '{0}: {1} A record(s)' -f $dns, ([int]$count) +} ``` If that does not resolve it (the server is correct but internal-only, a forwarder is From 66403221eee01b265bef6ed6c6f33601c8f8d25e Mon Sep 17 00:00:00 2001 From: 1008covingtonlane <42551186+1008covingtonlane@users.noreply.github.com> Date: Wed, 19 Aug 2026 08:11:02 -0400 Subject: [PATCH 3/3] Reconcile Remediation with the post-deployment support boundary (fix self-contradiction) The Quick fix section correctly states that on an already-deployed cluster the node DNS client must not be changed (unsupported post-deployment) and routes the fix upstream to a forwarder. The Remediation section still framed re-pointing the node DNS client as the [LOW RISK] 'Most common fix (start here)' with no such caveat, so a deployed-cluster operator reading Remediation was routed to the forbidden action. Reconciled all three spots (intro paragraph, step 3 first option, and the risk-label closing) to mirror the Quick fix support boundary: re-point node DNS only at deployment / add-node time; on a deployed cluster use the upstream DNS server / forwarder change. --- ...bleshooting-DNS-External-DNS-Resolution.md | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md b/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md index 7365847b..2fb2e0cb 100644 --- a/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md +++ b/TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md @@ -294,10 +294,14 @@ including a per-node fan-out to find every affected node and an option-by-option tree for the fix. **Most common fix (start here).** The usual cause is a node pointed at a DNS server that -cannot resolve external names. Re-point that node's management adapter at a DNS server -that can (step 3, first option), or add an external-resolving forwarder on the current -server (step 3, second option). The numbered steps confirm which applies; most failures -are resolved by one of those two. +cannot resolve external names, and the **supported** fix depends on whether the cluster is +already deployed (see [Quick fix](#quick-fix-start-here)). On an **already-deployed** +cluster, do **not** re-point the node's DNS client (unsupported post-deployment); make the +currently-configured server resolve the external name by adding an external-resolving +forwarder (step 3, second option). Only when **deploying or adding a node** may you +re-point that node's management adapter at a DNS server that can resolve (step 3, first +option). The numbered steps confirm which server is failing; fix it the way that matches +your situation. _New to any DNS term used here (A record, forwarder, split-horizon, WinHTTP proxy)? See the [Glossary](#glossary) at the end of this guide._ @@ -325,8 +329,10 @@ the [Glossary](#glossary) at the end of this guide._ 3. Fix the failing DNS server, choosing the option that matches the environment: - - If the configured server is wrong or stale, re-point the node's management adapter - at a DNS server that can resolve external names. First identify the management + - If the configured server is wrong or stale, and the node is **not yet a deployed + cluster member** (deploying or adding a node), re-point the node's management adapter + at a DNS server that can resolve external names. On an already-deployed cluster this + is unsupported; use the forwarder option below instead. First identify the management adapter (the up adapter whose IPv4 address is the node's management IP), so the `` placeholder is concrete: @@ -357,10 +363,11 @@ the [Glossary](#glossary) at the end of this guide._ present, this check self-skips and reports success. Only do this if a proxy is genuinely part of the design. -Re-pointing a node's DNS client is a [LOW RISK] change: it is per-node, immediate, and -reversible by restoring the previous servers. Changing an upstream DNS server is a -[MEDIUM RISK] change, because it can affect other systems that use it, so coordinate with -its owner. No node drain or reboot is required for DNS-client changes. +Re-pointing a node's DNS client (deployment or add-node time only) is a [LOW RISK] change: +it is per-node, immediate, and reversible by restoring the previous servers. On an +already-deployed cluster that path is unsupported, so the fix is the upstream DNS server or +forwarder change, a [MEDIUM RISK] change because it can affect other systems that use it, +so coordinate with its owner. No node drain or reboot is required for DNS-client changes. ## Verify the fix