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.