Add Deployment TSG: clean up an existing Azure Local deployment before redeployment

[AlBurns-MSFT]

What

Adds a Deployment TSG documenting how to clean up an existing Azure Local (23H2+) deployment before redeployment: delete the Azure resources a deployment creates in a dependency-safe order (workload resources, then the Arc resource bridge, then the custom location, then the infrastructure resources), then reimage and redeploy.

This is a thinly documented procedure. The official Decommission Azure Local doc lists the resources to remove but not the deletion order, the cross-resource-group dependency check, or the CLI, verification, and troubleshooting steps this guide adds.

Files

• TSG/Deployment/HowTo-Deployment-CleanUpBeforeRedeployment.md — new TSG
• TSG/Deployment/README.md — registers the TSG in the Deployment index

Validation

Every claim was checked against Microsoft Learn, the Azure CLI reference, and the product docs; the on-cluster behaviors were confirmed against a live deployed Azure Local cluster.

• Deletion order (Arc resource bridge, then custom location) is the documented Azure Local order: "The custom location should only be deleted after the Arc resource bridge has been deleted" (What is Azure Local VM management?, Components).
• CLI commands verified against the current reference: az arcappliance delete hci --config-file, az customlocation delete, az keyvault purge, the az stack-hci-vm delete subgroups, and the az stack-hci-vm nic (attach/detach) vs az stack-hci-vm network nic (resource) distinction.
• VM deletion side effects corrected to match the docs: deleting an Azure Local VM does not remove its network interfaces or data disks — those are deleted separately.
• Resource inventory matches Decommission Azure Local.
• Appliance-VM naming (*-control-plane-*) confirmed live: Get-VM on a deployed cluster returns a <GUID>-control-plane-0-<GUID> VM.

[Copilot]

Pull request overview

This PR adds a new Deployment How-To guide documenting how to clean up an existing Azure Local (23H2+) deployment before redeployment. It fills a gap in the official Decommission Azure Local documentation by prescribing a dependency-safe deletion order (workload resources → Arc resource bridge → custom location → infrastructure/registration resources), a cross-resource-group dependency checkpoint, CLI equivalents, verification, and troubleshooting. The guide follows the repository's HowTo-Template.md structure and is registered in the Deployment component index.

Changes:

• Adds HowTo-Deployment-CleanUpBeforeRedeployment.md, a step-by-step TSG covering resource inventory, lock removal, ordered deletion, reimaging, verification, and troubleshooting.
• Registers the new guide in TSG/Deployment/README.md.

Reviewed changes

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

File	Description
TSG/Deployment/HowTo-Deployment-CleanUpBeforeRedeployment.md	New How-To guide detailing the dependency-safe cleanup procedure for redeploying Azure Local; follows the repo How-To template with valid TOC anchors, internal/external links, and CLI examples.
TSG/Deployment/README.md	Adds an index entry linking to the new guide, consistent with existing entries.

I reviewed the template compliance, naming convention, README index entry, internal link (../ArcVMs/arc-vm-deletion.md exists), TOC anchor accuracy, external links (no version references), and CLI command accuracy. No blocking issues were found. Note that the guide documents destructive and irreversible Azure operations (deleting the Arc resource bridge, custom location, key vaults, and resource groups; purging soft-deleted vaults), so final technical validation against current Azure behavior is best confirmed by a human reviewer.

[aldawson33]

The depth of this TSG does a great job of supplementing the 'official' procedure.

[1008covingtonlane]

TSG grader results, clean up a deployment before redeployment

I ran this through our TSG grader (static structure/safety lint plus a 13-reader persona usability panel). Strong, careful How-To: static lint B, usability 4.0/5. This is a procedural teardown, so there is no live inject/detect/mitigate loop to run; the feedback is doc usability plus one lint note.

Lint note (both warnings are doc-type artifacts, no action needed). The lint flagged "no symptoms section" and "no verify-the-fix step." The first does not apply to a How-To (there is no failure to symptomatize), and the guide does have a ## Verification section (the heuristic only matches the literal phrase "verify the fix"). All relative links resolve, so structurally it is sound.

Usability work items (highest-leverage first).

• Add a top-of-document at-a-glance box (owner, downtime, irreversibility, rough time-to-complete) and lead with the most common scenario (failed deploy, then redeploy on the same hardware). (3 reviewers asked for this.)
• Add a glossary (custom location, Arc resource bridge, extendedLocation, soft-delete and purge) for less-experienced operators.
• Give the exact az delete commands per resource type in Step 3 as a copy-paste block, rather than describing the command groups in prose.
• Add a one-line owner/scope note at the top so a mis-assigned reader routes on quickly.
• Add a reminder to export or back up workload data before deletion, since the procedure is irreversible.
• Cross-link the exact reimage / OS-install steps for the hardware in Step 6.

