feat: VMFleet load testing implementation

- Add Prepare-VMFleetBaseImage.ps1 infrastructure provisioning script
- Add sequential-throughput.yml workload profile
- Add Azure Monitor workbook and KQL queries for VMFleet metrics
- Add custom_location_id and storage_path_id to config schema and example
- Add Pester tests for VMFleet scripts and base image preparation
- Add .psscriptanalyzer.psd1 settings; update PSScriptAnalyzer.ps1 to use it
- Add sample output files (aggregate, per-VM, metrics stream) in examples/
- Copy azurelocal-theme.yml to docs/themes/ (required by ReportGenerator.psm1)
- Update docs: fix my-cluster.yml references, remove phantom excel-template.xlsx
- Update prerequisites.md with azure_local config fields
- Expand CHANGELOG with VMFleet deliverables

Author: Kristopher Turner

.psscriptanalyzer.psd1

@@ -0,0 +1,58 @@
+# =============================================================================
+# PSScriptAnalyzer Settings — Azure Local Load Tools
+# =============================================================================
+# Usage: Invoke-ScriptAnalyzer -Path src/ -Settings .psscriptanalyzer.psd1
+# =============================================================================
+
+@{
+    Severity = @('Error', 'Warning')
+
+    ExcludeRules = @(
+        'PSAvoidUsingConvertToSecureStringWithPlainText'  # Demo/template code
+    )
+
+    Rules = @{
+        PSUseCompatibleSyntax = @{
+            Enable         = $true
+            TargetVersions = @('7.2')
+        }
+
+        PSPlaceOpenBrace = @{
+            Enable             = $true
+            OnSameLine         = $true
+            NewLineAfter       = $true
+            IgnoreOneLineBlock = $true
+        }
+
+        PSPlaceCloseBrace = @{
+            Enable             = $true
+            NewLineAfter       = $false
+            IgnoreOneLineBlock = $true
+            NoEmptyLineBefore  = $false
+        }
+
+        PSUseConsistentIndentation = @{
+            Enable              = $true
+            Kind                = 'space'
+            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
+            IndentationSize     = 4
+        }
+
+        PSUseConsistentWhitespace = @{
+            Enable                                  = $true
+            CheckInnerBrace                         = $true
+            CheckOpenBrace                          = $true
+            CheckOpenParen                          = $true
+            CheckOperator                           = $true
+            CheckPipe                               = $true
+            CheckPipeForRedundantWhitespace         = $false
+            CheckSeparator                          = $true
+            IgnoreAssignmentOperatorInsideHashTable  = $true
+        }
+
+        PSAlignAssignmentStatement = @{
+            Enable         = $true
+            CheckHashtable = $false
+        }
+    }
+}

CHANGELOG.md

@@ -13,6 +13,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Monitoring collectors, dashboards, and alert rules
 - Report templates for performance analysis
 
+### VMFleet
+
+- Add `Prepare-VMFleetBaseImage.ps1` — automates WS2022 Core Gen2 base image download from Azure Local marketplace
+- Add `sequential-throughput.yml` workload profile — 512K sequential writes for MB/s ceiling measurement
+- Add Azure Monitor workbook (`vmfleet-workbook.json`) with IOPS, latency P95, and throughput panels
+- Add KQL queries for Log Analytics (`vmfleet-iops.kql`, `vmfleet-latency.kql`)
+- Add `custom_location_id` and `storage_path_id` fields to config schema and example
+- Add Pester tests for VMFleet script standards compliance and base image script
+- Add PSScriptAnalyzer settings file (`.psscriptanalyzer.psd1`)
+- Expand VMFleet documentation: prerequisites, deployment, workload profiles, monitoring, reporting, troubleshooting
+
 ### Infrastructure
 
 - Add GitHub Actions workflows for docs, testing, and CI

config/profiles/vmfleet/sequential-throughput.yml

@@ -0,0 +1,23 @@
+# =============================================================================
+# VMFleet Workload Profile: Sequential Throughput
+# =============================================================================
+# Large-block sequential writes for maximum throughput (MB/s) measurement.
+# Tests the raw bandwidth ceiling of Storage Spaces Direct.
+# =============================================================================
+
+profile:
+  name: "Sequential Throughput"
+  description: "512K sequential writes for maximum storage throughput measurement"
+  category: "throughput"
+  parameters:
+    block_size: "512k"
+    write_ratio: 100
+    random_ratio: 0
+    outstanding_io: 32
+    threads_per_vm: 2
+    duration_seconds: 300
+    warmup_seconds: 60
+  expected_thresholds:
+    min_iops_per_node: 500
+    max_latency_ms: 50
+    min_throughput_mbps: 2000

config/schema/variables.schema.json

