DNS External Resolution TSG: quick-fix, full admin-surface discoverability, validator table

TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md

@@ -1,5 +1,32 @@
 # AzStackHci_DNS_ExternalDnsResolution
 
+<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse; margin-bottom:1em;">
+  <tr>
+    <th style="text-align:left; width: 180px;">Name</th>
+    <td><strong>AzStackHci_DNS_ExternalDnsResolution</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Validator / test</th>
+    <td><strong>Invoke-AzStackHciDNSValidation -Include Test-ExternalDnsResolution</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Component</th>
+    <td><strong>Environment Validator (DNS)</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Severity</th>
+    <td><strong>Critical</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Applicable Scenarios</th>
+    <td><strong>Deployment, AddNode, Update (pre-update health check)</strong></td>
+  </tr>
+  <tr>
+    <th style="text-align:left;">Affected Versions</th>
+    <td><strong>All versions</strong></td>
+  </tr>
+</table>
+
 > **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 +82,61 @@ 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)
+
+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, use the full decision tree under [Remediation](#remediation) after identifying the
+> failing server. Guessing can break name resolution for the whole node.
+
+**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 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 = '<node-management-ipv4>'
+$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 $mgmtAlias -AddressFamily IPv4
+
+# 3. Set the correct servers (your deployment's documented management DNS servers)
+Set-DnsClientServerAddress -InterfaceAlias $mgmtAlias -ServerAddresses '<dns1>','<dns2>'
+
+# 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
+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 +197,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
@@ -185,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._
@@ -216,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
      `<ManagementAdapter>` placeholder is concrete:
 
@@ -248,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