Add Environment Validator TSG: Azure_Kubernetes_Service_Cluster_connect - #330
Open
John Neemes (1008covingtonlane) wants to merge 5 commits into
Open
Add Environment Validator TSG: Azure_Kubernetes_Service_Cluster_connect#330John Neemes (1008covingtonlane) wants to merge 5 commits into
John Neemes (1008covingtonlane) wants to merge 5 commits into
Conversation
New public remediation TSG for the Connectivity validator's 'Cluster connect' target (ADO 38357506). The check probes outbound HTTPS reachability from each node to the Azure Arc cluster-connect Service Bus relay azgnrelay-<region>-l1.servicebus.windows.net:443 (used to reach AKS enabled by Azure Arc without inbound ports). Documents the four real failure sub-modes harvested from fleet telemetry (EnvironmentValidatorResult), branched by the 'Layer 3 (tnc)' discriminator: DNS resolution (tnc False), firewall/outbound-443 blocked (tnc False), proxy/app-layer (tnc True), and TLS inspection (tnc True). Includes the standalone Invoke-AzStackHciConnectivityValidation repro, the .AzStackHci component log/FailedUrls.txt pointer, the multi-surface 'where this does NOT appear' note, per-sub-mode remediation with risk labels, and a verify step. Lint grade A; admin discoverability surfaces 8/8 (gate met). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1d7f2348-e3be-4fe4-8598-6bf5dcb4050f
…ve surface Add an honest note in step 1: this connectivity target is validated as part of the pre-update / deployment readiness run and may not appear in every ad-hoc standalone Invoke-AzStackHciConnectivityValidation run on newer builds (the target set is versioned), so the authoritative confirmation for this check is the pre-update health-check result (HealthCheckResult JSON / Event ID 17205 / portal Updates tab). Use the standalone run to test raw reachability to the relay endpoint. Discovered during tier-1 live validation on a current-build lab cluster. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1d7f2348-e3be-4fe4-8598-6bf5dcb4050f
Copilot started reviewing on behalf of
John Neemes (1008covingtonlane)
July 13, 2026 17:00
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an Environment Validator TSG for diagnosing and remediating Azure Arc cluster-connect endpoint failures.
Changes:
- Documents failure signatures across DNS, firewall, proxy, and TLS layers.
- Provides per-node diagnostics, remediation, and verification steps.
- Explains operational impact and relevant Azure surfaces.
- Discovery filter: use the specific HealthCheckResult.EnvironmentChecker.*.json pattern (the folder also holds HealthCheckResult.CheckCloudHealth.*.json, so the broad filter could pick a newer unrelated file and wrongly report no match). - Name match: use -like '*Azure_Kubernetes_Service_Cluster_connect*' instead of an exact -eq (health-check results can carry a prefix/suffix, so the exact compare could hide the failure); read the readable state from AdditionalData.Status. - Verification: Test-NetConnection cannot confirm the proxy / TLS-inspection sub-modes (those already have tnc:True while failing), so lead verification with the validator / Invoke-SolutionUpdatePrecheck (authoritative for every sub-mode) and demote Test-NetConnection to a DNS/TCP-only quick check with an explicit caveat. - Discoverability: add the guide to TSG/EnvironmentValidator/README.md index. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1d7f2348-e3be-4fe4-8598-6bf5dcb4050f
The severity cell ended with 'See the detection note.', which points to no section in the guide. Remove the dangling reference; the cell already states the per-cloud severity and effect.
… changes Applied from a tsg-forge grading run with a multi-model persona panel across two frontier model families. Both models independently flagged the remediation section as the weakest part of the guide. - Every sub-mode was labelled [LOW RISK]. Repointing a cluster node's DNS is not low risk: a node's DNS also resolves Active Directory, the cluster name, and its management endpoints. That sub-mode is now [MEDIUM RISK] when node settings are changed, and [LOW RISK] only for the recommended path of fixing the customer's DNS forwarders. - Added an explicit warning never to point a node at a public resolver such as 8.8.8.8, which was the specific failure mode the accessibility lens predicted. - Added a current-state capture before any DNS or proxy change so every change is reversible, including concrete commands for the proxy case. - Added an ownership and approval gate: DNS, firewall, proxy, and TLS-inspection policy are customer network assets outside the Azure Local support boundary. - Clarified that the firewall to change is normally the perimeter device, not the Windows firewall on the node. - Expanded NSG and TLS inspection on first use, and directed proxy mismatches to the platform owner rather than an ad hoc node edit. - Added an instruction to apply one sub-mode fix at a time.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a public remediation TSG for the Environment Validator connectivity check
Azure_Kubernetes_Service_Cluster_connect(the Azure Arc "cluster connect" target). Closes the validator-tsg-gap for this check (ADO 38357506).The check
It probes outbound HTTPS reachability from each node to the Azure Arc cluster-connect Azure Relay endpoint
azgnrelay-<region>-l1.servicebus.windows.neton TCP 443, used to reach AKS enabled by Azure Arc without opening any inbound port. Severity Warning in the public cloud (non-blocking, but the feature breaks); Critical in Azure Government.What the TSG covers
Invoke-AzStackHciConnectivityValidation+Test-NetConnection), the pre-update health-check result (HealthCheckResultJSON / Event ID 17205 / portal Updates tab), and the Environment Checker's own.AzStackHcilog /FailedUrls.txt; plus an explicit "where this does NOT appear" note (cluster logs, Failover Cluster Manager, Windows Admin Center).Test Analysis - Layer 3 (tnc)discriminator: DNS resolution, firewall/outbound-443 blocked, proxy/application-layer, and TLS inspection.*.servicebus.windows.net, fix DNS, configure the proxy, or exclude the relay from TLS inspection) with risk labels, plus per-node identification and a verify step.Validation
The check's failure/recovery mechanism was validated end-to-end on a live Azure Local lab cluster (baseline reachable -> outbound blocked -> the validator reports the documented
Unable to connect ... Layer 3 (tnc): Falsefailure -> connectivity restored -> passes again). Failure signatures were cross-checked against fleet telemetry.Six required sections present; H1 is the exact canonical validator name.