refactor: narrow repo scope to ZTP automation only

[kristopherjturner]

Overview

The azurelocal-ztp repository currently includes content and guides that extend beyond the Zero-Touch Provisioning (ZTP) phase. This scope creep dilutes the repo's core value proposition and creates confusion about what this repository is for.

The repo's core purpose is to automate the ZTP phase as documented by Microsoft and Azure Local, specifically the portion that handles:

1. Server preparation (maintenance environment + voucher generation)
2. Azure portal provisioning (site setup, machine provisioning via simplified machine provisioning)
3. Provisioning status monitoring and verification

Anything beyond the point where machines show "Ready to cluster" is out of scope and belongs elsewhere.

Problem Statement

Currently, the repository includes:

• ✅ Server Preparation Guide — In scope (maintenance environment setup, voucher collection)
• ✅ Azure Portal Provisioning Guide — In scope (site creation, machine provisioning, Arc connectivity verification)
• ❌ Single-Node S2D Deployment Guide — Out of scope (post-ZTP cluster deployment and configuration)
• ❌ Automation Pipelines — Potentially out of scope (if it covers cluster automation rather than ZTP orchestration)

These out-of-scope guides assume machines are already provisioned and "Ready to cluster." They document post-ZTP activities: cluster creation, storage spaces direct configuration, networking setup, etc. This is deployment territory, not provisioning territory.

Related Documentation

Microsoft Official Documentation

• Install and Register Azure Local Machines using Simplified Machine Provisioning (preview) — The authoritative source for what ZTP covers
• Troubleshoot Simplified Machine Provisioning (preview) — Troubleshooting specific to ZTP

Azure Local Community Documentation

• Azure Local Documentation — Overall architecture and OS deployment guides (post-ZTP content lives here)

What This Issue Will Cover

Phase 1: Content Audit and Reorganization

• Audit docs/single-node-s2d-deployment.md to determine if content should be:

  • Moved to azurelocal.cloud docs (post-ZTP cluster deployment)
  • Removed entirely (redundant with Microsoft docs)
  • Rewritten to focus only on post-ZTP validation specific to ZTP-provisioned machines

• Audit docs/automation-pipelines.md to verify scope:

  • If it documents ZTP orchestration workflows (pre-provisioning): keep and enhance
  • If it documents post-provisioning cluster automation: move to azurelocal-toolkit
  • If mixed: split into ZTP-focused and post-ZTP components

Phase 2: Documentation Refocus

• Update mkdocs.yml nav structure to clearly separate:

  • ZTP phase guides (server preparation, portal provisioning)
  • Cluster deployment guides (if any remain) — marked as "next steps, not in-scope"

• Add a clear "What This Repo Is" section to README.md:

  • This repo = ZTP automation guides and BMC/Redfish orchestration for the provisioning phase
  • This repo ≠ cluster deployment, S2D configuration, or post-provisioning automation
  • Links to azurelocal-toolkit for post-ZTP scripts

• Create a "Next Steps" page that points users to:

  • Microsoft docs for cluster deployment
  • Azure Local docs for post-ZTP OS deployment
  • azurelocal-toolkit for reusable post-ZTP scripts

Phase 3: Content Removal or Relocation

• Decide on single-node-s2d-deployment.md:

  • Option A: Move to azurelocal.cloud docs as a "Lab Deployment Walkthrough"
  • Option B: Remove (pointing to Microsoft and Azure Local docs instead)
  • Option C: Rewrite to focus only on post-ZTP cluster validation

• Review automation-pipelines.md and split or move as needed

Phase 4: Validation

• README.md clearly states repo scope and links to related projects
• All mkdocs nav entries fit within ZTP phase only
• CI/CD workflows (if any) document ZTP-specific automation, not post-ZTP
• GitHub issue chore: migrate scripts and automation to azurelocal-toolkit #1 (script migration) is updated to reflect new scope

Acceptance Criteria

• Issue created and documented
• Content audit complete (determine what stays, moves, or gets removed)
• mkdocs.yml nav structure reorganized to eliminate post-ZTP guides
• README.md has clear scope statement + links to next-steps resources
• Existing guides updated to focus strictly on ZTP phase
• GitHub issue references updated to reflect new scope
• All cross-repo links point to appropriate destinations (azurelocal.cloud, azurelocal-toolkit, Microsoft docs)

Success Definition

After this refactor, the repository will be known as:

"The ZTP automation guide for Azure Local. Complements Microsoft Simplified Machine Provisioning documentation with practical, community-maintained guides for the provisioning phase: server prep, voucher collection, portal provisioning, and Arc connectivity verification. Does not cover cluster deployment—see Azure Local docs for next steps."

[kristopherjturner]

Tracked in Azure DevOps: https://dev.azure.com/hybridcloudsolutions/Azure%20Local%20ZTP/_workitems/edit/157