Skip to main content

Task 05: Deployment Documentation

Implementation Part 7

DOCUMENT CATEGORY: Implementation Runbook
SCOPE: One deployed Azure Local instance
PURPOSE: Write the documentation package the customer receives
MASTER REFERENCE: Azure Local documentation

Status: Active

The script collects, read only, the instance as the file describes it (customer, cluster name, tenant, subscription, resource group, region) and the cluster as it is now (nodes and quorum, cluster networks and virtual switches, storage pools, virtual disks and volumes, the Arc agent). It writes a Markdown page (overview, network, storage, Azure integration, a Mermaid architecture diagram, operational procedures) and a JSON file with the same data. A part the cluster cannot report is left out with a warning; the page is written anyway. It changes nothing on the cluster or in Azure.


Values from infrastructure.yml​

The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.

KeyWhat the script does with it
cluster.name, site.customerRequired. The cluster to read and the customer the package is for. Both name the output files
azure.tenant_id, azure.subscription_id, azure.resource_group, azure.locationWhere the instance is in Azure (written in the Azure integration section)
every secret reference of the fileWith -IncludeCredentialLocations only: the reference and the key it is under, never a value

Execution Options​

PowerShell​

ScriptWhat it does
scripts/deploy/07-validation-handover/task-05-deployment-documentation/powershell/New-DeploymentDocumentation.ps1Collects the cluster and writes <customer>-<cluster>-Documentation.md and -Config.json in -OutputPath. -WhatIf collects and writes no file
ParameterMeaning
-InfrastructureFileThe infrastructure.yml (schema 5). Required
-OutputPathThe folder for the package (created when it does not exist). Required
-IncludeCredentialLocationsAlso list where the secrets are kept (references only)
-LogPathAlso append the progress lines to this file
./New-DeploymentDocumentation.ps1 -InfrastructureFile ./infrastructure.yml -OutputPath ./handover

Exit codes: 0 the documentation is written (or planned under -WhatIf), 1 the files could not be written, 2 cluster.name or site.customer is missing, or the file cannot be read.

Put the output of tasks 01 to 04 and of Part 6 in the same folder: the toolkit has no script that merges the validation reports.


Validation​

  • The Markdown page and the JSON file are in the output folder
  • The page lists every node, the storage and the networks you expect, and holds no secret value

Troubleshooting​

IssueCauseResolution
site.customer is missingThe key is emptySet site.customer
A section is left out with a warningThe cluster could not report that partRun from a machine that reaches the cluster with PowerShell remoting

PreviousUpNext
Task 04: Storage PerformancePart 7 IndexTask 06: Customer Transfer

Version Control​

VersionDateAuthorChanges
1.0.02026-11-15Azure Local CloudInitial release (the script moved here from the old handover folder of the toolkit)