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

[John Neemes (1008covingtonlane)]

Summary

Documentation-completeness improvements to TSG/EnvironmentValidator/Troubleshooting-DNS-External-DNS-Resolution.md. No change to the diagnosis or remediation logic — this makes the common fix faster to reach and rounds out where the failure is (and is not) visible.

Changes

1. Quick fix (start here) block near the top: auto-identifies the management adapter and gives the exact, reversible Set-DnsClientServerAddress command for the ~90% case (a node pointed at a DNS server that cannot resolve external names), gated by a bold "do not guess DNS server IP addresses" so a literal follower stays safe. Readers who need the full decision tree are pointed to Remediation.
2. Where it appears across the admin surfaces: a new subsection that explicitly covers all eight admin surfaces — node PowerShell, Windows event logs, the Azure portal Updates tab, and the on-disk HealthCheckResult JSON are shown; Get-ClusterLog, Failover Cluster Manager, and Windows Admin Center (standalone and in-portal) are called out as not evident, so admins do not hunt in the wrong tool.
3. Validator metadata table under the H1 (Name / Validator-test / Component / Severity) naming Invoke-AzStackHciDNSValidation -Include Test-ExternalDnsResolution.

Why

• The most common resolution was buried under the discovery queries; surfacing it (safely gated) cuts time-to-fix for the typical case.
• Stating the not-evident surfaces is as useful as the shown ones — it tells an admin where not to look.
• The metadata table matches the Environment Validator TSG template.

Testing

• Markdown renders cleanly; all relative links and in-page anchors resolve.
• Reviewed for reader safety: the quick-fix records current DNS servers before changing them and is gated on having the correct addresses.

[Copilot]

Pull request overview

Expands the external DNS resolution TSG to improve remediation speed and failure discoverability.

Changes:

• Adds validator metadata.
• Introduces a quick-fix PowerShell workflow.
• Documents visibility across eight administrative surfaces.

[T.J. Hambley (tihamble)]

I checked the new content against the product source and the Azure Local docs, and ran the lint. On the facts it holds up. The identifiers are all real: Invoke-AzStackHciDNSValidation -Include Test-ExternalDnsResolution, both result names (AzStackHci_DNS_ExternalDnsResolution and AzStackHci_DNS_Test_External_Hostname_Resolution), Event ID 17205, the %USERPROFILE%\.AzStackHci\AzStackHciEnvironmentChecker.log path, and the verify cmdlets all match. Both relative links resolve and the #remediation and #verify-the-fix anchors are good. The Quick fix PowerShell parses cleanly, and its safety design is sound: it fails closed unless exactly one up adapter owns the management IP, records the current DNS servers before changing anything, and is marked deployment-time only. The statement that changing DNS after deployment is not supported matches the docs.

One consistency issue is worth fixing before merge. The new Quick fix correctly tells a deployed-cluster operator not to re-point the node's DNS client (unsupported post-deployment) and sends them to the upstream forwarder fix. The existing Remediation section still says the opposite: "Most common fix (start here)" routes to step 3 first option, which re-points the DNS client with no deployment caveat, and the closing line calls re-pointing a [LOW RISK] change with no qualification. The Overview says the deployed pre-update case is the one you will most often hit, so the most common reader is being pointed at the action the Quick fix says is unsupported and can break name resolution for the whole node, and it is labeled [LOW RISK]. Scope that pre-existing re-point option, the [LOW RISK] closing line, and the "At a glance" DNS-client-fix framing to deployment and add-node only, matching the Quick fix, and lead the deployed case to the forwarder option. [HIGH RISK]

(The lint flags a PowerShell parse error on the $ManagementIp line; that is a false positive from how the linter substitutes the <...> placeholder inside a quoted string, the block parses fine as written.)