Add Environment Validator TSG: AzStackHci_Software_IsNotPartofDomain (Domain Membership)

[1008covingtonlane]

What this adds

A public remediation TSG for the pre-deployment Environment Validator check AzStackHci_Software_IsNotPartofDomain (display name Domain Membership), plus its entry in the EnvironmentValidator README.

The check fails when a machine is already joined to an Active Directory domain before deployment. Azure Local requires each machine to start in a workgroup, and the deployment process joins it to the domain itself. There was no public remediation guide for this validator.

What the TSG covers

• Where the failure appears: the deployment Validation step in the portal, the targeted validator Invoke-AzStackHciSoftwareValidation -Include Test-IsNotPartofDomain, and the on-machine Event ID 17205, with the exact failure detail line.
• Remediation: unjoin the machine with Remove-Computer -UnjoinDomainCredential and restart, then re-validate. This is the remediation the validator itself recommends.
• Verification: re-run the single validator and confirm SUCCESS.

Accuracy and validation

• The check name, display name, severity, description, the failure and success detail strings, and the remediation text are taken from the validator source, not paraphrased.
• The guidance was validated end to end on a live lab cluster (Tier 1): baseline workgroup, inject a domain join, confirm the real check reports FAILURE with the production signature, run the documented unjoin and restart, and confirm the check returns to SUCCESS.
• Single validator only, no internal or telemetry content in the public guide.

Tracked by ADO 38564291. Follows the same structure as the System Drive Free Space TSG (#302).

[Copilot]

Pull request overview

This PR adds a new public troubleshooting guide (TSG) for the Environment Validator check AzStackHci_Software_IsNotPartofDomain (“Domain Membership”) and indexes it in the EnvironmentValidator README, improving self-service remediation for pre-deployment failures caused by nodes being domain-joined.

Changes:

• Adds Troubleshooting-Software-IsNotPartofDomain.md documenting symptom location, remediation (unjoin + reboot), and re-validation steps.
• Updates TSG/EnvironmentValidator/README.md to include the new TSG in the list.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
TSG/EnvironmentValidator/Troubleshooting-Software-IsNotPartofDomain.md	New TSG for the “Domain Membership” validator failure, including remediation and verification steps.
TSG/EnvironmentValidator/README.md	Adds an index entry pointing to the new TSG.

[1008covingtonlane]

Addressed the review feedback (commit b598478):

1. [MEDIUM] Local-admin lockout — added a new pre-unjoin step (now step 2) that confirms the built-in local Administrator is enabled with a known password (Get-LocalUser / Enable-LocalUser / Set-LocalUser, plus Get-LocalGroupMember) before Remove-Computer + restart, so an operator is not locked out of a previously domain-joined machine.
2. [LOW / verify] "excluded from the default Software run" — confirmed against the validator source that a bare Invoke-AzStackHciSoftwareValidation runs all checks (including Test-IsNotPartofDomain). The exclude is applied only by the deployment orchestrator (Test-AzStackHciSoftware) and is conditional. Reworded the instruction to "-Include runs only this check" and dropped the inaccurate claim.
3. [NIT] README — link now reads "Troubleshooting Domain Membership (Software IsNotPartofDomain)".
4. [NIT] reboot — remediation now uses Restart-Computer -Force.
5. [OPTIONAL] Related — added the canonical Learn deployment-local-identity link.

Merge note: findings 1 and 4 change on-box commands, so per our embedded-test standard the live VM-cluster loop will be re-run (the -Force reboot plus the new local-admin pre-check) and LastValidated refreshed before merge.

[1008covingtonlane]

Re-validation complete: the domain-membership loop re-validated Grade A on a live masonenode VM cluster (Azure Local build 2607) on 2026-06-25.

• baseline: throwaway workgroup node, validator SUCCESS
• inject (domain join): the real Environment Validator reported the exact documented FAILURE, '<NODE>' is part of a domain. Please remove '<NODE>' from the domain.
• mitigate (the TSG's own Remove-Computer -UnjoinDomainCredential + a forced restart): the node returned to a workgroup (PartOfDomain = False)
• revalidate: validator SUCCESS (1 of 1)
• teardown: throwaway node destroyed

This re-exercises the two material changes from the review mitigations: the Restart-Computer -Force reboot is covered by the loop's forced restart, and the new local-admin pre-check (finding #1) documents the precondition the harness itself relies on, it reaches the node as the local administrator for the detect, unjoin, and revalidate steps. The re-validation merge gate is therefore cleared.

LastValidated: 2026-06-25, build 2607 (recorded in the internal companion, not the public TSG).

[1008covingtonlane]

Re-reviewed at 79d4026 (unchanged since the last pass). Still clean: the three customer-understandability items from the earlier review are in place (the expected credential/confirm prompts in the unjoin step, the machine/node equivalence note, and the consistent AzL-Node-01 example), the structure matches the sibling EnvironmentValidator TSGs, and there is no internal or PII content. No new findings. Ready for maintainer review.

[AlBurns-MSFT]

Independent validation — verified accurate

I independently validated this TSG against the validator behavior and on a live lab cluster node. It's accurate and the remediation is correct.

Confirmed:

• Check name AzStackHci_Software_IsNotPartofDomain, display name Domain Membership, severity Critical.
• On a domain-joined node, Invoke-AzStackHciSoftwareValidation -Include Test-IsNotPartofDomain -PassThru returns AzStackHci_Software_IsNotPartofDomain / FAILURE / Critical with the exact detail string the doc quotes ('<NODE>' is part of a domain. Please remove '<NODE>' from the domain.); a workgroup node returns the documented success string.
• The remediation (Remove-Computer -UnjoinDomainCredential ... -Force + restart) matches the validator's own recommended remediation text.
• The Event ID 17205 / AzStackHciEnvironmentChecker log read is correct.

Minor (non-blocking): Remove-Computer is Windows PowerShell 5.1 only (removed in PowerShell 7+) — correct for the node context here; just noting in case the snippet is ever modernized.

Thanks for closing this gap.

[1008covingtonlane]

@AlBurns-MSFT thank you for the independent validation, especially confirming the check name, the exact FAILURE detail string, the Remove-Computer remediation, and the EventID 17205 / AzStackHciEnvironmentChecker read against a live node. That is exactly the on-box confirmation this TSG needed.

One small process note: your validation came through as a Comment review rather than an Approve, so GitHub still reports the PR as REVIEW_REQUIRED and branch protection is blocking the merge. When you have a moment, could you click Approve (Files changed > Review changes > Approve)? That formal approval is the only thing left before this can merge; everything else is green and the re-validation gate is cleared. Thanks again.