@@ -26,10 +26,12 @@
     },
     "azure_local": {
       "type": "object",
-      "required": ["cluster_name", "nodes"],
+      "required": ["cluster_name", "custom_location_id", "storage_path_id", "nodes"],
       "properties": {
         "cluster_name": { "type": "string" },
         "cluster_domain": { "type": "string" },
+        "custom_location_id": { "type": "string" },
+        "storage_path_id": { "type": "string" },
         "nodes": {
           "type": "array",
           "minItems": 1,

config/variables.example.yml

@@ -44,6 +44,8 @@ keyvault:
 azure_local:
   cluster_name: "azl-cluster-01"
   cluster_domain: "iic.local"
+  custom_location_id: "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.ExtendedLocation/customLocations/azl-cluster-01-cl"
+  storage_path_id: "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureStackHCI/storageContainers/sp-vmstore-01"
   nodes:
     - name: "azl-node-01"
       management_ip: "10.0.0.1"

docs/getting-started/prerequisites.md

@@ -56,6 +56,8 @@ Required only if using Azure Monitor integration or Azure Key Vault for credenti
 | Azure Key Vault | Provisioned Key Vault with secrets for cluster credentials |
 | Log Analytics Workspace | Provisioned workspace for Azure Monitor metric ingestion |
 | Service Principal or Managed Identity | For non-interactive Azure authentication in CI/CD |
+| Azure Local custom location | Required for marketplace image acquisition (`azure_local.custom_location_id`) |
+| Azure Local storage container | Required to resolve VHDX path (`azure_local.storage_path_id`) |
 
 ## Validating Prerequisites
 

docs/themes/azurelocal-theme.yml

@@ -0,0 +1,113 @@
+# =============================================================================
+# Azure Local Load Tools - Custom PDF Theme for asciidoctor-pdf
+# =============================================================================
+# Usage: asciidoctor-pdf -a pdf-theme=azurelocal-theme docs/main.adoc
+extends: default
+font:
+  catalog:
+    merge: true
+page:
+  margin: [0.75in, 0.75in, 1in, 0.75in]
+  size: A4
+  layout: portrait
+base:
+  font-family: Noto Sans
+  font-size: 10
+  font-color: #333333
+  line-height-length: 15
+  line-height: $base_line_height_length / $base_font_size
+heading:
+  font-color: #0078D4
+  font-style: bold
+  h1-font-size: 24
+  h2-font-size: 20
+  h3-font-size: 16
+  h4-font-size: 14
+  margin-top: 15
+  margin-bottom: 10
+title-page:
+  align: center
+  font-color: #0078D4
+  title:
+    top: 40%
+    font-size: 32
+    font-style: bold
+    font-color: #0078D4
+    line-height: 1.2
+  subtitle:
+    font-size: 18
+    font-color: #505050
+    margin-top: 10
+  authors:
+    font-size: 14
+    font-color: #505050
+    margin-top: 20
+  revision:
+    font-size: 12
+    font-color: #808080
+    margin-top: 10
+header:
+  height: 0.5in
+  font-size: 8
+  font-color: #808080
+  border-color: #DDDDDD
+  border-width: 0.5
+  recto:
+    right:
+      content: '{document-title}'
+  verso:
+    left:
+      content: '{document-title}'
+footer:
+  height: 0.5in
+  font-size: 8
+  font-color: #808080
+  border-color: #DDDDDD
+  border-width: 0.5
+  recto:
+    center:
+      content: 'Page {page-number} of {page-count}'
+    right:
+      content: '{revdate}'
+  verso:
+    center:
+      content: 'Page {page-number} of {page-count}'
+    left:
+      content: '{revdate}'
+code:
+  font-family: Noto Sans Mono
+  font-size: 9
+  background-color: #F5F5F5
+  border-color: #DDDDDD
+  border-width: 0.5
+  padding: [8, 10, 8, 10]
+table:
+  head:
+    font-color: #FFFFFF
+    background-color: #0078D4
+    font-style: bold
+  body:
+    stripe-background-color: #F0F6FF
+  border-color: #CCCCCC
+  border-width: 0.5
+admonition:
+  icon:
+    note:
+      stroke-color: #0078D4
+    tip:
+      stroke-color: #107C10
+    warning:
+      stroke-color: #FF8C00
+    caution:
+      stroke-color: #D83B01
+    important:
+      stroke-color: #A4262C
+sidebar:
+  background-color: #F0F6FF
+  border-color: #0078D4
+  border-width: 1
+toc:
+  dot-leader:
+    font-color: #CCCCCC
+  indent: 20
+  line-height: 1.8

docs/tools/vmfleet/deployment.md

@@ -5,14 +5,25 @@
 
 This guide covers installing the VMFleet module and deploying fleet VMs across your Azure Local cluster.
 
+## Phase 0: Prepare Base Image (first run only)
+
+Before deployment, prepare the base image from Azure Local marketplace (or verify it already exists):
+
+```powershell
+.\src\infrastructure\Prepare-VMFleetBaseImage.ps1 `
+    -ConfigPath "config/variables.yml" `
+    -ClusterConfigPath "config/clusters/my-cluster.yml"
+```
+
+After completion, set the resolved VHDX path in `storage.base_vhd_path` in `config/variables.yml`.
+
 ## Install VMFleet
 
 Installs the VMFleet PowerShell module and prepares the cluster:
 
 ```powershell
 .\src\solutions\vmfleet\scripts\Install-VMFleet.ps1 `
-    -ClusterConfig "config/clusters/my-cluster.yml" `
-    -CredentialSource Interactive
+    -ClusterConfigPath "config/clusters/my-cluster.yml"
 ```
 
 ## Deploy Fleet VMs
@@ -21,10 +32,10 @@ Creates fleet VMs across all cluster nodes:
 
 ```powershell
 .\src\solutions\vmfleet\scripts\Deploy-VMFleet.ps1 `
-    -ClusterConfig "config/clusters/my-cluster.yml" `
-    -VmCountPerNode 10 `
-    -VmVcpuCount 2 `
-    -VmMemoryGb 2
+    -ClusterConfigPath "config/clusters/my-cluster.yml" `
+    -VMCount 10 `
+    -VMProcessorCount 2 `
+    -VMMemoryGB 2
 ```
 
 The number of VMs, vCPUs, and memory per VM are configurable via:
@@ -41,11 +52,16 @@ To remove fleet VMs and restore the cluster to its pre-test state:
 
 ```powershell
 .\src\solutions\vmfleet\scripts\Remove-VMFleet.ps1 `
-    -ClusterConfig "config/clusters/my-cluster.yml" `
-    -CredentialSource Interactive `
+    -ClusterConfigPath "config/clusters/my-cluster.yml" `
     -Confirm
 ```
 
+## First-Time vs Subsequent Runs
+
+- First-time environment bootstrap: run Phase 0 image prep once, then Install and Deploy.
+- Subsequent test cycles: skip Phase 0 unless you want to force-refresh image download.
+- Day-2 operations: run test, monitor, collect, report, and optional cleanup.
+
 ## Next Steps
 
 - [Workload Profiles](workload-profiles.md) — Run test workloads

docs/tools/vmfleet/monitoring.md

@@ -21,6 +21,19 @@ PowerShell Get-Counter (remote sessions)
               Azure Portal dashboards, alerts
 ```
 
+## Live Console Monitoring
+
+Use the built-in watcher during active tests:
+
+```powershell
+.\src\solutions\vmfleet\scripts\Watch-VMFleetMonitor.ps1 `
+    -ClusterConfigPath "config/clusters/my-cluster.yml" `
+    -RefreshIntervalSeconds 5 `
+    -DurationMinutes 30
+```
+
+The watcher prints rolling VM count, read/write IOPS, read/write latency, and throughput.
+
 ## Metric Categories
 
 ### Storage Metrics
@@ -105,6 +118,15 @@ Optionally push collected metrics to Azure Monitor for centralized dashboards an
     -CredentialSource KeyVault
 ```
 
+Each pushed metric contains these core fields:
+
+- `timestamp`
+- `node`
+- `counter_name`
+- `value`
+- `run_id`
+- `profile_name`
+
 !!! note
     Azure Monitor integration requires the `monitoring.bicep` infrastructure template to be deployed. See `src/infrastructure/bicep/monitoring.bicep`.
 
@@ -134,6 +156,37 @@ During test execution, use the monitoring dashboard wrapper:
 ```powershell
 # Launch real-time monitoring (combines VMFleet Watch-FleetCluster with custom metrics)
 .\src\solutions\vmfleet\monitoring\Export-MetricsDashboard.ps1 `
-    -ClusterConfig "config/clusters/my-cluster.yml" `
-    -RefreshIntervalSeconds 5
+    -InputPath "results/run-001/metrics/" `
+    -OutputPath "reports/run-001/" `
+    -Title "VMFleet Run 001"
+```
+
+## Counter Reference
+
+| Category | Counter name | Purpose |
+| --- | --- | --- |
+| Storage | `CSVFS_ReadIOPS` | CSVFS read operations per second |
+| Storage | `CSVFS_WriteIOPS` | CSVFS write operations per second |
+| Storage | `CSVFS_ReadMBps` | Read throughput |
+| Storage | `CSVFS_WriteMBps` | Write throughput |
+| Storage | `CSVFS_ReadLatencyMs` | Read latency |
+| Storage | `CSVFS_WriteLatencyMs` | Write latency |
+| Compute | `HostCpuPercent` | Host CPU saturation |
+| Compute | `HostAvailableMemoryMB` | Available memory headroom |
+| Compute | `HyperVLogicalProcessorRunTime` | Hypervisor CPU pressure |
+
+## KQL Examples
+
+```kusto
+VMFleetMetrics_CL
+| where CounterName_s in ("CSVFS_ReadIOPS", "CSVFS_WriteIOPS")
+| summarize AvgValue=avg(Value_d) by bin(TimeGenerated, 1m), CounterName_s
+| render timechart
+```
+
+```kusto
+VMFleetMetrics_CL
+| where CounterName_s in ("CSVFS_ReadLatencyMs", "CSVFS_WriteLatencyMs")
+| summarize P95=percentile(Value_d, 95) by bin(TimeGenerated, 1m), CounterName_s
+| render timechart
 ```