Nice touches already: the inside-out deletion order with the zero-rows Resource Graph checkpoint, the az arcappliance delete hci versus portal-delete distinction, and the Key Vault purge-to-reuse-the-name note are exactly the gotchas that bite people.

[1008covingtonlane]

Ran the 13-reader usability panel on this one: 4.0/5, a strong How-To. The dependency-safe inside-out deletion order, the zero-rows extendedLocation Resource Graph checkpoint, the az arcappliance delete hci versus portal-delete distinction, and the Key Vault purge-to-reuse-the-name note all landed well with the panel.

Five reader-driven items would take it to 5/5:

1. Turn the Step 3 workload deletes from prose into an exact copy-paste az block, one command per resource type (az stack-hci-vm delete, image, network nic, disk, network nsg, storagepath, network lnet), matching the concrete style Step 4 already uses. This was the single most-requested item (five readers).
2. A short glossary: custom location, Arc resource bridge, extendedLocation, soft-delete versus purge. (3 readers)
3. A top-of-doc at-a-glance box: owner, downtime, irreversibility, rough time to complete. (2 readers)
4. A reminder to back up or export workload data before the irreversible delete steps.
5. Cross-link Step 6 to the exact reimage / OS-install procedure.

Optional polish from a reader already at 5: list the node-side EventIDs / logs to capture if a delete hangs. No correctness issues, this is all usability.

[AlBurns-MSFT]

Pushed a commit addressing the usability feedback:

• Step 3 — exact az block: replaced the prose CLI description with a copy-paste az stack-hci-vm delete block, one command per resource type (delete, image delete, network nic delete, disk delete, network nsg delete, storagepath delete, network lnet delete) in the inside-out deletion order. Commands verified against the current Azure CLI reference.
• Glossary: Arc resource bridge, custom location, extendedLocation, soft-delete vs. purge (also added to the TOC).
• At-a-glance box: added header-table rows for who runs it, reversibility, impact/downtime, and estimated time.
• Back-up reminder: a warning to export/back up workload data before the Step 3 deletes.
• Step 6 cross-link: links the "Install the Azure Local operating system" doc for the reimage step.

I left out the optional "node-side EventIDs if a delete hangs" idea — I didn't have verified EventIDs and didn't want to publish unverified identifiers.

[Karl-WE]

I would like to add that the installation also creates a number of permission which then sprawl, especially seen on testing subscriptions.

Often these result into objects that cannot be resolved by Entra similar to unresolved SIDs in AD.

Personally I would appreciate a full script provided by Microsoft, at best as text for copy paste to az cli.
Either this could be done similar to Azure Migrate appliance, or Azure Portal linking to this TSG which also adds to the point making TSG more prominently known.

I am aware Portal changes often take a long time to come to prod for good reasons, so an aka.ms link in Port to TSG would be my preference.
Adding a button wipe and redeploy.

Risk: sometimes customers may use the witness storage account for multiple things.
Also Azure backup is not simply untied, as well as monitoring / Az Local insights.

Please check if the intention of cleanup is as thorough as intended.

[AlBurns-MSFT]

Addressed the review in the latest push. What was added, for the objects a resource-group delete leaves behind:

• Orphaned identities (Step 5c): find and remove role assignments left as "Identity not found (Unknown)" after a deployment principal is deleted, confirming each principal is actually gone first (an empty principalName can just mean no directory-read), and leaving the Microsoft first-party resource-provider principals alone.
• Witness storage (Step 5): confirm the cloud witness account is dedicated before deleting it; quorum-loss risk called out for a running two-node system.
• Monitoring / Insights (Step 5b): remove the DCRs, DCEs, alert rules, and Log Analytics workspace that survive the machine delete (often in a separate resource group).
• Azure Backup (Step 5b): the Recovery Services vault will not delete while backup items exist (including soft-deleted), and --delete-backup-data is irreversible.
• On-prem AD (Step 5d): remove the deployment OU (CNO, node accounts, CAU object, users), clearing accidental-deletion protection across the whole subtree before the recursive delete, and export BitLocker recovery keys first.
• Prerequisites: noted that Contributor alone cannot remove locks or role assignments, plus the directory-read and AD module requirements.

Commands are provided per step and marked to validate in-environment first; I did not exercise a full teardown end to end.

The portal wipe-and-redeploy button is a product ask rather than a doc change, so it is out of scope for this TSG.