diff --git a/.github/workflows/AzLocal.UpdateManagement-pester.yml b/.github/workflows/AzLocal.UpdateManagement-pester.yml
new file mode 100644
index 00000000..2927c670
--- /dev/null
+++ b/.github/workflows/AzLocal.UpdateManagement-pester.yml
@@ -0,0 +1,159 @@
+name: AzLocal.UpdateManagement - Pester
+
+# Runs the AzLocal.UpdateManagement Pester unit suite on every PR + push to main
+# that touches the module. Live-tagged Azure integration tests are excluded
+# (they need az login + the AdaptiveCloudLab subscription and are gated by
+# -IncludeLive in the local Invoke-Tests.ps1).
+#
+# Runner choice: windows-latest is required so the tests exercise the same
+# Windows PowerShell 5.1 + .NET 4.x surface that the published module targets.
+# Cost mitigation: path-filtered to AzLocal.UpdateManagement/** only, and only
+# fires on the three useful PR activities (opened, synchronize, reopened).
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened]
+ paths:
+ - 'AzLocal.UpdateManagement/**'
+ - '.github/workflows/AzLocal.UpdateManagement-pester.yml'
+ push:
+ branches: [main]
+ paths:
+ - 'AzLocal.UpdateManagement/**'
+ - '.github/workflows/AzLocal.UpdateManagement-pester.yml'
+ workflow_dispatch:
+
+concurrency:
+ group: azlocal-updatemanagement-pester-${{ github.ref }}
+ cancel-in-progress: true
+
+permissions:
+ contents: read
+ checks: write
+ pull-requests: write
+
+jobs:
+ pester:
+ name: Pester (Windows PowerShell 5.1)
+ runs-on: windows-latest
+ timeout-minutes: 20
+
+ defaults:
+ run:
+ shell: powershell
+ working-directory: AzLocal.UpdateManagement
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Show PowerShell + Pester baseline
+ run: |
+ $PSVersionTable | Format-List | Out-String | Write-Host
+ Get-Module Pester -ListAvailable | Select-Object Name, Version, Path | Format-Table -AutoSize | Out-String | Write-Host
+
+ - name: Install Pester 5.x
+ run: |
+ $needed = $true
+ $installed = Get-Module Pester -ListAvailable | Where-Object { $_.Version -ge [version]'5.0.0' } | Sort-Object Version -Descending | Select-Object -First 1
+ if ($installed) {
+ Write-Host "Pester $($installed.Version) already available at $($installed.Path)"
+ $needed = $false
+ }
+ if ($needed) {
+ Write-Host 'Installing Pester 5.x from PSGallery (CurrentUser scope)'
+ Install-Module Pester -MinimumVersion 5.5.0 -Force -SkipPublisherCheck -Scope CurrentUser
+ }
+ Import-Module Pester -MinimumVersion 5.0.0 -Force
+ (Get-Module Pester).Version | Write-Host
+
+ - name: Install powershell-yaml
+ # Required by one Describe block ('ITSM: Get-AzLocalItsmConfig normalises
+ # non-Hashtable YAML dictionaries') which Mock-overrides ConvertFrom-Yaml.
+ # Mock can only intercept commands that exist, so the source module must
+ # be present even though no actual YAML parsing happens at test time.
+ run: |
+ if (-not (Get-Module powershell-yaml -ListAvailable)) {
+ Write-Host 'Installing powershell-yaml from PSGallery (CurrentUser scope)'
+ Install-Module powershell-yaml -Force -SkipPublisherCheck -Scope CurrentUser
+ } else {
+ Write-Host 'powershell-yaml already available'
+ }
+ (Get-Module powershell-yaml -ListAvailable | Select-Object -First 1).Version | Write-Host
+
+ - name: Import module (smoke test)
+ run: |
+ Get-Module AzLocal.UpdateManagement -All | Remove-Module -Force -ErrorAction SilentlyContinue
+ Import-Module .\AzLocal.UpdateManagement.psd1 -Force -ErrorAction Stop
+ $m = Get-Module AzLocal.UpdateManagement
+ Write-Host "Loaded module $($m.Name) $($m.Version) with $($m.ExportedFunctions.Count) exported functions"
+
+ - name: Run Pester (unit suite, Live excluded)
+ run: |
+ New-Item -ItemType Directory -Path Tests\TestResults -Force | Out-Null
+ Get-Module AzLocal.UpdateManagement -All | Remove-Module -Force -ErrorAction SilentlyContinue
+ $config = New-PesterConfiguration
+ $config.Run.Path = '.\Tests'
+ $config.Run.PassThru = $true
+ $config.Run.Exit = $false
+ $config.Filter.ExcludeTag = @('Live')
+ $config.TestResult.Enabled = $true
+ $config.TestResult.OutputPath = 'Tests\TestResults\pester-junit.xml'
+ # JUnitXml is supported by Pester 5.4+ and is consumable by
+ # dorny/test-reporter with reporter=jest-junit below.
+ $config.TestResult.OutputFormat = 'JUnitXml'
+ $config.Output.Verbosity = 'Normal'
+ $result = Invoke-Pester -Configuration $config
+ "Passed=$($result.PassedCount) Failed=$($result.FailedCount) Skipped=$($result.SkippedCount) Duration=$($result.Duration)" | Tee-Object -FilePath Tests\TestResults\summary.txt
+ if ($result.FailedCount -gt 0) {
+ $result.Failed | ForEach-Object { "FAIL: $($_.ExpandedPath) :: $($_.ErrorRecord.Exception.Message)" } | Out-File Tests\TestResults\failures.txt
+ Write-Error "Pester reported $($result.FailedCount) failing test(s)."
+ exit 1
+ }
+
+ - name: Strip UTF-8 BOM from JUnit XML
+ # Windows PowerShell 5.1's UTF-8 writer (which Pester uses for the
+ # JUnit output) emits a 3-byte BOM. The EnricoMi publish-test-results
+ # action's lxml parser rejects it with: "Start tag expected, '<' not
+ # found, line 1, column 1" / "missing toplevel element". Re-write the
+ # file without BOM (read with BOM-aware UTF-8, write with BOM-less
+ # UTF-8). Idempotent: if the file is already BOM-less this is a no-op.
+ if: always()
+ run: |
+ $xml = 'Tests\TestResults\pester-junit.xml'
+ if (Test-Path -LiteralPath $xml) {
+ $bytes = [System.IO.File]::ReadAllBytes($xml)
+ $hasBom = ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF)
+ if ($hasBom) {
+ $text = [System.IO.File]::ReadAllText($xml, [System.Text.UTF8Encoding]::new($true))
+ [System.IO.File]::WriteAllText($xml, $text, [System.Text.UTF8Encoding]::new($false))
+ Write-Host "Stripped UTF-8 BOM from $xml (was $($bytes.Length) bytes, now $((Get-Item -LiteralPath $xml).Length) bytes)"
+ } else {
+ Write-Host "$xml has no BOM; nothing to strip."
+ }
+ } else {
+ Write-Host "$xml not found; skipping BOM strip."
+ }
+
+ - name: Upload test results
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: pester-results-${{ github.run_id }}
+ path: AzLocal.UpdateManagement/Tests/TestResults/
+ if-no-files-found: warn
+ retention-days: 14
+
+ - name: Publish test report (PR check)
+ # EnricoMi/publish-unit-test-result-action understands Pester's
+ # JUnitXml output natively. dorny/test-reporter was rejected because
+ # its 'jest-junit' parser threw `stackTrace.split is not a function`
+ # on Pester's stackTrace shape (Pester serialises it as a multi-line
+ # string array, not the single-string shape jest produces).
+ if: always() && github.event_name == 'pull_request'
+ uses: EnricoMi/publish-unit-test-result-action/windows@v2
+ with:
+ check_name: AzLocal.UpdateManagement Pester
+ junit_files: AzLocal.UpdateManagement/Tests/TestResults/pester-junit.xml
+ comment_mode: off
+ ignore_runs: true
diff --git a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.0_authentication-test.yml b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.0_authentication-test.yml
index 1ef5dabf..402c0fdf 100644
--- a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.0_authentication-test.yml
+++ b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.0_authentication-test.yml
@@ -59,7 +59,7 @@ variables:
# log if the YAML appears stale - prompting you to refresh via
# Copy-AzLocalPipelineExample -Update. See Automation-Pipeline-Examples/README.md section 5.
- name: GENERATED_AGAINST_MODULE_VERSION
- value: '0.8.4'
+ value: '0.8.5'
# Resolution order for the module version pin (leave all unset to install the latest,
# which is the default "fix-forward" behaviour): queue-time parameter > pipeline variable
# 'REQUIRED_MODULE_VERSION' overridden at queue time > empty (latest).
@@ -83,13 +83,15 @@ stages:
steps:
- task: PowerShell@2
displayName: 'Install AzLocal.UpdateManagement from PSGallery'
- # Step.0 itself does not call the module (the auth/RBAC/ARG probes
- # below use raw az CLI), but installing the module here gives operators
- # an early, consistent drift signal *before* the rest of the seven
- # pipelines run. If this step warns that the YAML is stale or the
- # installed module is older than expected, refresh the YAMLs via
- # Copy-AzLocalPipelineExample -Platform AzureDevOps -Update and re-run -
- # same pattern as Step.1+.
+ # Step.0 itself relies on the module (Export-AzLocalAuthValidationReport
+ # runs the four auth/RBAC/ARG probes); installing here also gives
+ # operators an early, consistent drift signal *before* the rest of
+ # the seven pipelines run. If the banner reports the YAML is stale
+ # or the installed module is older than expected, refresh the
+ # YAMLs via Copy-AzLocalPipelineExample -Platform AzureDevOps -Update
+ # and re-run.
+ # v0.8.5 thin-YAML: drift detection + banner + step outputs are all
+ # produced by Add-AzLocalPipelineVersionBanner (Public cmdlet).
env:
REQUIRED_MODULE_VERSION: $(REQUIRED_MODULE_VERSION)
GENERATED_AGAINST_MODULE_VERSION: $(GENERATED_AGAINST_MODULE_VERSION)
@@ -107,51 +109,16 @@ stages:
}
Install-Module @installArgs
Import-Module AzLocal.UpdateManagement -Force
- # Get-Module can return multiple entries when nested modules are loaded - pick the highest version.
- $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generated = [version]$env:GENERATED_AGAINST_MODULE_VERSION
- $latest = (Find-Module -Name AzLocal.UpdateManagement -Repository PSGallery -ErrorAction SilentlyContinue).Version
- Write-Host ""
- Write-Host "Module version summary"
- Write-Host " Installed on agent : $installed"
- Write-Host " YAML generated against : $generated"
- Write-Host " Latest on PSGallery : $(if ($latest) { $latest } else { '(lookup failed - check network)' })"
- Write-Host ""
- Get-Module AzLocal.UpdateManagement | Format-List Name, Version, Path
- # Drift signal 0: the module installed at runtime is OLDER than the version this YAML was generated against. Cmdlets, parameters, or output schemas referenced by this YAML may not exist in the installed module - emitted as a warning because this is the most likely cause of a hard runtime failure later in the job.
- if ($installed -lt $generated) {
- Write-Host "##vso[task.logissue type=warning]AzLocal.UpdateManagement v$installed is OLDER than the version this pipeline YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Platform AzureDevOps -Update'."
- }
- if ($installed -gt $generated) {
- $msg = "Pipeline YAML was generated against AzLocal.UpdateManagement v$generated but the agent installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Destination .\pipelines -Platform AzureDevOps -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
- Write-Host "##vso[task.logissue type=warning]$msg"
- }
- if ($latest -and ($latest -gt $installed)) {
- $msg = "AzLocal.UpdateManagement v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
- Write-Host "##vso[task.logissue type=warning]$msg"
- }
-
- # v0.8.4 - one-line version banner uploaded to the build run
- # Summary so the YAML version (GENERATED_AGAINST_MODULE_VERSION),
- # the module version actually loaded on the agent, the PSGallery
- # latest, and the REQUIRED_MODULE_VERSION pin status are visible
- # at the top of every run summary without scrolling the agent
- # log. Same data is also echoed to the console above.
- $pin = if ($env:REQUIRED_MODULE_VERSION) { "pinned to v$($env:REQUIRED_MODULE_VERSION)" } else { 'latest (fix-forward)' }
- $latestStr = if ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
- $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
- elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
- elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
- else { 'in sync' }
- $bannerPath = Join-Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY 'module-version-banner.md'
- "_Pipeline YAML v$generated | Module v$installed installed ($pin) | PSGallery latest $latestStr | $verdict_" | Out-File -FilePath $bannerPath -Encoding utf8
- Write-Host "##vso[task.uploadsummary]$bannerPath"
-
- # Persist the three versions so the report step (below) can include them
- # in the JUnit XML + markdown summary alongside the auth/RBAC checks.
- Write-Host "##vso[task.setvariable variable=installedModuleVersion;isOutput=false]$installed"
- Write-Host "##vso[task.setvariable variable=generatedAgainstVersion;isOutput=false]$generated"
- Write-Host "##vso[task.setvariable variable=latestOnPsGallery;isOutput=false]$(if ($latest) { $latest } else { '' })"
+ $banner = Add-AzLocalPipelineVersionBanner `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
+ -PinnedVersion $env:REQUIRED_MODULE_VERSION `
+ -PassThru
+ # Forward to ADO job-scoped variables so the report step (below) can
+ # surface the three versions in its JUnit + markdown summary.
+ $latestStr = if ($banner.LatestOnPSGallery) { $banner.LatestOnPSGallery } else { '' }
+ Write-Host "##vso[task.setvariable variable=installedModuleVersion;isOutput=false]$($banner.InstalledVersion)"
+ Write-Host "##vso[task.setvariable variable=generatedAgainstVersion;isOutput=false]$($banner.GeneratedAgainstVersion)"
+ Write-Host "##vso[task.setvariable variable=latestOnPsGallery;isOutput=false]$latestStr"
- task: AzureCLI@2
displayName: 'Collect Authentication and Subscription Scope Report'
@@ -159,145 +126,24 @@ stages:
azureSubscription: 'AzureLocal-ServiceConnection' # Update if your service connection has a different name.
scriptType: 'pscore'
scriptLocation: 'inlineScript'
+ # v0.8.5 thin-YAML: the ~200-line inline run block (az probes,
+ # XML scaffolding, markdown summary, ##vso writes) has been
+ # condensed into the Public cmdlet Export-AzLocalAuthValidationReport.
+ # The cmdlet performs all four probes (az account show / role
+ # assignment list / az account list / Resource Graph query),
+ # writes the JUnit XML + subscriptions.json + subscriptions.csv,
+ # uploads the markdown summary via ##vso[task.uploadsummary],
+ # and emits the three pipeline variables (subscription_count,
+ # cluster_count, auth_valid) via Set-AzLocalPipelineOutput.
inlineScript: |
$ErrorActionPreference = 'Stop'
+ Import-Module AzLocal.UpdateManagement -Force
$reportDir = Join-Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY 'auth-report'
- New-Item -ItemType Directory -Path $reportDir -Force | Out-Null
-
- Write-Host '--- 1. az account show (proves service-connection auth) ---'
- $accountJson = az account show -o json
- if ($LASTEXITCODE -ne 0) { throw "az account show failed (exit $LASTEXITCODE)" }
- $account = $accountJson | ConvertFrom-Json
- $account | Format-List name, id, tenantId, user
-
- Write-Host ''
- Write-Host '--- 2. role assignments for the service connection identity (proves RBAC grant) ---'
- $appId = az account show --query user.name -o tsv
- Write-Host "Service connection identity (appId): $appId"
- az role assignment list `
- --assignee $appId `
- --all `
- -o table
-
- Write-Host ''
- Write-Host '--- 3. Subscription Scope: enumerating all subscriptions visible to the pipeline identity ---'
- $subsJson = az account list --refresh --query "[].{name:name, subscriptionId:id, tenantId:tenantId, state:state}" -o json
- if ($LASTEXITCODE -ne 0) { throw "az account list failed (exit $LASTEXITCODE)" }
- $subs = @($subsJson | ConvertFrom-Json | Sort-Object name)
- $subCount = $subs.Count
- Write-Host "Count of subscriptions accessible = $subCount"
- $subs | Format-Table @{N='#';E={[array]::IndexOf($subs,$_)+1}}, name, subscriptionId, state -AutoSize
-
- $subs | ConvertTo-Json -Depth 4 | Out-File "$reportDir/subscriptions.json" -Encoding utf8
- $subs | Select-Object name, subscriptionId, tenantId, state |
- Export-Csv "$reportDir/subscriptions.csv" -NoTypeInformation -Encoding utf8
-
- Write-Host ''
- Write-Host '--- 4. Resource Graph query (proves cluster reachability) ---'
- az extension add --name resource-graph --yes --only-show-errors | Out-Null
- $clusterJson = az graph query `
- -q "resources | where type =~ 'microsoft.azurestackhci/clusters' | project name, resourceGroup, subscriptionId" `
- --first 1000 `
- -o json
- $clusterRows = @()
- if ($LASTEXITCODE -eq 0 -and $clusterJson) {
- $parsed = $clusterJson | ConvertFrom-Json
- if ($parsed -is [System.Collections.IEnumerable] -and -not ($parsed -is [string])) {
- $clusterRows = @($parsed)
- } elseif ($parsed.data) {
- $clusterRows = @($parsed.data)
- }
- }
- $clusterCount = $clusterRows.Count
- Write-Host "Clusters visible to the pipeline identity = $clusterCount"
- if ($clusterCount -gt 0) {
- $clusterRows | Select-Object -First 10 | Format-Table -AutoSize
- }
-
- # ------------------------------------------------------------------
- # Emit JUnit XML
- # ------------------------------------------------------------------
- $now = Get-Date -Format 'yyyy-MM-ddTHH:mm:ss'
- function ConvertTo-XmlSafe([string]$s) {
- if ($null -eq $s) { return '' }
- $s -replace '&','&' -replace '<','<' -replace '>','>' -replace '"','"'
- }
-
- $xml = [System.Text.StringBuilder]::new()
- [void]$xml.AppendLine('')
- [void]$xml.AppendLine('')
-
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(' ')
-
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- $i = 0
- foreach ($s in $subs) {
- $i++
- $nm = ConvertTo-XmlSafe $s.name
- $sid = ConvertTo-XmlSafe $s.subscriptionId
- $st = ConvertTo-XmlSafe $s.state
- [void]$xml.AppendLine(" ")
- }
- [void]$xml.AppendLine(' ')
-
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(' ')
-
- # Suite 4: Module Version Drift (informational - never fails)
- $installedVersion = "$env:INSTALLEDMODULEVERSION"
- $generatedVersion = "$env:GENERATEDAGAINSTVERSION"
- $latestVersion = "$env:LATESTONPSGALLERY"
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(' ')
-
- [void]$xml.AppendLine('')
- $xmlPath = "$reportDir/auth-report.xml"
- [System.IO.File]::WriteAllText($xmlPath, $xml.ToString(), [System.Text.UTF8Encoding]::new($false))
- Write-Host "JUnit XML written to: $xmlPath"
-
- # ------------------------------------------------------------------
- # Emit markdown summary for the ADO run Summary tab
- # ------------------------------------------------------------------
- $md = [System.Text.StringBuilder]::new()
- [void]$md.AppendLine('## Step.0 - Authentication Validation and Subscription Scope Report')
- [void]$md.AppendLine('')
- [void]$md.AppendLine('| Check | Result |')
- [void]$md.AppendLine('|---|---|')
- [void]$md.AppendLine("| Authentication (Workload Identity Federation) | :white_check_mark: working |")
- [void]$md.AppendLine("| Default Subscription | $($account.name) (``$($account.id)``) |")
- [void]$md.AppendLine("| Tenant | ``$($account.tenantId)`` |")
- [void]$md.AppendLine("| Pipeline identity (appId) | ``$($account.user.name)`` |")
- [void]$md.AppendLine("| Resource Graph reachability | :white_check_mark: $clusterCount cluster(s) visible |")
- [void]$md.AppendLine("| AzLocal.UpdateManagement (installed) | ``$installedVersion`` |")
- [void]$md.AppendLine("| AzLocal.UpdateManagement (YAML generated against) | ``$generatedVersion`` |")
- [void]$md.AppendLine("| AzLocal.UpdateManagement (latest on PSGallery) | ``$(if ($latestVersion) { $latestVersion } else { '(lookup failed)' })`` |")
- [void]$md.AppendLine('')
- [void]$md.AppendLine("### Count of subscriptions accessible = $subCount")
- [void]$md.AppendLine('')
- [void]$md.AppendLine('| # | Subscription Name | Subscription ID | Tenant ID | State |')
- [void]$md.AppendLine('|---|---|---|---|---|')
- $i = 0
- foreach ($s in $subs) {
- $i++
- [void]$md.AppendLine("| $i | $($s.name) | ``$($s.subscriptionId)`` | ``$($s.tenantId)`` | $($s.state) |")
- }
- [void]$md.AppendLine('')
- [void]$md.AppendLine("*Generated at $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss UTC')*")
- $summaryPath = Join-Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY 'auth-report-summary.md'
- $md.ToString() | Out-File -FilePath $summaryPath -Encoding utf8
- Write-Host "##vso[task.uploadsummary]$summaryPath"
-
- Write-Host "##vso[task.setvariable variable=subscriptionCount;isOutput=false]$subCount"
- Write-Host "##vso[task.setvariable variable=clusterCount;isOutput=false]$clusterCount"
+ Export-AzLocalAuthValidationReport `
+ -ReportDirectory $reportDir `
+ -InstalledModuleVersion "$(installedModuleVersion)" `
+ -GeneratedAgainstVersion "$(generatedAgainstVersion)" `
+ -LatestOnPSGallery "$(latestOnPsGallery)"
- task: PublishTestResults@2
displayName: 'Publish Authentication Validation JUnit Diagnostics'
diff --git a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.1_inventory-clusters.yml b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.1_inventory-clusters.yml
index 2a69a78c..6413c57e 100644
--- a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.1_inventory-clusters.yml
+++ b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.1_inventory-clusters.yml
@@ -42,7 +42,7 @@ variables:
# log if the YAML appears stale - prompting you to refresh via
# Copy-AzLocalPipelineExample -Update. See Automation-Pipeline-Examples/README.md section 5.
- name: GENERATED_AGAINST_MODULE_VERSION
- value: '0.8.4'
+ value: '0.8.5'
# Resolution order for the module version pin (leave all unset to install the latest,
# which is the default "fix-forward" behaviour): queue-time parameter > pipeline variable
# 'REQUIRED_MODULE_VERSION' overridden at queue time > empty (latest).
@@ -74,6 +74,8 @@ stages:
- task: PowerShell@2
displayName: 'Install AzLocal.UpdateManagement from PSGallery'
+ # v0.8.5 thin-YAML: drift detection + banner + step outputs are all
+ # produced by Add-AzLocalPipelineVersionBanner (Public cmdlet).
env:
REQUIRED_MODULE_VERSION: $(REQUIRED_MODULE_VERSION)
GENERATED_AGAINST_MODULE_VERSION: $(GENERATED_AGAINST_MODULE_VERSION)
@@ -91,196 +93,35 @@ stages:
}
Install-Module @installArgs
Import-Module AzLocal.UpdateManagement -Force
- # Get-Module can return multiple entries when nested modules are loaded - pick the highest version.
- $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generated = [version]$env:GENERATED_AGAINST_MODULE_VERSION
- $latest = (Find-Module -Name AzLocal.UpdateManagement -Repository PSGallery -ErrorAction SilentlyContinue).Version
- Write-Host ""
- Write-Host "Module version summary"
- Write-Host " Installed on agent : $installed"
- Write-Host " YAML generated against : $generated"
- Write-Host " Latest on PSGallery : $(if ($latest) { $latest } else { '(lookup failed - check network)' })"
- Write-Host ""
- Get-Module AzLocal.UpdateManagement | Format-List Name, Version, Path
- # Drift signal 0: the module installed at runtime is OLDER than the version this YAML was generated against. Cmdlets, parameters, or output schemas referenced by this YAML may not exist in the installed module - emitted as a warning because this is the most likely cause of a hard runtime failure later in the job.
- if ($installed -lt $generated) {
- Write-Host "##vso[task.logissue type=warning]AzLocal.UpdateManagement v$installed is OLDER than the version this pipeline YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Platform AzureDevOps -Update'."
- }
- if ($installed -gt $generated) {
- $msg = "Pipeline YAML was generated against AzLocal.UpdateManagement v$generated but the agent installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Destination .\pipelines -Platform AzureDevOps -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
- Write-Host "##vso[task.logissue type=warning]$msg"
- }
- if ($latest -and ($latest -gt $installed)) {
- $msg = "AzLocal.UpdateManagement v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
- Write-Host "##vso[task.logissue type=warning]$msg"
- }
+ $banner = Add-AzLocalPipelineVersionBanner `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
+ -PinnedVersion $env:REQUIRED_MODULE_VERSION `
+ -PassThru
+ # Forward to ADO job-scoped variables so the inventory step (below)
+ # can stamp the installed module version into README_Instructions.txt.
+ Write-Host "##vso[task.setvariable variable=installedModuleVersion;isOutput=false]$($banner.InstalledVersion)"
- # v0.8.4 - one-line version banner uploaded to the build run
- # Summary so the YAML version (GENERATED_AGAINST_MODULE_VERSION),
- # the module version actually loaded on the agent, the PSGallery
- # latest, and the REQUIRED_MODULE_VERSION pin status are visible
- # at the top of every run summary without scrolling the agent
- # log. Same data is also echoed to the console above.
- $pin = if ($env:REQUIRED_MODULE_VERSION) { "pinned to v$($env:REQUIRED_MODULE_VERSION)" } else { 'latest (fix-forward)' }
- $latestStr = if ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
- $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
- elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
- elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
- else { 'in sync' }
- $bannerPath = Join-Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY 'module-version-banner.md'
- "_Pipeline YAML v$generated | Module v$installed installed ($pin) | PSGallery latest $latestStr | $verdict_" | Out-File -FilePath $bannerPath -Encoding utf8
- Write-Host "##vso[task.uploadsummary]$bannerPath"
-
- task: AzureCLI@2
displayName: 'Run Cluster Inventory'
inputs:
azureSubscription: 'AzureLocal-ServiceConnection' # Update with your service connection name
scriptType: 'pscore'
scriptLocation: 'inlineScript'
+ # v0.8.5 thin-YAML: the inline run block (inventory query, dual
+ # CSV/JSON export, canonical CSV copy, README_Instructions.txt,
+ # per-pipeline summary, separate 'Generate Summary' task) has
+ # been condensed into the Public cmdlet
+ # Invoke-AzLocalClusterInventory. The cmdlet writes the four
+ # artifacts to -OutputDirectory, emits the markdown summary via
+ # ##vso[task.uploadsummary], and sets the four step outputs.
inlineScript: |
+ $ErrorActionPreference = 'Stop'
Import-Module AzLocal.UpdateManagement -Force
-
- # Create output directory
- $outputDir = "$(Build.ArtifactStagingDirectory)"
-
- $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
- $csvPath = Join-Path $outputDir "ClusterInventory_$timestamp.csv"
- $jsonPath = Join-Path $outputDir "ClusterInventory_$timestamp.json"
-
- # Add subscription filter if provided
- $subFilter = "${{ parameters.subscriptionFilter }}"
- $subscriptionParam = @{}
- if ($subFilter -and $subFilter -ne '') {
- $subscriptionParam['SubscriptionId'] = $subFilter
- Write-Host "Filtering to subscription: $subFilter"
- } else {
- Write-Host "Querying all accessible subscriptions"
- }
-
- # Export to CSV (for Excel workflow)
- Get-AzLocalClusterInventory @subscriptionParam -ExportPath $csvPath
-
- # Export to JSON (for CI/CD integrations and dashboards)
- $inventory = Get-AzLocalClusterInventory @subscriptionParam -ExportPath $jsonPath -PassThru
-
- # Output summary
- Write-Host ""
- Write-Host "========================================" -ForegroundColor Cyan
- Write-Host "Inventory Complete" -ForegroundColor Cyan
- Write-Host "========================================" -ForegroundColor Cyan
- Write-Host "Total Clusters: $($inventory.Count)"
- Write-Host "CSV exported to: $csvPath"
- Write-Host "JSON exported to: $jsonPath"
-
- # ---- Canonical no-timestamp copy expected by 'Manage UpdateRing Tags' ----
- $canonicalCsvPath = Join-Path $outputDir "ClusterUpdateRings.csv"
- Copy-Item -Path $csvPath -Destination $canonicalCsvPath -Force
- Write-Host "Canonical copy created: $canonicalCsvPath (edit this one)"
-
- # ---- README_Instructions.txt explaining what to do with the CSV ----
- $installedVersion = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generatedUtc = (Get-Date).ToUniversalTime().ToString("yyyy-MM-dd HH:mm:ss 'UTC'")
- $readmePath = Join-Path $outputDir "README_Instructions.txt"
- $readme = @'
- ========================================================================
- Cluster Inventory - Next Steps
- AzLocal.UpdateManagement (UpdateRing tagging workflow)
- ========================================================================
-
- This ZIP contains the cluster inventory generated by the
- 'Inventory Azure Local Clusters' pipeline. Use it to assign each
- cluster to an update wave (UpdateRing tag), then commit the result
- back into your repository so the 'Manage UpdateRing Tags' pipeline
- can apply the tags to Azure.
-
- ------------------------------------------------------------------------
- FILES IN THIS ARTIFACT
- ------------------------------------------------------------------------
-
- ClusterUpdateRings.csv
- <-- EDIT THIS FILE. Canonical name expected by the 'Manage
- UpdateRing Tags' pipeline's default csvFilePath parameter
- ('config/ClusterUpdateRings.csv').
-
- ClusterInventory_.csv
- Audit / historical copy of this run's inventory. Do NOT edit -
- keep it so you can diff future inventory runs against this
- snapshot.
-
- ClusterInventory_.json
- Machine-readable copy for dashboards / custom integrations.
-
- README_Instructions.txt
- This file.
-
- ------------------------------------------------------------------------
- STEP 1 - Open ClusterUpdateRings.csv in Excel
- ------------------------------------------------------------------------
-
- - For each cluster row, fill in the 'UpdateRing' column with the
- wave name you want that cluster to belong to. Examples:
- Canary, Pilot, Production
- (or your own scheme, e.g. Wave1, Wave2, Wave3 / Dev, Test, Prod)
- - Leave the 'UpdateRing' column EMPTY for any cluster you do not
- want this run to tag - those rows will be skipped.
- - Save as CSV (UTF-8). Do not change other columns or column order.
- - Do NOT rename the file. Keep it as 'ClusterUpdateRings.csv' so
- the 'Manage UpdateRing Tags' pipeline's default path picks it up.
+ Invoke-AzLocalClusterInventory `
+ -OutputDirectory "$(Build.ArtifactStagingDirectory)" `
+ -SubscriptionFilter "${{ parameters.subscriptionFilter }}" `
+ -InstalledModuleVersion "$(installedModuleVersion)"
- ------------------------------------------------------------------------
- STEP 2 - Commit ClusterUpdateRings.csv into your ops repository
- ------------------------------------------------------------------------
-
- - Recommended path: config/ClusterUpdateRings.csv
- - Commit and push (PR review optional but recommended).
- - The repo path you commit it to is what you will pass as
- 'csvFilePath' on the next run of the 'Manage UpdateRing Tags'
- pipeline.
-
- ------------------------------------------------------------------------
- STEP 3 - Run the 'Manage UpdateRing Tags' pipeline
- ------------------------------------------------------------------------
-
- - Open Azure DevOps Pipelines and trigger 'Manage UpdateRing Tags'
- via 'Run pipeline'.
- - Set 'csvFilePath' to the path you committed in STEP 2
- (default is 'config/ClusterUpdateRings.csv').
- - RECOMMENDED FIRST RUN: leave 'dryRun' = true. The pipeline
- will preview which tags would be set/changed without modifying
- any Azure resources.
- - Once the preview looks correct, re-run with 'dryRun' = false
- to apply the tags. Use 'force' = true only if you need to
- overwrite existing UpdateRing values already set on a cluster.
-
- ------------------------------------------------------------------------
- DOCUMENTATION
- ------------------------------------------------------------------------
-
- Pipeline examples README (online):
- https://github.com/NeilBird/Azure-Local/blob/main/AzLocal.UpdateManagement/Automation-Pipeline-Examples/README.md
-
- Module README (online):
- https://github.com/NeilBird/Azure-Local/blob/main/AzLocal.UpdateManagement/README.md
-
- Module on the PowerShell Gallery:
- https://www.powershellgallery.com/packages/AzLocal.UpdateManagement
-
- Generated by AzLocal.UpdateManagement v__MODULE_VERSION__
- Run timestamp (UTC): __TIMESTAMP__
- ========================================================================
- '@
- $readme = $readme.Replace('__MODULE_VERSION__', "$installedVersion").Replace('__TIMESTAMP__', $generatedUtc)
- Set-Content -Path $readmePath -Value $readme -Encoding ASCII
- Write-Host "Instructions written to: $readmePath"
-
- # Generate summary for pipeline
- $withTag = ($inventory | Where-Object { $_.HasUpdateRingTag -eq 'Yes' }).Count
- $withoutTag = ($inventory | Where-Object { $_.HasUpdateRingTag -eq 'No' }).Count
-
- Write-Host "##vso[task.setvariable variable=TotalClusters]$($inventory.Count)"
- Write-Host "##vso[task.setvariable variable=WithTag]$withTag"
- Write-Host "##vso[task.setvariable variable=WithoutTag]$withoutTag"
-
# compute a UTC timestamp variable so every downloadable artifact name is unique per run.
- pwsh: |
$stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd_HHmmss')
@@ -296,29 +137,4 @@ stages:
PathtoPublish: '$(Build.ArtifactStagingDirectory)'
ArtifactName: 'azlocal-step.1-cluster-inventory_$(stamp.artifactStamp)'
publishLocation: 'Container'
-
- - task: PowerShell@2
- displayName: 'Generate Summary'
- inputs:
- targetType: 'inline'
- script: |
- Write-Host "##vso[task.uploadsummary]$(Build.ArtifactStagingDirectory)/summary.md"
-
- $summary = @"
- # Cluster Inventory Summary
-
- | Metric | Value |
- |--------|-------|
- | Total Clusters | $(TotalClusters) |
- | With UpdateRing Tag | $(WithTag) |
- | Without UpdateRing Tag | $(WithoutTag) |
-
- ## Next Steps
-
- 1. Download the CSV artifact from this build
- 2. Open in Excel and set UpdateRing values for clusters
- 3. Run the "Manage UpdateRing Tags" pipeline with the updated CSV
- "@
-
- $summary | Out-File "$(Build.ArtifactStagingDirectory)/summary.md" -Encoding UTF8
diff --git a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.2_manage-updatering-tags.yml b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.2_manage-updatering-tags.yml
index 2c341022..37a01d1c 100644
--- a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.2_manage-updatering-tags.yml
+++ b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.2_manage-updatering-tags.yml
@@ -45,7 +45,7 @@ variables:
# log if the YAML appears stale - prompting you to refresh via
# Copy-AzLocalPipelineExample -Update. See Automation-Pipeline-Examples/README.md section 5.
- name: GENERATED_AGAINST_MODULE_VERSION
- value: '0.8.4'
+ value: '0.8.5'
# Resolution order for the module version pin (leave all unset to install the latest,
# which is the default "fix-forward" behaviour): queue-time parameter > pipeline variable
# 'REQUIRED_MODULE_VERSION' overridden at queue time > empty (latest).
@@ -68,105 +68,36 @@ stages:
- task: PowerShell@2
displayName: 'Validate CSV File Exists'
+ # v0.8.5 thin-YAML: the full TWO-STAGE operator workflow guidance
+ # is now emitted by Set-AzLocalClusterUpdateRingTagFromCsv when
+ # the Apply task runs. This task still fails fast (and surfaces
+ # the path) before we spend time installing the module.
inputs:
targetType: 'inline'
script: |
$csvPath = Join-Path "$(System.DefaultWorkingDirectory)" "${{ parameters.csvFilePath }}"
-
if (-not (Test-Path $csvPath)) {
Write-Host "##vso[task.logissue type=error]CSV file not found: ${{ parameters.csvFilePath }}"
+ Write-Host "The full TWO-STAGE operator workflow guidance will be emitted by"
+ Write-Host "Set-AzLocalClusterUpdateRingTagFromCsv when the Apply task runs."
Write-Host ""
- Write-Host "===========================================================================" -ForegroundColor Yellow
- Write-Host " UpdateRing tagging is a TWO-STAGE pipeline. You must run the inventory" -ForegroundColor Yellow
- Write-Host " pipeline first, edit the CSV, commit it, then re-run THIS pipeline." -ForegroundColor Yellow
- Write-Host "===========================================================================" -ForegroundColor Yellow
+ Write-Host "Quick recap:"
+ Write-Host " 1. Run Step.1 (Inventory) and download/edit/commit the CSV."
+ Write-Host " 2. Re-run this Step.2 with csvFilePath pointing to the committed CSV."
Write-Host ""
- Write-Host "STEP 1 - Generate the cluster inventory (one-off, then on demand)" -ForegroundColor Cyan
- Write-Host " a. Open Azure DevOps Pipelines in this project."
- Write-Host " b. Run the pipeline named 'Inventory Azure Local Clusters'"
- Write-Host " (file: azure-pipelines/Step.1_inventory-clusters.yml or similar)."
- Write-Host " c. Wait for the run to finish successfully."
- Write-Host " d. On the completed run summary, open the published artifact"
- Write-Host " named 'cluster-inventory' and download it."
- Write-Host " e. Extract it locally. You will get 'ClusterUpdateRings.csv' (the"
- Write-Host " one to edit), a timestamped audit copy, a .json copy, and a"
- Write-Host " 'README_Instructions.txt' file that mirrors these instructions."
- Write-Host ""
- Write-Host "STEP 2 - Edit the CSV in Excel" -ForegroundColor Cyan
- Write-Host " a. Open 'ClusterUpdateRings.csv' in Excel."
- Write-Host " b. For each cluster row, fill in the 'UpdateRing' column with the wave"
- Write-Host " name you want that cluster to belong to. Examples:"
- Write-Host " Canary, Pilot, Production"
- Write-Host " (or your own scheme, e.g. Wave1, Wave2, Wave3 / Dev, Test, Prod)."
- Write-Host " c. Leave the 'UpdateRing' column EMPTY for any cluster you do not want"
- Write-Host " this run to tag - those rows will be skipped."
- Write-Host " d. Save as CSV (UTF-8). Do not change other columns or column order."
- Write-Host " e. Do NOT rename the file - keep it as 'ClusterUpdateRings.csv' so"
- Write-Host " the default 'csvFilePath' below picks it up."
- Write-Host ""
- Write-Host "STEP 3 - Commit the edited CSV to this repository" -ForegroundColor Cyan
- Write-Host " a. Copy the edited CSV into a stable location in this repo, for example:"
- Write-Host " config/ClusterUpdateRings.csv"
- Write-Host " b. Commit and push it (PR review optional but recommended)."
- Write-Host " c. The path you commit it to is what you will pass as 'csvFilePath'"
- Write-Host " on the next run of this pipeline."
- Write-Host ""
- Write-Host "STEP 4 - Re-run THIS pipeline ('Manage UpdateRing Tags')" -ForegroundColor Cyan
- Write-Host " a. Click 'Run pipeline' on this pipeline."
- Write-Host " b. Set 'csvFilePath' to the path you committed in step 3"
- Write-Host " (default is 'config/ClusterUpdateRings.csv')."
- Write-Host " c. RECOMMENDED FIRST RUN: leave 'dryRun' = true to preview which tags"
- Write-Host " would be set/changed, without modifying any Azure resources."
- Write-Host " d. Once the preview looks correct, re-run with 'dryRun' = false to"
- Write-Host " apply the tags. Use 'force' = true only if you need to overwrite"
- Write-Host " existing UpdateRing values already set on a cluster."
- Write-Host ""
- Write-Host "Documentation:" -ForegroundColor Yellow
+ Write-Host "Docs:"
Write-Host " AzLocal.UpdateManagement/README.md - 'Update Rings' section"
Write-Host " AzLocal.UpdateManagement/Automation-Pipeline-Examples/README.md"
- Write-Host ""
- Write-Host "The path you supplied ('${{ parameters.csvFilePath }}') does not exist" -ForegroundColor Red
- Write-Host "in the checked-out branch of this repository. Did you forget to commit" -ForegroundColor Red
- Write-Host "the CSV, point at the wrong branch on 'Run pipeline', or mistype it?" -ForegroundColor Red
exit 1
}
-
Write-Host "Found CSV file: $csvPath"
Write-Host "##vso[task.setvariable variable=CsvPath]$csvPath"
-
- - task: PowerShell@2
- displayName: 'Validate CSV File'
- inputs:
- targetType: 'inline'
- script: |
- $csvPath = "$(CsvPath)"
- $data = Import-Csv $csvPath
-
- Write-Host "CSV File: $csvPath"
- Write-Host "Total Rows: $($data.Count)"
-
- # Check required columns
- $requiredColumns = @('ResourceId', 'UpdateRing')
- $columns = $data[0].PSObject.Properties.Name
-
- foreach ($col in $requiredColumns) {
- if ($col -notin $columns) {
- Write-Error "Required column '$col' not found in CSV"
- exit 1
- }
- }
-
- # Count rows with UpdateRing values
- $rowsWithValues = ($data | Where-Object { $_.UpdateRing -and $_.UpdateRing.Trim() -ne '' }).Count
- Write-Host "Rows with UpdateRing values: $rowsWithValues"
-
- if ($rowsWithValues -eq 0) {
- Write-Error "No rows have UpdateRing values set. Please edit the CSV and set UpdateRing values before running this pipeline."
- exit 1
- }
-
+
- task: PowerShell@2
displayName: 'Install AzLocal.UpdateManagement from PSGallery'
+ name: moduleVersionStep
+ # v0.8.5 thin-YAML: drift detection + banner + step outputs are
+ # all produced by Add-AzLocalPipelineVersionBanner (Public cmdlet).
env:
REQUIRED_MODULE_VERSION: $(REQUIRED_MODULE_VERSION)
GENERATED_AGAINST_MODULE_VERSION: $(GENERATED_AGAINST_MODULE_VERSION)
@@ -184,102 +115,38 @@ stages:
}
Install-Module @installArgs
Import-Module AzLocal.UpdateManagement -Force
- $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generated = [version]$env:GENERATED_AGAINST_MODULE_VERSION
- $latest = (Find-Module -Name AzLocal.UpdateManagement -Repository PSGallery -ErrorAction SilentlyContinue).Version
- Write-Host ""
- Write-Host "Module version summary"
- Write-Host " Installed on agent : $installed"
- Write-Host " YAML generated against : $generated"
- Write-Host " Latest on PSGallery : $(if ($latest) { $latest } else { '(lookup failed - check network)' })"
- Write-Host ""
- Get-Module AzLocal.UpdateManagement | Format-List Name, Version, Path
- # Drift signal 0: the module installed at runtime is OLDER than the version this YAML was generated against. Cmdlets, parameters, or output schemas referenced by this YAML may not exist in the installed module - emitted as a warning because this is the most likely cause of a hard runtime failure later in the job.
- if ($installed -lt $generated) {
- Write-Host "##vso[task.logissue type=warning]AzLocal.UpdateManagement v$installed is OLDER than the version this pipeline YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Platform AzureDevOps -Update'."
- }
- if ($installed -gt $generated) {
- $msg = "Pipeline YAML was generated against AzLocal.UpdateManagement v$generated but the agent installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Destination .\pipelines -Platform AzureDevOps -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
- Write-Host "##vso[task.logissue type=warning]$msg"
- }
- if ($latest -and ($latest -gt $installed)) {
- $msg = "AzLocal.UpdateManagement v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
- Write-Host "##vso[task.logissue type=warning]$msg"
- }
+ Add-AzLocalPipelineVersionBanner `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
+ -PinnedVersion $env:REQUIRED_MODULE_VERSION
- # v0.8.4 - one-line version banner uploaded to the build run
- # Summary so the YAML version (GENERATED_AGAINST_MODULE_VERSION),
- # the module version actually loaded on the agent, the PSGallery
- # latest, and the REQUIRED_MODULE_VERSION pin status are visible
- # at the top of every run summary without scrolling the agent
- # log. Same data is also echoed to the console above.
- $pin = if ($env:REQUIRED_MODULE_VERSION) { "pinned to v$($env:REQUIRED_MODULE_VERSION)" } else { 'latest (fix-forward)' }
- $latestStr = if ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
- $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
- elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
- elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
- else { 'in sync' }
- $bannerPath = Join-Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY 'module-version-banner.md'
- "_Pipeline YAML v$generated | Module v$installed installed ($pin) | PSGallery latest $latestStr | $verdict_" | Out-File -FilePath $bannerPath -Encoding utf8
- Write-Host "##vso[task.uploadsummary]$bannerPath"
-
- task: AzureCLI@2
displayName: 'Apply UpdateRing Tags'
+ # v0.8.5 thin-YAML: the inline Set-AzLocalClusterUpdateRingTag
+ # invocation, JSON sidecar write, and Generate Summary task have
+ # been condensed into the Public cmdlet
+ # Set-AzLocalClusterUpdateRingTagFromCsv. The cmdlet writes
+ # UpdateRingTag_Results.json into -OutputDirectory, emits the
+ # markdown step summary via ##vso[task.uploadsummary], and
+ # surfaces the eight pipeline variables (total_count,
+ # created_count, updated_count, already_in_sync_count,
+ # skipped_count, failed_count, whatif_count, results_json_path).
inputs:
azureSubscription: 'AzureLocal-ServiceConnection' # Update with your service connection name
scriptType: 'pscore'
scriptLocation: 'inlineScript'
inlineScript: |
Import-Module AzLocal.UpdateManagement -Force
-
- $csvPath = "$(CsvPath)"
$forceOverwrite = [System.Convert]::ToBoolean("${{ parameters.forceOverwrite }}")
- $dryRun = [System.Convert]::ToBoolean("${{ parameters.dryRun }}")
-
- # Create output directory for logs
- $outputDir = "$(Build.ArtifactStagingDirectory)"
-
- # Build parameters
+ $dryRun = [System.Convert]::ToBoolean("${{ parameters.dryRun }}")
$params = @{
- InputCsvPath = $csvPath
- LogFolderPath = $outputDir
- }
-
- if ($forceOverwrite) {
- $params['Force'] = $true
- Write-Host "Force mode enabled - will overwrite existing tags"
- }
-
- if ($dryRun) {
- $params['WhatIf'] = $true
- Write-Host "##vso[task.logissue type=warning]DRY RUN MODE - No changes will be applied"
+ InputCsvPath = "$(CsvPath)"
+ OutputDirectory = "$(Build.ArtifactStagingDirectory)"
+ InstalledModuleVersion = "$(moduleVersionStep.installed_module_version)"
}
-
- Write-Host ""
- Write-Host "========================================" -ForegroundColor Cyan
- Write-Host "Applying UpdateRing Tags" -ForegroundColor Cyan
- Write-Host "========================================" -ForegroundColor Cyan
+ if ($forceOverwrite) { $params['Force'] = $true }
+ if ($dryRun) { $params['WhatIf'] = $true }
+ Set-AzLocalClusterUpdateRingTagFromCsv @params
- # Run tag management. -PassThru returns the per-cluster results so
- # the Summary task can build a breakdown table rather than parroting
- # only the pipeline inputs back at the operator.
- $results = Set-AzLocalClusterUpdateRingTag @params -PassThru
-
- # Persist results to a JSON sidecar so the Summary task (separate
- # PowerShell process) can read them. Lives in the artifact staging
- # dir that gets published.
- $resultsJsonPath = Join-Path $outputDir 'UpdateRingTag_Results.json'
- if ($null -ne $results) {
- @($results) | ConvertTo-Json -Depth 5 | Out-File -FilePath $resultsJsonPath -Encoding utf8
- Write-Host "Wrote $($results.Count) per-cluster result row(s) to: $resultsJsonPath"
- } else {
- '[]' | Out-File -FilePath $resultsJsonPath -Encoding utf8
- Write-Host "No per-cluster results returned (empty CSV?). Wrote empty array to: $resultsJsonPath"
- }
-
- Write-Host ""
- Write-Host "Tag management complete"
-
# compute a UTC timestamp variable so every downloadable artifact name is unique per run.
- pwsh: |
$stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd_HHmmss')
@@ -295,82 +162,4 @@ stages:
PathtoPublish: '$(Build.ArtifactStagingDirectory)'
ArtifactName: 'azlocal-step.2-updatering-tag-logs_$(stamp.artifactStamp)'
publishLocation: 'Container'
-
- - task: PowerShell@2
- displayName: 'Generate Summary'
- inputs:
- targetType: 'inline'
- script: |
- $dryRun = [System.Convert]::ToBoolean("${{ parameters.dryRun }}")
- $forceOverwrite = [System.Convert]::ToBoolean("${{ parameters.forceOverwrite }}")
-
- $lines = New-Object System.Collections.Generic.List[string]
- [void]$lines.Add('# UpdateRing Tag Management Summary')
- [void]$lines.Add('')
- [void]$lines.Add('| Setting | Value |')
- [void]$lines.Add('|---------|-------|')
- [void]$lines.Add("| Dry Run | $dryRun |")
- [void]$lines.Add("| Force Overwrite | $forceOverwrite |")
-
- # Per-cluster results breakdown - read the JSON sidecar the apply task wrote.
- # See AzLocal.UpdateManagement Set-AzLocalClusterUpdateRingTag -PassThru schema.
- $resultsJsonPath = Join-Path '$(Build.ArtifactStagingDirectory)' 'UpdateRingTag_Results.json'
- if (Test-Path $resultsJsonPath) {
- $results = @(Get-Content -Raw -Path $resultsJsonPath | ConvertFrom-Json)
- $total = $results.Count
- $created = @($results | Where-Object { $_.Action -eq 'Created' -and $_.Status -eq 'Success' }).Count
- $updated = @($results | Where-Object { $_.Action -eq 'Updated' -and $_.Status -eq 'Success' }).Count
- $alreadyInSync = @($results | Where-Object { $_.Status -eq 'AlreadyInSync' }).Count
- $skipped = @($results | Where-Object { $_.Status -eq 'Skipped' }).Count
- $failed = @($results | Where-Object { $_.Status -eq 'Failed' }).Count
- $whatIf = @($results | Where-Object { $_.Status -eq 'WhatIf' }).Count
-
- [void]$lines.Add('')
- [void]$lines.Add('## Result breakdown')
- [void]$lines.Add('')
- [void]$lines.Add('| Outcome | Count |')
- [void]$lines.Add('|---------|------:|')
- [void]$lines.Add("| Total clusters processed | $total |")
- [void]$lines.Add("| Tags created | $created |")
- [void]$lines.Add("| Tags updated | $updated |")
- [void]$lines.Add("| Already in sync (no-op) | $alreadyInSync |")
- [void]$lines.Add("| Skipped (UpdateRing differs, no -Force) | $skipped |")
- if ($whatIf -gt 0) {
- [void]$lines.Add("| WhatIf (dry-run preview) | $whatIf |")
- }
- [void]$lines.Add("| Failed | $failed |")
-
- if ($total -gt 0) {
- [void]$lines.Add('')
- [void]$lines.Add("Per-cluster results ($total rows)
")
- [void]$lines.Add('')
- [void]$lines.Add('| Cluster | Action | Previous | New | Status | Message |')
- [void]$lines.Add('|---------|--------|----------|-----|--------|---------|')
- foreach ($r in $results) {
- $cn = ("$($r.ClusterName)") -replace '\|','\|'
- $act = ("$($r.Action)") -replace '\|','\|'
- $pv = ("$($r.PreviousTagValue)") -replace '\|','\|'
- $nv = ("$($r.NewTagValue)") -replace '\|','\|'
- $st = ("$($r.Status)") -replace '\|','\|'
- $msg = ("$($r.Message)") -replace '\|','\|' -replace '\r?\n',' '
- [void]$lines.Add("| $cn | $act | $pv | $nv | $st | $msg |")
- }
- [void]$lines.Add('')
- [void]$lines.Add('
')
- $severityScore = 0.0
- if ($hasStepError) { $severityScore += 1000 }
- if ($r.State -eq 'Failed') { $severityScore += 800 }
- if ($runSeverity -eq 'skull') { $severityScore += 500 }
- elseif ($runSeverity -eq 'crit') { $severityScore += 300 }
- elseif ($runSeverity -eq 'warn') { $severityScore += 50 }
- if ($stepSeverity -eq 'crit') { $severityScore += 200 }
- elseif ($stepSeverity -eq 'warn') { $severityScore += 30 }
- $elapsedHoursForScore = if ($elapsed) { $elapsed.TotalHours } else { 0 }
- $severityScore += [math]::Round($elapsedHoursForScore / 24, 2)
- # v0.7.98: surface a meaningful per-row JUnit time= so the Tests tab + Test Reporter
- # widgets stop rendering "0ms" totals. For in-flight rows we report how long the run
- # has been going (now - startDt). For unresolved-failed rows with both start and end
- # timestamps we report the actual run duration (end - start). Anything else falls
- # back to 0 (no usable timestamps).
- $runDurationSeconds = 0
- if ($r.State -ne 'InProgress' -and $startDt -and $endDt) {
- $runDurationSeconds = [int][math]::Round(($endDt - $startDt).TotalSeconds, 0)
- } elseif ($elapsed) {
- $runDurationSeconds = [int][math]::Round($elapsed.TotalSeconds, 0)
- }
- if ($runDurationSeconds -lt 0) { $runDurationSeconds = 0 }
- [PSCustomObject]@{
- ClusterName = $r.ClusterName
- ClusterPortalUrl = $clusterPortalUrl
- UpdateName = $r.UpdateName
- UpdateRunPortalUrl = $updateRunPortalUrl
- State = $r.State
- Status = $progressStatus
- CurrentStep = $r.CurrentStep
- Progress = $r.Progress
- StartTimeUtc = if ($startDt) { $startDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
- EndTimeUtc = if ($endDt) { $endDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
- ElapsedDisplay = $elapsedDisplay
- ElapsedHours = if ($elapsed) { [math]::Round($elapsed.TotalHours, 2) } else { '' }
- StepStartTimeUtc = if ($stepStartDt) { $stepStartDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
- StepElapsedDisplay = $stepElapsedDisplay
- StepElapsedHours = $stepElapsedHoursVal
- ExceedsThreshold = $exceeds
- ExceedsStepThreshold = $exceedsStep
- HasStepError = $hasStepError
- IsRecentFailure = $isRecentFailure
- IsUnresolvedFailure = $isUnresolvedFailure
- ThresholdHours = $thresholdHours
- StepThresholdHours = $stepThresholdHours
- CriticalElapsedDays = $criticalElapsedDays
- StepSeverity = $stepSeverity
- RunSeverity = $runSeverity
- StateIcon = $stateIcon
- StatusIcon = $statusIcon
- Flags = $flagDisplay
- SeverityScore = $severityScore
- RunDurationSeconds = $runDurationSeconds
- RunId = $r.RunId
- RunResourceId = if ($r.PSObject.Properties['RunResourceId']) { $r.RunResourceId } else { '' }
- ClusterResourceId = $r.ClusterResourceId
- Duration = $r.Duration
- CurrentStepDetail = $r.CurrentStepDetail
- ErrorMessage = if ($r.PSObject.Properties['ErrorMessage']) { [string]$r.ErrorMessage } else { '' }
- }
- }
-
- $inFlight = @($rows | Where-Object { $_.State -eq 'InProgress' })
- $longRunning = @($inFlight | Where-Object { $_.ExceedsThreshold })
- $longRunningStep = @($inFlight | Where-Object { $_.ExceedsStepThreshold })
- $stepErrored = @($inFlight | Where-Object { $_.HasStepError })
- $recentlyFailed = @($rows | Where-Object { $_.IsRecentFailure })
- $unresolvedFailed = @($rows | Where-Object { $_.IsUnresolvedFailure })
-
- if ($rows -and $rows.Count -gt 0) {
- $rows | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName | Export-Csv -Path $monitorCsv -NoTypeInformation -Encoding utf8
- } else {
- '' | Set-Content -Path $monitorCsv -Encoding utf8
- }
-
- # JUnit XML - in-flight + unresolved-failed test cases. Failure types (v0.7.96):
- # StepError - HIGHEST PRIORITY: properties.progress.status == 'Error' while State is InProgress
- # (canonical "step has errored, run is stuck" signal - independent of elapsed time)
- # LongRunningStep - current step elapsed exceeds per-step threshold
- # LongRunningOverall - BACKSTOP: overall run elapsed exceeds overall threshold
- # RecentFailure - run in state Failed (kept name for backwards-compatible parsers;
- # emitted for ALL latest-Failed runs, not just within failureWindowHours)
- $xmlLines = New-Object 'System.Collections.Generic.List[string]'
- $xmlLines.Add('')
- # v0.7.99: testsuite/testsuites time="0". Per-testcase time= IS still surfaced (gives
- # the ADO Tests tab meaningful per-row durations), but summing wall-clock ages across
- # 5 unrelated stuck runs (e.g. ~88 days) is misleading at the suite header.
- $xmlLines.Add('')
- $tests = $inFlight.Count + $unresolvedFailed.Count
- $failures = @($inFlight | Where-Object { $_.HasStepError -or $_.ExceedsStepThreshold -or $_.ExceedsThreshold }).Count + $unresolvedFailed.Count
- $xmlLines.Add((' ' -f $tests, $failures))
- foreach ($r in ($inFlight | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName)) {
- $safeName = ($r.ClusterName -replace '[^A-Za-z0-9_.-]', '_')
- $caseName = "$safeName - $($r.UpdateName) - $($r.CurrentStep)"
- $caseNameXml = [System.Security.SecurityElement]::Escape($caseName)
- if ($r.HasStepError) {
- $errSnippet = if ($r.ErrorMessage) { $r.ErrorMessage } else { '(no errorMessage on deepest failed step)' }
- $msg = ('Progress status is Error (state still InProgress) - step is stuck. CurrentStep: {0}. StepElapsed: {1}. ErrorMessage: {2}' -f $r.CurrentStep, $r.StepElapsedDisplay, $errSnippet)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- } elseif ($r.ExceedsStepThreshold) {
- $msg = ('Current step elapsed {0} exceeds per-step threshold of {1}h. CurrentStep: {2}. Overall elapsed: {3}. Progress: {4}.' -f $r.StepElapsedDisplay, $r.StepThresholdHours, $r.CurrentStep, $r.ElapsedDisplay, $r.Progress)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- } elseif ($r.ExceedsThreshold) {
- $msg = ('Overall elapsed {0} exceeds backstop threshold of {1}h (current step within {2}h per-step budget). CurrentStep: {3}. Progress: {4}.' -f $r.ElapsedDisplay, $r.ThresholdHours, $r.StepThresholdHours, $r.CurrentStep, $r.Progress)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- } else {
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- }
- }
- foreach ($r in ($unresolvedFailed | Sort-Object @{Expression='EndTimeUtc';Descending=$true})) {
- $safeName = ($r.ClusterName -replace '[^A-Za-z0-9_.-]', '_')
- $caseName = "$safeName - $($r.UpdateName) - FAILED"
- $caseNameXml = [System.Security.SecurityElement]::Escape($caseName)
- $detail = if ($r.ErrorMessage) { $r.ErrorMessage } elseif ($r.CurrentStepDetail) { $r.CurrentStepDetail } else { $r.CurrentStep }
- $msg = ('Run failed at {0} UTC. Step: {1}. Detail: {2}.' -f $r.EndTimeUtc, $r.CurrentStep, $detail)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- }
- $xmlLines.Add(' ')
- $xmlLines.Add('')
- ($xmlLines -join [Environment]::NewLine) | Set-Content -Path $monitorXml -Encoding utf8
-
- Write-Host "##vso[task.setvariable variable=inFlight;isOutput=true]$($inFlight.Count)"
- Write-Host "##vso[task.setvariable variable=longRunning;isOutput=true]$($longRunning.Count)"
- Write-Host "##vso[task.setvariable variable=longRunningStep;isOutput=true]$($longRunningStep.Count)"
- Write-Host "##vso[task.setvariable variable=stepErrored;isOutput=true]$($stepErrored.Count)"
- Write-Host "##vso[task.setvariable variable=recentFailures;isOutput=true]$($recentlyFailed.Count)"
- Write-Host "##vso[task.setvariable variable=unresolvedFailures;isOutput=true]$($unresolvedFailed.Count)"
-
- # Markdown summary (uploaded via task.uploadsummary below)
- $md = New-Object 'System.Collections.Generic.List[string]'
- $md.Add('## In-Flight Update Monitor')
- $md.Add('')
- # v0.7.98 fleet status badge: rolls up the worst signal across in-flight rows so the
- # operator gets a single at-a-glance verdict above the metrics table.
- $hasCritical = ($stepErrored.Count -gt 0) -or (@($inFlight | Where-Object { $_.RunSeverity -eq 'skull' -or $_.RunSeverity -eq 'crit' -or $_.StepSeverity -eq 'crit' }).Count -gt 0)
- $hasWarn = (@($inFlight | Where-Object { $_.StepSeverity -eq 'warn' -or $_.RunSeverity -eq 'warn' }).Count -gt 0)
- if ($hasCritical) {
- $crits = @()
- if ($stepErrored.Count -gt 0) { $crits += "$($stepErrored.Count) stuck step error(s)" }
- $skullCount = @($inFlight | Where-Object { $_.RunSeverity -eq 'skull' }).Count
- $critRunCount = @($inFlight | Where-Object { $_.RunSeverity -eq 'crit' }).Count
- $critStepCount = @($inFlight | Where-Object { $_.StepSeverity -eq 'crit' }).Count
- if ($skullCount -gt 0) { $crits += "$skullCount run(s) > $($criticalElapsedDays * 2)d" }
- if ($critRunCount -gt 0) { $crits += "$critRunCount run(s) > ${criticalElapsedDays}d" }
- if ($critStepCount -gt 0) { $crits += "$critStepCount step(s) > $($stepThresholdHours * 2)h" }
- $md.Add((':red_circle: **Fleet Status: CRITICAL** - ' + ($crits -join ', ')))
- } elseif ($hasWarn) {
- $warnCount = @($inFlight | Where-Object { $_.StepSeverity -eq 'warn' -or $_.RunSeverity -eq 'warn' }).Count
- $md.Add((":yellow_circle: **Fleet Status: WARN** - $warnCount long-running run(s) within tolerance"))
- } elseif ($inFlight.Count -gt 0) {
- $md.Add((":green_circle: **Fleet Status: HEALTHY** - $($inFlight.Count) in-flight run(s), all within tolerance"))
- } elseif ($unresolvedFailed.Count -gt 0) {
- $md.Add((":red_circle: **Fleet Status: FAILED** - $($unresolvedFailed.Count) unresolved-failed run(s) (no in-flight activity)"))
- } else {
- $md.Add(':white_check_mark: **Fleet Status: IDLE** - no in-flight runs, no unresolved failures')
- }
- $md.Add('')
- $scopeLabel = if ($scope -eq 'by-update-ring' -and $updateRing) { "by-update-ring (UpdateRing = $updateRing)" } else { 'all clusters' }
- $md.Add("**Scope**: $scopeLabel - **Per-step**: ${stepThresholdHours}h warn / $($stepThresholdHours * 2)h crit - **Overall**: ${thresholdHours}h warn / ${criticalElapsedDays}d crit / $($criticalElapsedDays * 2)d skull - **Recent-failure window**: ${failureWindowHours}h - **Snapshot (UTC)**: $($now.ToString('yyyy-MM-dd HH:mm'))")
- $md.Add('')
- $md.Add('**Legend**: :large_blue_circle: InProgress · :large_green_circle: Succeeded · :red_circle: Failed · :white_circle: NotStarted · :white_check_mark: success · :hourglass_flowing_sand: in-progress · :x: error · :warning: warn tier · :rotating_light: critical tier · :skull: extreme (>2x critical)')
- $md.Add('')
- $md.Add('| Metric | Count |')
- $md.Add('|--------|-------|')
- $md.Add("| Clusters scoped | $($rows.Count) |")
- $md.Add("| Update runs in flight | $($inFlight.Count) |")
- $md.Add("| Step errored (progress.status == 'Error', state still InProgress) | $($stepErrored.Count) |")
- $md.Add("| Step elapsed > ${stepThresholdHours}h (primary) | $($longRunningStep.Count) |")
- $md.Add("| Overall elapsed > ${thresholdHours}h (backstop) | $($longRunning.Count) |")
- $md.Add("| Unresolved-failed runs (latest run is Failed) | $($unresolvedFailed.Count) |")
- if ($failureWindowHours -gt 0) {
- $md.Add("| Recently-failed runs (last ${failureWindowHours}h) | $($recentlyFailed.Count) |")
- }
- $md.Add('')
- if ($inFlight.Count -gt 0) {
- $md.Add('### In-flight runs (sorted by composite severity score, worst first)')
- $md.Add('')
- $md.Add('| Cluster | State | Status | Current Step | Progress | Step Elapsed | Run Elapsed | Flags |')
- $md.Add('|---------|-------|--------|--------------|----------|--------------|-------------|-------|')
- foreach ($r in ($inFlight | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName)) {
- $cs = if ($r.CurrentStep) { $r.CurrentStep } else { '-' }
- $pg = if ($r.Progress) { $r.Progress } else { '-' }
- $stepEl = if ($r.StepElapsedDisplay) { $r.StepElapsedDisplay } else { '-' }
- $runEl = if ($r.ElapsedDisplay) { $r.ElapsedDisplay } else { '-' }
- $stateCell = if ($r.StateIcon) { "$($r.StateIcon) $($r.State)" } else { [string]$r.State }
- $statusCell = if (-not $r.Status) { '-' }
- elseif ($r.StatusIcon) { "$($r.StatusIcon) $($r.Status)" }
- else { [string]$r.Status }
- $stepElPrefix = switch ($r.StepSeverity) {
- 'crit' { ':rotating_light: ' }
- 'warn' { ':warning: ' }
- default { '' }
- }
- $runElPrefix = switch ($r.RunSeverity) {
- 'skull' { ':skull: ' }
- 'crit' { ':rotating_light: ' }
- 'warn' { ':warning: ' }
- default { '' }
- }
- $stepElCell = $stepElPrefix + $stepEl
- $runElCell = $runElPrefix + $runEl
- # target=_blank so links open in a new tab (preserves the pipeline summary tab).
- $clusterCell = if ($r.ClusterPortalUrl) { '' + $r.ClusterName + '' } else { $r.ClusterName }
- if ($r.UpdateRunPortalUrl) {
- $clusterCell = $clusterCell + '
' + $r.UpdateName + ''
- } else {
- $clusterCell = $clusterCell + '
' + $r.UpdateName + ''
- }
- # Collapsible verbose error inline in Current Step cell when present.
- if ($r.HasStepError -and $r.ErrorMessage) {
- $rawErr = $r.ErrorMessage
- if ($rawErr.Length -gt 1500) { $rawErr = $rawErr.Substring(0, 1500) + ' ...' }
- $errEsc = ($rawErr -replace '\|', '\|') -replace '\r?\n', ' '
- $cs = $cs + '
Verbose error
' + $errEsc + '
'
- # as a line break inside a cell.
- $updateVersionsCell = (($groupRows | ForEach-Object {
- '{0} x {1}' -f $_.Version, $_.Count
- }) -join '
')
- # Union of cluster names across versions in this YYMM. Each
- # cluster appears in exactly one CurrentVersion row, so a
- # simple concat + sort -Unique is sufficient.
- $clusterNames = @()
- foreach ($r in $groupRows) {
- if ($r.Clusters) {
- $clusterNames += @($r.Clusters -split '; ' | Where-Object { $_ })
- }
- }
- $clusterNames = @($clusterNames | Sort-Object -Unique)
- $clCell = if ($clusterNames.Count -le 15) {
- $clusterNames -join '; '
- } else {
- (($clusterNames | Select-Object -First 15) -join '; ') + (' ... (+{0} more)' -f ($clusterNames.Count - 15))
- }
- $clCell = $clCell -replace '\|','\|'
- $versionSection += ('| {0} | {1} | {2} | {3} | {4}% | {5} |' -f $yymmDisplay, $updateVersionsCell, $supportEmoji, $totalCount, $totalPct, $clCell) + "`n"
- }
- $versionSection += "`n_Support roll-up: Supported = $supportedClusters cluster(s), Unsupported = $unsupportedClusters, Unknown = $unknownVersionClusters. Anchor source: ``$supportSource``._`n"
- $versionSection += "_Note: the **Clusters (first 15 shown only)** column is intentionally truncated for readability. Download ``readiness-status.csv`` from artifacts to see the full cluster-name list._`n`n"
- } catch {
- Write-Warning "Failed to render Fleet Version Distribution markdown table: $($_.Exception.Message)"
- $versionSection = ''
- }
- }
-
- $summary = @"
- ## Fleet Update Status Summary _(generated $generatedUtc)_
-
- $versionSection
- ### Critical Health Status (matches JUnit XML pass/fail)
-
- | Metric | Count | Status |
- |--------|-------|--------|
- | **Passed** (healthy, no failures, not SBE-blocked) | $chPassed | ✅ |
- | **Failed** (HealthState=Failure OR UpdateState=Failed OR SBE prerequisite blocked) | $chFailed | $(if ([int]$chFailed -gt 0) { '❌' } else { '✅' }) |
-
- ### Primary Status (each cluster counted once; rows sum to Total Clusters)
-
- | Metric | Count | Status |
- |--------|-------|--------|
- | **Total Clusters** | $total | ℹ️ |
- | **Up to Date** | $upToDate | ✅ |
- | **Ready for Update** | $ready | 🟢 |
- | **Update In Progress** | $inProgress | 🔄 |
- | **SBE Prerequisite Blocked** | $sbeBlocked | $(if ([int]$sbeBlocked -gt 0) { '🟡' } else { '✅' }) |
- | **Health Failure** (HealthState=Failure) | $healthFailure | $(if ([int]$healthFailure -gt 0) { '❌' } else { '✅' }) |
- | **Update Failed** (Failed / UpdateFailed / NeedsAttention) | $updateFailed | $(if ([int]$updateFailed -gt 0) { '❌' } else { '✅' }) |
- | **Action Required** (PreparationFailed) | $actionRequired | $(if ([int]$actionRequired -gt 0) { '❌' } else { '✅' }) |
- | **Needs Investigation** | $needsInvestigation | $(if ([int]$needsInvestigation -gt 0) { '⚠️' } else { '✅' }) |
-
- Priority cascade used to bucket each cluster exactly once:
- Update Failed > Action Required > Health Failure > SBE Prerequisite Blocked > Update In Progress > Ready for Update > Up to Date > Needs Investigation.
- "@
-
- # Actions Required section
- $actionsRequired = @()
- if ([int]$updateFailed -gt 0) { $actionsRequired += "- **$updateFailed cluster(s) have UpdateState in (Failed, UpdateFailed, NeedsAttention)** - Review the most recent update run in Azure Portal and the ``update-runs.csv`` artifact for the failure detail." }
- if ([int]$actionRequired -gt 0) { $actionsRequired += "- **$actionRequired cluster(s) have UpdateState=PreparationFailed** - Update preparation hit a blocker before the run started. Inspect the cluster activity log (most common: prerequisite-check failure, missing SBE content, ARB extension drift). Resolve before re-arming the update." }
- if ([int]$healthFailure -gt 0) { $actionsRequired += "- **$healthFailure cluster(s) have HealthState=Failure** - Resolve critical health check issues in Azure Portal before retrying any updates." }
- if ([int]$hasPrerequisite -gt 0) { $actionsRequired += "- **$hasPrerequisite cluster(s) blocked by SBE prerequisite** - Install the required Solution Builder Extension (SBE) update from the hardware vendor. See ``available-updates.csv`` for vendor details." }
-
- if ($actionsRequired.Count -gt 0) {
- $summary += "`n`n### Actions Required`n`n"
- $summary += ($actionsRequired -join "`n")
- }
-
- # '📜 Update Run History and Error Details' markdown table
- # provides an ARG-first fleet-scale view of recent unresolved failures. Rendered only when there
- # are unresolved failed runs. Reads the base64 JSON blob set by the
- # collect step so we don't re-query ARG.
- # Cluster Name renders as a portal hyperlink (per-row
- # ClusterPortalUrl from ARG) so the operator can jump straight to the
- # cluster blade. Verbose Error Details renders inside an inline
- # ...
.... Group
- # key = (ClusterName, UpdateName, DeepestErrMsg). Each group's
- # canonical row is the LATEST StartTime; the other rows are
- # summarised in a small 'Earlier occurrences' bullet list
- # appended to the verbose-error block. This keeps the
- # table scannable on fleets where the same step keeps failing.
- $groups = @($rows) | Group-Object -Property @{
- Expression = { "$($_.ClusterName)|$($_.UpdateName)|$($_.DeepestErrMsg)" }
- }
- $renderRows = @()
- foreach ($g in $groups) {
- $ordered = @($g.Group | Sort-Object @{ Expression = 'StartTime'; Descending = $true })
- $latest = $ordered[0]
- $extras = @($ordered | Select-Object -Skip 1)
- $latest | Add-Member -NotePropertyName 'EarlierOccurrences' -NotePropertyValue $extras -Force
- $renderRows += $latest
- }
- # Preserve top-of-table = latest run across the whole fleet
- $renderRows = @($renderRows | Sort-Object @{Expression='StartTime';Descending=$true}, @{Expression='ClusterName';Descending=$false})
- $totalRows = (@($rows)).Count
- $groupCount = $renderRows.Count
- $dedupSuffix = if ($groupCount -lt $totalRows) { " (collapsed $totalRows run(s) into $groupCount unique failure group(s); older same-error reruns are listed inside each row's 'Show error' panel)" } else { '' }
- $summary += "`n`n### 📜 Update Run History and Error Details`n`n"
- $summary += "_ARG-first, fleet-scale failure-detail view. Shows up to 25 most recent unresolved Failed update runs (last 30 days). Source cmdlet: ``Get-AzLocalUpdateRunFailures -State Failed -OnlyUnresolved``.$dedupSuffix._`n`n"
- $summary += "| Cluster Name | Update Name | Update State | Status | Current Step | Verbose Error Details | Duration | Time Started | Last Updated |`n"
- $summary += "|---|---|---|---|---|---|---|---|---|`n"
- foreach ($r in $renderRows) {
- $errCell = if ($r.DeepestErrMsg) {
- $e = [string]$r.DeepestErrMsg
- # HTML-encode so '<', '>', '&' in stack traces don't get
- # parsed as tags by the renderer; escape pipes so the
- # table row stays intact; collapse newlines to
so
- # multi-line stack traces remain readable inside the
- # collapsible block.
- $e = $e -replace '&','&' -replace '<','<' -replace '>','>'
- $e = $e -replace "`r`n",'
' -replace "`n",'
' -replace '\|','\|'
- $extraBlock = ''
- if ($r.EarlierOccurrences -and @($r.EarlierOccurrences).Count -gt 0) {
- $bullets = (@($r.EarlierOccurrences) | ForEach-Object {
- $dur = if ($_.Duration) { " (Duration: $($_.Duration))" } else { '' }
- "• Started $($_.StartTime), Last updated $($_.LastUpdated)$dur"
- }) -join '
'
- $extraBlock = '
Earlier occurrences with the same error (' + (@($r.EarlierOccurrences).Count) + '):
' + $bullets
- }
- 'Show error
' + $e + '' + $extraBlock + ' block per cluster. The
- # carries the cluster name (linkified to portal), a severity tally
- # ('[Critical] x N · [Warning] x M', non-zero tiers only, Critical first)
- # and the most-recent LastOccurrence across all that cluster's rows. The
- # expanded body holds the existing per-failure table.
- #
- # Cluster ordering: CriticalCount desc, then WarningCount desc, then
- # most-recent LastOccurrence desc (worst-cluster-first). Within a cluster,
- # rows sort Critical-first then LastOccurrence desc.
- #
- # Cap is per-CLUSTER (not per-row) so no cluster's failures are silently
- # truncated. CSV artifact always has every row.
- $md += "`n*Click a cluster to expand its failing health checks. Worst-affected clusters appear first.*`n"
-
- $detailByCluster = @(
- $detailRows | Group-Object -Property ClusterName | ForEach-Object {
- $rows = @($_.Group)
- $crit = @($rows | Where-Object { $_.Severity -eq 'Critical' }).Count
- $warn = @($rows | Where-Object { $_.Severity -eq 'Warning' }).Count
- $portalRow = $rows | Where-Object {
- $_.PSObject.Properties.Match('ClusterPortalUrl').Count -gt 0 -and $_.ClusterPortalUrl
- } | Select-Object -First 1
- $lastOcc = ($rows | Measure-Object -Property LastOccurrence -Maximum).Maximum
- [PSCustomObject]@{
- ClusterName = $_.Name
- ClusterPortalUrl = if ($portalRow) { [string]$portalRow.ClusterPortalUrl } else { '' }
- CriticalCount = $crit
- WarningCount = $warn
- LastOccurrence = $lastOcc
- Rows = @(
- $rows | Sort-Object @{Expression={ if($_.Severity -eq 'Critical'){1}else{2} };Descending=$false},
- @{Expression={$_.LastOccurrence};Descending=$true}
- )
- }
- } | Sort-Object @{Expression={$_.CriticalCount};Descending=$true},
- @{Expression={$_.WarningCount};Descending=$true},
- @{Expression={$_.LastOccurrence};Descending=$true}
- )
-
- $totalClusters = $detailByCluster.Count
- $clustersToShow = @($detailByCluster | Select-Object -First 100)
-
- foreach ($cl in $clustersToShow) {
- $sevParts = @()
- if ($cl.CriticalCount -gt 0) { $sevParts += ('[Critical] x {0}' -f $cl.CriticalCount) }
- if ($cl.WarningCount -gt 0) { $sevParts += ('[Warning] x {0}' -f $cl.WarningCount) }
- $sevTally = $sevParts -join ' · '
-
- # target="_blank" so clicking the cluster name in the
- # opens the portal in a new tab and leaves the pipeline run open.
- $clusterCell = if ($cl.ClusterPortalUrl) {
- '{1}' -f $cl.ClusterPortalUrl, $cl.ClusterName
- } else {
- $cl.ClusterName
- }
- $lastOccStr = if ($cl.LastOccurrence) { ('{0:yyyy-MM-ddTHH:mm:ssZ}' -f $cl.LastOccurrence) } else { '-' }
-
- $md += "`n`n"
- $md += "$clusterCell · $sevTally · last $lastOccStr
`n`n"
- $md += "| Severity | Failure Reason | Failure Remediation | Target Resource Name | Target Resource Type | Last Occurrence | Resource Group |`n"
- $md += "|----------|----------------|---------------------|----------------------|----------------------|------------------|----------------|`n"
- foreach ($r in $cl.Rows) {
- $sevTag = if ($r.Severity -eq 'Critical') { '[Critical]' } else { '[Warning]' }
- $rem = if ($r.PSObject.Properties.Match('Remediation').Count -gt 0) { [string]$r.Remediation } else { '' }
- # Remediation links open in a new tab so the operator can
- # read the Microsoft Learn / docs page without losing the
- # pipeline run.
- $remCell = if ($rem -and $rem.StartsWith('https://')) { 'link' -f $rem } else { $rem }
- $tName = if ($r.PSObject.Properties.Match('TargetResourceName').Count -gt 0) { [string]$r.TargetResourceName } else { '' }
- $tType = if ($r.PSObject.Properties.Match('TargetResourceType').Count -gt 0) { [string]$r.TargetResourceType } else { '' }
- $md += ('| {0} | {1} | {2} | {3} | {4} | {5} | {6} |' -f $sevTag, $r.FailureReason, $remCell, $tName, $tType, $r.LastOccurrence, $r.ResourceGroup) + "`n"
- }
- $md += "`n `n"
- }
-
- if ($totalClusters -gt 100) {
- $md += "`n*Showing first 100 clusters of $totalClusters; see ``fleet-health-detail.csv`` artifact for the full list.*`n"
- }
- }
-
- $md += @"
-
- ### Reports Available in Artifacts
- - ``fleet-health-detail.csv`` - one row per (cluster, failing health check)
- - ``fleet-health-summary.csv`` - one row per (FailureReason, Severity); ordered Critical-first, then by ClusterCount desc
- - ``fleet-health-overview.csv`` - one row per cluster (ARG-first fleet health summary)
- - ``fleet-health-detail.json`` / ``fleet-health-summary.json`` / ``fleet-health-overview.json`` - machine-readable
- - ``fleet-health-status.xml`` - JUnit XML (see Tests tab)
-
- _Note: test sections prefixed **[JUnit Debug]** in the Tests tab are a diagnostic mirror of the tables above (for CI tooling/ITSM integration). For primary readability, use this summary and the CSV artifacts._
- "@
-
- Write-Host $md
- displayName: 'Display Fleet Health Summary'
- condition: always()
-
# Publish JUnit test results LAST so the Test Results tab is populated but the
# markdown summary above is the first thing visible on the run extensions view.
- task: PublishTestResults@2
@@ -750,4 +333,3 @@ stages:
testResultsFiles: '$(reportsPath)/itsm-results.xml'
testRunTitle: 'ITSM Tickets (Step.9) - $(Build.BuildNumber)'
failTaskOnFailedTests: false
-
diff --git a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.0_authentication-test.yml b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.0_authentication-test.yml
index 6e24c53d..9cace295 100644
--- a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.0_authentication-test.yml
+++ b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.0_authentication-test.yml
@@ -78,7 +78,7 @@ env:
# this to the version actually installed and to the latest on PSGallery, and emits a
# ::notice annotation if the YAML appears stale - prompting you to refresh via
# Copy-AzLocalPipelineExample. See Automation-Pipeline-Examples/README.md section 5.
- GENERATED_AGAINST_MODULE_VERSION: '0.8.4'
+ GENERATED_AGAINST_MODULE_VERSION: '0.8.5'
# Resolution order for the module version pin (leave all unset to install the latest,
# which is the default "fix-forward" behaviour): manual workflow_dispatch input >
# repository variable 'REQUIRED_MODULE_VERSION' > empty (latest).
@@ -136,13 +136,16 @@ jobs:
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
- name: Install AzLocal.UpdateManagement from PSGallery
- # Step.0 itself does not call the module (the auth/RBAC/ARG probes below use
- # raw az CLI), but installing the module here gives operators an early,
- # consistent drift signal *before* the rest of the seven pipelines run.
- # If this step warns that the YAML is stale or the installed module is
- # older than expected, refresh the YAMLs via Copy-AzLocalPipelineExample
- # and re-run - same pattern as Step.1+.
+ # Step.0 itself relies on the module (Export-AzLocalAuthValidationReport
+ # runs the four auth/RBAC/ARG probes); installing here also gives
+ # operators an early, consistent drift signal *before* the rest of
+ # the seven pipelines run. If the banner reports the YAML is stale
+ # or the installed module is older than expected, refresh the YAMLs
+ # via Copy-AzLocalPipelineExample -Update and re-run.
+ # v0.8.5 thin-YAML: drift detection + banner + step outputs are all
+ # produced by Add-AzLocalPipelineVersionBanner (Public cmdlet).
shell: pwsh
+ id: module-version
run: |
$ErrorActionPreference = 'Stop'
$installArgs = @{ Name = 'AzLocal.UpdateManagement'; Scope = 'CurrentUser'; Force = $true; AllowClobber = $true }
@@ -154,56 +157,9 @@ jobs:
}
Install-Module @installArgs
Import-Module AzLocal.UpdateManagement -Force
- # Get-Module can return multiple entries when nested modules are loaded - pick the highest version.
- $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generated = [version]$env:GENERATED_AGAINST_MODULE_VERSION
- $latest = (Find-Module -Name AzLocal.UpdateManagement -Repository PSGallery -ErrorAction SilentlyContinue).Version
- Write-Host ""
- Write-Host "Module version summary"
- Write-Host " Installed on runner : $installed"
- Write-Host " YAML generated against : $generated"
- Write-Host " Latest on PSGallery : $(if ($latest) { $latest } else { '(lookup failed - check network)' })"
- Write-Host ""
- Get-Module AzLocal.UpdateManagement | Format-List Name, Version, Path
- # Drift signal 0: the module installed at runtime is OLDER than the version this YAML was generated against. Cmdlets, parameters, or output schemas referenced by this YAML may not exist in the installed module - emitted as a warning because this is the most likely cause of a hard runtime failure later in the job.
- if ($installed -lt $generated) {
- $msg = "AzLocal.UpdateManagement v$installed is OLDER than the version this workflow YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Destination .\.github\workflows -Platform GitHub -Update'."
- Write-Host "::warning title=AzLocal.UpdateManagement is older than workflow YAML expects::$msg"
- }
- # Drift signal 1: the YAML in this repo is older than the module that was installed.
- if ($installed -gt $generated) {
- $msg = "Workflow YAML was generated against AzLocal.UpdateManagement v$generated but the runner installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Destination .\.github\workflows -Platform GitHub -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
- Write-Host "::notice title=Workflow YAML may be stale::$msg"
- }
- # Drift signal 2: the user pinned (or PSGallery shipped a release mid-run) and the install is behind the latest.
- if ($latest -and ($latest -gt $installed)) {
- $msg = "AzLocal.UpdateManagement v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
- Write-Host "::notice title=Newer AzLocal.UpdateManagement version available on PSGallery::$msg"
- }
-
- # v0.8.4 - one-line version banner emitted to the rendered Step
- # Summary so the YAML version (GENERATED_AGAINST_MODULE_VERSION), the
- # module version actually loaded on the runner, the PSGallery latest,
- # and the REQUIRED_MODULE_VERSION pin status are visible at the top
- # of every run summary without scrolling the agent log. Same data is
- # also echoed to the console above as 'Module version summary'.
- $pin = if ($env:REQUIRED_MODULE_VERSION) { "pinned to v$($env:REQUIRED_MODULE_VERSION)" } else { 'latest (fix-forward)' }
- $latestStr = if ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
- $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
- elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
- elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
- else { 'in sync' }
- if ($env:GITHUB_STEP_SUMMARY) {
- "_Pipeline YAML v$generated | Module v$installed installed ($pin) | PSGallery latest $latestStr | $verdict_" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
- "" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
- }
-
- # Persist the three versions so the report step (below) can include them
- # in the JUnit XML + markdown summary alongside the auth/RBAC checks.
- "installed_module_version=$installed" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
- "generated_against_version=$generated" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
- "latest_on_psgallery=$(if ($latest) { $latest } else { '' })" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
- id: module-version
+ Add-AzLocalPipelineVersionBanner `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
+ -PinnedVersion $env:REQUIRED_MODULE_VERSION
- name: Collect Authentication and Subscription Scope Report
id: report
@@ -213,151 +169,23 @@ jobs:
INSTALLED_MODULE_VERSION: ${{ steps.module-version.outputs.installed_module_version }}
GENERATED_AGAINST_VERSION: ${{ steps.module-version.outputs.generated_against_version }}
LATEST_ON_PSGALLERY: ${{ steps.module-version.outputs.latest_on_psgallery }}
+ # v0.8.5 thin-YAML: the ~200-line inline run block (az probes,
+ # XML scaffolding, markdown summary, step-output writes) has been
+ # condensed into the Public cmdlet Export-AzLocalAuthValidationReport.
+ # The cmdlet performs all four probes (az account show / role
+ # assignment list / az account list / Resource Graph query),
+ # writes the JUnit XML + subscriptions.json + subscriptions.csv,
+ # emits the markdown step summary, and writes the three step
+ # outputs (subscription_count, cluster_count, auth_valid).
run: |
$ErrorActionPreference = 'Stop'
- $reportDir = './reports'
- New-Item -ItemType Directory -Path $reportDir -Force | Out-Null
-
- Write-Host '--- 1. az account show (proves OIDC token exchange + sub-id secret) ---'
- $accountJson = az account show -o json
- if ($LASTEXITCODE -ne 0) { throw "az account show failed (exit $LASTEXITCODE)" }
- $account = $accountJson | ConvertFrom-Json
- $account | Format-List name, id, tenantId, user
-
- Write-Host ''
- Write-Host '--- 2. role assignments for AZURE_CLIENT_ID (proves RBAC grant) ---'
- az role assignment list `
- --assignee $env:AZURE_CLIENT_ID `
- --all `
- -o table
-
- Write-Host ''
- Write-Host '--- 3. Subscription Scope: enumerating all subscriptions visible to the pipeline identity ---'
- # --refresh forces az to ask the server for the current sub list rather than using
- # the cached tenant slice from `az login`. This is what makes the count authoritative.
- $subsJson = az account list --refresh --query "[].{name:name, subscriptionId:id, tenantId:tenantId, state:state}" -o json
- if ($LASTEXITCODE -ne 0) { throw "az account list failed (exit $LASTEXITCODE)" }
- $subs = @($subsJson | ConvertFrom-Json | Sort-Object name)
- $subCount = $subs.Count
- Write-Host "Count of subscriptions accessible = $subCount"
- $subs | Format-Table @{N='#';E={[array]::IndexOf($subs,$_)+1}}, name, subscriptionId, state -AutoSize
-
- # Persist machine-readable copies for the artifact upload.
- $subs | ConvertTo-Json -Depth 4 | Out-File "$reportDir/subscriptions.json" -Encoding utf8
- $subs | Select-Object name, subscriptionId, tenantId, state |
- Export-Csv "$reportDir/subscriptions.csv" -NoTypeInformation -Encoding utf8
-
- Write-Host ''
- Write-Host '--- 4. Resource Graph query (proves cluster reachability) ---'
- az extension add --name resource-graph --yes --only-show-errors | Out-Null
- $clusterJson = az graph query `
- -q "resources | where type =~ 'microsoft.azurestackhci/clusters' | project name, resourceGroup, subscriptionId" `
- --first 1000 `
- -o json
- $clusterRows = @()
- if ($LASTEXITCODE -eq 0 -and $clusterJson) {
- $parsed = $clusterJson | ConvertFrom-Json
- # `az graph query -o json` returns either a top-level array or a {data: [...]} object
- # depending on CLI version - normalise.
- if ($parsed -is [System.Collections.IEnumerable] -and -not ($parsed -is [string])) {
- $clusterRows = @($parsed)
- } elseif ($parsed.data) {
- $clusterRows = @($parsed.data)
- }
- }
- $clusterCount = $clusterRows.Count
- Write-Host "Clusters visible to the pipeline identity = $clusterCount"
- if ($clusterCount -gt 0) {
- $clusterRows | Select-Object -First 10 | Format-Table -AutoSize
- }
-
- # ------------------------------------------------------------------
- # Emit JUnit XML
- # ------------------------------------------------------------------
- $now = Get-Date -Format 'yyyy-MM-ddTHH:mm:ss'
- function ConvertTo-XmlSafe([string]$s) {
- if ($null -eq $s) { return '' }
- $s -replace '&','&' -replace '<','<' -replace '>','>' -replace '"','"'
- }
-
- $xml = [System.Text.StringBuilder]::new()
- [void]$xml.AppendLine('')
- [void]$xml.AppendLine('')
-
- # Suite 1: Authentication
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(' ')
-
- # Suite 2: Subscription Scope
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- $i = 0
- foreach ($s in $subs) {
- $i++
- $nm = ConvertTo-XmlSafe $s.name
- $sid = ConvertTo-XmlSafe $s.subscriptionId
- $st = ConvertTo-XmlSafe $s.state
- [void]$xml.AppendLine(" ")
- }
- [void]$xml.AppendLine(' ')
-
- # Suite 3: Resource Graph Reachability
- $rgTests = 1
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(' ')
-
- # Suite 4: Module Version Drift (informational - never fails)
- $installedVersion = $env:INSTALLED_MODULE_VERSION
- $generatedVersion = $env:GENERATED_AGAINST_VERSION
- $latestVersion = $env:LATEST_ON_PSGALLERY
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(" ")
- [void]$xml.AppendLine(' ')
-
- [void]$xml.AppendLine('')
- $xmlPath = "$reportDir/auth-report.xml"
- [System.IO.File]::WriteAllText($xmlPath, $xml.ToString(), [System.Text.UTF8Encoding]::new($false))
- Write-Host "JUnit XML written to: $xmlPath"
-
- # ------------------------------------------------------------------
- # Emit GITHUB_STEP_SUMMARY markdown
- # ------------------------------------------------------------------
- $md = [System.Text.StringBuilder]::new()
- [void]$md.AppendLine('## Step.0 - Authentication Validation and Subscription Scope Report')
- [void]$md.AppendLine('')
- [void]$md.AppendLine('| Check | Result |')
- [void]$md.AppendLine('|---|---|')
- [void]$md.AppendLine("| Authentication (OIDC) | :white_check_mark: working |")
- [void]$md.AppendLine("| Default Subscription | $($account.name) (``$($account.id)``) |")
- [void]$md.AppendLine("| Tenant | ``$($account.tenantId)`` |")
- [void]$md.AppendLine("| Pipeline identity (appId) | ``$($account.user.name)`` |")
- [void]$md.AppendLine("| Resource Graph reachability | :white_check_mark: $clusterCount cluster(s) visible |")
- [void]$md.AppendLine("| AzLocal.UpdateManagement (installed) | ``$installedVersion`` |")
- [void]$md.AppendLine("| AzLocal.UpdateManagement (YAML generated against) | ``$generatedVersion`` |")
- [void]$md.AppendLine("| AzLocal.UpdateManagement (latest on PSGallery) | ``$(if ($latestVersion) { $latestVersion } else { '(lookup failed)' })`` |")
- [void]$md.AppendLine('')
- [void]$md.AppendLine("### Count of subscriptions accessible = $subCount")
- [void]$md.AppendLine('')
- [void]$md.AppendLine('| # | Subscription Name | Subscription ID | Tenant ID | State |')
- [void]$md.AppendLine('|---|---|---|---|---|')
- $i = 0
- foreach ($s in $subs) {
- $i++
- [void]$md.AppendLine("| $i | $($s.name) | ``$($s.subscriptionId)`` | ``$($s.tenantId)`` | $($s.state) |")
- }
- [void]$md.AppendLine('')
- [void]$md.AppendLine("*Generated at $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss UTC')*")
- $md.ToString() | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
-
- # Surface the count as a step output so downstream steps / jobs can consume it.
- "subscription_count=$subCount" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
- "cluster_count=$clusterCount" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+ Import-Module AzLocal.UpdateManagement -Force
+ Export-AzLocalAuthValidationReport `
+ -AzureClientId $env:AZURE_CLIENT_ID `
+ -ReportDirectory './reports' `
+ -InstalledModuleVersion $env:INSTALLED_MODULE_VERSION `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_VERSION `
+ -LatestOnPSGallery $env:LATEST_ON_PSGALLERY
- name: Compute Artifact Timestamp
id: artifact-stamp
diff --git a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.1_inventory-clusters.yml b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.1_inventory-clusters.yml
index 3ddb82ac..3a62c9b3 100644
--- a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.1_inventory-clusters.yml
+++ b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.1_inventory-clusters.yml
@@ -47,7 +47,7 @@ env:
# this to the version actually installed and to the latest on PSGallery, and emits a
# ::notice annotation if the YAML appears stale - prompting you to refresh via
# Copy-AzLocalPipelineExample. See Automation-Pipeline-Examples/README.md section 5.
- GENERATED_AGAINST_MODULE_VERSION: '0.8.4'
+ GENERATED_AGAINST_MODULE_VERSION: '0.8.5'
# Resolution order for the module version pin (leave all unset to install the latest,
# which is the default "fix-forward" behaviour): manual workflow_dispatch input >
# repository variable 'REQUIRED_MODULE_VERSION' > empty (latest).
@@ -104,7 +104,10 @@ jobs:
az extension add --name resource-graph --yes
- name: Install AzLocal.UpdateManagement from PSGallery
+ # v0.8.5 thin-YAML: drift detection + banner + step outputs are all
+ # produced by Add-AzLocalPipelineVersionBanner (Public cmdlet).
shell: pwsh
+ id: module-version
run: |
$ErrorActionPreference = 'Stop'
$installArgs = @{ Name = 'AzLocal.UpdateManagement'; Scope = 'CurrentUser'; Force = $true; AllowClobber = $true }
@@ -116,198 +119,32 @@ jobs:
}
Install-Module @installArgs
Import-Module AzLocal.UpdateManagement -Force
- # Get-Module can return multiple entries when nested modules are loaded - pick the highest version.
- $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generated = [version]$env:GENERATED_AGAINST_MODULE_VERSION
- $latest = (Find-Module -Name AzLocal.UpdateManagement -Repository PSGallery -ErrorAction SilentlyContinue).Version
- Write-Host ""
- Write-Host "Module version summary"
- Write-Host " Installed on runner : $installed"
- Write-Host " YAML generated against : $generated"
- Write-Host " Latest on PSGallery : $(if ($latest) { $latest } else { '(lookup failed - check network)' })"
- Write-Host ""
- Get-Module AzLocal.UpdateManagement | Format-List Name, Version, Path
- # Drift signal 0: the module installed at runtime is OLDER than the version this YAML was generated against. Cmdlets, parameters, or output schemas referenced by this YAML may not exist in the installed module - emitted as a warning because this is the most likely cause of a hard runtime failure later in the job.
- if ($installed -lt $generated) {
- $msg = "AzLocal.UpdateManagement v$installed is OLDER than the version this workflow YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Destination .\.github\workflows -Platform GitHub -Update'."
- Write-Host "::warning title=AzLocal.UpdateManagement is older than workflow YAML expects::$msg"
- }
- # Drift signal 1: the YAML in this repo is older than the module that was installed.
- if ($installed -gt $generated) {
- $msg = "Workflow YAML was generated against AzLocal.UpdateManagement v$generated but the runner installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Destination .\.github\workflows -Platform GitHub -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
- Write-Host "::notice title=Workflow YAML may be stale::$msg"
- }
- # Drift signal 2: the user pinned (or PSGallery shipped a release mid-run) and the install is behind the latest.
- if ($latest -and ($latest -gt $installed)) {
- $msg = "AzLocal.UpdateManagement v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
- Write-Host "::notice title=Newer AzLocal.UpdateManagement version available on PSGallery::$msg"
- }
+ Add-AzLocalPipelineVersionBanner `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
+ -PinnedVersion $env:REQUIRED_MODULE_VERSION
- # v0.8.4 - one-line version banner emitted to the rendered Step
- # Summary so the YAML version (GENERATED_AGAINST_MODULE_VERSION), the
- # module version actually loaded on the runner, the PSGallery latest,
- # and the REQUIRED_MODULE_VERSION pin status are visible at the top
- # of every run summary without scrolling the agent log. Same data is
- # also echoed to the console above as 'Module version summary'.
- $pin = if ($env:REQUIRED_MODULE_VERSION) { "pinned to v$($env:REQUIRED_MODULE_VERSION)" } else { 'latest (fix-forward)' }
- $latestStr = if ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
- $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
- elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
- elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
- else { 'in sync' }
- if ($env:GITHUB_STEP_SUMMARY) {
- "_Pipeline YAML v$generated | Module v$installed installed ($pin) | PSGallery latest $latestStr | $verdict_" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
- "" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
- }
-
- name: Run Cluster Inventory
+ id: inventory
shell: pwsh
env:
INPUT_SUBSCRIPTION_FILTER: ${{ github.event.inputs.subscription_filter }}
+ INSTALLED_MODULE_VERSION: ${{ steps.module-version.outputs.installed_module_version }}
+ # v0.8.5 thin-YAML: the inline run block (inventory query, dual
+ # CSV/JSON export, canonical CSV copy, README_Instructions.txt,
+ # step outputs, separate "Summary" step) has been condensed into
+ # the Public cmdlet Invoke-AzLocalClusterInventory. The cmdlet
+ # writes the four artifacts to -OutputDirectory, emits the
+ # markdown step summary via GITHUB_STEP_SUMMARY, and sets the
+ # four step outputs (cluster_count, with_tag_count,
+ # without_tag_count, csv_path).
run: |
+ $ErrorActionPreference = 'Stop'
Import-Module AzLocal.UpdateManagement -Force
-
- # Create output directory
- $outputDir = "./artifacts"
- New-Item -ItemType Directory -Path $outputDir -Force | Out-Null
-
- $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
- $csvPath = Join-Path $outputDir "ClusterInventory_$timestamp.csv"
- $jsonPath = Join-Path $outputDir "ClusterInventory_$timestamp.json"
-
- # Add subscription filter if provided
- $subFilter = $env:INPUT_SUBSCRIPTION_FILTER
- $subscriptionParam = @{}
- if ($subFilter -and $subFilter -ne '') {
- $subscriptionParam['SubscriptionId'] = $subFilter
- Write-Host "Filtering to subscription: $subFilter"
- } else {
- Write-Host "Querying all accessible subscriptions"
- }
-
- # Export to CSV (for Excel workflow)
- Get-AzLocalClusterInventory @subscriptionParam -ExportPath $csvPath
-
- # Export to JSON (for CI/CD integrations and dashboards)
- $inventory = Get-AzLocalClusterInventory @subscriptionParam -ExportPath $jsonPath -PassThru
-
- # Output summary
- Write-Host ""
- Write-Host "========================================" -ForegroundColor Cyan
- Write-Host "Inventory Complete" -ForegroundColor Cyan
- Write-Host "========================================" -ForegroundColor Cyan
- Write-Host "Total Clusters: $($inventory.Count)"
- Write-Host "CSV exported to: $csvPath"
- Write-Host "JSON exported to: $jsonPath"
-
- # ---- Canonical no-timestamp copy expected by the 'Manage UpdateRing Tags' workflow ----
- # The timestamped CSV is retained for audit / longitudinal comparison.
- $canonicalCsvPath = Join-Path $outputDir "ClusterUpdateRings.csv"
- Copy-Item -Path $csvPath -Destination $canonicalCsvPath -Force
- Write-Host "Canonical copy created: $canonicalCsvPath (edit this one)"
-
- # ---- README_Instructions.txt explaining what to do with the CSV ----
- $installedVersion = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generatedUtc = (Get-Date).ToUniversalTime().ToString("yyyy-MM-dd HH:mm:ss 'UTC'")
- $readmePath = Join-Path $outputDir "README_Instructions.txt"
- $readme = @'
- ========================================================================
- Cluster Inventory - Next Steps
- AzLocal.UpdateManagement (UpdateRing tagging workflow)
- ========================================================================
-
- This ZIP contains the cluster inventory generated by the
- 'Inventory Azure Local Clusters' workflow. Use it to assign each
- cluster to an update wave (UpdateRing tag), then commit the result
- back into your repository so the 'Manage UpdateRing Tags' workflow
- can apply the tags to Azure.
-
- ------------------------------------------------------------------------
- FILES IN THIS ARTIFACT
- ------------------------------------------------------------------------
-
- ClusterUpdateRings.csv
- <-- EDIT THIS FILE. Canonical name expected by the 'Manage
- UpdateRing Tags' workflow's default csv_file_path input
- ('config/ClusterUpdateRings.csv').
-
- ClusterInventory_.csv
- Audit / historical copy of this run's inventory. Do NOT edit -
- keep it so you can diff future inventory runs against this
- snapshot.
-
- ClusterInventory_.json
- Machine-readable copy for dashboards / custom integrations.
-
- README_Instructions.txt
- This file.
-
- ------------------------------------------------------------------------
- STEP 1 - Open ClusterUpdateRings.csv in Excel
- ------------------------------------------------------------------------
+ Invoke-AzLocalClusterInventory `
+ -OutputDirectory './artifacts' `
+ -SubscriptionFilter $env:INPUT_SUBSCRIPTION_FILTER `
+ -InstalledModuleVersion $env:INSTALLED_MODULE_VERSION
- - For each cluster row, fill in the 'UpdateRing' column with the
- wave name you want that cluster to belong to. Examples:
- Canary, Pilot, Production
- (or your own scheme, e.g. Wave1, Wave2, Wave3 / Dev, Test, Prod)
- - Leave the 'UpdateRing' column EMPTY for any cluster you do not
- want this run to tag - those rows will be skipped.
- - Save as CSV (UTF-8). Do not change other columns or column order.
- - Do NOT rename the file. Keep it as 'ClusterUpdateRings.csv' so
- the 'Manage UpdateRing Tags' workflow's default path picks it up.
-
- ------------------------------------------------------------------------
- STEP 2 - Commit ClusterUpdateRings.csv into your ops repository
- ------------------------------------------------------------------------
-
- - Recommended path: config/ClusterUpdateRings.csv
- - Commit and push (PR review optional but recommended).
- - The repo path you commit it to is what you will pass as
- 'csv_file_path' on the next run of the 'Manage UpdateRing Tags'
- workflow.
-
- ------------------------------------------------------------------------
- STEP 3 - Run the 'Manage UpdateRing Tags' workflow
- ------------------------------------------------------------------------
-
- - Open the Actions tab and trigger 'Manage UpdateRing Tags' via
- 'Run workflow'.
- - Set 'csv_file_path' to the path you committed in STEP 2
- (default is 'config/ClusterUpdateRings.csv').
- - RECOMMENDED FIRST RUN: leave 'dry_run' = true. The workflow
- will preview which tags would be set/changed without modifying
- any Azure resources.
- - Once the preview looks correct, re-run with 'dry_run' = false
- to apply the tags. Use 'force' = true only if you need to
- overwrite existing UpdateRing values already set on a cluster.
-
- ------------------------------------------------------------------------
- DOCUMENTATION
- ------------------------------------------------------------------------
-
- Pipeline examples README (online):
- https://github.com/NeilBird/Azure-Local/blob/main/AzLocal.UpdateManagement/Automation-Pipeline-Examples/README.md
-
- Module README (online):
- https://github.com/NeilBird/Azure-Local/blob/main/AzLocal.UpdateManagement/README.md
-
- Module on the PowerShell Gallery:
- https://www.powershellgallery.com/packages/AzLocal.UpdateManagement
-
- Generated by AzLocal.UpdateManagement v__MODULE_VERSION__
- Run timestamp (UTC): __TIMESTAMP__
- ========================================================================
- '@
- $readme = $readme.Replace('__MODULE_VERSION__', "$installedVersion").Replace('__TIMESTAMP__', $generatedUtc)
- Set-Content -Path $readmePath -Value $readme -Encoding ASCII
- Write-Host "Instructions written to: $readmePath"
-
- # Set output for next steps
- echo "CSV_PATH=$csvPath" >> $env:GITHUB_OUTPUT
- echo "JSON_PATH=$jsonPath" >> $env:GITHUB_OUTPUT
- echo "CLUSTER_COUNT=$($inventory.Count)" >> $env:GITHUB_OUTPUT
- id: inventory
-
- name: Compute Artifact Timestamp
id: artifact-stamp
shell: pwsh
@@ -325,39 +162,6 @@ jobs:
path: |
./artifacts/*.csv
./artifacts/*.json
+ ./artifacts/README_Instructions.txt
retention-days: 30
-
- - name: Summary
- shell: pwsh
- run: |
- $csvPath = "${{ steps.inventory.outputs.CSV_PATH }}"
- if (Test-Path $csvPath) {
- $data = Import-Csv $csvPath
-
- "## Cluster Inventory Summary" >> $env:GITHUB_STEP_SUMMARY
- "" >> $env:GITHUB_STEP_SUMMARY
- "| Metric | Value |" >> $env:GITHUB_STEP_SUMMARY
- "|--------|-------|" >> $env:GITHUB_STEP_SUMMARY
- "| Total Clusters | $($data.Count) |" >> $env:GITHUB_STEP_SUMMARY
-
- $withTag = ($data | Where-Object { $_.HasUpdateRingTag -eq 'Yes' }).Count
- $withoutTag = ($data | Where-Object { $_.HasUpdateRingTag -eq 'No' }).Count
- "| With UpdateRing Tag | $withTag |" >> $env:GITHUB_STEP_SUMMARY
- "| Without UpdateRing Tag | $withoutTag |" >> $env:GITHUB_STEP_SUMMARY
-
- "" >> $env:GITHUB_STEP_SUMMARY
- "### UpdateRing Distribution" >> $env:GITHUB_STEP_SUMMARY
- "" >> $env:GITHUB_STEP_SUMMARY
-
- $rings = $data | Where-Object { $_.UpdateRing } | Group-Object UpdateRing
- if ($rings) {
- "| UpdateRing | Count |" >> $env:GITHUB_STEP_SUMMARY
- "|------------|-------|" >> $env:GITHUB_STEP_SUMMARY
- foreach ($ring in $rings) {
- "| $($ring.Name) | $($ring.Count) |" >> $env:GITHUB_STEP_SUMMARY
- }
- } else {
- "No UpdateRing tags found." >> $env:GITHUB_STEP_SUMMARY
- }
- }
diff --git a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.2_manage-updatering-tags.yml b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.2_manage-updatering-tags.yml
index bf8d4df2..bbf815b2 100644
--- a/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.2_manage-updatering-tags.yml
+++ b/AzLocal.UpdateManagement/Automation-Pipeline-Examples/github-actions/Step.2_manage-updatering-tags.yml
@@ -64,7 +64,7 @@ env:
# this to the version actually installed and to the latest on PSGallery, and emits a
# ::notice annotation if the YAML appears stale - prompting you to refresh via
# Copy-AzLocalPipelineExample -Update. See Automation-Pipeline-Examples/README.md section 5.
- GENERATED_AGAINST_MODULE_VERSION: '0.8.4'
+ GENERATED_AGAINST_MODULE_VERSION: '0.8.5'
# Resolution order for the module version pin (leave all unset to install the latest,
# which is the default "fix-forward" behaviour): manual workflow_dispatch input >
# repository variable 'REQUIRED_MODULE_VERSION' > empty (latest).
@@ -119,102 +119,35 @@ jobs:
shell: pwsh
env:
INPUT_CSV_FILE_PATH: ${{ github.event.inputs.csv_file_path }}
+ # v0.8.5 thin-YAML: the existence + missing-file operator messaging is
+ # now produced by Set-AzLocalClusterUpdateRingTagFromCsv itself. This
+ # step still runs first to fail fast (and to surface the path) before
+ # we spend time installing the module.
run: |
$csvPath = $env:INPUT_CSV_FILE_PATH
-
if (-not (Test-Path $csvPath)) {
Write-Host "ERROR: CSV file not found at path: $csvPath" -ForegroundColor Red
+ Write-Host "The full TWO-STAGE operator workflow guidance will be emitted by"
+ Write-Host "Set-AzLocalClusterUpdateRingTagFromCsv when the Apply step runs."
Write-Host ""
- Write-Host "===========================================================================" -ForegroundColor Yellow
- Write-Host " UpdateRing tagging is a TWO-STAGE workflow. You must run the inventory" -ForegroundColor Yellow
- Write-Host " workflow first, edit the CSV, commit it, then re-run THIS workflow." -ForegroundColor Yellow
- Write-Host "===========================================================================" -ForegroundColor Yellow
+ Write-Host "Quick recap:"
+ Write-Host " 1. Run Step.1 (Inventory) and download/edit/commit the CSV."
+ Write-Host " 2. Re-run this Step.2 with csv_file_path pointing to the committed CSV."
Write-Host ""
- Write-Host "STEP 1 - Generate the cluster inventory (one-off, then on demand)" -ForegroundColor Cyan
- Write-Host " a. Go to the 'Actions' tab in this repository."
- Write-Host " b. Open the workflow named 'Inventory Azure Local Clusters'"
- Write-Host " (file: .github/workflows/Step.1_inventory-clusters.yml)."
- Write-Host " c. Click 'Run workflow' and wait for the run to finish successfully."
- Write-Host " d. On the completed run page, scroll to the 'Artifacts' section and"
- Write-Host " download the artifact named 'cluster-inventory'."
- Write-Host " e. Unzip it locally. You will get 'ClusterUpdateRings.csv' (the one"
- Write-Host " to edit), a timestamped audit copy, a .json copy, and a"
- Write-Host " 'README_Instructions.txt' file that mirrors these instructions."
- Write-Host ""
- Write-Host "STEP 2 - Edit the CSV in Excel" -ForegroundColor Cyan
- Write-Host " a. Open 'ClusterUpdateRings.csv' in Excel."
- Write-Host " b. For each cluster row, fill in the 'UpdateRing' column with the wave"
- Write-Host " name you want that cluster to belong to. Examples:"
- Write-Host " Canary, Pilot, Production"
- Write-Host " (or your own scheme, e.g. Wave1, Wave2, Wave3 / Dev, Test, Prod)."
- Write-Host " c. Leave the 'UpdateRing' column EMPTY for any cluster you do not want"
- Write-Host " this run to tag - those rows will be skipped."
- Write-Host " d. Save as CSV (UTF-8). Do not change other columns or column order."
- Write-Host " e. Do NOT rename the file - keep it as 'ClusterUpdateRings.csv' so"
- Write-Host " the default 'csv_file_path' below picks it up."
- Write-Host ""
- Write-Host "STEP 3 - Commit the edited CSV to this repository" -ForegroundColor Cyan
- Write-Host " a. Copy the edited CSV into a stable location in this repo, for example:"
- Write-Host " config/ClusterUpdateRings.csv"
- Write-Host " b. Commit and push it (PR review optional but recommended)."
- Write-Host " c. The path you commit it to is what you will pass as 'csv_file_path'"
- Write-Host " on the next run of this workflow."
- Write-Host ""
- Write-Host "STEP 4 - Re-run THIS workflow ('Manage UpdateRing Tags')" -ForegroundColor Cyan
- Write-Host " a. Click 'Run workflow' on this workflow."
- Write-Host " b. Set 'csv_file_path' to the path you committed in step 3"
- Write-Host " (default is 'config/ClusterUpdateRings.csv')."
- Write-Host " c. RECOMMENDED FIRST RUN: leave 'dry_run' = true to preview which tags"
- Write-Host " would be set/changed, without modifying any Azure resources."
- Write-Host " d. Once the preview looks correct, re-run with 'dry_run' = false to"
- Write-Host " apply the tags. Use 'force' = true only if you need to overwrite"
- Write-Host " existing UpdateRing values already set on a cluster."
- Write-Host ""
- Write-Host "Documentation:" -ForegroundColor Yellow
+ Write-Host "Docs:"
Write-Host " AzLocal.UpdateManagement/README.md - 'Update Rings' section"
Write-Host " AzLocal.UpdateManagement/Automation-Pipeline-Examples/README.md"
- Write-Host ""
- Write-Host "The path you supplied ('$csvPath') does not exist in the checked-out" -ForegroundColor Red
- Write-Host "branch of this repository. Did you forget to commit the CSV, point at" -ForegroundColor Red
- Write-Host "the wrong branch on 'Run workflow', or mistype the path?" -ForegroundColor Red
exit 1
}
-
Write-Host "Found CSV file: $csvPath"
echo "CSV_PATH=$csvPath" >> $env:GITHUB_OUTPUT
id: csv-path
-
- - name: Validate CSV File
- shell: pwsh
- run: |
- $csvPath = "${{ steps.csv-path.outputs.CSV_PATH }}"
- $data = Import-Csv $csvPath
-
- Write-Host "CSV File: $csvPath"
- Write-Host "Total Rows: $($data.Count)"
-
- # Check required columns
- $requiredColumns = @('ResourceId', 'UpdateRing')
- $columns = $data[0].PSObject.Properties.Name
-
- foreach ($col in $requiredColumns) {
- if ($col -notin $columns) {
- Write-Error "Required column '$col' not found in CSV"
- exit 1
- }
- }
-
- # Count rows with UpdateRing values
- $rowsWithValues = ($data | Where-Object { $_.UpdateRing -and $_.UpdateRing.Trim() -ne '' }).Count
- Write-Host "Rows with UpdateRing values: $rowsWithValues"
-
- if ($rowsWithValues -eq 0) {
- Write-Warning "No rows have UpdateRing values set. Please edit the CSV and set UpdateRing values before running this pipeline."
- exit 1
- }
-
+
- name: Install AzLocal.UpdateManagement from PSGallery
+ # v0.8.5 thin-YAML: drift detection + banner + step outputs are all
+ # produced by Add-AzLocalPipelineVersionBanner (Public cmdlet).
shell: pwsh
+ id: module-version
run: |
$ErrorActionPreference = 'Stop'
$installArgs = @{ Name = 'AzLocal.UpdateManagement'; Scope = 'CurrentUser'; Force = $true; AllowClobber = $true }
@@ -226,105 +159,42 @@ jobs:
}
Install-Module @installArgs
Import-Module AzLocal.UpdateManagement -Force
- $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
- $generated = [version]$env:GENERATED_AGAINST_MODULE_VERSION
- $latest = (Find-Module -Name AzLocal.UpdateManagement -Repository PSGallery -ErrorAction SilentlyContinue).Version
- Write-Host ""
- Write-Host "Module version summary"
- Write-Host " Installed on runner : $installed"
- Write-Host " YAML generated against : $generated"
- Write-Host " Latest on PSGallery : $(if ($latest) { $latest } else { '(lookup failed - check network)' })"
- Write-Host ""
- Get-Module AzLocal.UpdateManagement | Format-List Name, Version, Path
- # Drift signal 0: the module installed at runtime is OLDER than the version this YAML was generated against. Cmdlets, parameters, or output schemas referenced by this YAML may not exist in the installed module - emitted as a warning because this is the most likely cause of a hard runtime failure later in the job.
- if ($installed -lt $generated) {
- $msg = "AzLocal.UpdateManagement v$installed is OLDER than the version this workflow YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Destination .\.github\workflows -Platform GitHub -Update'."
- Write-Host "::warning title=AzLocal.UpdateManagement is older than workflow YAML expects::$msg"
- }
- if ($installed -gt $generated) {
- $msg = "Workflow YAML was generated against AzLocal.UpdateManagement v$generated but the runner installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Destination .\.github\workflows -Platform GitHub -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
- Write-Host "::notice title=Workflow YAML may be stale::$msg"
- }
- if ($latest -and ($latest -gt $installed)) {
- $msg = "AzLocal.UpdateManagement v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
- Write-Host "::notice title=Newer AzLocal.UpdateManagement version available on PSGallery::$msg"
- }
+ Add-AzLocalPipelineVersionBanner `
+ -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
+ -PinnedVersion $env:REQUIRED_MODULE_VERSION
- # v0.8.4 - one-line version banner emitted to the rendered Step
- # Summary so the YAML version (GENERATED_AGAINST_MODULE_VERSION), the
- # module version actually loaded on the runner, the PSGallery latest,
- # and the REQUIRED_MODULE_VERSION pin status are visible at the top
- # of every run summary without scrolling the agent log. Same data is
- # also echoed to the console above as 'Module version summary'.
- $pin = if ($env:REQUIRED_MODULE_VERSION) { "pinned to v$($env:REQUIRED_MODULE_VERSION)" } else { 'latest (fix-forward)' }
- $latestStr = if ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
- $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
- elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
- elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
- else { 'in sync' }
- if ($env:GITHUB_STEP_SUMMARY) {
- "_Pipeline YAML v$generated | Module v$installed installed ($pin) | PSGallery latest $latestStr | $verdict_" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
- "" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
- }
-
- name: Apply UpdateRing Tags
+ id: apply-tags
shell: pwsh
env:
- INPUT_FORCE_OVERWRITE: ${{ github.event.inputs.force_overwrite }}
- INPUT_DRY_RUN: ${{ github.event.inputs.dry_run }}
+ INPUT_CSV_FILE_PATH: ${{ steps.csv-path.outputs.CSV_PATH }}
+ INPUT_FORCE_OVERWRITE: ${{ github.event.inputs.force_overwrite }}
+ INPUT_DRY_RUN: ${{ github.event.inputs.dry_run }}
+ INSTALLED_MODULE_VERSION: ${{ steps.module-version.outputs.installed_module_version }}
+ # v0.8.5 thin-YAML: the inline run block (CSV column validation,
+ # Set-AzLocalClusterUpdateRingTag invocation, JSON sidecar write,
+ # outcome tallies, and the GITHUB_STEP_SUMMARY breakdown) has been
+ # condensed into the Public cmdlet
+ # Set-AzLocalClusterUpdateRingTagFromCsv. The cmdlet writes
+ # UpdateRingTag_Results.json to -OutputDirectory, emits the markdown
+ # step summary via GITHUB_STEP_SUMMARY, and sets the eight step
+ # outputs (total_count, created_count, updated_count,
+ # already_in_sync_count, skipped_count, failed_count, whatif_count,
+ # results_json_path).
run: |
$ErrorActionPreference = 'Stop'
Import-Module AzLocal.UpdateManagement -Force
-
- $csvPath = "${{ steps.csv-path.outputs.CSV_PATH }}"
- $forceOverwrite = $env:INPUT_FORCE_OVERWRITE -eq "true"
- $dryRun = $env:INPUT_DRY_RUN -eq "true"
-
- # Create output directory for logs
- $outputDir = "./artifacts"
- New-Item -ItemType Directory -Path $outputDir -Force | Out-Null
-
- # Build parameters
+ $forceOverwrite = $env:INPUT_FORCE_OVERWRITE -eq 'true'
+ $dryRun = $env:INPUT_DRY_RUN -eq 'true'
$params = @{
- InputCsvPath = $csvPath
- LogFolderPath = $outputDir
- }
-
- if ($forceOverwrite) {
- $params['Force'] = $true
- Write-Host "Force mode enabled - will overwrite existing tags"
- }
-
- if ($dryRun) {
- $params['WhatIf'] = $true
- Write-Host "DRY RUN MODE - No changes will be applied"
- }
-
- Write-Host ""
- Write-Host "========================================" -ForegroundColor Cyan
- Write-Host "Applying UpdateRing Tags" -ForegroundColor Cyan
- Write-Host "========================================" -ForegroundColor Cyan
-
- # Run tag management. -PassThru returns the per-cluster results so the
- # Summary step can build a breakdown table rather than parroting only
- # the workflow inputs back at the operator.
- $results = Set-AzLocalClusterUpdateRingTag @params -PassThru
-
- # Persist results to a JSON sidecar so the Summary step (separate shell)
- # can read them. Lives in the same artifacts folder that gets uploaded.
- $resultsJsonPath = Join-Path $outputDir 'UpdateRingTag_Results.json'
- if ($null -ne $results) {
- @($results) | ConvertTo-Json -Depth 5 | Out-File -FilePath $resultsJsonPath -Encoding utf8
- Write-Host "Wrote $($results.Count) per-cluster result row(s) to: $resultsJsonPath"
- } else {
- '[]' | Out-File -FilePath $resultsJsonPath -Encoding utf8
- Write-Host "No per-cluster results returned (empty CSV?). Wrote empty array to: $resultsJsonPath"
+ InputCsvPath = $env:INPUT_CSV_FILE_PATH
+ OutputDirectory = './artifacts'
+ InstalledModuleVersion = $env:INSTALLED_MODULE_VERSION
}
+ if ($forceOverwrite) { $params['Force'] = $true }
+ if ($dryRun) { $params['WhatIf'] = $true }
+ Set-AzLocalClusterUpdateRingTagFromCsv @params
- Write-Host ""
- Write-Host "Tag management complete"
- id: apply-tags
-
- name: Compute Artifact Timestamp
id: artifact-stamp
shell: pwsh
@@ -341,77 +211,4 @@ jobs:
name: azlocal-step.2-updatering-tag-logs_${{ steps.artifact-stamp.outputs.timestamp }}
path: ./artifacts/*
retention-days: 30
-
- - name: Summary
- shell: pwsh
- env:
- INPUT_DRY_RUN: ${{ github.event.inputs.dry_run }}
- INPUT_FORCE_OVERWRITE: ${{ github.event.inputs.force_overwrite }}
- run: |
- "## UpdateRing Tag Management Summary" >> $env:GITHUB_STEP_SUMMARY
- "" >> $env:GITHUB_STEP_SUMMARY
-
- $dryRun = $env:INPUT_DRY_RUN -eq "true"
- $forceOverwrite = $env:INPUT_FORCE_OVERWRITE -eq "true"
-
- "| Setting | Value |" >> $env:GITHUB_STEP_SUMMARY
- "|---------|-------|" >> $env:GITHUB_STEP_SUMMARY
- "| Dry Run | $dryRun |" >> $env:GITHUB_STEP_SUMMARY
- "| Force Overwrite | $forceOverwrite |" >> $env:GITHUB_STEP_SUMMARY
-
- # Per-cluster results breakdown - read the JSON sidecar the apply step wrote.
- # See AzLocal.UpdateManagement Set-AzLocalClusterUpdateRingTag -PassThru schema.
- $resultsJsonPath = './artifacts/UpdateRingTag_Results.json'
- if (Test-Path $resultsJsonPath) {
- $results = @(Get-Content -Raw -Path $resultsJsonPath | ConvertFrom-Json)
- $total = $results.Count
- $created = @($results | Where-Object { $_.Action -eq 'Created' -and $_.Status -eq 'Success' }).Count
- $updated = @($results | Where-Object { $_.Action -eq 'Updated' -and $_.Status -eq 'Success' }).Count
- $alreadyInSync = @($results | Where-Object { $_.Status -eq 'AlreadyInSync' }).Count
- $skipped = @($results | Where-Object { $_.Status -eq 'Skipped' }).Count
- $failed = @($results | Where-Object { $_.Status -eq 'Failed' }).Count
- $whatIf = @($results | Where-Object { $_.Status -eq 'WhatIf' }).Count
-
- "" >> $env:GITHUB_STEP_SUMMARY
- "### Result breakdown" >> $env:GITHUB_STEP_SUMMARY
- "" >> $env:GITHUB_STEP_SUMMARY
- "| Outcome | Count |" >> $env:GITHUB_STEP_SUMMARY
- "|---------|------:|" >> $env:GITHUB_STEP_SUMMARY
- "| Total clusters processed | $total |" >> $env:GITHUB_STEP_SUMMARY
- "| Tags created | $created |" >> $env:GITHUB_STEP_SUMMARY
- "| Tags updated | $updated |" >> $env:GITHUB_STEP_SUMMARY
- "| Already in sync (no-op) | $alreadyInSync |" >> $env:GITHUB_STEP_SUMMARY
- "| Skipped (UpdateRing differs, no -Force) | $skipped |" >> $env:GITHUB_STEP_SUMMARY
- if ($whatIf -gt 0) {
- "| WhatIf (dry-run preview) | $whatIf |" >> $env:GITHUB_STEP_SUMMARY
- }
- "| Failed | $failed |" >> $env:GITHUB_STEP_SUMMARY
-
- if ($total -gt 0) {
- "" >> $env:GITHUB_STEP_SUMMARY
- "Per-cluster results ($total rows)
" >> $env:GITHUB_STEP_SUMMARY
- "" >> $env:GITHUB_STEP_SUMMARY
- "| Cluster | Action | Previous | New | Status | Message |" >> $env:GITHUB_STEP_SUMMARY
- "|---------|--------|----------|-----|--------|---------|" >> $env:GITHUB_STEP_SUMMARY
- foreach ($r in $results) {
- $cn = ($r.ClusterName | ForEach-Object { "$_" }) -replace '\|','\|'
- $act = ($r.Action | ForEach-Object { "$_" }) -replace '\|','\|'
- $pv = ($r.PreviousTagValue | ForEach-Object { "$_" }) -replace '\|','\|'
- $nv = ($r.NewTagValue | ForEach-Object { "$_" }) -replace '\|','\|'
- $st = ($r.Status | ForEach-Object { "$_" }) -replace '\|','\|'
- $msg = ($r.Message | ForEach-Object { "$_" }) -replace '\|','\|' -replace '\r?\n',' '
- "| $cn | $act | $pv | $nv | $st | $msg |" >> $env:GITHUB_STEP_SUMMARY
- }
- "" >> $env:GITHUB_STEP_SUMMARY
- "
-separated chips inside one Flag cell.
- $chipList = New-Object 'System.Collections.Generic.List[string]'
- if ($hasStepError) { $chipList.Add(':rotating_light: step errored') | Out-Null }
- if ($stepSeverity -eq 'crit') { $chipList.Add((':rotating_light: step >{0}h' -f ($stepThresholdHours * 2))) | Out-Null }
- elseif ($stepSeverity -eq 'warn') { $chipList.Add((':warning: step >{0}h' -f $stepThresholdHours)) | Out-Null }
- if ($runSeverity -eq 'skull') { $chipList.Add((':skull: run >{0}d' -f ($criticalElapsedDays * 2))) | Out-Null }
- elseif ($runSeverity -eq 'crit') { $chipList.Add((':rotating_light: run >{0}d' -f $criticalElapsedDays)) | Out-Null }
- elseif ($runSeverity -eq 'warn') { $chipList.Add((':warning: run >{0}h' -f $thresholdHours)) | Out-Null }
- if ($chipList.Count -eq 0 -and $r.State -eq 'InProgress') { $chipList.Add('within') | Out-Null }
- $flagDisplay = ($chipList -join '
')
- # SeverityScore - bigger = worse. StepError tops the scale; Failed-latest is just
- # below; skull > crit > warn; tiebreaker is elapsed hours / 24 (days). All Within
- # rows tie at 0 + days; ClusterName is the secondary alphabetical sort.
- $severityScore = 0.0
- if ($hasStepError) { $severityScore += 1000 }
- if ($r.State -eq 'Failed') { $severityScore += 800 }
- if ($runSeverity -eq 'skull') { $severityScore += 500 }
- elseif ($runSeverity -eq 'crit') { $severityScore += 300 }
- elseif ($runSeverity -eq 'warn') { $severityScore += 50 }
- if ($stepSeverity -eq 'crit') { $severityScore += 200 }
- elseif ($stepSeverity -eq 'warn') { $severityScore += 30 }
- $elapsedHoursForScore = if ($elapsed) { $elapsed.TotalHours } else { 0 }
- $severityScore += [math]::Round($elapsedHoursForScore / 24, 2)
- # v0.7.98: surface a meaningful per-row JUnit time= so the Test Reporter
- # widget stops rendering "0ms" totals. For in-flight rows we report how long
- # the run has been going (now - startDt). For unresolved-failed rows with both
- # start and end timestamps we report the actual run duration (end - start).
- # Anything else falls back to 0 (no usable timestamps).
- $runDurationSeconds = 0
- if ($r.State -ne 'InProgress' -and $startDt -and $endDt) {
- $runDurationSeconds = [int][math]::Round(($endDt - $startDt).TotalSeconds, 0)
- } elseif ($elapsed) {
- $runDurationSeconds = [int][math]::Round($elapsed.TotalSeconds, 0)
- }
- if ($runDurationSeconds -lt 0) { $runDurationSeconds = 0 }
- [PSCustomObject]@{
- ClusterName = $r.ClusterName
- ClusterPortalUrl = $clusterPortalUrl
- UpdateName = $r.UpdateName
- UpdateRunPortalUrl = $updateRunPortalUrl
- State = $r.State
- Status = $progressStatus
- CurrentStep = $r.CurrentStep
- Progress = $r.Progress
- StartTimeUtc = if ($startDt) { $startDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
- EndTimeUtc = if ($endDt) { $endDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
- ElapsedDisplay = $elapsedDisplay
- ElapsedHours = if ($elapsed) { [math]::Round($elapsed.TotalHours, 2) } else { '' }
- StepStartTimeUtc = if ($stepStartDt) { $stepStartDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
- StepElapsedDisplay = $stepElapsedDisplay
- StepElapsedHours = $stepElapsedHoursVal
- ExceedsThreshold = $exceeds
- ExceedsStepThreshold = $exceedsStep
- HasStepError = $hasStepError
- IsRecentFailure = $isRecentFailure
- IsUnresolvedFailure = $isUnresolvedFailure
- ThresholdHours = $thresholdHours
- StepThresholdHours = $stepThresholdHours
- CriticalElapsedDays = $criticalElapsedDays
- StepSeverity = $stepSeverity
- RunSeverity = $runSeverity
- StateIcon = $stateIcon
- StatusIcon = $statusIcon
- Flags = $flagDisplay
- SeverityScore = $severityScore
- RunDurationSeconds = $runDurationSeconds
- RunId = $r.RunId
- RunResourceId = if ($r.PSObject.Properties['RunResourceId']) { $r.RunResourceId } else { '' }
- ClusterResourceId = $r.ClusterResourceId
- Duration = $r.Duration
- CurrentStepDetail = $r.CurrentStepDetail
- ErrorMessage = if ($r.PSObject.Properties['ErrorMessage']) { [string]$r.ErrorMessage } else { '' }
- }
- }
-
- $inFlight = @($rows | Where-Object { $_.State -eq 'InProgress' })
- $longRunning = @($inFlight | Where-Object { $_.ExceedsThreshold })
- $longRunningStep = @($inFlight | Where-Object { $_.ExceedsStepThreshold })
- $stepErrored = @($inFlight | Where-Object { $_.HasStepError })
- $recentlyFailed = @($rows | Where-Object { $_.IsRecentFailure })
- $unresolvedFailed = @($rows | Where-Object { $_.IsUnresolvedFailure })
-
- # CSV (always emit, even if empty, so the artifact step has a file)
- if ($rows -and $rows.Count -gt 0) {
- $rows | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName | Export-Csv -Path $monitorCsv -NoTypeInformation -Encoding utf8
- } else {
- '' | Set-Content -Path $monitorCsv -Encoding utf8
- }
-
- # JUnit XML - one per in-flight cluster + one per unresolved-failed cluster.
- # Failure types (v0.7.96):
- # StepError - HIGHEST PRIORITY: properties.progress.status == 'Error' while State is InProgress
- # (canonical "step has errored, run is stuck" signal - independent of elapsed time)
- # LongRunningStep - current step elapsed exceeds per-step threshold
- # LongRunningOverall - BACKSTOP: overall run elapsed exceeds overall threshold
- # RecentFailure - run is in state Failed (kept name for backwards-compatible parsers;
- # emitted for ALL latest-Failed runs, not just those within failureWindowHours)
- # Empty suite (no in-flight + no unresolved failures) still emits valid XML so the publish step works.
- $xmlLines = New-Object 'System.Collections.Generic.List[string]'
- $xmlLines.Add('')
- # v0.7.99: testsuite/testsuites time="0". Per-testcase time= IS still surfaced (gives
- # the Test Reporter widget meaningful per-row durations), but summing wall-clock ages
- # across 5 unrelated stuck runs (e.g. ~88 days) is misleading at the suite header.
- $xmlLines.Add('')
- $tests = $inFlight.Count + $unresolvedFailed.Count
- # A single run can trigger ANY combination of StepError + LongRunningStep + LongRunningOverall
- # - we emit the highest-priority match as ONE failure per testcase, so $failures matches the
- # testcase count of actually-failing rows (not the union of failure flags).
- $failures = @($inFlight | Where-Object { $_.HasStepError -or $_.ExceedsStepThreshold -or $_.ExceedsThreshold }).Count + $unresolvedFailed.Count
- $xmlLines.Add((' ' -f $tests, $failures))
- foreach ($r in ($inFlight | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName)) {
- $safeName = ($r.ClusterName -replace '[^A-Za-z0-9_.-]', '_')
- $caseName = "$safeName - $($r.UpdateName) - $($r.CurrentStep)"
- $caseNameXml = [System.Security.SecurityElement]::Escape($caseName)
- if ($r.HasStepError) {
- $errSnippet = if ($r.ErrorMessage) { $r.ErrorMessage } else { '(no errorMessage on deepest failed step)' }
- $msg = ('Progress status is Error (state still InProgress) - step is stuck. CurrentStep: {0}. StepElapsed: {1}. ErrorMessage: {2}' -f $r.CurrentStep, $r.StepElapsedDisplay, $errSnippet)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- } elseif ($r.ExceedsStepThreshold) {
- $msg = ('Current step elapsed {0} exceeds per-step threshold of {1}h. CurrentStep: {2}. Overall elapsed: {3}. Progress: {4}.' -f $r.StepElapsedDisplay, $r.StepThresholdHours, $r.CurrentStep, $r.ElapsedDisplay, $r.Progress)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- } elseif ($r.ExceedsThreshold) {
- $msg = ('Overall elapsed {0} exceeds backstop threshold of {1}h (current step within {2}h per-step budget). CurrentStep: {3}. Progress: {4}.' -f $r.ElapsedDisplay, $r.ThresholdHours, $r.StepThresholdHours, $r.CurrentStep, $r.Progress)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- } else {
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- }
- }
- foreach ($r in ($unresolvedFailed | Sort-Object @{Expression='EndTimeUtc';Descending=$true})) {
- $safeName = ($r.ClusterName -replace '[^A-Za-z0-9_.-]', '_')
- $caseName = "$safeName - $($r.UpdateName) - FAILED"
- $caseNameXml = [System.Security.SecurityElement]::Escape($caseName)
- $detail = if ($r.ErrorMessage) { $r.ErrorMessage } elseif ($r.CurrentStepDetail) { $r.CurrentStepDetail } else { $r.CurrentStep }
- $msg = ('Run failed at {0} UTC. Step: {1}. Detail: {2}.' -f $r.EndTimeUtc, $r.CurrentStep, $detail)
- $msgXml = [System.Security.SecurityElement]::Escape($msg)
- $xmlLines.Add((' ' -f $caseNameXml, $r.RunDurationSeconds))
- $xmlLines.Add((' {0}' -f $msgXml))
- $xmlLines.Add(' ')
- }
- $xmlLines.Add(' ')
- $xmlLines.Add('')
- ($xmlLines -join [Environment]::NewLine) | Set-Content -Path $monitorXml -Encoding utf8
-
- # Job outputs
- "IN_FLIGHT=$($inFlight.Count)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
- "LONG_RUNNING=$($longRunning.Count)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
- "LONG_RUNNING_STEP=$($longRunningStep.Count)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
- "STEP_ERRORED=$($stepErrored.Count)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
- "RECENT_FAILURES=$($recentlyFailed.Count)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
- "UNRESOLVED_FAILURES=$($unresolvedFailed.Count)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
-
- # Markdown step summary
- $md = New-Object 'System.Collections.Generic.List[string]'
- $md.Add('## In-Flight Update Monitor')
- $md.Add('')
- # Top-of-summary status badge (v0.7.98) - single at-a-glance verdict for the whole
- # scope. Critical when ANY stuck-step error, skull/crit run-elapsed, or unresolved
- # Failed latest; Warn when any warn-tier signal; Healthy otherwise.
- $hasCritical = ($stepErrored.Count -gt 0) -or $unresolvedFailed.Count -gt 0 -or @($inFlight | Where-Object { $_.RunSeverity -eq 'skull' -or $_.RunSeverity -eq 'crit' -or $_.StepSeverity -eq 'crit' }).Count -gt 0
- $hasWarn = @($inFlight | Where-Object { $_.StepSeverity -eq 'warn' -or $_.RunSeverity -eq 'warn' }).Count -gt 0
- $statusBadge = if ($hasCritical) {
- $crits = @()
- if ($stepErrored.Count -gt 0) { $crits += "$($stepErrored.Count) stuck step error(s)" }
- $skullCount = @($inFlight | Where-Object { $_.RunSeverity -eq 'skull' }).Count
- $critRunCount = @($inFlight | Where-Object { $_.RunSeverity -eq 'crit' }).Count
- $critStepCount = @($inFlight | Where-Object { $_.StepSeverity -eq 'crit' }).Count
- if ($skullCount -gt 0) { $crits += "$skullCount run(s) > $($criticalElapsedDays * 2)d" }
- if ($critRunCount -gt 0) { $crits += "$critRunCount run(s) > ${criticalElapsedDays}d" }
- if ($critStepCount -gt 0){ $crits += "$critStepCount step(s) > $($stepThresholdHours * 2)h" }
- if ($unresolvedFailed.Count -gt 0) { $crits += "$($unresolvedFailed.Count) unresolved failure(s)" }
- ':red_circle: **Fleet Status: CRITICAL** - ' + ($crits -join ', ')
- } elseif ($hasWarn) {
- $warnCount = @($inFlight | Where-Object { $_.StepSeverity -eq 'warn' -or $_.RunSeverity -eq 'warn' }).Count
- ":yellow_circle: **Fleet Status: WARN** - $warnCount long-running run(s)"
- } elseif ($inFlight.Count -gt 0) {
- ":green_circle: **Fleet Status: HEALTHY** - $($inFlight.Count) in-flight run(s) within all thresholds"
- } else {
- ':white_circle: **Fleet Status: IDLE** - no update runs currently in flight'
- }
- $md.Add($statusBadge)
- $md.Add('')
- $scopeLabel = if ($scope -eq 'by-update-ring' -and $updateRing) { "by-update-ring (UpdateRing = $updateRing)" } else { 'all clusters' }
- $md.Add("**Scope**: $scopeLabel - **Per-step warn/crit**: ${stepThresholdHours}h / $($stepThresholdHours * 2)h - **Overall warn/crit/skull**: ${thresholdHours}h / ${criticalElapsedDays}d / $($criticalElapsedDays * 2)d - **Recent-failure window**: ${failureWindowHours}h - **Snapshot (UTC)**: $($now.ToString('yyyy-MM-dd HH:mm'))")
- $md.Add('')
- $md.Add('| Metric | Count |')
- $md.Add('|--------|-------|')
- $md.Add("| Clusters scoped | $($rows.Count) |")
- $md.Add("| Update runs in flight | $($inFlight.Count) |")
- $md.Add("| Step errored (progress.status == 'Error', state still InProgress) | $($stepErrored.Count) |")
- $md.Add("| Step elapsed > ${stepThresholdHours}h (primary) | $($longRunningStep.Count) |")
- $md.Add("| Overall elapsed > ${thresholdHours}h (backstop) | $($longRunning.Count) |")
- $md.Add("| Unresolved-failed runs (latest run is Failed) | $($unresolvedFailed.Count) |")
- if ($failureWindowHours -gt 0) {
- $md.Add("| Recently-failed runs (last ${failureWindowHours}h) | $($recentlyFailed.Count) |")
- }
- $md.Add('')
- if ($inFlight.Count -gt 0) {
- $md.Add('### In-flight runs (sorted by severity score, worst first)')
- $md.Add('')
- $md.Add('| Cluster | Update | State | Progress Status | Current Step | Progress | Step Started (UTC) | Step Elapsed | Run Started (UTC) | Run Elapsed | Flags |')
- $md.Add('|---------|--------|-------|-----------------|--------------|----------|--------------------|--------------|-------------------|-------------|-------|')
- foreach ($r in ($inFlight | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName)) {
- $cs = if ($r.CurrentStep) { $r.CurrentStep } else { '-' }
- $pg = if ($r.Progress) { $r.Progress } else { '-' }
- $stepStart = if ($r.StepStartTimeUtc) { $r.StepStartTimeUtc } else { '-' }
- # Per-cell icons (v0.7.98). State + Status get inline icons; Step/Run elapsed
- # cells get a severity prefix so the worst rows are scannable without reading
- # the Flags column. Avoid nested inline-if expressions - they parse but at
- # runtime PowerShell treats the inner (if ...) as a command call ("'if' is not
- # recognized as the name of a cmdlet"). Use elseif chains instead.
- $stateCell = if ($r.StateIcon) { "$($r.StateIcon) $($r.State)" } else { [string]$r.State }
- $statusCell = if (-not $r.Status) { '-' }
- elseif ($r.StatusIcon) { "$($r.StatusIcon) $($r.Status)" }
- else { [string]$r.Status }
- $stepElPrefix = switch ($r.StepSeverity) { 'crit' { ':rotating_light: ' } 'warn' { ':warning: ' } default { '' } }
- $runElPrefix = switch ($r.RunSeverity) { 'skull' { ':skull: ' } 'crit' { ':rotating_light: ' } 'warn' { ':warning: ' } default { '' } }
- $stepEl = if ($r.StepElapsedDisplay) { $stepElPrefix + $r.StepElapsedDisplay } else { '-' }
- $runEl = if ($r.ElapsedDisplay) { $runElPrefix + $r.ElapsedDisplay } else { '-' }
- $flagCell = if ($r.Flags) { $r.Flags } else { '-' }
- # target=_blank so links open in a new tab (preserves the workflow summary tab).
- $clusterCell = if ($r.ClusterPortalUrl) { '' + $r.ClusterName + '' } else { $r.ClusterName }
- $updateCell = if ($r.UpdateRunPortalUrl) { '' + $r.UpdateName + '' } else { $r.UpdateName }
- $md.Add("| $clusterCell | $updateCell | $stateCell | $statusCell | $cs | $pg | $stepStart | $stepEl | $($r.StartTimeUtc) | $runEl | $flagCell |")
- }
- $md.Add('')
- } else {
- $md.Add('### No update runs currently in flight')
- $md.Add('')
- $md.Add("No clusters in scope have a latest run in state ``InProgress``. To verify scope, see the artifact CSV (``update-monitor.csv``).")
- $md.Add('')
- }
- if ($unresolvedFailed.Count -gt 0) {
- $md.Add('### Failed runs (latest run is Failed, unresolved - shown regardless of age)')
- $md.Add('')
- $md.Add('| Cluster | Update | Ended (UTC) | Failed Step | Verbose Error Details | Recent |')
- $md.Add('|---------|--------|-------------|-------------|-----------------------|--------|')
- foreach ($r in ($unresolvedFailed | Sort-Object @{Expression='EndTimeUtc';Descending=$true})) {
- $cs = if ($r.CurrentStep) { $r.CurrentStep } else { '-' }
- # Verbose error column (v0.7.98) - mirror Step.8 pattern: full error body inside
- # a collapsible so the row stays compact but operators can expand for
- # the entire stack trace. HTML-encode <, >, & so embedded markup doesn't render
- # as tags; escape pipes; collapse newlines to
so multi-line traces stay
- # readable inside the panel. CurrentStepDetail is used when ErrorMessage is
- # empty (older runs without the deep-error projection).
- $rawDetail = if ($r.ErrorMessage) { [string]$r.ErrorMessage } elseif ($r.CurrentStepDetail) { [string]$r.CurrentStepDetail } else { '' }
- $detailCell = if ([string]::IsNullOrWhiteSpace($rawDetail)) { '_(no error detail)_' } else {
- $e = $rawDetail -replace '&','&' -replace '<','<' -replace '>','>'
- $e = $e -replace "`r`n",'
' -replace "`n",'
' -replace '\|','\|'
- 'Show error
' + $e + '
'
- # as a line break inside a cell.
- $updateVersionsCell = (($groupRows | ForEach-Object {
- '{0} x {1}' -f $_.Version, $_.Count
- }) -join '
')
- # Union of cluster names across versions in this YYMM. Each
- # cluster appears in exactly one CurrentVersion row, so a
- # simple concat + sort -Unique is sufficient.
- $clusterNames = @()
- foreach ($r in $groupRows) {
- if ($r.Clusters) {
- $clusterNames += @($r.Clusters -split '; ' | Where-Object { $_ })
- }
- }
- $clusterNames = @($clusterNames | Sort-Object -Unique)
- $clCell = if ($clusterNames.Count -le 15) {
- $clusterNames -join '; '
- } else {
- (($clusterNames | Select-Object -First 15) -join '; ') + (' ... (+{0} more)' -f ($clusterNames.Count - 15))
- }
- $clCell = $clCell -replace '\|','\|'
- $versionSection += ('| {0} | {1} | {2} | {3} | {4}% | {5} |' -f $yymmDisplay, $updateVersionsCell, $supportEmoji, $totalCount, $totalPct, $clCell) + "`n"
- }
- $versionSection += "`n_Support roll-up: Supported = $supportedClusters cluster(s), Unsupported = $unsupportedClusters, Unknown = $unknownVersionClusters. Anchor source: ``$supportSource``._`n"
- $versionSection += "_Note: the **Clusters (first 15 shown only)** column is intentionally truncated for readability. Download ``readiness-status.csv`` from artifacts to see the full cluster-name list._`n`n"
- } catch {
- Write-Warning "Failed to render Fleet Version Distribution markdown table: $($_.Exception.Message)"
- $versionSection = ''
- }
- }
-
- $summary = @"
- ## Fleet Update Status Summary _(generated $generatedUtc)_
-
- $versionSection
- ### Critical Health Status (matches JUnit XML pass/fail)
-
- | Metric | Count | Status |
- |--------|-------|--------|
- | **Passed** (healthy, no failures, not SBE-blocked) | $chPassed | ✅ |
- | **Failed** (HealthState=Failure OR UpdateState=Failed OR SBE prerequisite blocked) | $chFailed | $(if ([int]$chFailed -gt 0) { '❌' } else { '✅' }) |
-
- ### Primary Status (each cluster counted once; rows sum to Total Clusters)
-
- | Metric | Count | Status |
- |--------|-------|--------|
- | **Total Clusters** | $total | ℹ️ |
- | **Up to Date** | $upToDate | ✅ |
- | **Ready for Update** | $ready | 🟢 |
- | **Update In Progress** | $inProgress | 🔄 |
- | **SBE Prerequisite Blocked** | $sbeBlocked | $(if ([int]$sbeBlocked -gt 0) { '🟡' } else { '✅' }) |
- | **Health Failure** (HealthState=Failure) | $healthFailure | $(if ([int]$healthFailure -gt 0) { '❌' } else { '✅' }) |
- | **Update Failed** (Failed / UpdateFailed / NeedsAttention) | $updateFailed | $(if ([int]$updateFailed -gt 0) { '❌' } else { '✅' }) |
- | **Action Required** (PreparationFailed) | $actionRequired | $(if ([int]$actionRequired -gt 0) { '❌' } else { '✅' }) |
- | **Needs Investigation** | $needsInvestigation | $(if ([int]$needsInvestigation -gt 0) { '⚠️' } else { '✅' }) |
-
- Priority cascade used to bucket each cluster exactly once:
- Update Failed > Action Required > Health Failure > SBE Prerequisite Blocked > Update In Progress > Ready for Update > Up to Date > Needs Investigation.
- "@
-
- # Actions Required section
- $actions = @()
- if ([int]$updateFailed -gt 0) { $actions += "- **$updateFailed cluster(s) have UpdateState in (Failed, UpdateFailed, NeedsAttention)** - Review the most recent update run in Azure Portal and the ``update-runs.csv`` artifact for the failure detail." }
- if ([int]$actionRequired -gt 0) { $actions += "- **$actionRequired cluster(s) have UpdateState=PreparationFailed** - Update preparation hit a blocker before the run started. Inspect the cluster activity log (most common: prerequisite-check failure, missing SBE content, ARB extension drift). Resolve before re-arming the update." }
- if ([int]$healthFailure -gt 0) { $actions += "- **$healthFailure cluster(s) have HealthState=Failure** - Resolve critical health check issues in Azure Portal before retrying any updates." }
- if ([int]$hasPrerequisite -gt 0) { $actions += "- **$hasPrerequisite cluster(s) blocked by SBE prerequisite** - Install the required Solution Builder Extension (SBE) update from the hardware vendor. See ``available-updates.csv`` for vendor details (Publisher, Family)." }
-
- if ($actions.Count -gt 0) {
- $summary += "`n`n### Actions Required`n`n"
- $summary += ($actions -join "`n")
- }
-
- # Update Run History table: ARG-first view of unresolved failures.
- # Cluster/Update cells link to portal; Error Details are collapsed
- # behind with HTML-escaping so stack traces stay intact.
- $runHistoryCount = "${{ steps.fleet-status.outputs.RUN_HISTORY_COUNT }}"
- $runHistoryB64 = "${{ steps.fleet-status.outputs.RUN_HISTORY_B64 }}"
- if ($runHistoryCount -and ([int]$runHistoryCount) -gt 0 -and $runHistoryB64) {
- try {
- $rows = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($runHistoryB64)) | ConvertFrom-Json
- # v0.7.90 dedupe: collapse same-error reruns - group by
- # (ClusterName, UpdateName, DeepestErrMsg); canonical row = latest
- # StartTime; older N-1 rows listed inside the panel.
- $groups = @($rows) | Group-Object -Property @{
- Expression = { "$($_.ClusterName)|$($_.UpdateName)|$($_.DeepestErrMsg)" }
- }
- $renderRows = @()
- foreach ($g in $groups) {
- $ordered = @($g.Group | Sort-Object @{ Expression = 'StartTime'; Descending = $true })
- $latest = $ordered[0]
- $extras = @($ordered | Select-Object -Skip 1)
- $latest | Add-Member -NotePropertyName 'EarlierOccurrences' -NotePropertyValue $extras -Force
- $renderRows += $latest
- }
- # Preserve top-of-table = latest run across the whole fleet
- $renderRows = @($renderRows | Sort-Object @{Expression='StartTime';Descending=$true}, @{Expression='ClusterName';Descending=$false})
- $totalRows = (@($rows)).Count
- $groupCount = $renderRows.Count
- $dedupSuffix = if ($groupCount -lt $totalRows) { " (collapsed $totalRows run(s) into $groupCount unique failure group(s); older same-error reruns are listed inside each row's 'Show error' panel)" } else { '' }
- $summary += "`n`n### 📜 Update Run History and Error Details`n`n"
- $summary += "_ARG-first, fleet-scale failure-detail view. Shows up to 25 most recent unresolved Failed update runs (last 30 days). Source cmdlet: ``Get-AzLocalUpdateRunFailures -State Failed -OnlyUnresolved``.$dedupSuffix._`n`n"
- $summary += "| Cluster Name | Update Name | Update State | Status | Current Step | Verbose Error Details | Duration | Time Started | Last Updated |`n"
- $summary += "|---|---|---|---|---|---|---|---|---|`n"
- foreach ($r in $renderRows) {
- $errCell = if ($r.DeepestErrMsg) {
- $e = [string]$r.DeepestErrMsg
- # HTML-encode so '<', '>', '&' in stack traces don't get
- # parsed as tags by the renderer; escape pipes so the
- # table row stays intact; collapse newlines to
so
- # multi-line stack traces remain readable inside the
- # collapsible block.
- $e = $e -replace '&','&' -replace '<','<' -replace '>','>'
- $e = $e -replace "`r`n",'
' -replace "`n",'
' -replace '\|','\|'
- $extraBlock = ''
- if ($r.EarlierOccurrences -and @($r.EarlierOccurrences).Count -gt 0) {
- $bullets = (@($r.EarlierOccurrences) | ForEach-Object {
- $dur = if ($_.Duration) { " (Duration: $($_.Duration))" } else { '' }
- "• Started $($_.StartTime), Last updated $($_.LastUpdated)$dur"
- }) -join '
'
- $extraBlock = '
Earlier occurrences with the same error (' + (@($r.EarlierOccurrences).Count) + '):
' + $bullets
- }
- 'Show error
' + $e + '' + $extraBlock + ' block per cluster. The
- # carries the cluster name (linkified to portal), a severity tally
- # ('[Critical] x N · [Warning] x M', non-zero tiers only, Critical first)
- # and the most-recent LastOccurrence across all that cluster's rows. The
- # expanded body holds the existing per-failure table.
- #
- # Cluster ordering: CriticalCount desc, then WarningCount desc, then
- # most-recent LastOccurrence desc (worst-cluster-first). Within a cluster,
- # rows sort Critical-first then LastOccurrence desc.
- #
- # Cap is per-CLUSTER (not per-row) so no cluster's failures are silently
- # truncated. CSV artifact always has every row.
- $md += "`n*Click a cluster to expand its failing health checks. Worst-affected clusters appear first.*`n"
-
- $detailByCluster = @(
- $detailRows | Group-Object -Property ClusterName | ForEach-Object {
- $rows = @($_.Group)
- $crit = @($rows | Where-Object { $_.Severity -eq 'Critical' }).Count
- $warn = @($rows | Where-Object { $_.Severity -eq 'Warning' }).Count
- $portalRow = $rows | Where-Object {
- $_.PSObject.Properties.Match('ClusterPortalUrl').Count -gt 0 -and $_.ClusterPortalUrl
- } | Select-Object -First 1
- $lastOcc = ($rows | Measure-Object -Property LastOccurrence -Maximum).Maximum
- [PSCustomObject]@{
- ClusterName = $_.Name
- ClusterPortalUrl = if ($portalRow) { [string]$portalRow.ClusterPortalUrl } else { '' }
- CriticalCount = $crit
- WarningCount = $warn
- LastOccurrence = $lastOcc
- Rows = @(
- $rows | Sort-Object @{Expression={ if($_.Severity -eq 'Critical'){1}else{2} };Descending=$false},
- @{Expression={$_.LastOccurrence};Descending=$true}
- )
- }
- } | Sort-Object @{Expression={$_.CriticalCount};Descending=$true},
- @{Expression={$_.WarningCount};Descending=$true},
- @{Expression={$_.LastOccurrence};Descending=$true}
- )
-
- $totalClusters = $detailByCluster.Count
- $clustersToShow = @($detailByCluster | Select-Object -First 100)
-
- foreach ($cl in $clustersToShow) {
- $sevParts = @()
- if ($cl.CriticalCount -gt 0) { $sevParts += ('[Critical] x {0}' -f $cl.CriticalCount) }
- if ($cl.WarningCount -gt 0) { $sevParts += ('[Warning] x {0}' -f $cl.WarningCount) }
- $sevTally = $sevParts -join ' · '
-
- # target="_blank" so clicking the cluster name in the
- # opens the portal in a new tab and leaves the pipeline run open.
- $clusterCell = if ($cl.ClusterPortalUrl) {
- '{1}' -f $cl.ClusterPortalUrl, $cl.ClusterName
- } else {
- $cl.ClusterName
- }
- $lastOccStr = if ($cl.LastOccurrence) { ('{0:yyyy-MM-ddTHH:mm:ssZ}' -f $cl.LastOccurrence) } else { '-' }
-
- $md += "`n`n"
- $md += "$clusterCell · $sevTally · last $lastOccStr
`n`n"
- $md += "| Severity | Failure Reason | Failure Remediation | Target Resource Name | Target Resource Type | Last Occurrence | Resource Group |`n"
- $md += "|----------|----------------|---------------------|----------------------|----------------------|------------------|----------------|`n"
- foreach ($r in $cl.Rows) {
- $sevTag = if ($r.Severity -eq 'Critical') { '[Critical]' } else { '[Warning]' }
- $rem = if ($r.PSObject.Properties.Match('Remediation').Count -gt 0) { [string]$r.Remediation } else { '' }
- # Remediation links open in a new tab so the operator can
- # read the Microsoft Learn / docs page without losing the
- # pipeline run.
- $remCell = if ($rem -and $rem.StartsWith('https://')) { 'link' -f $rem } else { $rem }
- $tName = if ($r.PSObject.Properties.Match('TargetResourceName').Count -gt 0) { [string]$r.TargetResourceName } else { '' }
- $tType = if ($r.PSObject.Properties.Match('TargetResourceType').Count -gt 0) { [string]$r.TargetResourceType } else { '' }
- $md += ('| {0} | {1} | {2} | {3} | {4} | {5} | {6} |' -f $sevTag, $r.FailureReason, $remCell, $tName, $tType, $r.LastOccurrence, $r.ResourceGroup) + "`n"
- }
- $md += "`n `n"
- }
-
- if ($totalClusters -gt 100) {
- $md += "`n*Showing first 100 clusters of $totalClusters; see ``fleet-health-detail.csv`` artifact for the full list.*`n"
- }
- }
-
- $md += @"
-
- ### Reports Available
- - ``fleet-health-detail.csv`` - one row per (cluster, failing health check)
- - ``fleet-health-summary.csv`` - one row per (FailureReason, Severity); ordered Critical-first, then by ClusterCount desc
- - ``fleet-health-overview.csv`` - one row per cluster (ARG-first fleet health summary)
- - ``fleet-health-detail.json`` / ``fleet-health-summary.json`` / ``fleet-health-overview.json`` - same data, machine-readable
- - ``fleet-health-status.xml`` - JUnit XML for CI/CD visualisation
-
- _Note: test sections prefixed **[JUnit Debug]** in the Tests view are a diagnostic mirror of the tables above (for CI tooling/ITSM integration). For primary readability, use this summary and the CSV artifacts._
-
- *Generated at $(Get-Date -Format "yyyy-MM-dd HH:mm:ss UTC")*
- "@
-
- $md | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
-
- # Publish JUnit test results AFTER the markdown summary so the "Fleet Health
- # Status Summary" tables are the first thing visible on the run page. dorny
- # renders its testsuite expansion below; list-suites and list-tests are set
- # to "failed" so the expansion stays compact even for fleets where many
- # clusters report the same failure reason.
- name: Publish JUnit Diagnostic Results
uses: dorny/test-reporter@v3
if: always()
@@ -788,4 +340,3 @@ jobs:
path: ./reports/itsm-results.xml
reporter: java-junit
continue-on-error: true
-
diff --git a/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psd1 b/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psd1
index 4fd6705d..36ef40a9 100644
--- a/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psd1
+++ b/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psd1
@@ -3,7 +3,7 @@
RootModule = 'AzLocal.UpdateManagement.psm1'
# Version number of this module.
- ModuleVersion = '0.8.4'
+ ModuleVersion = '0.8.5'
# Supported PSEditions
CompatiblePSEditions = @('Desktop', 'Core')
@@ -96,6 +96,8 @@
'Private/Add-AzLocalPipelineStepSummary.ps1',
'Private/Write-AzLocalPipelineNotice.ps1',
'Private/Write-AzLocalPipelineWarning.ps1',
+ # Generic JUnit XML emitter shared by every Public Step.* cmdlet (v0.8.5)
+ 'Private/New-AzLocalPipelineJUnitXml.ps1',
# Public exported functions
'Public/Connect-AzLocalServicePrincipal.ps1',
@@ -103,6 +105,7 @@
'Public/Copy-AzLocalPipelineExample.ps1',
'Public/Export-AzLocalFleetState.ps1',
'Public/Get-AzLocalApplyUpdatesScheduleConfig.ps1',
+ 'Public/Get-AzLocalApplyUpdatesScheduleCycleCalendar.ps1',
'Public/Get-AzLocalApplyUpdatesScheduleNextFirings.ps1',
'Public/Get-AzLocalAvailableUpdates.ps1',
'Public/Get-AzLocalClusterInfo.ps1',
@@ -135,7 +138,34 @@
'Public/Update-AzLocalApplyUpdatesScheduleConfig.ps1',
'Public/Update-AzLocalPipelineExample.ps1',
'Public/Get-AzLocalFleetConnectivityStatus.ps1',
- 'Public/New-AzLocalFleetConnectivityStatusSummary.ps1'
+ 'Public/New-AzLocalFleetConnectivityStatusSummary.ps1',
+ # Thin-YAML pipeline foundation (v0.8.5)
+ 'Public/Add-AzLocalPipelineVersionBanner.ps1',
+ # Thin-YAML Step.0 (v0.8.5) - Authentication validation + subscription scope + cluster reachability
+ 'Public/Export-AzLocalAuthValidationReport.ps1',
+ # Thin-YAML Step.1 (v0.8.5) - Cluster inventory + canonical CSV + operator README + step summary
+ 'Public/Invoke-AzLocalClusterInventory.ps1',
+ # Thin-YAML Step.2 (v0.8.5) - UpdateRing tag management workload (CSV validation + apply + JSON sidecar + step summary)
+ 'Public/Set-AzLocalClusterUpdateRingTagFromCsv.ps1',
+ # Thin-YAML Step.7 (v0.8.5) - In-flight update-run monitor (severity scoring + CSV + JUnit + step summary + 6 step outputs)
+ 'Public/Export-AzLocalUpdateRunMonitorReport.ps1',
+ # Thin-YAML Step.8 (v0.8.5) - Fleet update status (inventory + readiness + version distribution + 3-suite JUnit XML + step summary + 22 step outputs)
+ 'Public/Export-AzLocalFleetUpdateStatusReport.ps1',
+ # Thin-YAML Step.5 (v0.8.5) - Pre-flight Update Readiness Assessment (readiness + blocking-health JUnit + combined JUnit + 8-section markdown summary + 2 step outputs)
+ 'Public/Export-AzLocalClusterUpdateReadinessReport.ps1',
+ # Thin-YAML Step.4 (v0.8.5) - Fleet Connectivity Status (Cluster/Arc/NIC/ARB severity classification + JUnit XML via shared helper + markdown summary + 12 step outputs)
+ 'Public/Export-AzLocalFleetConnectivityStatusReport.ps1',
+ # Thin-YAML Step.3 (v0.8.5) - Apply-Updates Schedule Coverage Audit (Audit + Matrix + Recommend views + 2-suite JUnit XML + 12-row summary table + allow-list section + always-on cycle calendar + 12 step outputs)
+ 'Public/Export-AzLocalApplyUpdatesScheduleAudit.ps1',
+ # Thin-YAML Step.9 (v0.8.5) - Fleet Health Status (Detail + in-process Summary + Overview + 2-suite JUnit XML + 4-section markdown + 8 step outputs; condenses ~600-line inline run: | block in Step.9_fleet-health-status.yml on both platforms)
+ 'Public/Export-AzLocalFleetHealthStatusReport.ps1',
+ # Thin-YAML Step.6 (v0.8.5) - Apply-Updates pipeline (resolve UpdateRing from schedule + readiness gate report + readiness-gated apply + per-host apply-updates step summary + no-clusters-ready step summary + ITSM ticketing from JUnit artifact; condenses ~6 inline run: | blocks across both Step.6_apply-updates.yml pipelines into 6 testable Public cmdlets)
+ 'Public/Resolve-AzLocalPipelineUpdateRing.ps1',
+ 'Public/Export-AzLocalClusterReadinessGateReport.ps1',
+ 'Public/Invoke-AzLocalReadinessGatedClusterUpdate.ps1',
+ 'Public/Add-AzLocalApplyUpdatesStepSummary.ps1',
+ 'Public/Add-AzLocalNoReadyClustersStepSummary.ps1',
+ 'Public/Invoke-AzLocalItsmTicketingFromArtifact.ps1'
)
FunctionsToExport = @(
@@ -185,6 +215,8 @@
'Get-AzLocalApplyUpdatesScheduleNextFirings',
'New-AzLocalApplyUpdatesScheduleConfig',
'Update-AzLocalApplyUpdatesScheduleConfig',
+ # Cycle Calendar (v0.8.5) - human-readable per-day projection of the resolver for one full cycle (or any -Days horizon), variable cycle length safe, year-boundary safe, per-ring 'next eligible date' summary
+ 'Get-AzLocalApplyUpdatesScheduleCycleCalendar',
# Fleet Health Overview (v0.7.70) - one row per cluster, ARG-first projection of cluster + updateSummaries (fleet-scale)
'Get-AzLocalFleetHealthOverview',
# Latest Released Solution Version (v0.7.70) - public manifest probe (aka.ms/AzureEdgeUpdates) that anchors the rolling YYMM support window
@@ -192,7 +224,34 @@
# Fleet Connectivity Status (v0.7.79) - 4-scope connectivity audit: cluster, Arc agent, physical NIC, ARB
'Get-AzLocalFleetConnectivityStatus',
# Fleet Connectivity Status Summary Renderer (v0.7.87) - markdown step-summary builder used by Step.4 GH+ADO pipelines
- 'New-AzLocalFleetConnectivityStatusSummary'
+ 'New-AzLocalFleetConnectivityStatusSummary',
+ # Thin-YAML pipeline foundation (v0.8.5) - install-step version banner + drift annotations + step outputs (condenses ~50-line inline block in every Step.*.yml)
+ 'Add-AzLocalPipelineVersionBanner',
+ # Thin-YAML Step.0 (v0.8.5) - Authentication validation + subscription scope + cluster reachability (condenses ~200-line inline run: | block in Step.0_authentication-test.yml on both platforms)
+ 'Export-AzLocalAuthValidationReport',
+ # Thin-YAML Step.1 (v0.8.5) - Cluster inventory workload (condenses the inline run: | block in Step.1_inventory-clusters.yml on both platforms; writes timestamped + canonical CSV, JSON, README, and step summary)
+ 'Invoke-AzLocalClusterInventory',
+ # Thin-YAML Step.2 (v0.8.5) - UpdateRing tag management workload (validates CSV, applies tags via Set-AzLocalClusterUpdateRingTag, writes JSON sidecar + step summary)
+ 'Set-AzLocalClusterUpdateRingTagFromCsv',
+ # Thin-YAML Step.7 (v0.8.5) - In-flight update-run monitor (calls Get-AzLocalUpdateRuns -Latest -PassThru, classifies by per-step + overall elapsed + progress-status, writes CSV + JUnit XML + markdown step summary + 6 step outputs)
+ 'Export-AzLocalUpdateRunMonitorReport',
+ # Thin-YAML Step.8 (v0.8.5) - Fleet-wide Azure Local update status snapshot (inventory + readiness + Microsoft-manifest-anchored version distribution + 3-suite JUnit XML + supplementary CSVs + markdown step summary + 22 step outputs; replaces the ~830-line inline 'Collect Fleet Update Status' + 'Create Status Summary' blocks in Step.8_fleet-update-status.yml on both platforms)
+ 'Export-AzLocalFleetUpdateStatusReport',
+ # Thin-YAML Step.5 (v0.8.5) - Pre-flight Update Readiness Assessment (calls Get-AzLocalClusterUpdateReadiness + Test-AzLocalClusterHealth -BlockingOnly, writes per-check CSV + JUnit XML, merges into combined assess-readiness.xml, emits 8-section markdown step summary + 2 step outputs; replaces the ~280-line inline 'Run readiness + blocking health checks' block in Step.5_assess-update-readiness.yml on both platforms)
+ 'Export-AzLocalClusterUpdateReadinessReport',
+ # Thin-YAML Step.4 (v0.8.5) - Fleet Connectivity Status (calls Get-AzLocalFleetConnectivityStatus, classifies severity across Cluster/Arc/NIC/ARB scopes, emits JUnit XML via shared New-AzLocalPipelineJUnitXml helper, renders markdown via shared New-AzLocalFleetConnectivityStatusSummary, emits 12 lowercase step outputs; replaces the ~255-line inline 'Collect Fleet Connectivity Data' block in Step.4_fleet-connectivity-status.yml on both platforms)
+ 'Export-AzLocalFleetConnectivityStatusReport',
+ # Thin-YAML Step.3 (v0.8.5) - Apply-Updates Schedule Coverage Audit (calls Test-AzLocalApplyUpdatesScheduleCoverage Audit + Matrix + Recommend, builds 2-suite JUnit XML via shared New-AzLocalPipelineJUnitXml helper, renders summary table + Schedule/Cron detail tables + allow-list coverage + always-on Cycle calendar via Get-AzLocalApplyUpdatesScheduleCycleCalendar; emits 12 lowercase step outputs; replaces the ~220-line inline 'Run Schedule Coverage Audit' + ~210-line inline 'Create Schedule Coverage Summary' blocks in Step.3_apply-updates-schedule-audit.yml on both platforms; ALWAYS renders the Cycle calendar when -SchedulePath is supplied, fixing the v0.8.4 hasIssues-gate regression that silently dropped the calendar on clean-fleet runs)
+ 'Export-AzLocalApplyUpdatesScheduleAudit',
+ # Thin-YAML Step.9 (v0.8.5) - Fleet Health Status (calls Get-AzLocalFleetHealthFailures Detail + Get-AzLocalFleetHealthOverview, computes Summary view in-process, builds 2-suite JUnit XML via shared New-AzLocalPipelineJUnitXml helper, renders KPI / Overview / By-Reason / per-cluster collapsible markdown; emits 8 lowercase step outputs; replaces the ~600-line inline 'Collect Fleet Health Status' + 'Create Fleet Health Summary' blocks in Step.9_fleet-health-status.yml on both platforms)
+ 'Export-AzLocalFleetHealthStatusReport',
+ # Thin-YAML Step.6 (v0.8.5) - Apply-Updates pipeline (6 cmdlets that condense ~430 lines of inline run: | blocks across both Step.6_apply-updates.yml pipelines into testable, host-aware Public cmdlets; preserves byte-for-byte parity of all markdown summaries, per-host icon literals, and ADO task.logissue warning/error lines)
+ 'Resolve-AzLocalPipelineUpdateRing',
+ 'Export-AzLocalClusterReadinessGateReport',
+ 'Invoke-AzLocalReadinessGatedClusterUpdate',
+ 'Add-AzLocalApplyUpdatesStepSummary',
+ 'Add-AzLocalNoReadyClustersStepSummary',
+ 'Invoke-AzLocalItsmTicketingFromArtifact'
)
# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
@@ -221,20 +280,19 @@
# ReleaseNotes of this module
ReleaseNotes = @'
-## Version 0.8.4 - Step.3 advisor enhancements (NoWindowTag CSV remediation + Cycle calendar + Exclusion windows summary) + Step.6 per-cluster Step Summary + Node 24 opt-in + version banner on every install step + RBAC custom role renamed to `Azure Stack HCI Update Operator (custom)`
-
-Step.3 advisor enhancement release. No public API removed. One new optional parameter on `Test-AzLocalApplyUpdatesScheduleCoverage`: `-ClusterCsvPath `. Two new informational sections on `-View Recommend` that render whenever `-SchedulePath` is supplied (Step.3 yml now passes it). All v0.8.3 behaviour preserved unchanged.
-
-- **Enhancement A - NoWindowTag CSV remediation (new `-ClusterCsvPath` parameter).** When the operator supplies the path to the source-controlled cluster inventory CSV (the file Step.2 consumes - default `config/ClusterUpdateRings.csv`), `-View Recommend` emits a new `## Action required - NoWindowTag remediation` section. For each cluster that has an `UpdateRing` tag but no `UpdateStartWindow` tag, the advisor proposes a **peer-derived `UpdateStartWindow` value** (mode of peers' values in the same ring) plus a source label explaining the choice (unanimous / majority / sole peer / no peers). It then looks up the cluster in the CSV - **case-insensitive on `ResourceId` first, falling back to `ClusterName + ResourceGroup`** for older CSVs that pre-date the `ResourceId` column - and tells the operator either to edit the `UpdateStartWindow` cell on that row, or (if the cluster is absent from the CSV) to re-run Step.1 to regenerate the inventory artifact and replace the source-controlled CSV with it. ARG query also projects `UpdateExclusionsWindow` so the new Enhancement C section has data to render.
-- **Enhancement B - Cycle calendar (informational, auto-emits when `-SchedulePath` is supplied).** A new `## Cycle calendar - next N day(s)` table renders one row per UTC day for one full cycle (`CycleWeeks * 7` days starting today). Each row shows Date, Day-of-week, CycleWeek (`X of N`, with `(cycle wraps)` annotation on the wrap row), Eligible rings (UNION of all matching schedule rows), and effective `AllowedUpdateVersions` (or `_(no constraint)_`). Re-uses `Resolve-AzLocalCurrentUpdateRing` per-day so cycle-week, UNION, and allow-list math is identical to runtime - no duplicate ISO-8601 / week-arithmetic logic to drift. Lets operators verify ring coverage matches policy and spot dead days where no ring is eligible.
-- **Enhancement C - Configured exclusion windows summary (informational, auto-emits when at least one cluster has a non-empty `UpdateExclusionsWindow` tag).** A new `## Configured exclusion windows (UpdateExclusionsWindow tag)` section groups tagged clusters by `(UpdateRing, UpdateExclusionsWindow)` and renders a rollup table (cluster count + first 10 cluster names + `+N more`). Plus a per-ring breakdown of clusters that have NO `UpdateExclusionsWindow` tag (so operators can spot drift where some clusters in a ring have a blackout configured and others do not).
-- **Step.3 GH + ADO yml: new `cluster_csv_path` / `clusterCsvPath` input** (default `config/ClusterUpdateRings.csv`). Validates the file exists at job time - missing file skips Enhancement A quietly (vs throwing) so repos that don't version-control a cluster CSV yet keep getting the legacy advisor output. Both yml templates now also pass `-SchedulePath` to the `-View Recommend` invocation so Enhancements B+C render in the Step Summary.
-- **Pester suite updates**: drift-sync test bumped to `'0.8.4'`; new It blocks for CSV-lookup paths, peer-derivation modes, cycle-calendar math + cycle-wrap rendering + UNION rows, and exclusion-windows rollup grouping.
-- **Step.6 Enhancement D - per-cluster Step Summary in `apply-updates` (GH + ADO).** `apply-updates` step persists `apply-results.json`; Summary renders new `### Cluster Actions` (icon + Status + UpdateName + Duration + Message per cluster handed to apply) + `### Clusters Skipped at Readiness Gate` (reads `readiness-report.csv`, capped at 100 rows). Eliminates JUnit-artifact downloads to identify per-cluster outcomes.
-- **Node.js 24 opt-in across all 10 GH yml.** `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` at workflow level, ahead of GitHub's platform-wide cutover.
-- **Version banner appended to every install step** - one banner per yml across all 20 bundled `Step.{0..9}.yml` templates (Step.6 ADO has 2 install steps but the second deliberately skips upload to avoid duplicating the banner): `_Pipeline YAML v | Module v installed () | PSGallery latest | _` rendered in the Summary view, eliminating "is my YAML / module out of date?" investigation lag.
-- **RBAC custom role renamed: `Azure Stack HCI Update Operator` -> `Azure Stack HCI Update Operator (custom)`.** Bundled JSON `Name` updated; `Actions[]` byte-identical to v0.8.3. Existing tenants: `az role definition update --role-definition ./azlocal-update-management-custom-role.json` is an in-place rename - GUID + every existing role assignment preserved; zero pipeline downtime. Reference by `roleDefinitionId` (GUID) in automation, not display name.
-- **All 20 bundled `Step.{0..9}.yml` templates** bump `GENERATED_AGAINST_MODULE_VERSION` from `'0.8.3'` to `'0.8.4'`.
+## Version 0.8.5 - New Public cmdlet `Get-AzLocalApplyUpdatesScheduleCycleCalendar` + Step.6 manual schedule-file inputs + Step.3 cycle-calendar regression fix + per-ring cluster-count column
+
+Step.3 cycle-calendar refactor + regression fix release. One new Public cmdlet, two new Step.6 manual-run inputs. No other public API removed; no parameter changes on existing cmdlets. The v0.8.4 cycle-calendar silent-drop bug in `Test-AzLocalApplyUpdatesScheduleCoverage -View Recommend` is fixed at the architectural level (decoupled from the advisor's findings gate).
+
+- **NEW Step.6 manual schedule-file inputs.** GH `workflow_dispatch.inputs` gains `use_schedule_file` (choice false/true) + `resolve_for_date_utc` (string, YYYY-MM-DD); ADO `parameters` gains symmetric `useScheduleFile` (boolean) + `resolveForDateUtc` (string). When `use_schedule_file=true` on a manual run, the resolver reads `apply-updates-schedule.yml` and runs `Resolve-AzLocalCurrentUpdateRing -Schedule $cfg -Now $resolveAt` (today UTC, or the operator-supplied date) - exactly as a scheduled run would. Use this to test a schedule change before the next tick, re-run a missed scheduled day, or preview a future cycleWeek/dayOfWeek. `update_ring` is no longer `required: true` - either supply it OR set `use_schedule_file=true`. The resolver throws a helpful error if BOTH are empty. Back-compat: manual runs with `use_schedule_file=false` use the manual ring verbatim (v0.8.4 behaviour). Scheduled firings are unchanged.
+
+- **NEW Public cmdlet `Get-AzLocalApplyUpdatesScheduleCycleCalendar`.** Projects an `apply-updates-schedule.yml` configuration forward across the calendar - one row per UTC day - and emits either a structured object pipeline (default) or a fully-rendered markdown block (`-AsMarkdown`). Parameters: `-Schedule ` (mandatory), `-StartDate ` (default UTC today), `-Days ` (default = `CycleWeeks * 7`; ValidateRange 1-3650), `-AsMarkdown`, `-IncludePerRingSummary`, `-ClusterRingCounts `. Object output per day: `DateUtc, DayOfWeekName, CycleWeek, CycleWeeksTotal, CycleWeekLabel, IsCycleWrap, Rings, UpdateRingValue, AllowedUpdateVersions, AllowedUpdateVersionsSource, MatchedRowCount, IsDeadDay, Reason`. Re-uses `Resolve-AzLocalCurrentUpdateRing` per-day so cycle-week math, UNION semantics, and AllowedUpdateVersions precedence stay identical to runtime. Variable cycle length safe (4 / 8 / 52 weeks tested) and year-boundary safe (W52 -> W1 wrap, W53 years).
+- **REGRESSION FIX: v0.8.4 cycle calendar silently dropped on healthy fleets.** In v0.8.4 the Enhancement B cycle-calendar block lived inside the Recommend snippet builder, AFTER the "any findings?" gate; on a fleet with zero findings the snippet was empty and Step.3 yml `if ($hasIssues -and $reco)` / `if (-not $hasIssues -and $reco)` branches both fire only when `$reco` is non-empty - so the calendar quietly disappeared. The new cmdlet is invoked unconditionally whenever `$scheduleCfg` is parsed, so the calendar always renders. NO Step.3 yml structural change beyond the version bump.
+- **NEW: `Clusters in ring(s)` calendar column + `Cluster count` per-ring projection column** (via new `-ClusterRingCounts` hashtable). When supplied, the per-day table gains a 6th column (`3+12 (total: 15)` for UNION rows, `5` for single-ring days, blank for dead days), and the optional `### Per-ring projection` section gains a `Cluster count` column. Lookups are `OrdinalIgnoreCase`. Step.3 builds the map from the live tagged `$clusters` already in scope; the cmdlet itself stays pure (no CSV / Azure I/O).
+- **NEW: optional `### Per-ring projection` section (`-IncludePerRingSummary`).** Row per ring with next eligible UTC date + all eligible dates inside the horizon (with cluster count column when `-ClusterRingCounts` is supplied). Step.3 yml passes `-IncludePerRingSummary` so the section always appears.
+- **`Test-AzLocalApplyUpdatesScheduleCoverage -View Recommend` Enhancement B now delegates to the new cmdlet.** The v0.8.4 inline cycle-calendar block (~37 lines) is replaced by a single `Get-AzLocalApplyUpdatesScheduleCycleCalendar -Schedule $scheduleCfg -AsMarkdown -IncludePerRingSummary -ClusterRingCounts $ringCountMap` call, wrapped in `try/catch` with a `_Cycle calendar unavailable: ..._` fallback line.
+- **Pester suite updates**: drift-sync test bumped to `'0.8.5'`; new drift assertion asserts `Get-AzLocalApplyUpdatesScheduleCycleCalendar` is exported; ~28 new It blocks across two new Describe blocks cover object-pipeline shape, default Days math, day-0 resolution, IsDeadDay, UNION rendering, IsCycleWrap on rollover, 52-week / 8-week / 1-week cycles, multi-cycle horizon, defensive `CycleWeeks=0` throw, markdown heading + 5-column / 6-column header variants, the v0.8.4 silent-drop regression guard, ClusterRingCounts UNION + dead-day rendering, case-insensitive ring lookup, cycle-wrap annotation, year-boundary safety. Expected baseline: 882/0/1 -> ~910/0/1.
+- **All 20 bundled `Step.{0..9}.yml` templates** bump `GENERATED_AGAINST_MODULE_VERSION` from `'0.8.4'` to `'0.8.5'`.
## Version 0.8.3 - Test-AzLocalApplyUpdatesScheduleCoverage Step.3 advisor accuracy + readability fixes: Recommend now diff-prunes against `-PipelineYamlPath`, Step.3 yml `pipeline_path` REQUIRED, Allow-list heading reframed, closing-fence typo fixed
diff --git a/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psm1 b/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psm1
index 6aa73b68..680721bd 100644
--- a/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psm1
+++ b/AzLocal.UpdateManagement/AzLocal.UpdateManagement.psm1
@@ -151,7 +151,7 @@ Set-StrictMode -Version 1.0
# bumps to one but not the other are caught before release. Two consumers:
# - Start-AzLocalClusterUpdate emits this in the run log header.
# - Get-AzLocalFleetStatusData stamps it into exported fleet-state JSON.
-$script:ModuleVersion = '0.8.4'
+$script:ModuleVersion = '0.8.5'
$script:DefaultApiVersion = '2025-10-01'
$script:DefaultLogFolder = Join-Path -Path $env:ProgramData -ChildPath 'AzLocal.UpdateManagement'
@@ -307,6 +307,8 @@ Export-ModuleMember -Function @(
'Get-AzLocalApplyUpdatesScheduleNextFirings',
'New-AzLocalApplyUpdatesScheduleConfig',
'Update-AzLocalApplyUpdatesScheduleConfig',
+ # Cycle Calendar (v0.8.5) - human-readable per-day projection of the resolver for one full cycle (or any -Days horizon), variable cycle length safe, year-boundary safe, per-ring 'next eligible date' summary
+ 'Get-AzLocalApplyUpdatesScheduleCycleCalendar',
# Fleet Health Overview (v0.7.70) - one row per cluster, ARG-first projection of cluster + updateSummaries
'Get-AzLocalFleetHealthOverview',
# Latest Released Solution Version (v0.7.70 Phase E) - public manifest probe (aka.ms/AzureEdgeUpdates) that anchors the rolling YYMM support window in Step.6
@@ -314,5 +316,32 @@ Export-ModuleMember -Function @(
# Fleet Connectivity Status (v0.7.79) - 4-scope connectivity audit: cluster, Arc agent, physical NIC, ARB
'Get-AzLocalFleetConnectivityStatus',
# Fleet Connectivity Status Summary Renderer (v0.7.87) - markdown step-summary builder used by Step.4 GH+ADO pipelines
- 'New-AzLocalFleetConnectivityStatusSummary'
+ 'New-AzLocalFleetConnectivityStatusSummary',
+ # Thin-YAML pipeline foundation (v0.8.5) - install-step version banner + drift annotations + step outputs (condenses ~50-line inline block in every Step.*.yml)
+ 'Add-AzLocalPipelineVersionBanner',
+ # Thin-YAML Step.0 (v0.8.5) - Authentication validation + subscription scope + cluster reachability (condenses ~200-line inline run: | block in Step.0_authentication-test.yml on both platforms)
+ 'Export-AzLocalAuthValidationReport',
+ # Thin-YAML Step.1 (v0.8.5) - Cluster inventory workload (condenses the inline run: | block in Step.1_inventory-clusters.yml on both platforms; writes timestamped + canonical CSV, JSON, README, and step summary)
+ 'Invoke-AzLocalClusterInventory',
+ # Thin-YAML Step.2 (v0.8.5) - UpdateRing tag management workload (validates CSV, applies tags via Set-AzLocalClusterUpdateRingTag, writes JSON sidecar + step summary)
+ 'Set-AzLocalClusterUpdateRingTagFromCsv',
+ # Thin-YAML Step.7 (v0.8.5) - In-flight update-run monitor (CSV + JUnit + markdown + 6 step outputs)
+ 'Export-AzLocalUpdateRunMonitorReport',
+ # Thin-YAML Step.8 (v0.8.5) - Fleet update status snapshot (inventory + readiness + version distribution + 3-suite JUnit + markdown + 22 step outputs)
+ 'Export-AzLocalFleetUpdateStatusReport',
+ # Thin-YAML Step.5 (v0.8.5) - Pre-flight Update Readiness Assessment (readiness + blocking-health JUnit + combined JUnit + 8-section markdown + 2 step outputs)
+ 'Export-AzLocalClusterUpdateReadinessReport',
+ # Thin-YAML Step.4 (v0.8.5) - Fleet Connectivity Status (Cluster/Arc/NIC/ARB severity classification + JUnit + markdown + 12 step outputs)
+ 'Export-AzLocalFleetConnectivityStatusReport',
+ # Thin-YAML Step.3 (v0.8.5) - Apply-Updates Schedule Coverage Audit (Audit + Matrix + Recommend views + 2-suite JUnit + allow-list section + always-on cycle calendar + 12 step outputs)
+ 'Export-AzLocalApplyUpdatesScheduleAudit',
+ # Thin-YAML Step.9 (v0.8.5) - Fleet Health Status (Detail + Summary + Overview + 2-suite JUnit + KPI / Overview / By-Reason / per-cluster collapsible markdown + 8 step outputs)
+ 'Export-AzLocalFleetHealthStatusReport',
+ # Thin-YAML Step.6 (v0.8.5) - Apply-Updates pipeline (6 cmdlets condensing ~430 lines of inline run: | blocks across both Step.6_apply-updates.yml pipelines)
+ 'Resolve-AzLocalPipelineUpdateRing',
+ 'Export-AzLocalClusterReadinessGateReport',
+ 'Invoke-AzLocalReadinessGatedClusterUpdate',
+ 'Add-AzLocalApplyUpdatesStepSummary',
+ 'Add-AzLocalNoReadyClustersStepSummary',
+ 'Invoke-AzLocalItsmTicketingFromArtifact'
)
\ No newline at end of file
diff --git a/AzLocal.UpdateManagement/CHANGELOG.md b/AzLocal.UpdateManagement/CHANGELOG.md
index 83a588d8..d9664363 100644
--- a/AzLocal.UpdateManagement/CHANGELOG.md
+++ b/AzLocal.UpdateManagement/CHANGELOG.md
@@ -5,6 +5,102 @@ All notable changes to the AzLocal.UpdateManagement module (renamed from AzStack
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.8.5] - 2026-06-09
+
+Step.3 cycle-calendar refactor + regression fix release, followed by a **full thin-YAML port of all 10 Step pipelines** (GitHub Actions + Azure DevOps - 20 YAML files in total). Adds 15 new Public cmdlets (1 in the original 0.8.5 plus 14 over the thin-YAML port) and two new Step.6 manual-run inputs that let an operator trigger apply-updates by hand BUT resolve UpdateRing + AllowedUpdateVersions from `apply-updates-schedule.yml` exactly as a scheduled run would. No public API removed; no parameter changes on existing cmdlets. The v0.8.4 cycle-calendar silent-drop bug in `Test-AzLocalApplyUpdatesScheduleCoverage -View Recommend` is fixed at the architectural level (decoupled from the advisor's findings gate). **Total module export count grows from 35 (v0.8.4) to 55 (v0.8.5).**
+
+### Thin-YAML refactor across all 10 Step pipelines (Step.0 - Step.9)
+
+- **Goal**: condense the multi-hundred-line `run: |` PowerShell blocks that were duplicated between each Step's GitHub Actions YAML and Azure DevOps YAML into a single Public cmdlet that both pipelines invoke. Zero UI / outcome delta - step output names, artifact contents, JUnit XML, markdown summaries, exit codes, error messages, and stageDependencies bindings all preserved byte-for-byte.
+- **14 new Public cmdlets added** (one per Step plus shared helpers):
+ - `Add-AzLocalPipelineVersionBanner` (shared) - emits the install-time drift banner used by every Step's install step.
+ - `Export-AzLocalAuthValidationReport` (Step.0) - + shared `New-AzLocalPipelineJUnitXml` helper.
+ - `Invoke-AzLocalClusterInventory` (Step.1).
+ - `Set-AzLocalClusterUpdateRingTagFromCsv` (Step.2).
+ - `Export-AzLocalApplyUpdatesScheduleAudit` (Step.3).
+ - `Export-AzLocalFleetConnectivityStatusReport` (Step.4).
+ - `Export-AzLocalClusterUpdateReadinessReport` (Step.5).
+ - **6 Step.6 cmdlets** (apply-updates is the largest pipeline): `Resolve-AzLocalPipelineUpdateRing`, `Export-AzLocalClusterReadinessGateReport`, `Invoke-AzLocalReadinessGatedClusterUpdate`, `Add-AzLocalApplyUpdatesStepSummary`, `Add-AzLocalNoReadyClustersStepSummary`, `Invoke-AzLocalItsmTicketingFromArtifact`.
+ - `Export-AzLocalUpdateRunMonitorReport` (Step.7).
+ - `Export-AzLocalFleetUpdateStatusReport` (Step.8).
+ - `Export-AzLocalFleetHealthStatusReport` (Step.9).
+- **Per-host step-output naming** is owned by the cmdlet, not the YAML. GitHub Actions consumes `UPPER_SNAKE` names (e.g. `READY_COUNT`); Azure DevOps consumes `PascalCase` names (e.g. `ReadyCount`) for stageDependencies `outputs['readiness.ReadyCount']` bindings. Each cmdlet auto-detects the host (`$env:TF_BUILD` / `$env:GITHUB_ACTIONS`) and emits the correct naming convention.
+- **Per-host icon style** is owned by the cmdlet: Unicode emoji on GitHub markdown summaries, GitHub-Markdown shortcodes (`:white_check_mark:` etc.) on Azure DevOps summaries.
+- **Cumulative YAML reduction** across the 20 templates: approximately **9,000 lines** removed from `Automation-Pipeline-Examples/`. Step.6 alone: GitHub Actions 964 -> 480 lines (-484); Azure DevOps 985 -> 440 lines (-545).
+- **Why this matters** for ongoing maintenance:
+ - **Single source of truth.** Logic previously duplicated between GitHub Actions YAML and Azure DevOps YAML now lives in one place. A bug fix or feature lands in the cmdlet and immediately benefits both platforms.
+ - **Unit-testable.** The new Public cmdlets are mocked + asserted in Pester (`Tests/AzLocal.UpdateManagement.Tests.ps1`). Previously, validating an inline `run: |` block required spinning up a pipeline run or hand-running a copy-paste of the block in PowerShell.
+ - **Faster CI signal.** A typo or contract change is caught by the local Pester run (~5 minutes) instead of waiting for a pipeline run + artifact inspection on Azure.
+ - **Cleaner diffs.** YAML reviewers see "one step calls one cmdlet" instead of 300 lines of inline PowerShell; reviewers can focus on YAML wiring (triggers, env, artifacts, OIDC) while cmdlet behaviour is reviewed under the unit tests.
+ - **Discoverability.** Operators running the module interactively now have a documented `Get-Help -AzLocal*` for what was previously trapped inside a YAML `run:` block.
+ - **Re-usable building blocks.** `Add-AzLocalPipelineVersionBanner`, `Set-AzLocalPipelineOutput`, `Add-AzLocalPipelineStepSummary`, `Write-AzLocalPipelineWarning`, `New-AzLocalPipelineJUnitXml` are shared across every Step cmdlet - the next pipeline doesn't re-invent host-detection, step-output emission, JUnit framing, or markdown rendering.
+- **One semantically-significant fix shaken out during testing**: `Invoke-AzLocalReadinessGatedClusterUpdate`'s seven-counter emitter was originally defined as `$emitCounters = { ... }.GetNewClosure()`. `.GetNewClosure()` rebinds the scriptblock to the CALLER's SessionState - which makes Private (non-exported) module functions invisible from inside the closure. Removing `.GetNewClosure()` (lexical scoping already gives the inline scriptblock access to the surrounding `$n*` variables when invoked via `& $emitCounters` from the same function) restored access to the private `Set-AzLocalPipelineOutput` function. Pester regression guards are now in place for both GH and ADO short-circuit paths.
+- **Pester suite growth**: ~190 new It blocks across the 14 new cmdlets (parameter shape + per-host short-circuit + host-aware naming + error-path guards). Full local suite: **1069 passed, 0 failed, 1 skipped, ~4m38s**. Function-count drift test bumped from 35 -> 55 in two sites.
+- **Backwards compatibility**: every Step pipeline keeps its filename, name field, trigger block (cron / workflow_dispatch / schedules / parameters), env block, concurrency block, OIDC login + Option 2 commented block, action-version pins, step IDs, artifact names, ITSM markers, and per-host step-output naming. Consumer pipelines that were running v0.8.4 YAML against v0.8.4 module continue to work against v0.8.5 module (the install-time drift banner surfaces the version skew but does not block).
+
+### New Step.6 manual schedule-file inputs (`use_schedule_file` / `useScheduleFile` + `resolve_for_date_utc` / `resolveForDateUtc`)
+
+- **Problem**: in v0.8.4 and earlier, a manual `workflow_dispatch` / "Run pipeline" of Step.6 ALWAYS used the operator's `update_ring` / `updateRing` parameter verbatim and ignored `apply-updates-schedule.yml`. Operators wanting to (a) test a schedule change before the next scheduled tick, (b) re-run a missed scheduled day, or (c) preview a future cycleWeek/dayOfWeek had no clean way to do so - they had to hand-mirror what the resolver would have picked.
+- **Fix - GH `workflow_dispatch.inputs`**:
+ - `use_schedule_file` (choice `'false'`/`'true'`, default `'false'`) - "Resolve UpdateRing & AllowedUpdateVersions from apply-updates-schedule.yml (as a scheduled run would). Overrides update_ring."
+ - `resolve_for_date_utc` (string, default `''`, format `YYYY-MM-DD`) - "Only used when use_schedule_file=true. Date (UTC) to resolve the schedule for. Empty = today UTC. Useful for previewing a future cycleWeek/dayOfWeek."
+ - `update_ring` is no longer `required: true` - either supply it, OR set `use_schedule_file=true`. The resolver throws a helpful error if BOTH are empty.
+- **Fix - ADO `parameters`**: symmetric `useScheduleFile` (boolean, default `false`) and `resolveForDateUtc` (string, default `''`) parameters, with the same 4-branch resolver decision tree in `resolveRing`.
+- **Resolver decision tree (both platforms)**:
+ 1. Manual trigger + `use_schedule_file=false` -> use manual ring verbatim (back-compat, identical to v0.8.4).
+ 2. Manual trigger + `use_schedule_file=true` -> read schedule file, run `Resolve-AzLocalCurrentUpdateRing -Schedule $cfg -Now $resolveAt` for today UTC (or `resolve_for_date_utc` when set). Uses ring + AllowedUpdateVersions exactly as a scheduled run would.
+ 3. Manual trigger + `use_schedule_file=false` + `update_ring` empty -> throw with remediation pointing at both alternatives.
+ 4. Scheduled trigger -> unchanged (reads schedule for UTC now).
+- **`resolve_for_date_utc` parsing**: `[datetime]::ParseExact` against `'yyyy-MM-dd'` with `AssumeUniversal | AdjustToUniversal` so the date is treated as UTC regardless of agent timezone. Invalid format throws a helpful error.
+- **No change to scheduled runs**: scheduled `cron:` / `schedules:` firings still resolve via the schedule file for the current UTC moment (path 4) - no behaviour change.
+- **Pester guard**: 12 new It blocks under `Context 'v0.8.5 Step.6 manual schedule-file input'` cover both GH and ADO yml: new input declarations, `update_ring` no longer required, resolver script env-var wiring, `-Now $resolveAt` plumbing through to `Resolve-AzLocalCurrentUpdateRing`, the both-empty throw, and the `yyyy-MM-dd` parsing + invalid-format throw.
+
+### New Public cmdlet `Get-AzLocalApplyUpdatesScheduleCycleCalendar`
+
+- **Projects an `apply-updates-schedule.yml` configuration forward across the calendar** - one row per UTC day - and emits either a structured object pipeline (default) or a fully-rendered markdown block (`-AsMarkdown`).
+- **Parameters**:
+ - `-Schedule ` (mandatory) - pre-loaded schedule object (the same `$scheduleCfg` Test-...Coverage already builds via `Get-AzLocalApplyUpdatesSchedule`).
+ - `-StartDate ` - default UTC today.
+ - `-Days ` - default = `CycleWeeks * 7` (one full cycle). ValidateRange 1-3650.
+ - `-AsMarkdown` - switch. Without it: object pipeline. With it: full markdown block including `## Cycle calendar - next N day(s) (one full N-week cycle)` heading + per-day table + optional `### Per-ring projection` section.
+ - `-IncludePerRingSummary` - switch. Adds a per-ring projection table after the per-day calendar (next eligible UTC date per ring + all eligible dates inside the horizon).
+ - `-ClusterRingCounts ` - case-insensitive map (`@{ Std='5'; Canary='3'; Prod='12' }`-shape). When supplied, the per-day table gains a 6th column `Clusters in ring(s)` (e.g. `3+12 (total: 15)` for UNION rows, `5` for single-ring days, blank for dead days), and the per-ring projection table gains a `Cluster count` column.
+- **Object output (per day)**: `DateUtc, DayOfWeekName, CycleWeek, CycleWeeksTotal, CycleWeekLabel, IsCycleWrap, Rings, UpdateRingValue, AllowedUpdateVersions, AllowedUpdateVersionsValue, AllowedUpdateVersionsSource, MatchedRowCount, IsDeadDay, Reason`. `Rings` is the UNION of all matching schedule rows for that day (deduplicated, `OrdinalIgnoreCase`). `IsCycleWrap=$true` on the day where `prev CycleWeek = CycleWeeksTotal` AND `current CycleWeek = 1`.
+- **Re-uses `Resolve-AzLocalCurrentUpdateRing` per-day** so cycle-week math, UNION semantics, and AllowedUpdateVersions precedence remain identical to runtime - no duplicate ISO-8601 / week-arithmetic logic to drift away from the resolver.
+- **Variable cycle length safe** (4 / 8 / 52 weeks all tested via Pester) and **year-boundary safe** (W52 -> W1 wrap on the cycle-anchor week is correctly annotated; W53 years projected correctly).
+- **Defensive**: throws when `Schedule.CycleWeeks` is 0 or missing.
+
+### Regression fix: v0.8.4 cycle calendar silently dropped on healthy fleets
+
+- **Symptom**: in v0.8.4, Step.3 GH/ADO Summary on a fleet with zero advisor findings did NOT include the cycle-calendar table even though `-SchedulePath` was supplied.
+- **Root cause**: the v0.8.4 Enhancement B cycle-calendar block lived inside `Test-AzLocalApplyUpdatesScheduleCoverage -View Recommend`'s snippet builder, AFTER the "any findings?" gate. When there were no findings, the `$fullSb` snippet was empty, and the Step.3 yml `if ($hasIssues -and $reco)` / `if (-not $hasIssues -and $reco)` branches at lines 503/630 both fire only when `$reco` is non-empty - so the calendar quietly disappeared on healthy fleets.
+- **Fix**: the new cmdlet is invoked unconditionally whenever `$scheduleCfg` is parsed, so `$reco` is never empty when `-SchedulePath` is supplied - one of the two existing yml branches always fires. NO structural Step.3 yml change required beyond the version bump.
+- **Regression guard**: new Pester test `REGRESSION: -AsMarkdown returns the calendar even when the fleet has zero findings (v0.8.4 silent-drop bug)` asserts the markdown is non-empty and contains the `## Cycle calendar` heading even when the fleet input is empty.
+
+### `Test-AzLocalApplyUpdatesScheduleCoverage -View Recommend` Enhancement B now delegates to the new cmdlet
+
+- The v0.8.4 inline cycle-calendar block (~37 lines, lines 931-967) in `Test-AzLocalApplyUpdatesScheduleCoverage.ps1` is replaced by a single call: `Get-AzLocalApplyUpdatesScheduleCycleCalendar -Schedule $scheduleCfg -AsMarkdown -IncludePerRingSummary -ClusterRingCounts $ringCountMap`. Wrapped in `try { ... } catch { ... }` with a `_Cycle calendar unavailable: $($_.Exception.Message)_` fallback line so a malformed schedule on a single fleet doesn't break Step.3 for the whole job.
+- `$ringCountMap` is built from the live tagged `$clusters` (already in scope from the earlier ARG query) - iterates each `$c.UpdateRing.Trim()` and increments the map. The cmdlet itself stays pure (no CSV / Azure I/O) so it remains unit-testable from a synthetic schedule object.
+
+### New: per-ring projection section (`-IncludePerRingSummary`)
+
+- Renders a `### Per-ring projection` section after the per-day table. One row per ring with: ring name, next eligible UTC date inside the horizon (or `(none)`), all eligible UTC dates inside the horizon (comma-separated, first 10 + `+N more` for very long lists), and `Cluster count` (when `-ClusterRingCounts` is supplied).
+- Step.3 yml passes `-IncludePerRingSummary` so the section always appears on healthy fleets.
+
+### Pester suite updates
+
+- `Module: AzLocal.UpdateManagement / Module Load / Should have version` drift test bumped to `'0.8.5'`.
+- New drift assertion asserts `Get-AzLocalApplyUpdatesScheduleCycleCalendar` is present in `FunctionsToExport`.
+- Two new Describe blocks (`v0.8.5 ... (object pipeline)` + `v0.8.5 ... (markdown)`) under `#region v0.8.5: Get-AzLocalApplyUpdatesScheduleCycleCalendar` cover ~28 It blocks:
+ - **Object pipeline** (11): default `Days` math, row shape, `CycleWeeksTotal` invariant, day-0 resolution, `IsDeadDay` on no-match, UNION semantics on multi-row Friday, `IsCycleWrap` on `W8 -> W1` rollover, 52-week cycle 364 rows + year boundary, 8-week cycle with wrap, multi-cycle horizon, defensive `CycleWeeks=0` throw.
+ - **Markdown** (~17): output type `[string]`, `## Cycle calendar` heading present, 5-column header (no `-ClusterRingCounts`), 6-column header (with `-ClusterRingCounts`), regression guard for v0.8.4 silent-drop, `### Per-ring projection` section structure, UNION row rendering, ClusterRingCounts column variants (single ring, multi-ring `(total: N)`, case-insensitive key match, dead-day blank), cycle-wrap `_(cycle wraps)_` annotation, year-boundary safe with 1-week cycle.
+- Expected baseline shift: 882 / 0 / 1 (pre) -> ~910 / 0 / 1 (post).
+
+### Version pin bumped across all 20 bundled `Step.{0..9}.yml` templates
+
+- `GENERATED_AGAINST_MODULE_VERSION` moves from `0.8.4` to `0.8.5` across all 20 bundled `Step.{0..9}.yml` files (10 GitHub Actions + 10 Azure DevOps). The install-step drift annotation continues to surface stale YAML to operators.
+- `$script:ModuleVersion` (psm1) == `ModuleVersion` (psd1) == `'0.8.5'` (test assertion); the drift guard introduced in v0.7.67 enforces this.
+
## [0.8.4] - 2026-06-18
Step.3 advisor enhancement release. No public API removed; one new optional parameter on `Test-AzLocalApplyUpdatesScheduleCoverage` (`-ClusterCsvPath`); three new Recommend-view sections that render when their respective inputs are supplied. All v0.8.3 behaviour preserved unchanged.
diff --git a/AzLocal.UpdateManagement/Private/New-AzLocalPipelineJUnitXml.ps1 b/AzLocal.UpdateManagement/Private/New-AzLocalPipelineJUnitXml.ps1
new file mode 100644
index 00000000..7f4b0c3b
--- /dev/null
+++ b/AzLocal.UpdateManagement/Private/New-AzLocalPipelineJUnitXml.ps1
@@ -0,0 +1,274 @@
+function New-AzLocalPipelineJUnitXml {
+ <#
+ .SYNOPSIS
+ Builds a JUnit XML document from a structured suite/testcase
+ description and (optionally) writes it to disk.
+
+ .DESCRIPTION
+ Generic JUnit XML emitter for the v0.8.5 thin-YAML refactor. Every
+ Public Step.* cmdlet (Export-AzLocalAuthValidationReport,
+ Invoke-AzLocalClusterInventory, Export-AzLocalUpdateRunMonitorReport,
+ etc.) emits a JUnit XML report alongside its step-summary markdown so
+ downstream CI consumers (dorny/test-reporter on GitHub, PublishTestResults
+ on Azure DevOps) can render the report in the platform's native Tests UI.
+
+ Pre-v0.8.5 the JUnit XML was hand-built inline in every Step.*.yml,
+ which meant the same StringBuilder + XML-escape + /
+ / scaffolding was copy-pasted into 20 yml files.
+ This helper centralises the scaffolding so the per-Step cmdlets only
+ describe the suites + testcases as PowerShell data structures - no
+ XML formatting in the per-Step bodies, and a single place to add
+ new JUnit features (e.g. ) across all Steps.
+
+ The pre-existing Private/Export-ResultsToJUnitXml is per-cluster
+ update-shape (one testcase per cluster, Status -> failure / error /
+ skipped) used by Step.6's inline apply-updates path and is not
+ replaced - it remains in place for that cluster-result-row use case.
+
+ .PARAMETER TestSuitesName
+ Top-level attribute. Typically the Step
+ display name, e.g. "Step.0 - Authentication Validation and
+ Subscription Scope Report".
+
+ .PARAMETER Suites
+ An array of suite hashtables. Each hashtable describes one
+ . Recognised keys (all values are XML-escaped on emit):
+ Name [string] (required) testsuite name attribute
+ ClassName [string] (optional) default classname for testcases
+ that omit their own ClassName
+ Properties [hashtable|ordered] (optional) emits a suite-level
+
+ block. Use [ordered] to preserve insertion order.
+ TestCases [object[]] (required) array of testcase hashtables
+
+ Each testcase hashtable recognises:
+ Name [string] (required) testcase name attribute
+ ClassName [string] (optional) testcase classname attribute;
+ falls back to the suite ClassName, then to
+ the suite Name
+ Time [double] (optional) testcase time attribute (seconds);
+ default 0
+ Properties [hashtable|ordered] (optional) emits a per-testcase
+ block (e.g. dedupe keys consumed
+ by the ITSM connector: ClusterName,
+ ClusterResourceId, UpdateName, Status, ...).
+ SystemOut [string] (optional) wraps in
+ SystemErr [string] (optional) wraps in
+ Failure [hashtable] (optional) emits body;
+ keys: Message, Type, Body
+ Error [hashtable] (optional) emits body;
+ keys: Message, Type, Body
+ Skipped [string] (optional) emits
+ (passing an empty string still emits the
+ element with no message attribute)
+
+ The suite-level attributes are computed from the testcase array so
+ callers don't have to keep two counters in sync.
+
+ .PARAMETER OutputPath
+ Optional absolute path to write the rendered XML to. The file is
+ written UTF-8 without BOM (matches dorny/test-reporter and ADO
+ PublishTestResults expectations). When omitted, the cmdlet only
+ returns the XML string and writes nothing.
+
+ .PARAMETER Timestamp
+ Optional [datetime] used for every attribute.
+ Defaults to (Get-Date) at invocation time. Parameterised so unit tests
+ can assert against a fixed value.
+
+ .OUTPUTS
+ [string] The fully-rendered JUnit XML document. When -OutputPath is
+ supplied, the same string is also written to disk.
+
+ .EXAMPLE
+ $xml = New-AzLocalPipelineJUnitXml -TestSuitesName 'Step.0 - Auth' -Suites @(
+ @{
+ Name = 'Authentication'
+ ClassName = 'Authentication'
+ TestCases = @(
+ @{ Name = 'OIDC token exchange succeeded'; SystemOut = "Tenant: $tid" }
+ @{ Name = "Default subscription = $subName" }
+ )
+ }
+ @{
+ Name = "Subscription Scope (count=$subCount)"
+ ClassName = 'SubscriptionScope'
+ TestCases = $subTestCases
+ }
+ ) -OutputPath "$reportDir/auth-report.xml"
+ #>
+ [CmdletBinding()]
+ [OutputType([string])]
+ param(
+ [Parameter(Mandatory = $true)]
+ [ValidateNotNullOrEmpty()]
+ [string]$TestSuitesName,
+
+ [Parameter(Mandatory = $true)]
+ [ValidateNotNull()]
+ [object[]]$Suites,
+
+ [Parameter(Mandatory = $false)]
+ [string]$OutputPath,
+
+ [Parameter(Mandatory = $false)]
+ [datetime]$Timestamp = (Get-Date)
+ )
+
+ $xmlEscape = {
+ param([string]$Text)
+ if ($null -eq $Text) { return '' }
+ $Text -replace '&', '&' -replace '<', '<' -replace '>', '>' -replace '"', '"' -replace "'", '''
+ }
+
+ $emitProperties = {
+ param($PropTable, [string]$Indent)
+ if (-not $PropTable) { return '' }
+ $entries = @()
+ if ($PropTable -is [System.Collections.IDictionary]) {
+ foreach ($k in $PropTable.Keys) {
+ $entries += ,@($k, $PropTable[$k])
+ }
+ }
+ else { return '' }
+ if ($entries.Count -eq 0) { return '' }
+ $pb = [System.Text.StringBuilder]::new()
+ [void]$pb.AppendLine($Indent + '')
+ foreach ($e in $entries) {
+ $kEsc = & $xmlEscape ([string]$e[0])
+ $vEsc = & $xmlEscape ([string]$e[1])
+ [void]$pb.AppendLine($Indent + " ")
+ }
+ [void]$pb.Append($Indent + '')
+ $pb.AppendLine() | Out-Null
+ return $pb.ToString()
+ }
+
+ $now = $Timestamp.ToString('yyyy-MM-ddTHH:mm:ss')
+ $totalTimeAcrossSuites = 0.0
+
+ $sb = [System.Text.StringBuilder]::new()
+ [void]$sb.AppendLine('')
+
+ $suiteBlocks = [System.Text.StringBuilder]::new()
+
+ foreach ($suite in $Suites) {
+ if (-not $suite -or -not $suite.ContainsKey('Name')) {
+ throw "New-AzLocalPipelineJUnitXml: each Suites element must be a hashtable with a 'Name' key. Received: $($suite | Out-String)"
+ }
+ $suiteName = & $xmlEscape ([string]$suite.Name)
+ $suiteClass = if ($suite.ContainsKey('ClassName') -and $suite.ClassName) { [string]$suite.ClassName } else { [string]$suite.Name }
+ $tcs = @()
+ if ($suite.ContainsKey('TestCases') -and $null -ne $suite.TestCases) { $tcs = @($suite.TestCases) }
+
+ $tcCount = $tcs.Count
+ $tcFailures = 0
+ $tcErrors = 0
+ $tcSkipped = 0
+ $suiteTime = 0.0
+
+ $caseBlocks = [System.Text.StringBuilder]::new()
+ foreach ($tc in $tcs) {
+ if (-not $tc -or -not $tc.ContainsKey('Name')) {
+ throw "New-AzLocalPipelineJUnitXml: each TestCases element must be a hashtable with a 'Name' key. Received: $($tc | Out-String)"
+ }
+ $tcName = & $xmlEscape ([string]$tc.Name)
+ $tcClass = if ($tc.ContainsKey('ClassName') -and $tc.ClassName) { [string]$tc.ClassName } else { $suiteClass }
+ $tcClassEsc = & $xmlEscape $tcClass
+ $tcTime = 0.0
+ if ($tc.ContainsKey('Time') -and $null -ne $tc.Time) {
+ try { $tcTime = [double]$tc.Time } catch { $tcTime = 0.0 }
+ }
+ $suiteTime += $tcTime
+
+ $hasProps = $tc.ContainsKey('Properties') -and $tc.Properties
+ $hasChild = ($tc.ContainsKey('Failure') -and $tc.Failure) -or `
+ ($tc.ContainsKey('Error') -and $tc.Error) -or `
+ ($tc.ContainsKey('Skipped')) -or `
+ ($tc.ContainsKey('SystemOut') -and $tc.SystemOut) -or `
+ ($tc.ContainsKey('SystemErr') -and $tc.SystemErr) -or `
+ $hasProps
+
+ if (-not $hasChild) {
+ [void]$caseBlocks.AppendLine(" ")
+ continue
+ }
+
+ [void]$caseBlocks.AppendLine(" ")
+
+ if ($hasProps) {
+ $propsXml = & $emitProperties $tc.Properties ' '
+ if ($propsXml) { [void]$caseBlocks.Append($propsXml) }
+ }
+
+ if ($tc.ContainsKey('Failure') -and $tc.Failure) {
+ $tcFailures++
+ $fMsg = & $xmlEscape ([string]$tc.Failure.Message)
+ $fType = if ($tc.Failure.ContainsKey('Type') -and $tc.Failure.Type) { & $xmlEscape ([string]$tc.Failure.Type) } else { 'AssertionError' }
+ $fBody = if ($tc.Failure.ContainsKey('Body') -and $tc.Failure.Body) { [string]$tc.Failure.Body } else { '' }
+ if ($fBody) {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ else {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ }
+ if ($tc.ContainsKey('Error') -and $tc.Error) {
+ $tcErrors++
+ $eMsg = & $xmlEscape ([string]$tc.Error.Message)
+ $eType = if ($tc.Error.ContainsKey('Type') -and $tc.Error.Type) { & $xmlEscape ([string]$tc.Error.Type) } else { 'Error' }
+ $eBody = if ($tc.Error.ContainsKey('Body') -and $tc.Error.Body) { [string]$tc.Error.Body } else { '' }
+ if ($eBody) {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ else {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ }
+ if ($tc.ContainsKey('Skipped')) {
+ $tcSkipped++
+ $skMsg = & $xmlEscape ([string]$tc.Skipped)
+ if ($skMsg) {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ else {
+ [void]$caseBlocks.AppendLine(' ')
+ }
+ }
+ if ($tc.ContainsKey('SystemOut') -and $tc.SystemOut) {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ if ($tc.ContainsKey('SystemErr') -and $tc.SystemErr) {
+ [void]$caseBlocks.AppendLine(" ")
+ }
+ [void]$caseBlocks.AppendLine(' ')
+ }
+
+ $totalTimeAcrossSuites += $suiteTime
+ [void]$suiteBlocks.AppendLine(" ")
+ if ($suite.ContainsKey('Properties') -and $suite.Properties) {
+ $suitePropsXml = & $emitProperties $suite.Properties ' '
+ if ($suitePropsXml) { [void]$suiteBlocks.Append($suitePropsXml) }
+ }
+ [void]$suiteBlocks.Append($caseBlocks.ToString())
+ [void]$suiteBlocks.AppendLine(' ')
+ }
+
+ $suitesNameEsc = & $xmlEscape $TestSuitesName
+ [void]$sb.AppendLine("")
+ [void]$sb.Append($suiteBlocks.ToString())
+ [void]$sb.AppendLine('')
+
+ $xmlString = $sb.ToString()
+
+ if ($OutputPath) {
+ $dir = Split-Path -Path $OutputPath -Parent
+ if ($dir -and -not (Test-Path -LiteralPath $dir)) {
+ New-Item -ItemType Directory -Path $dir -Force | Out-Null
+ }
+ [System.IO.File]::WriteAllText($OutputPath, $xmlString, [System.Text.UTF8Encoding]::new($false))
+ }
+
+ return $xmlString
+}
diff --git a/AzLocal.UpdateManagement/Public/Add-AzLocalApplyUpdatesStepSummary.ps1 b/AzLocal.UpdateManagement/Public/Add-AzLocalApplyUpdatesStepSummary.ps1
new file mode 100644
index 00000000..18ff0604
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Add-AzLocalApplyUpdatesStepSummary.ps1
@@ -0,0 +1,277 @@
+function Add-AzLocalApplyUpdatesStepSummary {
+ <#
+ .SYNOPSIS
+ Renders the Update Application Summary markdown for the apply-updates
+ job in Step.6. Replaces ~100 lines of inline `run:` summary boilerplate
+ in both Step.6 pipeline YAMLs.
+ .DESCRIPTION
+ v0.8.5 Step.6 thin-YAML helper. Emits the same markdown layout the
+ prior inline blocks produced:
+ - H1: 'Update Application Summary' (ADO) / H2 (GitHub - already
+ inside a single $GITHUB_STEP_SUMMARY file).
+ - Target UpdateRing line.
+ - 'This was a dry run' note when -DryRun is set.
+ - Readiness KPI table (Total / Ready).
+ - Results KPI table (the seven status buckets).
+ - Cluster Actions table read from apply-results.json (when present).
+ - Clusters Skipped at Readiness Gate table read from
+ readiness-report.csv (when present, capped at MaxSkippedRows).
+ - Actions Required bullet list (one bullet per non-zero blocking
+ bucket, with the same operator-facing remediation text).
+
+ Per-host emoji choice (preserved byte-for-byte from the prior inline
+ blocks):
+ - GitHub Actions : Unicode emoji glyphs (U+2705 / U+274C / U+26D4 / U+23ED).
+ - Azure DevOps : GitHub-Markdown shortcode tokens
+ (:white_check_mark: / :x: / :no_entry: /
+ :next_track_button: / :warning:).
+ - Local : same as GitHub (Unicode emoji glyphs).
+ .PARAMETER UpdateRing
+ Resolved UpdateRing label (string).
+ .PARAMETER DryRun
+ Switch. When set, the dry-run note is rendered and Actions Required
+ is suppressed (matching prior inline behaviour on ADO).
+ .PARAMETER TotalCount
+ Readiness total count (string-or-int accepted; coerced to string for
+ display, to int for KPI checks).
+ .PARAMETER ReadyCount
+ Readiness ready count.
+ .PARAMETER Succeeded
+ Apply succeeded count.
+ .PARAMETER Skipped
+ Apply skipped count.
+ .PARAMETER Failed
+ Apply failed count.
+ .PARAMETER HealthBlocked
+ Apply health-blocked count.
+ .PARAMETER ScheduleBlocked
+ Apply schedule-blocked count.
+ .PARAMETER SideloadedBlocked
+ Apply sideloaded-blocked count.
+ .PARAMETER ExcludedByTag
+ Apply excluded-by-tag count.
+ .PARAMETER ApplyResultsJsonPath
+ Path to apply-results.json written by Invoke-AzLocalReadinessGatedClusterUpdate.
+ When the file is missing the Cluster Actions table is omitted.
+ .PARAMETER ReadinessCsvPath
+ Path to readiness-report.csv. When missing the Clusters Skipped table
+ is omitted.
+ .PARAMETER MaxClusterActionRows
+ Maximum cluster action rows rendered. Default 200 (the prior inline
+ block had no explicit cap - the entire list was rendered).
+ .PARAMETER MaxSkippedRows
+ Maximum skipped-cluster rows rendered. Default 100 (matches prior).
+ .PARAMETER SummaryFileName
+ Per-task markdown filename (ADO/Local only). Default
+ 'azlocal-step6-apply-summary.md'.
+ .PARAMETER PassThru
+ Returns PSCustomObject with: SummaryPath, ActionsRequiredCount,
+ ClusterActionsRendered, SkippedClustersRendered.
+ .NOTES
+ Author : AzLocal.UpdateManagement
+ Version : 0.8.5 (Step.6 thin-YAML port)
+ #>
+ [CmdletBinding()]
+ [OutputType([void])]
+ [OutputType([pscustomobject])]
+ param(
+ [Parameter(Mandatory = $true)]
+ [AllowEmptyString()]
+ [string]$UpdateRing,
+
+ [switch]$DryRun,
+
+ [Parameter(Mandatory = $false)] [object]$TotalCount = 0,
+ [Parameter(Mandatory = $false)] [object]$ReadyCount = 0,
+ [Parameter(Mandatory = $false)] [object]$Succeeded = 0,
+ [Parameter(Mandatory = $false)] [object]$Skipped = 0,
+ [Parameter(Mandatory = $false)] [object]$Failed = 0,
+ [Parameter(Mandatory = $false)] [object]$HealthBlocked = 0,
+ [Parameter(Mandatory = $false)] [object]$ScheduleBlocked = 0,
+ [Parameter(Mandatory = $false)] [object]$SideloadedBlocked = 0,
+ [Parameter(Mandatory = $false)] [object]$ExcludedByTag = 0,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [string]$ApplyResultsJsonPath = '',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [string]$ReadinessCsvPath = '',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 10000)]
+ [int]$MaxClusterActionRows = 200,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 10000)]
+ [int]$MaxSkippedRows = 100,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'azlocal-step6-apply-summary.md',
+
+ [switch]$PassThru
+ )
+
+ Set-StrictMode -Version Latest
+ $ErrorActionPreference = 'Stop'
+
+ $pipelineHost = Get-AzLocalPipelineHost
+ $useShortcodeIcons = ($pipelineHost -eq 'AzureDevOps')
+
+ # Unicode emoji glyphs (GH/Local) vs GitHub-Markdown shortcodes (ADO).
+ $iconSuccess = if ($useShortcodeIcons) { ':white_check_mark:' } else { [string][char]0x2705 }
+ $iconFail = if ($useShortcodeIcons) { ':x:' } else { [string][char]0x274C }
+ $iconBlock = if ($useShortcodeIcons) { ':no_entry:' } else { [string][char]0x26D4 }
+ $iconSkip = if ($useShortcodeIcons) { ':next_track_button:' } else { ([string][char]0x23ED + [string][char]0xFE0F) }
+ $iconWarn = if ($useShortcodeIcons) { ':warning:' } else { ([string][char]0x26A0 + [string][char]0xFE0F) }
+
+ $headingLevel = if ($pipelineHost -eq 'AzureDevOps') { '#' } else { '##' }
+
+ # Coerce numeric inputs.
+ $totalInt = [int]([string]$TotalCount)
+ $readyInt = [int]([string]$ReadyCount)
+ $succeededInt = [int]([string]$Succeeded)
+ $skippedInt = [int]([string]$Skipped)
+ $failedInt = [int]([string]$Failed)
+ $healthBlockedInt = [int]([string]$HealthBlocked)
+ $scheduleBlockedInt = [int]([string]$ScheduleBlocked)
+ $sideloadedInt = [int]([string]$SideloadedBlocked)
+ $excludedTagInt = [int]([string]$ExcludedByTag)
+
+ $sb = New-Object System.Text.StringBuilder
+
+ [void]$sb.AppendLine("$headingLevel Update Application Summary")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("**Target UpdateRing:** $UpdateRing")
+ [void]$sb.AppendLine()
+
+ if ($DryRun) {
+ [void]$sb.AppendLine("**This was a dry run. No updates were applied.**")
+ [void]$sb.AppendLine()
+ }
+
+ $h3 = if ($pipelineHost -eq 'AzureDevOps') { '##' } else { '###' }
+
+ [void]$sb.AppendLine("$h3 Readiness")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('| Metric | Count |')
+ [void]$sb.AppendLine('|--------|-------|')
+ [void]$sb.AppendLine("| Total Clusters | $totalInt |")
+ [void]$sb.AppendLine("| Ready for Update | $readyInt |")
+ [void]$sb.AppendLine()
+
+ [void]$sb.AppendLine("$h3 Results")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('| Status | Count |')
+ [void]$sb.AppendLine('|--------|-------|')
+ [void]$sb.AppendLine("| Updates Started | $succeededInt |")
+ [void]$sb.AppendLine("| Skipped | $skippedInt |")
+ [void]$sb.AppendLine("| Failed | $failedInt |")
+ [void]$sb.AppendLine("| Health Blocked | $healthBlockedInt |")
+ [void]$sb.AppendLine("| Schedule Blocked | $scheduleBlockedInt |")
+ [void]$sb.AppendLine("| Sideloaded Blocked | $sideloadedInt |")
+ [void]$sb.AppendLine("| Excluded By Tag | $excludedTagInt |")
+
+ $actionsRendered = 0
+
+ # Per-cluster apply results table (from apply-results.json).
+ if ($ApplyResultsJsonPath -and (Test-Path -LiteralPath $ApplyResultsJsonPath)) {
+ $applyRows = @(Get-Content -Raw -Path $ApplyResultsJsonPath | ConvertFrom-Json)
+ if ($applyRows.Count -gt 0) {
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("$h3 Cluster Actions ($($applyRows.Count) cluster(s))")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('| Cluster | Status | Update | Duration | Message |')
+ [void]$sb.AppendLine('|---|---|---|---|---|')
+ $startedStates = @('UpdateStarted', 'Started', 'Success')
+ $blockedStates = @('HealthCheckBlocked', 'ScheduleBlocked', 'SideloadedBlocked', 'ExcludedByTag', 'NotConnected')
+ $failedStates = @('Failed', 'Error', 'NotFound')
+ foreach ($r in ($applyRows | Sort-Object Status, ClusterName)) {
+ if ($actionsRendered -ge $MaxClusterActionRows) { break }
+ $st = "$($r.Status)"
+ $icon = if ($startedStates -contains $st) { $iconSuccess }
+ elseif ($failedStates -contains $st) { $iconFail }
+ elseif ($blockedStates -contains $st) { $iconBlock }
+ else { $iconSkip }
+ $upd = if ($r.UpdateName) { '`' + $r.UpdateName + '`' } else { '-' }
+ $dur = if ($r.Duration) { "$($r.Duration)" } else { '-' }
+ $msg = "$($r.Message)"
+ if ($msg.Length -gt 180) { $msg = $msg.Substring(0, 177) + '...' }
+ $msg = $msg -replace '\|', '\|' -replace '\r?\n', ' '
+ [void]$sb.AppendLine("| ``$($r.ClusterName)`` | $icon $st | $upd | $dur | $msg |")
+ $actionsRendered++
+ }
+ }
+ }
+
+ # Clusters Skipped at Readiness Gate table (from readiness-report.csv).
+ $skippedRendered = 0
+ if ($ReadinessCsvPath -and (Test-Path -LiteralPath $ReadinessCsvPath)) {
+ $blockedRows = @(Import-Csv -Path $ReadinessCsvPath | Where-Object { $_.ReadyForUpdate -ne 'True' })
+ if ($blockedRows.Count -gt 0) {
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("$h3 Clusters Skipped at Readiness Gate ($($blockedRows.Count) cluster(s))")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('_These clusters were assessed by Check Update Readiness but not handed to Apply Updates. Resolve the listed blocking reasons (or wait for them to clear) then re-run the pipeline._')
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('| Cluster | Update State | Health | Current Version | Recommended | Blocking Reasons |')
+ [void]$sb.AppendLine('|---|---|---|---|---|---|')
+ foreach ($b in ($blockedRows | Sort-Object UpdateState, ClusterName)) {
+ if ($skippedRendered -ge $MaxSkippedRows) { break }
+ $blocking = "$($b.BlockingReasons)"
+ if ($blocking.Length -gt 200) { $blocking = $blocking.Substring(0, 197) + '...' }
+ $blocking = $blocking -replace '\|', '\|' -replace '\r?\n', ' '
+ $reco = if ($b.RecommendedUpdate) { '`' + $b.RecommendedUpdate + '`' } else { '-' }
+ $curr = if ($b.CurrentVersion) { '`' + $b.CurrentVersion + '`' } else { '-' }
+ $hSt = "$($b.HealthState)"
+ $hCell = switch -Regex ($hSt) {
+ '^Success$' { "$iconSuccess $hSt"; break }
+ '^Warning$' { "$iconWarn $hSt"; break }
+ '^Failure$' { "$iconFail $hSt"; break }
+ default { $hSt }
+ }
+ [void]$sb.AppendLine("| ``$($b.ClusterName)`` | $($b.UpdateState) | $hCell | $curr | $reco | $blocking |")
+ $skippedRendered++
+ }
+ if ($blockedRows.Count -gt $MaxSkippedRows) {
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("_Showing first $MaxSkippedRows of $($blockedRows.Count) skipped clusters. Download the readiness-report.csv artifact for the full list._")
+ }
+ }
+ }
+
+ # Actions Required section (suppressed when -DryRun was set, matching ADO
+ # prior behaviour). GitHub always rendered it - keep consistent: emit
+ # when there is at least one actionable bucket regardless of dry-run.
+ # NOTE: prior GH inline block rendered Actions Required even on dry-run,
+ # so we match GH and ALWAYS rendered when non-dry; for dry-run we skip
+ # on ADO (matching ADO prior behaviour) but emit on GitHub.
+ $shouldRenderActions = if ($DryRun -and $pipelineHost -eq 'AzureDevOps') { $false } else { $true }
+ $actionsNeeded = @()
+ if ($shouldRenderActions) {
+ if ($failedInt -gt 0) { $actionsNeeded += "- **$failedInt cluster(s) failed** - Review pipeline logs and cluster health in Azure Portal" }
+ if ($healthBlockedInt -gt 0) { $actionsNeeded += "- **$healthBlockedInt cluster(s) blocked by health checks** - Resolve critical health failures before retrying" }
+ if ($scheduleBlockedInt -gt 0) { $actionsNeeded += "- **$scheduleBlockedInt cluster(s) outside maintenance window** - Updates will proceed when the cluster's UpdateStartWindow schedule allows, or re-run during the maintenance window" }
+ if ($sideloadedInt -gt 0) { $actionsNeeded += "- **$sideloadedInt cluster(s) blocked by UpdateSideloaded=False** - Operator must stage the sideloaded payload and flip the tag to True (or run Reset-AzLocalSideloadedTag) before updates can proceed" }
+ if ($excludedTagInt -gt 0) { $actionsNeeded += "- **$excludedTagInt cluster(s) excluded by UpdateExcluded=True operator override** - Flip the cluster's UpdateExcluded tag to False (Azure portal or 'az tag update') once the cluster should rejoin automation" }
+ }
+ if ($actionsNeeded.Count -gt 0) {
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("$h3 Actions Required")
+ [void]$sb.AppendLine()
+ foreach ($a in $actionsNeeded) { [void]$sb.AppendLine($a) }
+ }
+
+ $summaryPath = Add-AzLocalPipelineStepSummary -Markdown $sb.ToString() -SummaryFileName $SummaryFileName
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ SummaryPath = $summaryPath
+ ActionsRequiredCount = $actionsNeeded.Count
+ ClusterActionsRendered = $actionsRendered
+ SkippedClustersRendered = $skippedRendered
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Add-AzLocalNoReadyClustersStepSummary.ps1 b/AzLocal.UpdateManagement/Public/Add-AzLocalNoReadyClustersStepSummary.ps1
new file mode 100644
index 00000000..ae51b8ff
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Add-AzLocalNoReadyClustersStepSummary.ps1
@@ -0,0 +1,97 @@
+function Add-AzLocalNoReadyClustersStepSummary {
+ <#
+ .SYNOPSIS
+ Renders the 'No Clusters Ready for Update' markdown section emitted by
+ the third Step.6 job (no-clusters-ready / NoClustersReady stage).
+ .DESCRIPTION
+ v0.8.5 Step.6 thin-YAML helper. Replaces the ~25-line inline `run:`
+ block in both Step.6 pipelines (GH job no-clusters-ready, ADO stage
+ NoClustersReady).
+
+ Behaviour matches the prior inline block:
+ - Emits the same Markdown headings and bullet lists.
+ - When -TotalCount is 0: renders the "No clusters found with
+ UpdateRing tag value 'X'" message.
+ - When -TotalCount > 0: renders the "Found N cluster(s) ... but none
+ are ready" message + "Possible reasons" bullet list.
+ - On GitHub Actions ONLY: also emits Write-Warning with the same
+ text the prior inline block did (matches the GH no-clusters-ready
+ run block's `Write-Warning "No clusters ready for update in ring
+ ''"` final line so logs are identical).
+ - On Azure DevOps ONLY: emits the same task.logissue warning the
+ prior inline block did.
+ .PARAMETER UpdateRing
+ Resolved UpdateRing label (string; may be empty for schedule-no-row case).
+ .PARAMETER TotalCount
+ Total count of clusters discovered by the readiness query (string-
+ or-int accepted). 0 = no clusters found at all.
+ .PARAMETER SummaryFileName
+ Per-task markdown filename (ADO/Local). Default
+ 'azlocal-step6-no-ready-summary.md'.
+ .PARAMETER PassThru
+ Returns PSCustomObject with: SummaryPath.
+ .NOTES
+ Author : AzLocal.UpdateManagement
+ Version : 0.8.5 (Step.6 thin-YAML port)
+ #>
+ [CmdletBinding()]
+ [OutputType([void])]
+ [OutputType([pscustomobject])]
+ param(
+ [Parameter(Mandatory = $true)]
+ [AllowEmptyString()]
+ [string]$UpdateRing,
+
+ [Parameter(Mandatory = $false)]
+ [object]$TotalCount = 0,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'azlocal-step6-no-ready-summary.md',
+
+ [switch]$PassThru
+ )
+
+ Set-StrictMode -Version Latest
+ $ErrorActionPreference = 'Stop'
+
+ $pipelineHost = Get-AzLocalPipelineHost
+ $headingLevel = if ($pipelineHost -eq 'AzureDevOps') { '#' } else { '##' }
+ $totalInt = [int]([string]$TotalCount)
+
+ $sb = New-Object System.Text.StringBuilder
+ [void]$sb.AppendLine("$headingLevel No Clusters Ready for Update")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("**Target UpdateRing:** $UpdateRing")
+ [void]$sb.AppendLine()
+
+ if ($totalInt -eq 0) {
+ [void]$sb.AppendLine("No clusters found with UpdateRing tag value '$UpdateRing'")
+ }
+ else {
+ [void]$sb.AppendLine("Found $totalInt cluster(s) with UpdateRing='$UpdateRing', but none are ready for updates.")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('Possible reasons:')
+ [void]$sb.AppendLine('- Clusters may already be up to date')
+ [void]$sb.AppendLine('- Updates may be in progress')
+ [void]$sb.AppendLine('- Clusters may have health check failures')
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('Download the readiness report artifact for details.')
+ }
+
+ $summaryPath = Add-AzLocalPipelineStepSummary -Markdown $sb.ToString() -SummaryFileName $SummaryFileName
+
+ # Preserve per-host log surfacing of the warning (byte-for-byte equivalent
+ # to the prior inline run-block).
+ switch ($pipelineHost) {
+ 'GitHub' { Write-Warning "No clusters ready for update in ring '$UpdateRing'" }
+ 'AzureDevOps' { Write-Host "##vso[task.logissue type=warning]No clusters are ready for updates in ring '$UpdateRing'" }
+ default { Write-Warning "No clusters ready for update in ring '$UpdateRing'" }
+ }
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ SummaryPath = $summaryPath
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Add-AzLocalPipelineVersionBanner.ps1 b/AzLocal.UpdateManagement/Public/Add-AzLocalPipelineVersionBanner.ps1
new file mode 100644
index 00000000..20170e8a
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Add-AzLocalPipelineVersionBanner.ps1
@@ -0,0 +1,200 @@
+function Add-AzLocalPipelineVersionBanner {
+ <#
+ .SYNOPSIS
+ Emits the module-version drift banner and step outputs that every
+ AzLocal.UpdateManagement Step.*.yml install step needs.
+
+ .DESCRIPTION
+ Foundation cmdlet for the v0.8.5 thin-YAML refactor. Condenses the
+ ~50-line install/drift/banner block that the v0.8.4 Step.*.yml
+ files inline into ONE cmdlet call. The Step.*.yml install step
+ becomes a three-liner:
+
+ Install-Module AzLocal.UpdateManagement -Scope CurrentUser -Force -AllowClobber
+ Import-Module AzLocal.UpdateManagement -Force
+ Add-AzLocalPipelineVersionBanner -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION -PinnedVersion $env:REQUIRED_MODULE_VERSION
+
+ The cmdlet:
+ 1. Resolves the INSTALLED module version (handling the
+ multi-entry Get-Module quirk when nested modules are loaded)
+ 2. Looks up the LATEST version on PSGallery via Find-Module
+ (unless -SkipPSGalleryQuery is set)
+ 3. Prints a "Module version summary" console block (identical
+ shape to the v0.8.4 inline block so log greps keep working)
+ 4. Emits up to three drift annotations via
+ Write-AzLocalPipelineWarning / Write-AzLocalPipelineNotice:
+ - WARNING when installed < generated (YAML newer than module)
+ - NOTICE when installed > generated (YAML older than module)
+ - NOTICE when latest > installed (newer module on PSGallery)
+ 5. Appends a one-line banner to the rendered step summary via
+ Add-AzLocalPipelineStepSummary
+ 6. Emits three step outputs via Set-AzLocalPipelineOutput:
+ installed_module_version, generated_against_version,
+ latest_on_psgallery
+ 7. Optionally returns a PSCustomObject describing the verdict
+ when -PassThru is set (for test harnesses + downstream steps).
+
+ Host detection (GitHub / AzureDevOps / Local) flows through the
+ existing Phase 0 Private helpers - no per-host branching inside
+ this cmdlet.
+
+ .PARAMETER GeneratedAgainstVersion
+ The module version this workflow YAML was generated against
+ (typically '$env:GENERATED_AGAINST_MODULE_VERSION'). Required;
+ must parse as a [version].
+
+ .PARAMETER PinnedVersion
+ The module version the operator pinned via the
+ REQUIRED_MODULE_VERSION env var / workflow input. Empty / $null
+ means "latest (fix-forward)". Used only for the human-readable
+ "pin status" segment of the rendered banner.
+
+ .PARAMETER ModuleName
+ The PSGallery module to look up. Defaults to
+ 'AzLocal.UpdateManagement'. Parameterised so the cmdlet can be
+ unit-tested against a synthetic module without touching the
+ real Find-Module call.
+
+ .PARAMETER PSGalleryRepositoryName
+ The Find-Module -Repository value. Defaults to 'PSGallery'.
+
+ .PARAMETER SkipPSGalleryQuery
+ When set, the cmdlet does NOT call Find-Module. The "latest on
+ PSGallery" segment of the banner renders as
+ '(PSGallery lookup skipped)' and the step output
+ 'latest_on_psgallery' is the empty string. Use for offline
+ runners or in tests.
+
+ .PARAMETER SummaryFileName
+ Forwarded to Add-AzLocalPipelineStepSummary. Defaults to
+ 'azlocal-version-banner.md'. Ignored on GitHub Actions (which
+ uses a single $env:GITHUB_STEP_SUMMARY file managed by the
+ runner).
+
+ .PARAMETER PassThru
+ When set, returns a PSCustomObject with InstalledVersion,
+ GeneratedAgainstVersion, LatestOnPSGallery, PinStatus, Verdict.
+
+ .OUTPUTS
+ Nothing by default (side effects only). When -PassThru is set,
+ returns a single PSCustomObject:
+ InstalledVersion [version]
+ GeneratedAgainstVersion [version]
+ LatestOnPSGallery [version] or $null
+ PinStatus [string] - 'pinned to vX.Y.Z' or 'latest (fix-forward)'
+ Verdict [string] - one of:
+ 'in sync'
+ 'YAML newer than module - check REQUIRED_MODULE_VERSION'
+ 'YAML older than module - run Copy-AzLocalPipelineExample -Update'
+ 'newer module available on PSGallery'
+
+ .EXAMPLE
+ Add-AzLocalPipelineVersionBanner -GeneratedAgainstVersion '0.8.5'
+
+ Default usage from a Step.*.yml install step. Emits drift
+ annotations + banner + step outputs.
+
+ .EXAMPLE
+ $info = Add-AzLocalPipelineVersionBanner -GeneratedAgainstVersion '0.8.5' -PinnedVersion '0.8.5' -PassThru
+ if ($info.Verdict -ne 'in sync') { ... }
+ #>
+ [CmdletBinding()]
+ [OutputType([PSCustomObject])]
+ param(
+ [Parameter(Mandatory = $true)]
+ [ValidatePattern('^\d+\.\d+\.\d+(\.\d+)?$')]
+ [string]$GeneratedAgainstVersion,
+
+ [Parameter()]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$PinnedVersion,
+
+ [Parameter()]
+ [ValidateNotNullOrEmpty()]
+ [string]$ModuleName = 'AzLocal.UpdateManagement',
+
+ [Parameter()]
+ [ValidateNotNullOrEmpty()]
+ [string]$PSGalleryRepositoryName = 'PSGallery',
+
+ [Parameter()]
+ [switch]$SkipPSGalleryQuery,
+
+ [Parameter()]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'azlocal-version-banner.md',
+
+ [Parameter()]
+ [switch]$PassThru
+ )
+
+ $generated = [version]$GeneratedAgainstVersion
+
+ $installedModule = Get-Module -Name $ModuleName | Sort-Object Version -Descending | Select-Object -First 1
+ if (-not $installedModule) {
+ throw "Add-AzLocalPipelineVersionBanner: module '$ModuleName' is not loaded. Call Import-Module before invoking this cmdlet."
+ }
+ $installed = [version]$installedModule.Version
+
+ $latest = $null
+ if (-not $SkipPSGalleryQuery) {
+ try {
+ $found = Find-Module -Name $ModuleName -Repository $PSGalleryRepositoryName -ErrorAction Stop
+ if ($found -and $found.Version) {
+ $latest = [version]$found.Version
+ }
+ } catch {
+ Write-Verbose "Add-AzLocalPipelineVersionBanner: Find-Module lookup failed - $($_.Exception.Message)"
+ }
+ }
+
+ $pinStatus = if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { 'latest (fix-forward)' } else { "pinned to v$PinnedVersion" }
+ $latestStr = if ($SkipPSGalleryQuery) { '(PSGallery lookup skipped)' } elseif ($latest) { "v$latest" } else { '(PSGallery lookup failed)' }
+ $verdict = if ($installed -lt $generated) { 'YAML newer than module - check REQUIRED_MODULE_VERSION' }
+ elseif ($installed -gt $generated) { 'YAML older than module - run Copy-AzLocalPipelineExample -Update' }
+ elseif ($latest -and ($latest -gt $installed)) { 'newer module available on PSGallery' }
+ else { 'in sync' }
+
+ Write-Host ''
+ Write-Host 'Module version summary'
+ Write-Host " Installed on runner : $installed"
+ Write-Host " YAML generated against : $generated"
+ Write-Host " Latest on PSGallery : $(if ($SkipPSGalleryQuery) { '(skipped)' } elseif ($latest) { $latest } else { '(lookup failed - check network)' })"
+ Write-Host " Pin status : $pinStatus"
+ Write-Host " Verdict : $verdict"
+ Write-Host ''
+
+ if ($installed -lt $generated) {
+ Write-AzLocalPipelineWarning `
+ -Title "$ModuleName is older than workflow YAML expects" `
+ -Message "$ModuleName v$installed is OLDER than the version this workflow YAML was generated against (v$generated). Cmdlets, parameters, or output schemas referenced by this YAML may not exist in v$installed. Set REQUIRED_MODULE_VERSION to v$generated, or refresh the YAML to match the installed module via 'Copy-AzLocalPipelineExample -Update'."
+ }
+ if ($installed -gt $generated) {
+ Write-AzLocalPipelineNotice `
+ -Title 'Workflow YAML may be stale' `
+ -Message "Workflow YAML was generated against $ModuleName v$generated but the runner installed v$installed. Pipeline steps may have been improved in later releases - to refresh, re-run 'Copy-AzLocalPipelineExample -Update' (you will be prompted per file; add -Confirm:`$false to bypass). Pipeline YAMLs are under git so 'git diff' shows exactly what changed before commit."
+ }
+ if ($latest -and ($latest -gt $installed)) {
+ Write-AzLocalPipelineNotice `
+ -Title "Newer $ModuleName version available on PSGallery" `
+ -Message "$ModuleName v$latest is available on PSGallery; this run installed v$installed. Review the module CHANGELOG before bumping REQUIRED_MODULE_VERSION (or clear the pin to install the latest automatically)."
+ }
+
+ $banner = "_Pipeline YAML v$generated | Module v$installed installed ($pinStatus) | PSGallery latest $latestStr | ${verdict}_`n"
+ [void](Add-AzLocalPipelineStepSummary -Markdown $banner -SummaryFileName $SummaryFileName)
+
+ Set-AzLocalPipelineOutput -Name 'installed_module_version' -Value $installed.ToString()
+ Set-AzLocalPipelineOutput -Name 'generated_against_version' -Value $generated.ToString()
+ Set-AzLocalPipelineOutput -Name 'latest_on_psgallery' -Value $(if ($latest) { $latest.ToString() } else { '' })
+
+ if ($PassThru) {
+ [PSCustomObject]@{
+ InstalledVersion = $installed
+ GeneratedAgainstVersion = $generated
+ LatestOnPSGallery = $latest
+ PinStatus = $pinStatus
+ Verdict = $verdict
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalApplyUpdatesScheduleAudit.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalApplyUpdatesScheduleAudit.ps1
new file mode 100644
index 00000000..7f87bbbd
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalApplyUpdatesScheduleAudit.ps1
@@ -0,0 +1,613 @@
+function Export-AzLocalApplyUpdatesScheduleAudit {
+ <#
+ .SYNOPSIS
+ Runs the Step.3 Apply-Updates Schedule Coverage Audit workload:
+ Test-AzLocalApplyUpdatesScheduleCoverage (Audit + Matrix +
+ Recommend views) + JUnit XML + markdown step summary + cycle
+ calendar + allow-list coverage + step outputs for the v0.8.5
+ thin-YAML Step.3 pipeline.
+
+ .DESCRIPTION
+ Phase 1 (v0.8.5) of the thin-YAML refactor. Condenses the
+ ~220-line inline `run: |` audit block and the ~210-line inline
+ Create Summary block in v0.8.4 Step.3_apply-updates-schedule-
+ audit.yml (GitHub Actions + Azure DevOps) into a single cmdlet
+ call so the per-platform yml shrinks to a few lines and the
+ workload becomes unit-testable against synthetic schedule and
+ pipeline YAML inputs.
+
+ The cmdlet:
+
+ 1. Resolves the output directory (defaults to './reports' on
+ GitHub Actions / Local, or `$env:BUILD_ARTIFACTSTAGINGDIRECTORY`
+ on Azure DevOps).
+ 2. Calls `Test-AzLocalApplyUpdatesScheduleCoverage` 3 times:
+ -View Audit -PassThru (rows + CSV), -View Matrix
+ (CSV only), -View Recommend (markdown only). Re-uses the
+ v0.7.65+ advisor instead of re-implementing the
+ ring/cron diff math inline.
+ 3. Bucketises rows by Status into Covered / Uncovered /
+ PartiallyCovered / MalformedTag / UnparseableCron /
+ NoWindowTag / RingMissingFromSchedule /
+ RingOrphanedInSchedule / RingMixedWindows.
+ 4. Builds a JUnit XML report via the shared
+ `New-AzLocalPipelineJUnitXml` Private helper. Schedule
+ rows go in the 'Schedule (ring diff)' suite FIRST
+ (higher blast radius), Cron rows in the 'Cron coverage'
+ suite. Any non-Covered status becomes a .
+ 5. Emits 12 step outputs via `Set-AzLocalPipelineOutput`
+ (lowercase snake_case per v0.8.5 convention):
+ total_rows, covered, uncovered, partial, malformed,
+ unparseable, no_window_tag, ring_missing, ring_orphan,
+ ring_mixed, have_schedule, schedule_path.
+ 6. Builds the markdown step summary:
+ - Summary counts table (10 rows)
+ - Recommend snippet at the top when $hasIssues
+ - Audit Detail - Schedule (ring-file gap) sub-table
+ (rendered whenever -SchedulePath was supplied)
+ - Allow-list coverage section (renders schema v1
+ migration nudge or schema v2 per-row effective
+ allow-list with optional pin-snippet)
+ - Audit Detail - Cron coverage sub-table
+ - Recommend snippet at the bottom when clean fleet
+ - **Cycle calendar** - ALWAYS rendered when
+ -SchedulePath is supplied (v0.8.5 fix for the v0.8.4
+ $hasIssues-gate regression that silently dropped the
+ calendar from clean-fleet runs).
+ - Reports list with artifact filenames
+ 7. Pushes the markdown via `Add-AzLocalPipelineStepSummary`.
+
+ Internal reuse (per the v0.8.5 thin-YAML consistency contract):
+ * `Test-AzLocalApplyUpdatesScheduleCoverage` for advisor data.
+ * `Get-AzLocalApplyUpdatesScheduleConfig` for allow-list / cycle.
+ * `Get-AzLocalApplyUpdatesScheduleCycleCalendar -AsMarkdown
+ -IncludePerRingSummary` for the calendar section.
+ * `New-AzLocalPipelineJUnitXml` for JUnit XML.
+ * `Add-AzLocalPipelineStepSummary` for the rendered markdown.
+ * `Set-AzLocalPipelineOutput` for the step outputs.
+ * `Get-AzLocalPipelineHost` is implicit (the above branch on it).
+
+ .PARAMETER OutputDirectory
+ Directory to write artifacts into. Created if it does not exist.
+ Defaults to './reports' (GH / Local) or
+ `$env:BUILD_ARTIFACTSTAGINGDIRECTORY` (Azure DevOps).
+
+ .PARAMETER PipelineYamlPath
+ Path (file or folder) to Step.6_apply-updates.yml. REQUIRED so
+ the Recommend view can diff its proposed crons against what is
+ already in Step.6 and only emit a snippet for the truly missing
+ entries.
+
+ .PARAMETER SchedulePath
+ Optional path to apply-updates-schedule.yml. When set, the audit
+ also reports RingMissingFromSchedule / RingOrphanedInSchedule
+ rows, the Allow-list coverage section, and the always-rendered
+ Cycle calendar.
+
+ .PARAMETER LeadTimeMinutes
+ Minutes before UpdateStartWindow opens that the pipeline should
+ fire (0-60). Default 5.
+
+ .PARAMETER RecommendFiresPerWindow
+ Cron entries the Recommend view should emit per UpdateStartWindow
+ segment. 1 = opening edge only. 2 = belt-and-braces (default).
+
+ .PARAMETER IncludeUntagged
+ Surface clusters with no UpdateStartWindow tag as their own row.
+
+ .PARAMETER ClusterCsvPath
+ Optional path to the source-controlled cluster inventory CSV.
+ When set (and the file exists) the Recommend view emits a
+ NoWindowTag remediation section.
+
+ .PARAMETER Platform
+ Pipeline platform for the Recommend snippet:
+ GitHubActions (default in pipeline contexts), AzureDevOps, Both.
+
+ .PARAMETER AuditCsvFileName
+ Filename for the per-(Ring, Window) audit CSV.
+ Default 'schedule-coverage-audit.csv'.
+
+ .PARAMETER MatrixCsvFileName
+ Filename for the matrix-view CSV. Default 'schedule-coverage-matrix.csv'.
+
+ .PARAMETER RecommendMdFileName
+ Filename for the Recommend snippet markdown.
+ Default 'schedule-coverage-recommend.md'.
+
+ .PARAMETER JUnitXmlFileName
+ Filename for the JUnit XML report.
+ Default 'schedule-coverage-audit.xml'.
+
+ .PARAMETER SummaryFileName
+ Per-task markdown summary filename used by
+ `Add-AzLocalPipelineStepSummary` on Azure DevOps and Local hosts.
+ Default 'schedule-coverage-summary.md'.
+
+ .PARAMETER InstalledModuleVersion
+ Optional [string] used in the markdown footer
+ ('Generated by AzLocal.UpdateManagement v').
+
+ .PARAMETER PassThru
+ When set, returns a single PSCustomObject summarising the run.
+ Without -PassThru the cmdlet emits nothing to the pipeline; the
+ artifacts and step outputs are still produced.
+
+ .OUTPUTS
+ Nothing by default. When -PassThru is set, a single PSCustomObject
+ with: TotalRows, Covered, Uncovered, Partial, Malformed,
+ Unparseable, NoWindowTag, RingMissing, RingOrphan, RingMixed,
+ HaveSchedule, SchedulePath, AuditRows, AuditCsvPath,
+ MatrixCsvPath, RecommendMdPath, JUnitXmlPath, SummaryPath.
+
+ .EXAMPLE
+ Export-AzLocalApplyUpdatesScheduleAudit `
+ -PipelineYamlPath '.github/workflows' `
+ -SchedulePath '.github/apply-updates-schedule.yml' `
+ -Platform GitHubActions -PassThru
+
+ .NOTES
+ Author: Neil Bird, MSFT
+ Added: v0.8.5
+ Module: AzLocal.UpdateManagement
+ #>
+ [CmdletBinding()]
+ [OutputType([pscustomobject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [string]$OutputDirectory,
+
+ [Parameter(Mandatory = $true)]
+ [ValidateNotNullOrEmpty()]
+ [string]$PipelineYamlPath,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$SchedulePath,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(0, 60)]
+ [int]$LeadTimeMinutes = 5,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 2)]
+ [int]$RecommendFiresPerWindow = 2,
+
+ [Parameter(Mandatory = $false)]
+ [switch]$IncludeUntagged,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$ClusterCsvPath,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateSet('GitHubActions', 'AzureDevOps', 'Both')]
+ [string]$Platform = 'GitHubActions',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$AuditCsvFileName = 'schedule-coverage-audit.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$MatrixCsvFileName = 'schedule-coverage-matrix.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$RecommendMdFileName = 'schedule-coverage-recommend.md',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$JUnitXmlFileName = 'schedule-coverage-audit.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'schedule-coverage-summary.md',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$InstalledModuleVersion,
+
+ [Parameter(Mandatory = $false)]
+ [switch]$PassThru
+ )
+
+ Set-StrictMode -Version Latest
+ $ErrorActionPreference = 'Stop'
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ if (-not $OutputDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $OutputDirectory = $env:BUILD_ARTIFACTSTAGINGDIRECTORY
+ }
+ else {
+ $OutputDirectory = './reports'
+ }
+ }
+ if (-not (Test-Path -LiteralPath $OutputDirectory)) {
+ New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
+ }
+
+ if (-not (Test-Path -LiteralPath $PipelineYamlPath)) {
+ throw "PipelineYamlPath '$PipelineYamlPath' does not exist. Set it to the folder containing Step.6_apply-updates.yml (e.g. '.github/workflows' or '.azure-pipelines') so the Recommend view can diff its proposed crons against the existing file."
+ }
+
+ $haveSchedule = $false
+ if ($SchedulePath -and (Test-Path -LiteralPath $SchedulePath)) {
+ $haveSchedule = $true
+ }
+ $haveCsv = $false
+ if ($ClusterCsvPath -and (Test-Path -LiteralPath $ClusterCsvPath)) {
+ $haveCsv = $true
+ }
+
+ $auditCsv = Join-Path -Path $OutputDirectory -ChildPath $AuditCsvFileName
+ $matrixCsv = Join-Path -Path $OutputDirectory -ChildPath $MatrixCsvFileName
+ $recoMd = Join-Path -Path $OutputDirectory -ChildPath $RecommendMdFileName
+ $xmlPath = Join-Path -Path $OutputDirectory -ChildPath $JUnitXmlFileName
+
+ Write-Host '========================================'
+ Write-Host 'Apply-Updates Schedule Coverage Audit'
+ Write-Host '========================================'
+ Write-Host "PipelineYamlPath : $PipelineYamlPath"
+ Write-Host "SchedulePath : $(if ($haveSchedule) { $SchedulePath } else { '(skipped - empty or missing)' })"
+ Write-Host "LeadTimeMinutes : $LeadTimeMinutes"
+ Write-Host "FiresPerWindow : $RecommendFiresPerWindow"
+ Write-Host "IncludeUntagged : $IncludeUntagged"
+ Write-Host "ClusterCsvPath : $(if ($haveCsv) { $ClusterCsvPath } else { '(skipped - empty or missing)' })"
+ Write-Host "Platform : $Platform"
+ Write-Host ''
+
+ # ---- Audit view (rows + CSV) ------------------------------------------
+ $auditArgs = @{
+ View = 'Audit'
+ LeadTimeMinutes = $LeadTimeMinutes
+ RecommendFiresPerWindow = $RecommendFiresPerWindow
+ ExportPath = $auditCsv
+ Platform = $Platform
+ PassThru = $true
+ PipelineYamlPath = $PipelineYamlPath
+ }
+ if ($haveSchedule) { $auditArgs.SchedulePath = $SchedulePath }
+ if ($IncludeUntagged) { $auditArgs.IncludeUntagged = $true }
+ if ($haveCsv) { $auditArgs.ClusterCsvPath = $ClusterCsvPath }
+ $audit = Test-AzLocalApplyUpdatesScheduleCoverage @auditArgs
+ if (-not $audit) { $audit = @() }
+ $audit = @($audit)
+
+ # ---- Matrix view (CSV only) -------------------------------------------
+ Test-AzLocalApplyUpdatesScheduleCoverage -View Matrix `
+ -LeadTimeMinutes $LeadTimeMinutes -ExportPath $matrixCsv | Out-Null
+
+ # ---- Recommend view (markdown only) -----------------------------------
+ $recoArgs = @{
+ View = 'Recommend'
+ LeadTimeMinutes = $LeadTimeMinutes
+ RecommendFiresPerWindow = $RecommendFiresPerWindow
+ Platform = $Platform
+ ExportPath = $recoMd
+ PipelineYamlPath = $PipelineYamlPath
+ }
+ if ($haveSchedule) { $recoArgs.SchedulePath = $SchedulePath }
+ if ($haveCsv) { $recoArgs.ClusterCsvPath = $ClusterCsvPath }
+ Test-AzLocalApplyUpdatesScheduleCoverage @recoArgs | Out-Null
+
+ # ---- Bucketise --------------------------------------------------------
+ $covered = @($audit | Where-Object { $_.Status -eq 'Covered' })
+ $uncovered = @($audit | Where-Object { $_.Status -eq 'Uncovered' })
+ $partial = @($audit | Where-Object { $_.Status -eq 'PartiallyCovered' })
+ $malformed = @($audit | Where-Object { $_.Status -eq 'MalformedTag' })
+ $unparseable = @($audit | Where-Object { $_.Status -eq 'UnparseableCron' })
+ $noWindowTag = @($audit | Where-Object { $_.Status -eq 'NoWindowTag' })
+ $ringMissing = @($audit | Where-Object { $_.Status -eq 'RingMissingFromSchedule' })
+ $ringOrphan = @($audit | Where-Object { $_.Status -eq 'RingOrphanedInSchedule' })
+ $ringMixed = @($audit | Where-Object { $_.Status -eq 'RingMixedWindows' })
+
+ $hasIssues = ($uncovered.Count + $partial.Count + $malformed.Count + $unparseable.Count + $noWindowTag.Count + $ringMissing.Count + $ringOrphan.Count) -gt 0
+
+ Write-Host ''
+ Write-Host 'Audit complete:'
+ Write-Host " Covered : $($covered.Count)"
+ Write-Host " Uncovered : $($uncovered.Count)"
+ Write-Host " PartiallyCovered : $($partial.Count)"
+ Write-Host " MalformedTag : $($malformed.Count)"
+ Write-Host " UnparseableCron : $($unparseable.Count)"
+ Write-Host " NoWindowTag : $($noWindowTag.Count)"
+ Write-Host " RingMissingFromSchedule : $($ringMissing.Count)"
+ Write-Host " RingOrphanedInSchedule : $($ringOrphan.Count)"
+ Write-Host " RingMixedWindows : $($ringMixed.Count)"
+
+ # ---- JUnit XML --------------------------------------------------------
+ $scheduleRows = @($audit | Where-Object { $_.Section -eq 'Schedule' })
+ $cronRows = @($audit | Where-Object { $_.Section -ne 'Schedule' })
+
+ $buildCase = {
+ param($Row)
+ $tcName = '{0} / {1}' -f $Row.UpdateRing, ($(if ($Row.UpdateStartWindow) { $Row.UpdateStartWindow } else { '(no window)' }))
+ $tc = @{ Name = $tcName; ClassName = 'ScheduleCoverage' }
+ if ($Row.Status -ne 'Covered') {
+ $issue = if ($Row.PSObject.Properties['Issue'] -and $Row.Issue) { [string]$Row.Issue } else { '' }
+ $reco = if ($Row.PSObject.Properties['Recommendation'] -and $Row.Recommendation) { [string]$Row.Recommendation } else { '' }
+ $clCnt = if ($Row.PSObject.Properties['ClusterCount']) { [string]$Row.ClusterCount } else { '0' }
+ $body = "Recommendation: $reco`nCluster count: $clCnt"
+ $tc.Failure = @{ Message = $issue; Type = [string]$Row.Status; Body = $body }
+ }
+ $tc
+ }
+
+ $suites = @()
+ if ($haveSchedule -or $scheduleRows.Count -gt 0) {
+ $cases = @()
+ foreach ($r in $scheduleRows) { $cases += ,(& $buildCase $r) }
+ if ($cases.Count -eq 0) {
+ $cases = @(@{ Name = 'Schedule and fleet ring sets match - no gaps.'; ClassName = 'ScheduleCoverage' })
+ }
+ $suites += ,@{
+ Name = 'Apply-Updates Schedule Coverage - Schedule (ring diff)'
+ ClassName = 'ScheduleCoverage'
+ TestCases = $cases
+ }
+ }
+ if ($cronRows.Count -gt 0 -or -not $haveSchedule) {
+ $cases = @()
+ foreach ($r in $cronRows) { $cases += ,(& $buildCase $r) }
+ if ($cases.Count -eq 0) {
+ $cases = @(@{ Name = 'No tagged clusters found - nothing to audit'; ClassName = 'ScheduleCoverage' })
+ }
+ $suites += ,@{
+ Name = 'Apply-Updates Schedule Coverage - Cron coverage'
+ ClassName = 'ScheduleCoverage'
+ TestCases = $cases
+ }
+ }
+ New-AzLocalPipelineJUnitXml -TestSuitesName 'Apply-Updates Schedule Coverage' -Suites $suites -OutputPath $xmlPath | Out-Null
+
+ # ---- Step outputs -----------------------------------------------------
+ Set-AzLocalPipelineOutput -Name 'total_rows' -Value ([string]$audit.Count)
+ Set-AzLocalPipelineOutput -Name 'covered' -Value ([string]$covered.Count)
+ Set-AzLocalPipelineOutput -Name 'uncovered' -Value ([string]$uncovered.Count)
+ Set-AzLocalPipelineOutput -Name 'partial' -Value ([string]$partial.Count)
+ Set-AzLocalPipelineOutput -Name 'malformed' -Value ([string]$malformed.Count)
+ Set-AzLocalPipelineOutput -Name 'unparseable' -Value ([string]$unparseable.Count)
+ Set-AzLocalPipelineOutput -Name 'no_window_tag' -Value ([string]$noWindowTag.Count)
+ Set-AzLocalPipelineOutput -Name 'ring_missing' -Value ([string]$ringMissing.Count)
+ Set-AzLocalPipelineOutput -Name 'ring_orphan' -Value ([string]$ringOrphan.Count)
+ Set-AzLocalPipelineOutput -Name 'ring_mixed' -Value ([string]$ringMixed.Count)
+ Set-AzLocalPipelineOutput -Name 'have_schedule' -Value ([string]$haveSchedule)
+ Set-AzLocalPipelineOutput -Name 'schedule_path' -Value $(if ($haveSchedule) { $SchedulePath } else { '' })
+
+ # ---- Recommend snippet content (for top-of-summary inlining) ----------
+ $recoContent = ''
+ if (Test-Path -LiteralPath $recoMd) {
+ $recoContent = Get-Content -LiteralPath $recoMd -Raw
+ if ($null -eq $recoContent) { $recoContent = '' }
+ }
+
+ # ---- Markdown step summary --------------------------------------------
+ $md = New-Object 'System.Collections.Generic.List[string]'
+ [void]$md.Add('## Apply-Updates Schedule Coverage Audit')
+ [void]$md.Add('')
+ [void]$md.Add('| Metric | Count |')
+ [void]$md.Add('|--------|-------|')
+ [void]$md.Add("| **(Ring, Window) pairs audited** | $($audit.Count) |")
+ [void]$md.Add("| **Covered** | $($covered.Count) |")
+ [void]$md.Add("| **Uncovered** | $($uncovered.Count) |")
+ [void]$md.Add("| **PartiallyCovered** | $($partial.Count) |")
+ [void]$md.Add("| **MalformedTag** | $($malformed.Count) |")
+ [void]$md.Add("| **UnparseableCron** | $($unparseable.Count) |")
+ [void]$md.Add("| **NoWindowTag** | $($noWindowTag.Count) |")
+ [void]$md.Add("| **RingMissingFromSchedule** | $($ringMissing.Count) |")
+ [void]$md.Add("| **RingOrphanedInSchedule** | $($ringOrphan.Count) |")
+ [void]$md.Add("| **RingMixedWindows** | $($ringMixed.Count) |")
+ [void]$md.Add('')
+
+ if ($hasIssues -and $recoContent) {
+ [void]$md.Add($recoContent)
+ [void]$md.Add('')
+ }
+
+ # Helper for the per-section detail table (Schedule + Cron).
+ $addDetailTable = {
+ param([string]$Heading, [object[]]$DetailRows, [string]$EmptyText)
+ if ($Heading) { [void]$md.Add($Heading) }
+ [void]$md.Add('')
+ if ($DetailRows.Count -eq 0) {
+ [void]$md.Add("*$EmptyText*")
+ [void]$md.Add('')
+ return
+ }
+ [void]$md.Add('| Status | UpdateRing | UpdateStartWindow | Clusters | Required Cron (UTC) | Recommendation |')
+ [void]$md.Add('|--------|------------|--------------|---------:|----------------------|----------------|')
+ $shown = 0
+ foreach ($r in $DetailRows) {
+ if ($shown -ge 100) { break }
+ $status = if ($r.PSObject.Properties['Status']) { [string]$r.Status } else { '' }
+ $ring = if ($r.PSObject.Properties['UpdateRing']) { [string]$r.UpdateRing } else { '' }
+ $win = if ($r.PSObject.Properties['UpdateStartWindow']) { [string]$r.UpdateStartWindow } else { '' }
+ $clCnt = if ($r.PSObject.Properties['ClusterCount']) { [string]$r.ClusterCount } else { '' }
+ $reqCron = if ($r.PSObject.Properties['RequiredCronUTC']) { [string]$r.RequiredCronUTC } else { '' }
+ $reco = if ($r.PSObject.Properties['Recommendation']) { [string]$r.Recommendation } else { '' }
+ [void]$md.Add(('| {0} | {1} | {2} | {3} | {4} | {5} |' -f $status, $ring, $win, $clCnt, $reqCron, $reco))
+ $shown++
+ }
+ if ($DetailRows.Count -gt 100) {
+ [void]$md.Add('')
+ [void]$md.Add("*Showing first 100 of $($DetailRows.Count); see ``$AuditCsvFileName`` artifact for the full list.*")
+ }
+ [void]$md.Add('')
+ }
+
+ # Schedule detail (always rendered when -SchedulePath supplied OR when
+ # any Schedule-section rows exist - defensive fallback).
+ if ($haveSchedule -or $scheduleRows.Count -gt 0) {
+ [void]$md.Add('### Audit Detail - Schedule (ring-file gap)')
+ [void]$md.Add('')
+ [void]$md.Add('> **Higher blast radius.** A `RingMissingFromSchedule` row means apply-updates will NEVER fire on those clusters until you either add the ring to `apply-updates-schedule.yml` or retag them onto an existing scheduled ring.')
+ & $addDetailTable '' $scheduleRows 'Schedule and fleet ring sets match - no gaps.'
+ }
+
+ # Allow-list coverage (schema v1 nudge or schema v2 per-row table).
+ if ($haveSchedule) {
+ $sched = $null
+ try {
+ $sched = Get-AzLocalApplyUpdatesScheduleConfig -Path $SchedulePath -ErrorAction Stop
+ }
+ catch {
+ [void]$md.Add('### Allow-list coverage')
+ [void]$md.Add('')
+ [void]$md.Add("*Could not load schedule file ``$SchedulePath`` for allow-list analysis: $($_.Exception.Message)*")
+ [void]$md.Add('')
+ }
+ if ($sched) {
+ [void]$md.Add("### Allow-list coverage (schema v$($sched.SchemaVersion))")
+ [void]$md.Add('')
+ if ($sched.SchemaVersion -lt 2) {
+ [void]$md.Add('*This schedule is on schema v1. Schema v2 adds `allowedUpdateVersions` for fleet-wide + per-ring update allow-lists (e.g. enforce a ''minimum updates'' policy on Prod). Migrate the file with:*')
+ [void]$md.Add('')
+ [void]$md.Add('```powershell')
+ [void]$md.Add("Update-AzLocalApplyUpdatesScheduleConfig -Path '$SchedulePath' -SchemaMigrate")
+ [void]$md.Add('```')
+ [void]$md.Add('')
+ }
+ else {
+ $topAllow = @()
+ if ($sched.PSObject.Properties['AllowedUpdateVersions'] -and $sched.AllowedUpdateVersions) {
+ $topAllow = @($sched.AllowedUpdateVersions)
+ }
+ $topIsLatest = ($topAllow.Count -eq 1 -and $topAllow[0] -eq 'Latest')
+ if ($topIsLatest) {
+ $topLabel = '`Latest` _(no constraint - install the latest Ready update on each cluster)_'
+ }
+ else {
+ $topLabel = "``$($topAllow -join '; ')`` _(explicit allow-list - clusters only install matching updates)_"
+ }
+ [void]$md.Add("**Top-level fleet default:** $topLabel")
+ [void]$md.Add('')
+ [void]$md.Add('| Row | weeksInCycle | daysOfWeek | rings | Effective allowedUpdateVersions |')
+ [void]$md.Add('|----:|--------------|------------|-------|---------------------------------|')
+ $rowsMissingOverride = New-Object System.Collections.Generic.List[object]
+ $rowIdx = 0
+ foreach ($r in @($sched.Schedule)) {
+ $rowIdx++
+ $rowAllow = @()
+ if ($r.PSObject.Properties['AllowedUpdateVersionsParsed'] -and $r.AllowedUpdateVersionsParsed) {
+ $rowAllow = @($r.AllowedUpdateVersionsParsed)
+ }
+ if ($rowAllow.Count -gt 0) {
+ if ($rowAllow.Count -eq 1 -and $rowAllow[0] -eq 'Latest') {
+ $effLabel = '`Latest` _(row override: no constraint)_'
+ }
+ else {
+ $effLabel = "``$($rowAllow -join '; ')`` _(row override)_"
+ }
+ }
+ else {
+ if ($topIsLatest) {
+ $effLabel = '`Latest` _(inherits top-level - no constraint)_'
+ }
+ else {
+ $effLabel = "``$($topAllow -join '; ')`` _(inherits top-level)_"
+ }
+ $rowsMissingOverride.Add([pscustomobject]@{
+ Row = $rowIdx
+ WeeksInCycle = $r.weeksInCycle
+ DaysOfWeek = $r.daysOfWeek
+ Rings = $r.rings
+ })
+ }
+ [void]$md.Add(('| {0} | {1} | {2} | {3} | {4} |' -f $rowIdx, $r.weeksInCycle, $r.daysOfWeek, $r.rings, $effLabel))
+ }
+ [void]$md.Add('')
+ if ($rowsMissingOverride.Count -gt 0) {
+ [void]$md.Add("*$($rowsMissingOverride.Count) row(s) inherit the top-level allow-list. This is fine when you want each ring to install the latest Ready update as soon as it is available.*")
+ [void]$md.Add('')
+ [void]$md.Add("### Optional - pin a ring to a specific update in ``$SchedulePath``")
+ [void]$md.Add('')
+ [void]$md.Add('*Only needed if you want to PIN a ring to a specific update (e.g. keep Prod on the latest feature drop only). This is NOT a fix for the cron-coverage or ring-diff sections above.* Add `allowedUpdateVersions:` to the row that covers the ring you want to pin. Use `Get-AzLocalAvailableUpdates` (or the Azure portal -> Azure Local -> Updates) to find valid update names / version strings.')
+ [void]$md.Add('')
+ [void]$md.Add('```yaml')
+ [void]$md.Add("- weeksInCycle: '*'")
+ [void]$md.Add(" daysOfWeek: 'Tue,Wed,Thu'")
+ [void]$md.Add(" rings: 'Prod'")
+ [void]$md.Add(" allowedUpdateVersions: 'Solution12.2604.1003.1005;Solution12.2610.1003.XX'")
+ [void]$md.Add('```')
+ [void]$md.Add('')
+ }
+ else {
+ [void]$md.Add('*Every schedule row has an explicit `allowedUpdateVersions:` override - no inheritance from the top-level default.*')
+ [void]$md.Add('')
+ }
+ }
+ }
+ }
+
+ & $addDetailTable '### Audit Detail - Cron coverage (Uncovered / Partial / Malformed first)' $cronRows 'No tagged clusters found - nothing to audit.'
+
+ if (-not $hasIssues -and $recoContent) {
+ [void]$md.Add('### Reference - Recommended schedule (copy into Step.6_apply-updates.yml)')
+ [void]$md.Add('')
+ [void]$md.Add($recoContent)
+ [void]$md.Add('')
+ }
+
+ # ---- Cycle calendar - ALWAYS when -SchedulePath supplied --------------
+ # v0.8.5 fix for the v0.8.4 $hasIssues-gate regression where the
+ # calendar silently disappeared from clean-fleet runs.
+ if ($haveSchedule) {
+ $calendarMd = $null
+ try {
+ $schedForCalendar = if ($sched) { $sched } else { Get-AzLocalApplyUpdatesScheduleConfig -Path $SchedulePath -ErrorAction Stop }
+ $calendarMd = Get-AzLocalApplyUpdatesScheduleCycleCalendar -Schedule $schedForCalendar -AsMarkdown -IncludePerRingSummary -ErrorAction Stop
+ }
+ catch {
+ $calendarMd = $null
+ Write-Warning "Failed to build cycle calendar: $($_.Exception.Message)"
+ }
+ if ($calendarMd) {
+ [void]$md.Add($calendarMd)
+ [void]$md.Add('')
+ }
+ }
+
+ [void]$md.Add('### Reports Available')
+ [void]$md.Add("- ``$AuditCsvFileName`` - one row per (UpdateRing, UpdateStartWindow) pair")
+ [void]$md.Add("- ``$MatrixCsvFileName`` - full inventory + required cron per row")
+ [void]$md.Add("- ``$RecommendMdFileName`` - ready-to-paste cron block")
+ [void]$md.Add("- ``$JUnitXmlFileName`` - JUnit XML for CI/CD visualisation")
+ [void]$md.Add('')
+ [void]$md.Add("*Generated at $((Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss')) UTC*")
+
+ if ($InstalledModuleVersion) {
+ [void]$md.Add('')
+ [void]$md.Add(('_Generated by AzLocal.UpdateManagement v{0}._' -f $InstalledModuleVersion))
+ }
+
+ Add-AzLocalPipelineStepSummary -Markdown ($md -join [Environment]::NewLine) -SummaryFileName $SummaryFileName | Out-Null
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalRows = [int]$audit.Count
+ Covered = [int]$covered.Count
+ Uncovered = [int]$uncovered.Count
+ Partial = [int]$partial.Count
+ Malformed = [int]$malformed.Count
+ Unparseable = [int]$unparseable.Count
+ NoWindowTag = [int]$noWindowTag.Count
+ RingMissing = [int]$ringMissing.Count
+ RingOrphan = [int]$ringOrphan.Count
+ RingMixed = [int]$ringMixed.Count
+ HaveSchedule = [bool]$haveSchedule
+ SchedulePath = $(if ($haveSchedule) { $SchedulePath } else { '' })
+ AuditRows = $audit
+ AuditCsvPath = $auditCsv
+ MatrixCsvPath = $matrixCsv
+ RecommendMdPath = $recoMd
+ JUnitXmlPath = $xmlPath
+ SummaryPath = (Join-Path -Path $OutputDirectory -ChildPath $SummaryFileName)
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalAuthValidationReport.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalAuthValidationReport.ps1
new file mode 100644
index 00000000..8564576d
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalAuthValidationReport.ps1
@@ -0,0 +1,378 @@
+function Export-AzLocalAuthValidationReport {
+ <#
+ .SYNOPSIS
+ Validates the pipeline identity's Azure authentication, RBAC, and
+ subscription scope, and emits a JUnit XML report + step-summary
+ markdown for the v0.8.5 thin-YAML Step.0 pipeline.
+
+ .DESCRIPTION
+ Phase 1 (v0.8.5) of the thin-YAML refactor. Condenses the
+ ~200-line inline `run: |` block in the v0.8.4
+ `Step.0_authentication-test.yml` (GitHub Actions + Azure DevOps)
+ into a single cmdlet call so the per-platform yml shrinks to a
+ few lines and the logic becomes unit-testable against synthetic
+ `az` CLI responses.
+
+ The cmdlet probes four auth-relevant facts in sequence:
+
+ 1. `az account show` (proves OIDC / Workload Identity Federation
+ token exchange, secret wiring).
+ 2. Role assignments for the pipeline identity's appId (proves
+ RBAC grant). Surfaced to the console only (matches the
+ v0.8.4 yml behaviour, which used `-o table` for log inspection).
+ 3. `az account list --refresh` (proves which subscriptions the
+ identity can actually see; the authoritative count). Subscription
+ rows are persisted as both `subscriptions.json` and
+ `subscriptions.csv` in the report directory.
+ 4. Azure Resource Graph query for `microsoft.azurestackhci/clusters`
+ (proves cluster reachability for the downstream fleet pipelines).
+
+ All four facts feed FOUR JUnit `` blocks in the emitted
+ XML (Authentication / Subscription Scope / Resource Graph
+ Reachability / Module Version Drift). The markdown step summary
+ renders the same data as a table + subscription roster. Three step
+ outputs (`subscription_count`, `cluster_count`, `auth_valid`) are
+ emitted via the Phase 0 `Set-AzLocalPipelineOutput` helper so
+ downstream jobs / steps can consume them on either platform.
+
+ Internal reuse (per the v0.8.5 thin-YAML consistency contract):
+ * `Invoke-AzCliJson` for every `az` subcommand (safe stderr/stdout
+ split; never the inline `2>&1 | ConvertFrom-Json` pattern).
+ * `Install-AzGraphExtension` for the resource-graph extension
+ (idempotent install).
+ * `Invoke-AzResourceGraphQuery` for the cluster reachability KQL.
+ * `New-AzLocalPipelineJUnitXml` (Private) for the JUnit XML.
+ * `Add-AzLocalPipelineStepSummary` for the rendered markdown.
+ * `Set-AzLocalPipelineOutput` for the three step outputs.
+ * `Get-AzLocalPipelineHost` is implicit (all of the above branch
+ on it internally).
+
+ .PARAMETER AzureClientId
+ The pipeline identity's appId. Used to scope the
+ `az role assignment list --assignee ` console echo. When
+ empty / null, the cmdlet falls back to `account.user.name` from
+ `az account show` (the same fallback the v0.8.4 ADO yml uses,
+ because ADO service connections do not expose the appId via a
+ secret).
+
+ .PARAMETER ReportDirectory
+ Directory to write the JUnit XML and the subscription artifacts
+ (`subscriptions.json`, `subscriptions.csv`) into. Created if it
+ does not exist. Defaults to `./reports` (which is what the v0.8.4
+ GH yml uses) or, on AzureDevOps, to
+ `$env:BUILD_ARTIFACTSTAGINGDIRECTORY/auth-report` if that env var
+ is set (matching the v0.8.4 ADO yml).
+
+ .PARAMETER ReportFileName
+ Filename for the JUnit XML (relative to `-ReportDirectory`).
+ Default `auth-report.xml`.
+
+ .PARAMETER SubscriptionsJsonFileName
+ Filename for the JSON subscription artifact. Default
+ `subscriptions.json`.
+
+ .PARAMETER SubscriptionsCsvFileName
+ Filename for the CSV subscription artifact. Default
+ `subscriptions.csv`.
+
+ .PARAMETER MaxClusters
+ Upper bound on the ARG `--first` page size for the cluster query.
+ Default 1000.
+
+ .PARAMETER InstalledModuleVersion
+ Optional [version] / [string] for the Module Version Drift JUnit
+ suite. When all three of InstalledModuleVersion /
+ GeneratedAgainstVersion / LatestOnPSGallery are empty, the
+ Module Version Drift suite is omitted.
+
+ .PARAMETER GeneratedAgainstVersion
+ See InstalledModuleVersion.
+
+ .PARAMETER LatestOnPSGallery
+ See InstalledModuleVersion.
+
+ .PARAMETER PassThru
+ When set, returns a single PSCustomObject summarising the run
+ (Account, SubscriptionCount, ClusterCount, AuthValid, JUnitXmlPath,
+ SubscriptionsJsonPath, SubscriptionsCsvPath). Without -PassThru
+ the cmdlet emits nothing to the pipeline; the artifacts and step
+ outputs are still produced.
+
+ .OUTPUTS
+ Nothing by default. When -PassThru is set, a single PSCustomObject:
+ Account [PSCustomObject] (name, id, tenantId, user)
+ SubscriptionCount [int]
+ Subscriptions [PSCustomObject[]] (one per subscription)
+ ClusterCount [int]
+ AuthValid [bool]
+ JUnitXmlPath [string]
+ SubscriptionsJsonPath [string]
+ SubscriptionsCsvPath [string]
+
+ .EXAMPLE
+ Export-AzLocalAuthValidationReport -PassThru
+
+ Runs the four probes against the currently-authenticated `az`
+ context, writes auth-report.xml + subscriptions.{json,csv} to
+ ./reports, emits the rendered markdown to the active pipeline
+ host's step-summary, sets three step outputs, and returns the
+ summary object.
+
+ .NOTES
+ Module: AzLocal.UpdateManagement (v0.8.5+)
+ Roadmap: Step.0 — Authentication Validation and Subscription Scope Report.
+ #>
+ [CmdletBinding()]
+ [OutputType([PSCustomObject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$AzureClientId,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReportDirectory,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReportFileName = 'auth-report.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SubscriptionsJsonFileName = 'subscriptions.json',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SubscriptionsCsvFileName = 'subscriptions.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 5000)]
+ [int]$MaxClusters = 1000,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$InstalledModuleVersion,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$GeneratedAgainstVersion,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$LatestOnPSGallery,
+
+ [Parameter(Mandatory = $false)]
+ [switch]$PassThru
+ )
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ if (-not $ReportDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $ReportDirectory = Join-Path -Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY -ChildPath 'auth-report'
+ }
+ else {
+ $ReportDirectory = './reports'
+ }
+ }
+ if (-not (Test-Path -LiteralPath $ReportDirectory)) {
+ New-Item -ItemType Directory -Path $ReportDirectory -Force | Out-Null
+ }
+
+ Write-Host '--- 1. az account show (proves authentication wiring) ---'
+ $accountResult = Invoke-AzCliJson -Arguments @('account', 'show')
+ if (-not $accountResult.Ok) {
+ throw "Export-AzLocalAuthValidationReport: az account show failed - $($accountResult.Error)"
+ }
+ $account = $accountResult.Data
+ if (-not $account) {
+ throw "Export-AzLocalAuthValidationReport: az account show returned an empty body. The pipeline identity is not authenticated."
+ }
+ $account | Format-List name, id, tenantId, user | Out-Host
+
+ if (-not $AzureClientId) {
+ if ($account.user -and $account.user.name) {
+ $AzureClientId = [string]$account.user.name
+ Write-Host "AzureClientId not supplied - derived '$AzureClientId' from az account show (account.user.name)."
+ }
+ }
+
+ Write-Host ''
+ Write-Host '--- 2. role assignments for the pipeline identity (proves RBAC grant) ---'
+ if ($AzureClientId) {
+ $rolesResult = Invoke-AzCliJson -Arguments @('role', 'assignment', 'list', '--assignee', $AzureClientId, '--all')
+ if ($rolesResult.Ok -and $rolesResult.Data) {
+ $rolesRows = @($rolesResult.Data | Select-Object roleDefinitionName, principalType, scope)
+ if ($rolesRows.Count -gt 0) {
+ $rolesRows | Format-Table -AutoSize | Out-Host
+ }
+ else {
+ Write-Host "(no role assignments returned for appId '$AzureClientId' - confirm the App Registration's service principal has RBAC grants on at least one subscription / management group)"
+ }
+ }
+ else {
+ Write-Host "(role assignment lookup failed: $($rolesResult.Error))"
+ }
+ }
+ else {
+ Write-Host "(skipped - no AzureClientId supplied and az account show did not expose account.user.name)"
+ }
+
+ Write-Host ''
+ Write-Host '--- 3. Subscription Scope: enumerating all subscriptions visible to the pipeline identity ---'
+ $subsResult = Invoke-AzCliJson -Arguments @('account', 'list', '--refresh', '--query', '[].{name:name, subscriptionId:id, tenantId:tenantId, state:state}')
+ if (-not $subsResult.Ok) {
+ throw "Export-AzLocalAuthValidationReport: az account list --refresh failed - $($subsResult.Error)"
+ }
+ $subs = @()
+ if ($subsResult.Data) {
+ $subs = @($subsResult.Data | Sort-Object name)
+ }
+ $subCount = $subs.Count
+ Write-Host "Count of subscriptions accessible = $subCount"
+ if ($subCount -gt 0) {
+ $subs | Format-Table @{N='#';E={[array]::IndexOf($subs,$_)+1}}, name, subscriptionId, state -AutoSize | Out-Host
+ }
+
+ $subsJsonPath = Join-Path -Path $ReportDirectory -ChildPath $SubscriptionsJsonFileName
+ $subsCsvPath = Join-Path -Path $ReportDirectory -ChildPath $SubscriptionsCsvFileName
+ ($subs | ConvertTo-Json -Depth 4) | Out-File -FilePath $subsJsonPath -Encoding utf8
+ $subs | Select-Object name, subscriptionId, tenantId, state |
+ Export-Csv -Path $subsCsvPath -NoTypeInformation -Encoding utf8
+
+ Write-Host ''
+ Write-Host '--- 4. Resource Graph query (proves cluster reachability) ---'
+ [void](Install-AzGraphExtension)
+ $clusterKql = "resources | where type =~ 'microsoft.azurestackhci/clusters' | project name, resourceGroup, subscriptionId"
+ $clusterRows = @()
+ try {
+ $clusterRows = @(Invoke-AzResourceGraphQuery -Query $clusterKql -First $MaxClusters -ErrorAction Stop)
+ }
+ catch {
+ Write-Warning "Cluster ARG query failed: $($_.Exception.Message)"
+ $clusterRows = @()
+ }
+ $clusterCount = $clusterRows.Count
+ Write-Host "Clusters visible to the pipeline identity = $clusterCount"
+ if ($clusterCount -gt 0) {
+ $clusterRows | Select-Object -First 10 | Format-Table -AutoSize | Out-Host
+ }
+
+ # ------------------------------------------------------------------
+ # Build JUnit XML via the shared helper
+ # ------------------------------------------------------------------
+ $authSuite = @{
+ Name = "🔐 Authentication"
+ ClassName = 'Authentication'
+ TestCases = @(
+ @{
+ Name = 'OIDC token exchange (az account show succeeded)'
+ SystemOut = "Tenant: $($account.tenantId)`nSubscription: $($account.name) ($($account.id))`nIdentity: $(if ($account.user) { $account.user.name } else { '(none)' })"
+ }
+ @{ Name = "Default subscription = $($account.name)" }
+ @{ Name = "Pipeline identity (appId) = $(if ($account.user) { $account.user.name } else { '(none)' })" }
+ )
+ }
+
+ $subTestCases = @(
+ @{ Name = "Count of subscriptions accessible = $subCount" }
+ )
+ $i = 0
+ foreach ($s in $subs) {
+ $i++
+ $subTestCases += @{ Name = "#$i $($s.name) ($($s.subscriptionId)) [$($s.state)]" }
+ }
+ $subSuite = @{
+ Name = "📋 Subscription Scope (count=$subCount)"
+ ClassName = 'SubscriptionScope'
+ TestCases = $subTestCases
+ }
+
+ $rgSuite = @{
+ Name = "🌐 Resource Graph Reachability"
+ ClassName = 'ResourceGraph'
+ TestCases = @(
+ @{ Name = "Clusters visible to pipeline identity = $clusterCount" }
+ )
+ }
+
+ $suites = @($authSuite, $subSuite, $rgSuite)
+
+ $emitDriftSuite = ($InstalledModuleVersion -or $GeneratedAgainstVersion -or $LatestOnPSGallery)
+ if ($emitDriftSuite) {
+ $latestRender = if ($LatestOnPSGallery) { $LatestOnPSGallery } else { '(lookup failed)' }
+ $suites += @{
+ Name = "📦 Module Version Drift"
+ ClassName = 'ModuleVersion'
+ TestCases = @(
+ @{ Name = "Installed AzLocal.UpdateManagement = $InstalledModuleVersion" }
+ @{ Name = "YAML generated against = $GeneratedAgainstVersion" }
+ @{ Name = "Latest on PSGallery = $latestRender" }
+ )
+ }
+ }
+
+ $xmlPath = Join-Path -Path $ReportDirectory -ChildPath $ReportFileName
+ [void](New-AzLocalPipelineJUnitXml -TestSuitesName 'Step.0 - Authentication Validation and Subscription Scope Report' -Suites $suites -OutputPath $xmlPath)
+ Write-Host "JUnit XML written to: $xmlPath"
+
+ # ------------------------------------------------------------------
+ # Build markdown step summary via the shared helper
+ # ------------------------------------------------------------------
+ $md = [System.Text.StringBuilder]::new()
+ [void]$md.AppendLine('## Step.0 - Authentication Validation and Subscription Scope Report')
+ [void]$md.AppendLine('')
+ [void]$md.AppendLine('| Check | Result |')
+ [void]$md.AppendLine('|---|---|')
+ [void]$md.AppendLine("| Authentication | :white_check_mark: working |")
+ [void]$md.AppendLine("| Default Subscription | $($account.name) (``$($account.id)``) |")
+ [void]$md.AppendLine("| Tenant | ``$($account.tenantId)`` |")
+ $identityName = if ($account.user) { $account.user.name } else { '(none)' }
+ [void]$md.AppendLine("| Pipeline identity (appId) | ``$identityName`` |")
+ [void]$md.AppendLine("| Resource Graph reachability | :white_check_mark: $clusterCount cluster(s) visible |")
+ if ($emitDriftSuite) {
+ $latestRender = if ($LatestOnPSGallery) { $LatestOnPSGallery } else { '(lookup failed)' }
+ [void]$md.AppendLine("| AzLocal.UpdateManagement (installed) | ``$InstalledModuleVersion`` |")
+ [void]$md.AppendLine("| AzLocal.UpdateManagement (YAML generated against) | ``$GeneratedAgainstVersion`` |")
+ [void]$md.AppendLine("| AzLocal.UpdateManagement (latest on PSGallery) | ``$latestRender`` |")
+ }
+ [void]$md.AppendLine('')
+ [void]$md.AppendLine("### Count of subscriptions accessible = $subCount")
+ [void]$md.AppendLine('')
+ [void]$md.AppendLine('| # | Subscription Name | Subscription ID | Tenant ID | State |')
+ [void]$md.AppendLine('|---|---|---|---|---|')
+ $i = 0
+ foreach ($s in $subs) {
+ $i++
+ [void]$md.AppendLine("| $i | $($s.name) | ``$($s.subscriptionId)`` | ``$($s.tenantId)`` | $($s.state) |")
+ }
+ [void]$md.AppendLine('')
+ [void]$md.AppendLine("*Generated at $((Get-Date).ToString('yyyy-MM-dd HH:mm:ss UTC'))*")
+
+ [void](Add-AzLocalPipelineStepSummary -Markdown $md.ToString() -SummaryFileName 'auth-report-summary.md')
+
+ # ------------------------------------------------------------------
+ # Step outputs (consumed by downstream jobs / steps)
+ # ------------------------------------------------------------------
+ $authValid = ($null -ne $account) -and ($subCount -gt 0)
+ Set-AzLocalPipelineOutput -Name 'subscription_count' -Value ([string]$subCount)
+ Set-AzLocalPipelineOutput -Name 'cluster_count' -Value ([string]$clusterCount)
+ Set-AzLocalPipelineOutput -Name 'auth_valid' -Value ([string]$authValid.ToString().ToLowerInvariant())
+
+ if ($PassThru) {
+ return [PSCustomObject]@{
+ Account = $account
+ SubscriptionCount = $subCount
+ Subscriptions = $subs
+ ClusterCount = $clusterCount
+ AuthValid = $authValid
+ JUnitXmlPath = $xmlPath
+ SubscriptionsJsonPath = $subsJsonPath
+ SubscriptionsCsvPath = $subsCsvPath
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalClusterReadinessGateReport.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalClusterReadinessGateReport.ps1
new file mode 100644
index 00000000..6fd83722
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalClusterReadinessGateReport.ps1
@@ -0,0 +1,206 @@
+function Export-AzLocalClusterReadinessGateReport {
+ <#
+ .SYNOPSIS
+ Runs Get-AzLocalClusterUpdateReadiness for the given UpdateRing,
+ writes readiness-report.csv to the pipeline artifact folder, emits
+ step outputs READY_COUNT/TOTAL_COUNT/NOT_READY_COUNT, and renders the
+ per-cluster readiness markdown table to the run summary.
+ .DESCRIPTION
+ v0.8.5 Step.6 thin-YAML helper. Replaces the ~80-line inline `run:`
+ block that lived in both Step.6_apply-updates.yml pipelines.
+
+ Behaviour matches the prior inline block byte-for-byte:
+ - When -UpdateRing is empty/whitespace (no schedule row matched
+ today): skips the readiness query, emits zero counts, and exits
+ cleanly. Downstream apply-updates is gated on ready_count > 0
+ and will be skipped.
+ - Otherwise: discovers clusters by tag, exports CSV, counts ready
+ vs not-ready, emits the same READY_COUNT/TOTAL_COUNT step outputs
+ the apply-updates job consumes.
+ - Markdown table: one row per assessed cluster (sorted Ready-first
+ then ClusterName ASC), capped at -MaxRows (default 100). Same
+ columns and emoji as Enhancement D introduced in v0.8.4.
+ .PARAMETER UpdateRing
+ UpdateRing tag value to filter clusters by. Empty string OR whitespace
+ triggers the zero-clusters short-circuit (see DESCRIPTION).
+ .PARAMETER OutputDirectory
+ Directory where readiness-report.csv is written. Defaults to:
+ - Azure DevOps: $env:BUILD_ARTIFACTSTAGINGDIRECTORY
+ - GitHub / Local: './artifacts'
+ .PARAMETER ReadinessCsvFileName
+ Filename for the CSV. Default: 'readiness-report.csv'.
+ .PARAMETER MaxRows
+ Maximum rows rendered into the markdown table. Default 100. The CSV
+ always contains every assessed cluster regardless of this cap.
+ .PARAMETER SummaryFileName
+ Filename for the per-task markdown summary (ADO/Local only). Default:
+ 'azlocal-step6-readiness-summary.md'.
+ .PARAMETER PassThru
+ Returns PSCustomObject with: TotalCount, ReadyCount, NotReadyCount,
+ UpdateRing, ReadinessCsvPath, SummaryPath, Results (raw rows from
+ Get-AzLocalClusterUpdateReadiness when not in the short-circuit path,
+ else @()).
+ .NOTES
+ Author : AzLocal.UpdateManagement
+ Version : 0.8.5 (Step.6 thin-YAML port)
+ #>
+ [CmdletBinding()]
+ [OutputType([void])]
+ [OutputType([pscustomobject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [string]$UpdateRing = '',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [string]$OutputDirectory = '',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReadinessCsvFileName = 'readiness-report.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 10000)]
+ [int]$MaxRows = 100,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'azlocal-step6-readiness-summary.md',
+
+ [switch]$PassThru
+ )
+
+ Set-StrictMode -Version Latest
+ $ErrorActionPreference = 'Stop'
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ # OutputDirectory default (host-specific, byte-for-byte the same as the
+ # prior inline block).
+ if (-not $OutputDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $OutputDirectory = $env:BUILD_ARTIFACTSTAGINGDIRECTORY
+ }
+ else {
+ $OutputDirectory = './artifacts'
+ }
+ }
+
+ if (-not (Test-Path -LiteralPath $OutputDirectory)) {
+ New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
+ }
+
+ $csvPath = Join-Path -Path $OutputDirectory -ChildPath $ReadinessCsvFileName
+
+ # Per-host step-output naming - PRESERVE existing pipeline downstream
+ # bindings byte-for-byte: GH uses UPPER_SNAKE, ADO uses PascalCase
+ # (e.g. stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.ReadyCount']).
+ if ($pipelineHost -eq 'AzureDevOps') {
+ $nReadyCount = 'ReadyCount'; $nTotalCount = 'TotalCount'; $nNotReadyCount = 'NotReadyCount'
+ }
+ else {
+ $nReadyCount = 'READY_COUNT'; $nTotalCount = 'TOTAL_COUNT'; $nNotReadyCount = 'NOT_READY_COUNT'
+ }
+
+ # Short-circuit when the schedule resolver returned no ring.
+ if ([string]::IsNullOrWhiteSpace($UpdateRing)) {
+ Write-Host "No UpdateRing scheduled for this firing - skipping readiness check."
+ Set-AzLocalPipelineOutput -Name $nReadyCount -Value '0' -CrossJob
+ Set-AzLocalPipelineOutput -Name $nTotalCount -Value '0' -CrossJob
+ Set-AzLocalPipelineOutput -Name $nNotReadyCount -Value '0' -CrossJob
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalCount = 0
+ ReadyCount = 0
+ NotReadyCount = 0
+ UpdateRing = ''
+ ReadinessCsvPath = $csvPath
+ SummaryPath = $null
+ Results = @()
+ }
+ }
+ return
+ }
+
+ Write-Host "Checking readiness for clusters with UpdateRing = '$UpdateRing'"
+
+ $results = @(Get-AzLocalClusterUpdateReadiness `
+ -ScopeByUpdateRingTag `
+ -UpdateRingValue $UpdateRing `
+ -ExportPath $csvPath `
+ -PassThru)
+
+ $totalCount = $results.Count
+ $readyCount = @($results | Where-Object { $_.ReadyForUpdate -eq $true }).Count
+ $notReadyCount = $totalCount - $readyCount
+
+ Write-Host ""
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Readiness Summary" -ForegroundColor Cyan
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Total Clusters: $totalCount"
+ Write-Host "Ready for Update: $readyCount"
+ Write-Host "Not Ready: $notReadyCount"
+
+ Set-AzLocalPipelineOutput -Name $nReadyCount -Value "$readyCount" -CrossJob
+ Set-AzLocalPipelineOutput -Name $nTotalCount -Value "$totalCount" -CrossJob
+ Set-AzLocalPipelineOutput -Name $nNotReadyCount -Value "$notReadyCount" -CrossJob
+
+ if ($readyCount -eq 0 -and $pipelineHost -eq 'AzureDevOps') {
+ # Preserve byte-for-byte the original Step.6 ADO warning text.
+ Write-Host "##vso[task.logissue type=warning]No clusters are ready for updates in ring '$UpdateRing'"
+ }
+
+ # Per-cluster readiness markdown table. Heading is `# Cluster Readiness`
+ # on ADO (file is its own summary card) and `## Cluster Readiness` on
+ # GitHub (appended into GITHUB_STEP_SUMMARY which already has H1).
+ $headingLevel = if ($pipelineHost -eq 'AzureDevOps') { '#' } else { '##' }
+ $sb = New-Object System.Text.StringBuilder
+ [void]$sb.AppendLine("$headingLevel Cluster Readiness ($UpdateRing)")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("**Total:** $totalCount | **Ready:** $readyCount | **Not Ready:** $notReadyCount")
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine('| Cluster | Current Version | Update State | Health | Ready? | Recommended Update | Blocking Reasons |')
+ [void]$sb.AppendLine('|---|---|---|---|---|---|---|')
+
+ $rendered = 0
+ foreach ($r in ($results | Sort-Object @{Expression = { [bool]$_.ReadyForUpdate }; Descending = $true }, ClusterName)) {
+ if ($rendered -ge $MaxRows) { break }
+ $readyIcon = if ($r.ReadyForUpdate -eq $true) { [char]0x2705 } else { [char]0x26D4 }
+ $hSt = "$($r.HealthState)"
+ $hCell = switch -Regex ($hSt) {
+ '^Success$' { ("{0} {1}" -f [char]0x2705, $hSt); break }
+ '^Warning$' { ("{0} {1}" -f ([string]([char]0x26A0) + [char]0xFE0F), $hSt); break }
+ '^Failure$' { ("{0} {1}" -f [char]0x274C, $hSt); break }
+ default { $hSt }
+ }
+ $blocking = "$($r.BlockingReasons)"
+ if ($blocking.Length -gt 200) { $blocking = $blocking.Substring(0, 197) + '...' }
+ $blocking = $blocking -replace '\|', '\|' -replace '\r?\n', ' '
+ $reco = if ($r.RecommendedUpdate) { '`' + $r.RecommendedUpdate + '`' } else { '-' }
+ $curr = if ($r.CurrentVersion) { '`' + $r.CurrentVersion + '`' } else { '-' }
+ [void]$sb.AppendLine("| ``$($r.ClusterName)`` | $curr | $($r.UpdateState) | $hCell | $readyIcon | $reco | $blocking |")
+ $rendered++
+ }
+
+ if ($totalCount -gt $MaxRows) {
+ [void]$sb.AppendLine()
+ [void]$sb.AppendLine("_Showing first $MaxRows of $totalCount clusters. Download the readiness-report.csv artifact for the full list._")
+ }
+ [void]$sb.AppendLine()
+
+ $summaryPath = Add-AzLocalPipelineStepSummary -Markdown $sb.ToString() -SummaryFileName $SummaryFileName
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalCount = $totalCount
+ ReadyCount = $readyCount
+ NotReadyCount = $notReadyCount
+ UpdateRing = $UpdateRing
+ ReadinessCsvPath = $csvPath
+ SummaryPath = $summaryPath
+ Results = $results
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalClusterUpdateReadinessReport.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalClusterUpdateReadinessReport.ps1
new file mode 100644
index 00000000..be916c1c
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalClusterUpdateReadinessReport.ps1
@@ -0,0 +1,481 @@
+function Export-AzLocalClusterUpdateReadinessReport {
+ <#
+ .SYNOPSIS
+ Runs the Step.5 pre-flight Update Readiness Assessment workload:
+ Get-AzLocalClusterUpdateReadiness + Test-AzLocalClusterHealth
+ -BlockingOnly against a target UpdateRing (or whole fleet),
+ writes per-check CSV/JUnit XML artifacts, merges them into a
+ combined JUnit report, and emits the markdown step summary +
+ step outputs for the v0.8.5 thin-YAML Step.5 pipeline.
+
+ .DESCRIPTION
+ Phase 1 (v0.8.5) of the thin-YAML refactor. Condenses the inline
+ `run: |` body of the v0.8.4 Step.5_assess-update-readiness.yml
+ (GitHub Actions + Azure DevOps) into a single cmdlet call so the
+ per-platform yml shrinks to a few lines and the workload becomes
+ unit-testable against synthetic Get-AzLocalClusterUpdateReadiness
+ and Test-AzLocalClusterHealth results.
+
+ The cmdlet:
+
+ 1. Resolves the output directory (defaults to './artifacts' on
+ GitHub Actions / Local, or `$env:BUILD_ARTIFACTSTAGINGDIRECTORY`
+ on Azure DevOps - matching the v0.8.4 yml).
+ 2. Calls `Get-AzLocalClusterInventory -PassThru` to build a
+ ResourceId -> UpdateRing map for the per-ring pivot section.
+ 3. When -Scope is 'all' and the inventory is empty, short-
+ circuits with zero counts, an IDLE markdown summary, and
+ empty step outputs (matches the v0.8.4 yml early-exit).
+ 4. Calls `Get-AzLocalClusterUpdateReadiness` TWICE so the
+ cmdlet's native -ExportPath emitter produces both the
+ readiness.csv (humans) and readiness.xml (JUnit, one
+ per cluster). This preserves the v0.8.4
+ dorny/test-reporter contract byte-for-byte.
+ 5. Calls `Test-AzLocalClusterHealth -BlockingOnly` TWICE
+ (CSV + JUnit) for the same reason.
+ 6. Computes the 3-bucket model that matches the
+ Get-AzLocalClusterUpdateReadiness Summary:
+ ReadyForUpdate / UpToDate / NotReady.
+ 7. Computes Critical-health bucket counts from the
+ Test-AzLocalClusterHealth -PassThru row shape
+ (ClusterName, HealthState, CriticalCount, WarningCount).
+ 8. Merges readiness.xml + health-blocking.xml into a single
+ combined assess-readiness.xml (single Checks-tab entry).
+ 9. Emits the markdown step summary (8 sections: header tile,
+ action banner, summary counts, Not-Ready table, Critical-
+ health table, per-ring pivot, all-clusters detail,
+ cross-link list) via `Add-AzLocalPipelineStepSummary`.
+ 10. Emits 2 step outputs via `Set-AzLocalPipelineOutput`:
+ not_ready, critical_failures.
+
+ Internal reuse (per the v0.8.5 thin-YAML consistency contract):
+ * `Get-AzLocalClusterInventory` for the all-clusters scope and
+ the UpdateRing pivot map.
+ * `Get-AzLocalClusterUpdateReadiness` for the readiness CSV
+ and JUnit XML.
+ * `Test-AzLocalClusterHealth -BlockingOnly` for the blocking
+ health CSV and JUnit XML.
+ * `Add-AzLocalPipelineStepSummary` for the rendered markdown.
+ * `Set-AzLocalPipelineOutput` for the step outputs.
+ * `Get-AzLocalPipelineHost` is implicit (the above branch on it).
+
+ .PARAMETER OutputDirectory
+ Directory to write artifacts into. Created if it does not exist.
+ Defaults to './artifacts' (GH / Local) or
+ `$env:BUILD_ARTIFACTSTAGINGDIRECTORY` (Azure DevOps).
+
+ .PARAMETER Scope
+ 'all' (default) - assess every cluster the identity can see (via
+ Get-AzLocalClusterInventory). 'by-update-ring' - assess only
+ clusters whose UpdateRing tag matches -UpdateRing.
+
+ .PARAMETER UpdateRing
+ UpdateRing tag value to filter by when -Scope is 'by-update-ring'.
+ Accepts a single ring ('Wave1'), a semicolon-delimited list
+ ('Prod;Ring2'), or '***' to match every cluster that HAS the
+ UpdateRing tag set. Ignored when -Scope is 'all'.
+
+ .PARAMETER ReadinessCsvFileName
+ Filename for the per-cluster readiness CSV.
+ Default 'readiness.csv'.
+
+ .PARAMETER ReadinessXmlFileName
+ Filename for the readiness JUnit XML report.
+ Default 'readiness.xml'.
+
+ .PARAMETER HealthCsvFileName
+ Filename for the per-cluster blocking-health CSV.
+ Default 'health-blocking.csv'.
+
+ .PARAMETER HealthXmlFileName
+ Filename for the blocking-health JUnit XML report.
+ Default 'health-blocking.xml'.
+
+ .PARAMETER CombinedXmlFileName
+ Filename for the merged readiness + blocking-health JUnit report.
+ Default 'assess-readiness.xml'.
+
+ .PARAMETER SummaryFileName
+ Per-task summary filename used by `Add-AzLocalPipelineStepSummary`
+ on Azure DevOps and Local hosts.
+ Default 'assess-readiness-summary.md'.
+
+ .PARAMETER InstalledModuleVersion
+ Optional [string] used in the markdown footer
+ ('Generated by AzLocal.UpdateManagement v').
+
+ .PARAMETER PassThru
+ When set, returns a single PSCustomObject summarising the run
+ (TotalCount, ReadyForUpdateCount, UpToDateCount, NotReadyCount,
+ CriticalFindings, ClustersWithCritical, ReadinessRows,
+ HealthRows, and the 5 file paths). Without -PassThru the cmdlet
+ emits nothing to the pipeline; the artifacts and step outputs
+ are still produced.
+
+ .OUTPUTS
+ Nothing by default. When -PassThru is set, a single PSCustomObject.
+
+ .EXAMPLE
+ Export-AzLocalClusterUpdateReadinessReport -Scope all -PassThru
+
+ .EXAMPLE
+ Export-AzLocalClusterUpdateReadinessReport -Scope by-update-ring -UpdateRing 'Wave1'
+
+ .NOTES
+ Module: AzLocal.UpdateManagement (v0.8.5+)
+ Roadmap: Step.5 - Assess Update Readiness (pre-flight gate).
+ #>
+ [CmdletBinding()]
+ [OutputType([PSCustomObject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$OutputDirectory,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateSet('all', 'by-update-ring')]
+ [string]$Scope = 'all',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$UpdateRing,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReadinessCsvFileName = 'readiness.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReadinessXmlFileName = 'readiness.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$HealthCsvFileName = 'health-blocking.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$HealthXmlFileName = 'health-blocking.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$CombinedXmlFileName = 'assess-readiness.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'assess-readiness-summary.md',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$InstalledModuleVersion,
+
+ [Parameter(Mandatory = $false)]
+ [switch]$PassThru
+ )
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ if (-not $OutputDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $OutputDirectory = $env:BUILD_ARTIFACTSTAGINGDIRECTORY
+ }
+ else {
+ $OutputDirectory = './artifacts'
+ }
+ }
+ if (-not (Test-Path -LiteralPath $OutputDirectory)) {
+ New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
+ }
+
+ $readinessCsv = Join-Path -Path $OutputDirectory -ChildPath $ReadinessCsvFileName
+ $readinessXml = Join-Path -Path $OutputDirectory -ChildPath $ReadinessXmlFileName
+ $healthCsv = Join-Path -Path $OutputDirectory -ChildPath $HealthCsvFileName
+ $healthXml = Join-Path -Path $OutputDirectory -ChildPath $HealthXmlFileName
+ $combinedXml = Join-Path -Path $OutputDirectory -ChildPath $CombinedXmlFileName
+
+ # Always fetch inventory so we can build a ResourceId -> UpdateRing map
+ # for the per-ring pivot in the markdown summary (cheap ARG round-trip).
+ $inventory = Get-AzLocalClusterInventory -PassThru
+ $ringByResourceId = @{}
+ if ($inventory) {
+ foreach ($inv in $inventory) {
+ $ringValue = if ($inv.UpdateRing) { [string]$inv.UpdateRing } else { '(no ring tag)' }
+ $ringByResourceId[$inv.ResourceId] = $ringValue
+ }
+ }
+
+ # ---- Scope params -----------------------------------------------------
+ $scopeParams = @{}
+ if ($Scope -eq 'by-update-ring' -and $UpdateRing) {
+ $scopeParams['ScopeByUpdateRingTag'] = $true
+ $scopeParams['UpdateRingValue'] = $UpdateRing
+ Write-Host "Scope: UpdateRing = $UpdateRing"
+ }
+ else {
+ Write-Host "Scope: all clusters (via inventory)"
+ if (-not $inventory -or @($inventory).Count -eq 0) {
+ Write-Warning 'No clusters found in inventory.'
+ Set-AzLocalPipelineOutput -Name 'not_ready' -Value '0'
+ Set-AzLocalPipelineOutput -Name 'critical_failures' -Value '0'
+ $idleSb = New-Object 'System.Collections.Generic.List[string]'
+ [void]$idleSb.Add('## Update Readiness Assessment')
+ [void]$idleSb.Add('')
+ [void]$idleSb.Add('**[IDLE]** No clusters found in inventory. Nothing to assess.')
+ Add-AzLocalPipelineStepSummary -Markdown ($idleSb -join [Environment]::NewLine) -SummaryFileName $SummaryFileName | Out-Null
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalCount = 0
+ ReadyForUpdateCount = 0
+ UpToDateCount = 0
+ NotReadyCount = 0
+ CriticalFindings = 0
+ ClustersWithCritical = 0
+ ReadinessRows = @()
+ HealthRows = @()
+ ReadinessCsvPath = $readinessCsv
+ ReadinessXmlPath = $readinessXml
+ HealthCsvPath = $healthCsv
+ HealthXmlPath = $healthXml
+ CombinedXmlPath = $combinedXml
+ }
+ }
+ return
+ }
+ $scopeParams['ClusterResourceIds'] = @($inventory | Select-Object -ExpandProperty ResourceId)
+ }
+
+ Write-Host ''
+ Write-Host '========================================'
+ Write-Host 'Step 1: Readiness (Get-AzLocalClusterUpdateReadiness)'
+ Write-Host '========================================'
+
+ # CSV for humans
+ $readiness = Get-AzLocalClusterUpdateReadiness @scopeParams `
+ -ExportPath $readinessCsv `
+ -PassThru
+
+ # JUnit XML for the test reporter (ExportPath .xml auto-detects JUnitXml).
+ # Two calls intentionally - this preserves the v0.8.4 dorny/test-reporter
+ # contract byte-for-byte (the cmdlet's native JUnit shape is what operators
+ # have screenshots / automations for). ARG round-trip is cheap.
+ $null = Get-AzLocalClusterUpdateReadiness @scopeParams `
+ -ExportPath $readinessXml
+
+ # v0.7.99: 3-bucket model matches Get-AzLocalClusterUpdateReadiness Summary.
+ # UpToDate clusters are NOT rolled into NotReady - they are a distinct bucket.
+ $readyForUpdate = @($readiness | Where-Object { $_.ReadyForUpdate -eq $true }).Count
+ $upToDate = @($readiness | Where-Object {
+ $_.ReadyForUpdate -ne $true -and
+ $_.UpdateState -in @('UpToDate', 'AppliedSuccessfully') -and
+ [string]::IsNullOrEmpty([string]$_.AllAvailableUpdates)
+ }).Count
+ $total = @($readiness).Count
+ $notReady = $total - $readyForUpdate - $upToDate
+
+ Write-Host ''
+ Write-Host "Total clusters in scope: $total"
+ Write-Host "Ready for update : $readyForUpdate"
+ Write-Host "Up to date : $upToDate"
+ Write-Host "Not ready for update : $notReady"
+
+ Write-Host ''
+ Write-Host '========================================'
+ Write-Host 'Step 2: Blocking health (Test-AzLocalClusterHealth -BlockingOnly)'
+ Write-Host '========================================'
+
+ $health = Test-AzLocalClusterHealth @scopeParams `
+ -BlockingOnly `
+ -ExportPath $healthCsv `
+ -PassThru
+
+ $null = Test-AzLocalClusterHealth @scopeParams `
+ -BlockingOnly `
+ -ExportPath $healthXml
+
+ # ---- Combined JUnit XML ------------------------------------------------
+ # Merge readiness.xml + health-blocking.xml into assess-readiness.xml so
+ # operators get one Checks-tab entry instead of two. The individual XMLs
+ # are still published below as [JUnit Debug] entries for parity.
+ try {
+ $readinessDoc = [xml](Get-Content -LiteralPath $readinessXml -Raw)
+ $healthDoc = [xml](Get-Content -LiteralPath $healthXml -Raw)
+ $combinedDoc = New-Object System.Xml.XmlDocument
+ $declaration = $combinedDoc.CreateXmlDeclaration('1.0', 'utf-8', $null)
+ $combinedDoc.AppendChild($declaration) | Out-Null
+ $rootElement = $combinedDoc.CreateElement('testsuites')
+ $rootElement.SetAttribute('name', 'Update Readiness Assessment')
+ $combinedDoc.AppendChild($rootElement) | Out-Null
+ foreach ($srcDoc in @($readinessDoc, $healthDoc)) {
+ $suites = if ($srcDoc.DocumentElement.LocalName -eq 'testsuites') {
+ $srcDoc.DocumentElement.SelectNodes('testsuite')
+ }
+ else {
+ ,$srcDoc.DocumentElement
+ }
+ foreach ($suite in $suites) {
+ $imported = $combinedDoc.ImportNode($suite, $true)
+ $rootElement.AppendChild($imported) | Out-Null
+ }
+ }
+ $combinedDoc.Save($combinedXml)
+ Write-Host "Combined JUnit report: $combinedXml"
+ }
+ catch {
+ Write-Warning "Failed to build combined JUnit report: $($_.Exception.Message)"
+ }
+
+ # Test-AzLocalClusterHealth -PassThru row shape (one row per cluster):
+ # ClusterName, HealthState, Passed, CriticalCount, WarningCount, Failures
+ # Aggregate from CriticalCount / Failures (NOT a non-existent Severity
+ # property, which silently returned 0 in earlier yml versions).
+ $criticalSum = ($health | Measure-Object -Property CriticalCount -Sum).Sum
+ $criticalFindings = if ($criticalSum) { [int]$criticalSum } else { 0 }
+ $clustersWithCritical = @($health | Where-Object { [int]$_.CriticalCount -gt 0 }).Count
+
+ Write-Host ''
+ Write-Host "Critical findings : $criticalFindings"
+ Write-Host "Clusters with Critical : $clustersWithCritical"
+
+ # ---- Step outputs -----------------------------------------------------
+ Set-AzLocalPipelineOutput -Name 'not_ready' -Value ([string]$notReady)
+ Set-AzLocalPipelineOutput -Name 'critical_failures' -Value ([string]$clustersWithCritical)
+
+ # ---- Markdown step summary (8 sections) -------------------------------
+ $md = New-Object 'System.Collections.Generic.List[string]'
+ [void]$md.Add('## Update Readiness Assessment')
+ [void]$md.Add('')
+
+ # 1. Header tile (one-line status, ASCII-safe brackets)
+ $scopeLabel = $Scope
+ if ($UpdateRing) { $scopeLabel = "$Scope (UpdateRing = $UpdateRing)" }
+ $statusWord = if ($notReady -gt 0 -or $clustersWithCritical -gt 0) { 'ATTENTION' } else { 'OK' }
+ [void]$md.Add("**[$statusWord]** $total cluster(s) assessed | $readyForUpdate Ready for Update | $upToDate Up to Date | $notReady Not Ready for Update | $clustersWithCritical with Critical health failures | Scope: $scopeLabel")
+ [void]$md.Add('')
+
+ # 2. Action banner
+ if ($notReady -gt 0 -or $clustersWithCritical -gt 0) {
+ [void]$md.Add("> **Action required**: $notReady cluster(s) not ready and/or $clustersWithCritical cluster(s) with Critical health failures. Review the **Not-Ready** and **Critical-health** sections below first; the CSV artifacts in ``azlocal-step.5-readiness-assessment-report_*`` carry the full per-finding detail. Remediate (hardware vendor SBE / firmware / cluster health) before or alongside the next apply-updates run. **The healthy clusters are safe to proceed** - Step.6_apply-updates.yml is per-cluster scoped.")
+ }
+ else {
+ [void]$md.Add('> **All clear**: every cluster in scope is ready for update. Safe to proceed with Step.6_apply-updates.yml for this ring.')
+ }
+ [void]$md.Add('')
+
+ # 3. Summary counts
+ [void]$md.Add('### Summary counts')
+ [void]$md.Add('')
+ [void]$md.Add('| Metric | Count |')
+ [void]$md.Add('|--------|-------|')
+ [void]$md.Add("| Total clusters in scope | $total |")
+ [void]$md.Add("| Ready for update | $readyForUpdate |")
+ [void]$md.Add("| Up to date | $upToDate |")
+ [void]$md.Add("| Not ready for update | $notReady |")
+ [void]$md.Add("| Clusters with Critical health failures | $clustersWithCritical |")
+ [void]$md.Add("| Total Critical findings | $criticalFindings |")
+ [void]$md.Add('')
+
+ # 4. Not-Ready cluster table (blocking findings first)
+ $notReadyRows = @($readiness | Where-Object { $_.ReadyForUpdate -ne $true })
+ if ($notReadyRows.Count -gt 0) {
+ [void]$md.Add('### Not-Ready clusters (review first)')
+ [void]$md.Add('')
+ [void]$md.Add('| Cluster | UpdateRing | Current version | Update state | Health | Blocking reasons |')
+ [void]$md.Add('|---------|------------|-----------------|--------------|--------|------------------|')
+ foreach ($r in ($notReadyRows | Sort-Object @{Expression={ if ($ringByResourceId.ContainsKey($_.ClusterResourceId)) { $ringByResourceId[$_.ClusterResourceId] } else { 'zzz' } }}, ClusterName)) {
+ $ring = if ($ringByResourceId.ContainsKey($r.ClusterResourceId)) { $ringByResourceId[$r.ClusterResourceId] } else { '-' }
+ $cv = if ($r.CurrentVersion) { $r.CurrentVersion } else { '-' }
+ $br = if ($r.PSObject.Properties['BlockingReasons'] -and $r.BlockingReasons) { $r.BlockingReasons } else { '-' }
+ [void]$md.Add("| $($r.ClusterName) | $ring | $cv | $($r.UpdateState) | $($r.HealthState) | $br |")
+ }
+ [void]$md.Add('')
+ }
+
+ # 5. Critical-health cluster table
+ $criticalRows = @($health | Where-Object { [int]$_.CriticalCount -gt 0 })
+ if ($criticalRows.Count -gt 0) {
+ [void]$md.Add('### Critical-health clusters')
+ [void]$md.Add('')
+ [void]$md.Add('_Cross-link: see **Step.4_fleet-connectivity-status** for connectivity-class failures and **Step.9_fleet-health-status** for the broader Critical/Warning catalog._')
+ [void]$md.Add('')
+ [void]$md.Add('| Cluster | UpdateRing | Health state | Critical | Warning |')
+ [void]$md.Add('|---------|------------|--------------|----------|---------|')
+ foreach ($r in ($criticalRows | Sort-Object @{Expression={[int]$_.CriticalCount}; Descending=$true}, ClusterName)) {
+ $invMatch = $inventory | Where-Object { $_.ClusterName -eq $r.ClusterName } | Select-Object -First 1
+ $ring = if ($invMatch -and $invMatch.UpdateRing) { $invMatch.UpdateRing } else { '-' }
+ [void]$md.Add("| $($r.ClusterName) | $ring | $($r.HealthState) | $($r.CriticalCount) | $($r.WarningCount) |")
+ }
+ [void]$md.Add('')
+ }
+
+ # 6. Per-UpdateRing pivot (only when >1 ring in scope)
+ $ringGroups = $readiness | Group-Object @{Expression={ if ($ringByResourceId.ContainsKey($_.ClusterResourceId)) { $ringByResourceId[$_.ClusterResourceId] } else { '(no ring tag)' } }} | Sort-Object Name
+ if (@($ringGroups).Count -gt 1) {
+ [void]$md.Add('### Per UpdateRing breakdown')
+ [void]$md.Add('')
+ [void]$md.Add('| UpdateRing | Total | Ready for Update | Up to Date | Not Ready for Update |')
+ [void]$md.Add('|------------|-------|------------------|------------|----------------------|')
+ foreach ($g in $ringGroups) {
+ $gReady = @($g.Group | Where-Object { $_.ReadyForUpdate -eq $true }).Count
+ $gUpToDate = @($g.Group | Where-Object {
+ $_.ReadyForUpdate -ne $true -and
+ $_.UpdateState -in @('UpToDate', 'AppliedSuccessfully') -and
+ [string]::IsNullOrEmpty([string]$_.AllAvailableUpdates)
+ }).Count
+ $gNotReady = $g.Count - $gReady - $gUpToDate
+ [void]$md.Add("| $($g.Name) | $($g.Count) | $gReady | $gUpToDate | $gNotReady |")
+ }
+ [void]$md.Add('')
+ }
+
+ # 7. All-clusters detail table
+ if ($total -gt 0) {
+ [void]$md.Add('### All clusters detail')
+ [void]$md.Add('')
+ [void]$md.Add('| Cluster | UpdateRing | Current version | Current SBE version | Update state | Health | Ready | Recommended update |')
+ [void]$md.Add('|---------|------------|-----------------|---------------------|--------------|--------|-------|--------------------|')
+ foreach ($r in ($readiness | Sort-Object @{Expression={ if ($ringByResourceId.ContainsKey($_.ClusterResourceId)) { $ringByResourceId[$_.ClusterResourceId] } else { 'zzz' } }}, ClusterName)) {
+ $ring = if ($ringByResourceId.ContainsKey($r.ClusterResourceId)) { $ringByResourceId[$r.ClusterResourceId] } else { '-' }
+ $cv = if ($r.CurrentVersion) { $r.CurrentVersion } else { '-' }
+ $csv = if ($r.PSObject.Properties['CurrentSbeVersion'] -and $r.CurrentSbeVersion) { $r.CurrentSbeVersion } else { '-' }
+ $ru = if ($r.RecommendedUpdate) { $r.RecommendedUpdate } else { '-' }
+ [void]$md.Add("| $($r.ClusterName) | $ring | $cv | $csv | $($r.UpdateState) | $($r.HealthState) | $($r.ReadyForUpdate) | $ru |")
+ }
+ [void]$md.Add('')
+ }
+
+ # 8. Cross-links to other pipelines
+ [void]$md.Add('### Cross-link to other pipelines')
+ [void]$md.Add('')
+ [void]$md.Add('- **Step.4_fleet-connectivity-status** - root-cause Disconnected / Offline / partial-connectivity findings on the Not-Ready and Critical-health rows above.')
+ [void]$md.Add('- **Step.6_apply-updates** - apply updates to the Ready clusters in this ring (manual workflow_dispatch, or wait for the scheduled cron firing).')
+ [void]$md.Add('- **Step.7_monitor-updates** - tail in-flight runs once Step.6 has started (auto-trigger on Step.6 completion, or manual).')
+ [void]$md.Add('- **Step.9_fleet-health-status** - broader Critical / Warning health catalog across the whole fleet (not just blocking-only).')
+ [void]$md.Add('')
+ [void]$md.Add('_Note: the **Update Readiness Assessment** entry in the Checks tab is the merged combined view; the [JUnit Debug] entries are diagnostic mirrors for CI/test tooling._')
+
+ if ($InstalledModuleVersion) {
+ [void]$md.Add('')
+ [void]$md.Add(('_Generated by AzLocal.UpdateManagement v{0}._' -f $InstalledModuleVersion))
+ }
+
+ Add-AzLocalPipelineStepSummary -Markdown ($md -join [Environment]::NewLine) -SummaryFileName $SummaryFileName | Out-Null
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalCount = [int]$total
+ ReadyForUpdateCount = [int]$readyForUpdate
+ UpToDateCount = [int]$upToDate
+ NotReadyCount = [int]$notReady
+ CriticalFindings = [int]$criticalFindings
+ ClustersWithCritical = [int]$clustersWithCritical
+ ReadinessRows = @($readiness)
+ HealthRows = @($health)
+ ReadinessCsvPath = $readinessCsv
+ ReadinessXmlPath = $readinessXml
+ HealthCsvPath = $healthCsv
+ HealthXmlPath = $healthXml
+ CombinedXmlPath = $combinedXml
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalFleetConnectivityStatusReport.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalFleetConnectivityStatusReport.ps1
new file mode 100644
index 00000000..a4562a7d
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalFleetConnectivityStatusReport.ps1
@@ -0,0 +1,443 @@
+function Export-AzLocalFleetConnectivityStatusReport {
+ <#
+ .SYNOPSIS
+ Runs the Step.4 Fleet Connectivity Status workload:
+ Get-AzLocalFleetConnectivityStatus + per-scope severity
+ classification + JUnit XML + markdown summary + step outputs
+ for the v0.8.5 thin-YAML Step.4 pipeline.
+
+ .DESCRIPTION
+ Phase 1 (v0.8.5) of the thin-YAML refactor. Condenses the inline
+ `run: |` body of the v0.8.4 Step.4_fleet-connectivity-status.yml
+ (GitHub Actions + Azure DevOps) into a single cmdlet call so the
+ per-platform yml shrinks to a few lines and the workload becomes
+ unit-testable against synthetic Get-AzLocalFleetConnectivityStatus
+ results.
+
+ The cmdlet:
+
+ 1. Resolves the output directory (defaults to './reports' on
+ GitHub Actions / Local, or `$env:BUILD_ARTIFACTSTAGINGDIRECTORY`
+ on Azure DevOps - matching the v0.8.4 yml).
+ 2. Calls `Get-AzLocalFleetConnectivityStatus` once (with the
+ optional -SubscriptionId scope) to get all 7 row-sets:
+ ClusterRows, ArcSummary, NonConnectedMachines, NicIssues,
+ NicAll, NicStats, ArbRows. The cmdlet's native -ExportPath
+ emitter writes the 7 CSV + 7 JSON files to the output dir.
+ 3. Classifies severity per row using the v0.8.4 rules:
+ Critical = confirmed disconnected/offline/expired,
+ Warning = expired/partial/unknown, Pass = healthy.
+ 4. Builds a JUnit XML report (4 suites: Cluster, Arc Agent,
+ Physical NIC, ARB) via the shared
+ `New-AzLocalPipelineJUnitXml` Private helper. When the
+ fleet is fully green, a single synthetic
+ 'Fleet Connectivity' suite with one passing testcase is
+ emitted so dorny renders a green banner instead of an
+ empty file (matches v0.8.4 byte-for-byte).
+ 5. Calls `New-AzLocalFleetConnectivityStatusSummary` (Public
+ renderer shared with the v0.8.4 ADO yml) to build the
+ markdown step summary.
+ 6. Pushes the markdown via `Add-AzLocalPipelineStepSummary`.
+ 7. Emits 12 step outputs via `Set-AzLocalPipelineOutput`
+ (lowercase snake_case per v0.8.5 convention):
+ cluster_total, cluster_fail, arc_total, arc_fail,
+ nic_total, nic_fail, nic_all_total, arb_total, arb_fail,
+ total_failures, critical_count, warning_count.
+
+ Internal reuse (per the v0.8.5 thin-YAML consistency contract):
+ * `Get-AzLocalFleetConnectivityStatus` for all data fetch.
+ * `New-AzLocalPipelineJUnitXml` for JUnit XML (replaces the
+ inline 200-line StringBuilder of the v0.8.4 yml).
+ * `New-AzLocalFleetConnectivityStatusSummary` for markdown.
+ * `Add-AzLocalPipelineStepSummary` for the rendered markdown.
+ * `Set-AzLocalPipelineOutput` for the step outputs.
+ * `Get-AzLocalPipelineHost` is implicit (the above branch on it).
+
+ .PARAMETER OutputDirectory
+ Directory to write artifacts into. Created if it does not exist.
+ Defaults to './reports' (GH / Local) or
+ `$env:BUILD_ARTIFACTSTAGINGDIRECTORY` (Azure DevOps).
+
+ .PARAMETER SubscriptionFilter
+ Optional comma-delimited subscription-id list. When set, the
+ first entry is forwarded as -SubscriptionId to
+ `Get-AzLocalFleetConnectivityStatus` (matches the v0.8.4 yml's
+ INPUT_SUBSCRIPTION_FILTER semantics). When empty, the cmdlet
+ scans every subscription visible to the federated identity.
+
+ .PARAMETER JUnitXmlFileName
+ Filename for the connectivity-status JUnit XML report.
+ Default 'fleet-connectivity-status.xml'.
+
+ .PARAMETER SummaryFileName
+ Per-task markdown summary filename used by
+ `Add-AzLocalPipelineStepSummary` on Azure DevOps and Local hosts.
+ Default 'fleet-connectivity-summary.md'.
+
+ .PARAMETER InstalledModuleVersion
+ Optional [string] used in the markdown footer
+ ('Generated by AzLocal.UpdateManagement v'). Forwarded to
+ `New-AzLocalFleetConnectivityStatusSummary`.
+
+ .PARAMETER PassThru
+ When set, returns a single PSCustomObject summarising the run
+ (counts, the raw data row-sets, the filtered Fail row-sets,
+ and the JUnit/summary file paths). Without -PassThru the
+ cmdlet emits nothing to the pipeline; the artifacts and step
+ outputs are still produced.
+
+ .OUTPUTS
+ Nothing by default. When -PassThru is set, a single PSCustomObject
+ with: ClusterTotal, ClusterFail, ArcTotal, ArcFail, NicTotal,
+ NicFail, NicAllTotal, ArbTotal, ArbFail, TotalFailures,
+ CriticalCount, WarningCount, ClusterRows, ArcSummary,
+ NonConnectedMachines, NicIssues, NicAll, NicStats, ArbRows,
+ ClusterFailures, ArcFailures, NicFailures, ArbFailures,
+ JUnitXmlPath, SummaryPath.
+
+ .EXAMPLE
+ Export-AzLocalFleetConnectivityStatusReport -PassThru
+
+ .EXAMPLE
+ Export-AzLocalFleetConnectivityStatusReport `
+ -SubscriptionFilter '00000000-0000-0000-0000-000000000001' `
+ -OutputDirectory './my-reports'
+
+ .NOTES
+ Module: AzLocal.UpdateManagement (v0.8.5+)
+ Roadmap: Step.4 - Fleet Connectivity Status (observability gate).
+ #>
+ [CmdletBinding()]
+ [OutputType([PSCustomObject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$OutputDirectory,
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$SubscriptionFilter,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$JUnitXmlFileName = 'fleet-connectivity-status.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'fleet-connectivity-summary.md',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$InstalledModuleVersion,
+
+ [Parameter(Mandatory = $false)]
+ [switch]$PassThru
+ )
+
+ Set-StrictMode -Version Latest
+ $ErrorActionPreference = 'Stop'
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ if (-not $OutputDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $OutputDirectory = $env:BUILD_ARTIFACTSTAGINGDIRECTORY
+ }
+ else {
+ $OutputDirectory = './reports'
+ }
+ }
+ if (-not (Test-Path -LiteralPath $OutputDirectory)) {
+ New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
+ }
+
+ $xmlPath = Join-Path -Path $OutputDirectory -ChildPath $JUnitXmlFileName
+
+ # ---- Optional subscription scope --------------------------------------
+ $invokeArgs = @{ ExportPath = $OutputDirectory; PassThru = $true }
+ if ($SubscriptionFilter) {
+ $subList = $SubscriptionFilter -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ }
+ if ($subList -and @($subList).Count -gt 0) {
+ $invokeArgs['SubscriptionId'] = [string]$subList[0]
+ Write-Host "Subscription filter active (first sub): $($subList[0])"
+ }
+ }
+ if (-not $invokeArgs.ContainsKey('SubscriptionId')) {
+ Write-Host 'Subscription filter empty - scanning all subscriptions visible to the federated identity.'
+ }
+
+ Write-Host '========================================'
+ Write-Host 'Fleet Connectivity Status Collection'
+ Write-Host '========================================'
+
+ # Collect all 7 connectivity row-sets via the module cmdlet.
+ # Runs 5 ARG queries, processes results client-side, and exports
+ # 7 CSV + 7 JSON files to $OutputDirectory.
+ $data = Get-AzLocalFleetConnectivityStatus @invokeArgs
+
+ $clusterRows = @($data.ClusterRows)
+ $arcSummary = @($data.ArcSummary)
+ $arcRows = @($data.NonConnectedMachines)
+ $nicRows = @($data.NicIssues)
+ $nicAllRows = @($data.NicAll)
+ $nicStats = @($data.NicStats)
+ $arbRows = @($data.ArbRows)
+
+ Write-Host 'Fleet Connectivity Collection complete:'
+ Write-Host " Clusters : $($clusterRows.Count) total"
+ Write-Host " Arc agents: $($arcSummary.Count) distinct status value(s); $($arcRows.Count) NOT 'Connected'"
+ Write-Host " Physical NIC issues: $($nicRows.Count) (Disconnected with non-APIPA IP)"
+ Write-Host " NIC inventory (full): $($nicAllRows.Count) total NICs across $($nicStats.Count) NicType+NicStatus groups"
+ Write-Host " ARB appliances: $($arbRows.Count)"
+
+ # ---- Severity classifiers ---------------------------------------------
+ # Case-insensitive. Healthy = Pass; confirmed bad = Critical;
+ # everything else (Unknown / NotSpecified / partial) = Warning.
+ $getClusterSeverity = { param($s) switch -Regex ([string]$s) { '^(Connected|ConnectedRecently)$' { 'Pass'; break } '^(Disconnected|Expired|Offline|Error)$' { 'Critical'; break } default { 'Warning' } } }
+ $getArcSeverity = { param($s) switch -Regex ([string]$s) { '^(Connected)$' { 'Pass'; break } '^(Disconnected|Expired|Offline|Error)$' { 'Critical'; break } default { 'Warning' } } }
+ $getNicSeverity = { param($s) switch -Regex ([string]$s) { '^(Connected|Up)$' { 'Pass'; break } '^(Disconnected|Down|Disabled)$' { 'Critical'; break } default { 'Warning' } } }
+ $getArbSeverity = { param($s) switch -Regex ([string]$s) { '^(Running)$' { 'Pass'; break } '^(Offline|Failed)$' { 'Critical'; break } default { 'Warning' } } }
+
+ $clusterFail = @($clusterRows | Where-Object { (& $getClusterSeverity $_.ConnectivityStatus) -ne 'Pass' })
+ $arcFail = @($arcRows | Where-Object { (& $getArcSeverity $_.AgentStatus) -ne 'Pass' })
+ $nicFail = @($nicRows | Where-Object { (& $getNicSeverity $_.NicStatus) -ne 'Pass' })
+ $arbFail = @($arbRows | Where-Object { (& $getArbSeverity $_.ArbStatus) -ne 'Pass' })
+
+ $totalFailures = $clusterFail.Count + $arcFail.Count + $nicFail.Count + $arbFail.Count
+ $criticalCount = @($clusterFail | Where-Object { (& $getClusterSeverity $_.ConnectivityStatus) -eq 'Critical' }).Count `
+ + @($arcFail | Where-Object { (& $getArcSeverity $_.AgentStatus) -eq 'Critical' }).Count `
+ + @($nicFail | Where-Object { (& $getNicSeverity $_.NicStatus) -eq 'Critical' }).Count `
+ + @($arbFail | Where-Object { (& $getArbSeverity $_.ArbStatus) -eq 'Critical' }).Count
+ $warningCount = $totalFailures - $criticalCount
+
+ # ---- Build JUnit suites via the shared helper -------------------------
+ $suites = @()
+
+ if ($clusterFail.Count -gt 0) {
+ $cases = foreach ($r in $clusterFail) {
+ $sev = & $getClusterSeverity $r.ConnectivityStatus
+ $portal = "https://portal.azure.com/#@/resource$($r.ClusterId)"
+ @{
+ Name = "Cluster '$($r.ClusterName)' :: ConnectivityStatus=$($r.ConnectivityStatus)"
+ ClassName = [string]$r.ClusterName
+ Failure = @{
+ Type = $sev
+ Message = "Cluster connectivity is '$($r.ConnectivityStatus)' (cluster.status='$($r.ClusterStatus)')"
+ Body = "ResourceGroup: $($r.ResourceGroup)`nSubscriptionId: $($r.SubscriptionId)`nClusterPortalUrl: $portal"
+ }
+ Properties = [ordered]@{
+ ClusterName = [string]$r.ClusterName
+ ClusterResourceId = [string]$r.ClusterId
+ UpdateName = "ClusterConnectivity=$($r.ConnectivityStatus)"
+ Status = $sev
+ FailureReason = "Cluster connectivity '$($r.ConnectivityStatus)'"
+ Severity = $sev
+ ClusterPortalUrl = $portal
+ TargetResourceName = [string]$r.ClusterName
+ TargetResourceType = 'microsoft.azurestackhci/clusters'
+ }
+ }
+ }
+ $suites += @{ Name = 'Cluster Connectivity'; TestCases = @($cases) }
+ }
+
+ if ($arcFail.Count -gt 0) {
+ $cases = foreach ($r in $arcFail) {
+ $sev = & $getArcSeverity $r.AgentStatus
+ $portal = "https://portal.azure.com/#@/resource$($r.MachineId)"
+ @{
+ Name = "Machine '$($r.NodeName)' :: Status=$($r.AgentStatus)"
+ ClassName = [string]$r.ClusterName
+ Failure = @{
+ Type = $sev
+ Message = "Machine '$($r.NodeName)' has Arc agent status '$($r.AgentStatus)' (last status change: $($r.LastStatusChange))"
+ Body = "ClusterName: $($r.ClusterName)`n" +
+ "AgentStatus: $($r.AgentStatus)`n" +
+ "OS SKU: $($r.OsSku)`n" +
+ "OS Version: $($r.OsVersion)`n" +
+ "Cluster Version: $($r.ClusterVersion)`n" +
+ "AgentVersion: $($r.AgentVersion)`n" +
+ "Disconnected Since (lastStatusChange): $($r.LastStatusChange)`n" +
+ "ResourceGroup: $($r.ResourceGroup)`n" +
+ "MachineId: $($r.MachineId)"
+ }
+ Properties = [ordered]@{
+ ClusterName = [string]$r.ClusterName
+ ClusterResourceId = [string]$r.ClusterId
+ UpdateName = "ArcAgent=$($r.AgentStatus) [$($r.NodeName)]"
+ Status = $sev
+ FailureReason = "Arc agent '$($r.AgentStatus)' on machine '$($r.NodeName)'"
+ Severity = $sev
+ ClusterPortalUrl = $portal
+ TargetResourceName = [string]$r.NodeName
+ TargetResourceType = 'microsoft.hybridcompute/machines'
+ }
+ }
+ }
+ $suites += @{ Name = 'Arc Agent Connectivity'; TestCases = @($cases) }
+ }
+
+ if ($nicFail.Count -gt 0) {
+ $cases = foreach ($r in $nicFail) {
+ $sev = & $getNicSeverity $r.NicStatus
+ $portal = "https://portal.azure.com/#@/resource$($r.MachineId)"
+ @{
+ Name = "NIC '$($r.NicName)' on '$($r.NodeName)' :: NicStatus=$($r.NicStatus)"
+ ClassName = [string]$r.ClusterName
+ Failure = @{
+ Type = $sev
+ Message = "Physical NIC '$($r.NicName)' on node '$($r.NodeName)' reports status '$($r.NicStatus)'"
+ Body = "ClusterName: $($r.ClusterName)`nInterface: $($r.InterfaceDescription)`nDriverVersion: $($r.DriverVersion)`nIp4Address: $($r.Ip4Address)`nMachineId: $($r.MachineId)"
+ }
+ Properties = [ordered]@{
+ ClusterName = [string]$r.ClusterName
+ ClusterResourceId = ''
+ UpdateName = "PhysicalNic=$($r.NicStatus) [$($r.NodeName)/$($r.NicName)]"
+ Status = $sev
+ FailureReason = "Physical NIC '$($r.NicName)' status '$($r.NicStatus)' on node '$($r.NodeName)'"
+ Severity = $sev
+ ClusterPortalUrl = $portal
+ TargetResourceName = "$($r.NodeName)/$($r.NicName)"
+ TargetResourceType = 'microsoft.azurestackhci/edgedevices/nicDetails'
+ }
+ }
+ }
+ $suites += @{ Name = 'Physical NIC Status'; TestCases = @($cases) }
+ }
+
+ if ($arbFail.Count -gt 0) {
+ $cases = foreach ($r in $arbFail) {
+ $sev = & $getArbSeverity $r.ArbStatus
+ $portal = "https://portal.azure.com/#@/resource$($r.ArbId)"
+ # ClusterId / ClusterName may be a comma-separated list when the
+ # ARB's resource group hosts multiple HCI clusters. The [string[]]
+ # cast is required - without it, when Where-Object yields a single
+ # scalar, the if-as-expression collapses $clusterIdList to a bare
+ # [string] and indexing it returns a [char] (no Trim() method).
+ [string[]]$clusterIdList = if ($r.ClusterId) { ($r.ClusterId -split ',\s*') | Where-Object { $_ } } else { @() }
+ $primaryClusterId = if ($clusterIdList.Count -gt 0) { ([string]$clusterIdList[0]).Trim() } else { '' }
+ $clusterPortal = if ($primaryClusterId) { "https://portal.azure.com/#@/resource$primaryClusterId" } else { '' }
+ $multiClusterNote = if ($clusterIdList.Count -gt 1) { " (multi-cluster RG; $($clusterIdList.Count) clusters)" } else { '' }
+ @{
+ Name = "ARB '$($r.ArbName)' :: ArbStatus=$($r.ArbStatus)"
+ ClassName = if ($r.ClusterName) { [string]$r.ClusterName } else { '(no cluster mapping)' }
+ Failure = @{
+ Type = $sev
+ Message = "Azure Resource Bridge '$($r.ArbName)' is '$($r.ArbStatus)' (days since lastModified=$($r.DaysSinceLastModified))$multiClusterNote"
+ Body = "ClusterName: $($r.ClusterName)`nArbId: $($r.ArbId)`nLastModified: $($r.LastModified)`nDaysSinceLastModified: $($r.DaysSinceLastModified)`nClusterPortalUrl: $clusterPortal"
+ }
+ Properties = [ordered]@{
+ ClusterName = if ($r.ClusterName) { [string]$r.ClusterName } else { '' }
+ ClusterResourceId = if ($primaryClusterId) { $primaryClusterId } else { '' }
+ UpdateName = "ARB=$($r.ArbStatus) [$($r.ArbName)]"
+ Status = $sev
+ FailureReason = "ARB '$($r.ArbName)' status '$($r.ArbStatus)'$multiClusterNote"
+ Severity = $sev
+ ClusterPortalUrl = $clusterPortal
+ TargetResourceName = [string]$r.ArbName
+ TargetResourceType = 'microsoft.resourceconnector/appliances'
+ }
+ }
+ }
+ $suites += @{ Name = 'Azure Resource Bridge'; TestCases = @($cases) }
+ }
+
+ if ($totalFailures -eq 0) {
+ # All-green: emit a single passing testcase so dorny renders a
+ # green banner instead of an empty file (matches v0.8.4 yml).
+ $suites += @{
+ Name = 'Fleet Connectivity'
+ TestCases = @(
+ @{ Name = 'No connectivity issues across the fleet' }
+ )
+ }
+ }
+
+ $null = New-AzLocalPipelineJUnitXml `
+ -TestSuitesName 'AzureLocalFleetConnectivity' `
+ -Suites $suites `
+ -OutputPath $xmlPath
+
+ # ---- Markdown summary via the shared renderer -------------------------
+ # Arc totals come from the status-summary histogram so the markdown
+ # table can show healthy + .
+ $arcTotalMachines = ($arcSummary | Measure-Object -Property Count -Sum).Sum
+ if ($null -eq $arcTotalMachines) { $arcTotalMachines = 0 }
+
+ $counts = @{
+ ClusterTotal = $clusterRows.Count
+ ClusterFail = $clusterFail.Count
+ ArcTotal = $arcTotalMachines
+ ArcFail = $arcRows.Count
+ NicTotal = $nicRows.Count
+ NicFail = $nicFail.Count
+ NicAllTotal = $nicAllRows.Count
+ ArbTotal = $arbRows.Count
+ ArbFail = $arbFail.Count
+ TotalFailures = $totalFailures
+ CriticalCount = $criticalCount
+ WarningCount = $warningCount
+ }
+
+ $summaryArgs = @{
+ ClusterRows = $clusterRows
+ ArcSummary = $arcSummary
+ ArcRows = $arcRows
+ NicRows = $nicRows
+ NicStats = $nicStats
+ ArbRows = $arbRows
+ Counts = $counts
+ }
+ $md = New-AzLocalFleetConnectivityStatusSummary @summaryArgs
+
+ Add-AzLocalPipelineStepSummary -Markdown $md -SummaryFileName $SummaryFileName | Out-Null
+
+ # ---- Step outputs (lowercase snake_case, v0.8.5 convention) -----------
+ Set-AzLocalPipelineOutput -Name 'cluster_total' -Value ([string]$clusterRows.Count)
+ Set-AzLocalPipelineOutput -Name 'cluster_fail' -Value ([string]$clusterFail.Count)
+ Set-AzLocalPipelineOutput -Name 'arc_total' -Value ([string]$arcTotalMachines)
+ Set-AzLocalPipelineOutput -Name 'arc_fail' -Value ([string]$arcRows.Count)
+ Set-AzLocalPipelineOutput -Name 'nic_total' -Value ([string]$nicRows.Count)
+ Set-AzLocalPipelineOutput -Name 'nic_fail' -Value ([string]$nicFail.Count)
+ Set-AzLocalPipelineOutput -Name 'nic_all_total' -Value ([string]$nicAllRows.Count)
+ Set-AzLocalPipelineOutput -Name 'arb_total' -Value ([string]$arbRows.Count)
+ Set-AzLocalPipelineOutput -Name 'arb_fail' -Value ([string]$arbFail.Count)
+ Set-AzLocalPipelineOutput -Name 'total_failures' -Value ([string]$totalFailures)
+ Set-AzLocalPipelineOutput -Name 'critical_count' -Value ([string]$criticalCount)
+ Set-AzLocalPipelineOutput -Name 'warning_count' -Value ([string]$warningCount)
+
+ Write-Host ''
+ Write-Host "TOTAL FAILURES: $totalFailures (Critical=$criticalCount, Warning=$warningCount)"
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ ClusterTotal = $clusterRows.Count
+ ClusterFail = $clusterFail.Count
+ ArcTotal = $arcTotalMachines
+ ArcFail = $arcRows.Count
+ NicTotal = $nicRows.Count
+ NicFail = $nicFail.Count
+ NicAllTotal = $nicAllRows.Count
+ ArbTotal = $arbRows.Count
+ ArbFail = $arbFail.Count
+ TotalFailures = $totalFailures
+ CriticalCount = $criticalCount
+ WarningCount = $warningCount
+ ClusterRows = $clusterRows
+ ArcSummary = $arcSummary
+ NonConnectedMachines = $arcRows
+ NicIssues = $nicRows
+ NicAll = $nicAllRows
+ NicStats = $nicStats
+ ArbRows = $arbRows
+ ClusterFailures = $clusterFail
+ ArcFailures = $arcFail
+ NicFailures = $nicFail
+ ArbFailures = $arbFail
+ JUnitXmlPath = $xmlPath
+ SummaryPath = (Join-Path -Path $OutputDirectory -ChildPath $SummaryFileName)
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalFleetHealthStatusReport.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalFleetHealthStatusReport.ps1
new file mode 100644
index 00000000..226df40f
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalFleetHealthStatusReport.ps1
@@ -0,0 +1,632 @@
+function Export-AzLocalFleetHealthStatusReport {
+ <#
+ .SYNOPSIS
+ Snapshots 24-hour fleet health-check failures and emits the full
+ Step.9 artefact bundle (CSV + JSON + JUnit XML + markdown summary).
+
+ .DESCRIPTION
+ Public entry-point for the v0.8.5 thin-YAML refactor of the Step.9
+ fleet-health-status pipeline. Before v0.8.5 the GitHub Actions and
+ Azure DevOps Step.9_fleet-health-status.yml files each carried
+ ~600 lines of inline PowerShell (failure collection + summary
+ roll-up + overview collection + JUnit XML construction +
+ collapsible markdown rendering + step-output emission). This
+ cmdlet condenses that workload into a single Public PowerShell
+ entry-point that both pipeline platforms call with a thin
+ parameter splat.
+
+ The cmdlet:
+ 1. Queries the fleet for unresolved Critical / Warning
+ health-check failures via Get-AzLocalFleetHealthFailures
+ (ARG-first; -View Detail). Detail rows feed the JUnit XML,
+ the in-process Summary roll-up, and the per-cluster
+ collapsible markdown view.
+ 2. Computes a SUMMARY view (Group-Object FailureReason +
+ Severity) entirely in-process, so the cmdlet issues at
+ most ONE health-failures ARG query regardless of fleet
+ size. Severity sorts FIRST (Critical before Warning),
+ then ClusterCount desc, then FailureCount desc.
+ 3. Queries Get-AzLocalFleetHealthOverview for the per-cluster
+ rollup (HealthStatus / UpdateStatus / CurrentVersion /
+ SbeVersion / AzureConnection / LastChecked / NodeCount).
+ 4. Writes the standard CSV+JSON artefact bundle: detail,
+ summary and overview pairs under -OutputDirectory.
+ 5. Generates a JUnit XML document with two diagnostic
+ testsuites ('[JUnit Debug] Critical Health Failures' /
+ '[JUnit Debug] Warning Health Failures'). Each testcase
+ carries consumed by the New-AzLocalIncident
+ ITSM connector (ClusterResourceId / FailureReason / Severity /
+ ClusterPortalUrl / TargetResourceName / TargetResourceType).
+ FailureReason is fed into the UpdateName slot of the SHA256
+ dedupe key so the ITSM connector raises one ticket per
+ (cluster, failing check) pair.
+ 6. Renders a four-section markdown step summary: KPI table,
+ Fleet Health Overview (top 100 clusters, one row each),
+ Health Check Failures By Reason (top 25 reasons, with
+ zipped portal-link hyperlinks for affected clusters), and
+ a per-cluster collapsible block showing every
+ failing check (capped at 100 clusters; CSV artefact carries
+ the full list).
+ 7. Emits 8 lowercase step outputs describing fleet bucket
+ counts (total_clusters, total_failures, critical_count,
+ warning_count, distinct_reasons, overview_rows,
+ healthy_clusters, total_in_sub).
+
+ The cmdlet replaces the inline 'Collect Fleet Health Failures'
+ AND the downstream 'Create Fleet Health Summary' steps from the
+ pre-v0.8.5 YAML.
+
+ .PARAMETER OutputDirectory
+ Directory to write artefacts into. When omitted, defaults to
+ $env:BUILD_ARTIFACTSTAGINGDIRECTORY\reports on Azure DevOps
+ hosts (resolved via Get-AzLocalPipelineHost) and './reports'
+ everywhere else (GitHub Actions, local interactive use).
+
+ .PARAMETER Scope
+ Fleet selector: 'all' (every cluster the caller can read) or
+ 'by-update-ring' (clusters whose UpdateRing tag matches
+ -UpdateRing). 'by-update-ring' is forwarded to
+ Get-AzLocalFleetHealthFailures and Get-AzLocalFleetHealthOverview
+ via the -UpdateRingTag parameter.
+
+ .PARAMETER UpdateRing
+ UpdateRing tag value to filter on when Scope='by-update-ring'.
+ Accepts a single value, a ';'-delimited list, or '***' (three
+ stars) as a wildcard. Ignored when Scope='all'.
+
+ .PARAMETER Severity
+ Severity filter applied at Resource Graph. 'All' (default) =
+ Critical + Warning; 'Critical' or 'Warning' restricts to that
+ tier only. Informational is always excluded.
+
+ .PARAMETER MaxOverviewRows
+ Maximum rows rendered in the Fleet Health Overview table.
+ Default 100. Beyond this the markdown shows a
+ '*Showing first N clusters of M; see csv artifact for the full
+ list.*' truncation note. Does NOT cap the CSV / JSON outputs.
+
+ .PARAMETER MaxSummaryRows
+ Maximum rows rendered in the Health Check Failures By Reason
+ table. Default 25. Same truncation behaviour as
+ -MaxOverviewRows.
+
+ .PARAMETER MaxDetailClusters
+ Maximum collapsible blocks rendered. Default 100.
+ Cap is per-CLUSTER, not per-row, so no cluster's failures are
+ silently truncated.
+
+ .PARAMETER DetailCsvFileName
+ Override the default 'fleet-health-detail.csv' filename.
+
+ .PARAMETER DetailJsonFileName
+ Override the default 'fleet-health-detail.json' filename.
+
+ .PARAMETER SummaryCsvFileName
+ Override the default 'fleet-health-summary.csv' filename.
+
+ .PARAMETER SummaryJsonFileName
+ Override the default 'fleet-health-summary.json' filename.
+
+ .PARAMETER OverviewCsvFileName
+ Override the default 'fleet-health-overview.csv' filename.
+
+ .PARAMETER OverviewJsonFileName
+ Override the default 'fleet-health-overview.json' filename.
+
+ .PARAMETER XmlFileName
+ Override the default 'fleet-health-status.xml' JUnit filename.
+
+ .PARAMETER SummaryFileName
+ Override the default 'fleet-health-status-summary.md' filename
+ (the markdown rendered into GITHUB_STEP_SUMMARY / ADO
+ upload-summary).
+
+ .PARAMETER InstalledModuleVersion
+ Optional version string rendered in the markdown footer
+ (e.g. v0.8.5). When omitted, no footer line is appended.
+
+ .PARAMETER Now
+ Optional [datetime] used as 'snapshot time' in the markdown
+ summary (Generated at ...). Defaults to (Get-Date).
+ Parameterised so unit tests can assert against a fixed value.
+
+ .PARAMETER PassThru
+ Return a PSCustomObject describing the snapshot (counts + file
+ paths + DetailRows + SummaryRows + OverviewRows). Default is
+ no return value (the cmdlet only writes files + step outputs
+ + markdown summary).
+
+ .OUTPUTS
+ [PSCustomObject] when -PassThru is supplied. Properties:
+ - TotalClusters, TotalFailures, CriticalCount, WarningCount,
+ DistinctReasons, OverviewRows, HealthyClusters, TotalInSub
+ - DetailCsvPath, DetailJsonPath, SummaryCsvPath,
+ SummaryJsonPath, OverviewCsvPath, OverviewJsonPath,
+ XmlPath, SummaryPath
+ - DetailRows, SummaryRows, OverviewRowsData
+
+ .EXAMPLE
+ Export-AzLocalFleetHealthStatusReport
+ # All-cluster snapshot; writes the full artefact bundle to ./reports/.
+
+ .EXAMPLE
+ Export-AzLocalFleetHealthStatusReport -Scope by-update-ring -UpdateRing Prod -PassThru
+ # Restricts to clusters tagged UpdateRing=Prod and returns the
+ # snapshot object for downstream PowerShell use.
+
+ .EXAMPLE
+ # Used by Step.9_fleet-health-status.yml (GitHub Actions + Azure DevOps):
+ Export-AzLocalFleetHealthStatusReport `
+ -Scope $env:INPUT_SCOPE `
+ -UpdateRing $env:INPUT_UPDATE_RING `
+ -Severity $env:INPUT_SEVERITY `
+ -InstalledModuleVersion (Get-Module AzLocal.UpdateManagement).Version
+
+ .NOTES
+ Author : Neil Bird, Microsoft
+ Version: v0.8.5
+ Added : v0.8.5 (Step.9 thin-YAML port - condenses ~600 lines of inline
+ PowerShell into a single Public entry-point).
+ Reuses : Get-AzLocalFleetHealthFailures, Get-AzLocalFleetHealthOverview,
+ New-AzLocalPipelineJUnitXml, Set-AzLocalPipelineOutput,
+ Add-AzLocalPipelineStepSummary, Get-AzLocalPipelineHost.
+ #>
+ [CmdletBinding()]
+ [OutputType([PSCustomObject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$OutputDirectory,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateSet('all', 'by-update-ring')]
+ [string]$Scope = 'all',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$UpdateRing,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateSet('All', 'Critical', 'Warning')]
+ [string]$Severity = 'All',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 1000)]
+ [int]$MaxOverviewRows = 100,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 500)]
+ [int]$MaxSummaryRows = 25,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 1000)]
+ [int]$MaxDetailClusters = 100,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$DetailCsvFileName = 'fleet-health-detail.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$DetailJsonFileName = 'fleet-health-detail.json',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryCsvFileName = 'fleet-health-summary.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryJsonFileName = 'fleet-health-summary.json',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$OverviewCsvFileName = 'fleet-health-overview.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$OverviewJsonFileName = 'fleet-health-overview.json',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$XmlFileName = 'fleet-health-status.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'fleet-health-status-summary.md',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$InstalledModuleVersion,
+
+ [Parameter(Mandatory = $false)]
+ [datetime]$Now = (Get-Date),
+
+ [Parameter(Mandatory = $false)]
+ [switch]$PassThru
+ )
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ if (-not $OutputDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $OutputDirectory = Join-Path -Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY -ChildPath 'reports'
+ }
+ else {
+ $OutputDirectory = './reports'
+ }
+ }
+ if (-not (Test-Path -LiteralPath $OutputDirectory)) {
+ New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
+ }
+
+ $detailCsv = Join-Path -Path $OutputDirectory -ChildPath $DetailCsvFileName
+ $detailJson = Join-Path -Path $OutputDirectory -ChildPath $DetailJsonFileName
+ $summaryCsv = Join-Path -Path $OutputDirectory -ChildPath $SummaryCsvFileName
+ $summaryJson = Join-Path -Path $OutputDirectory -ChildPath $SummaryJsonFileName
+ $overviewCsv = Join-Path -Path $OutputDirectory -ChildPath $OverviewCsvFileName
+ $overviewJson = Join-Path -Path $OutputDirectory -ChildPath $OverviewJsonFileName
+ $xmlPath = Join-Path -Path $OutputDirectory -ChildPath $XmlFileName
+
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Fleet Health Status Collection" -ForegroundColor Cyan
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Scope : $Scope"
+ Write-Host "Severity : $Severity"
+ if ($Scope -eq 'by-update-ring' -and $UpdateRing) { Write-Host "UpdateRing: $UpdateRing" }
+ Write-Host ""
+
+ # ---- Step 1: pull DETAIL view once ------------------------------------
+ $argSplat = @{ Severity = $Severity }
+ if ($Scope -eq 'by-update-ring' -and $UpdateRing) { $argSplat['UpdateRingTag'] = $UpdateRing }
+
+ Write-Host "Step 1: Collecting fleet health failure rows (Detail view)..." -ForegroundColor Yellow
+ $detail = @(Get-AzLocalFleetHealthFailures -View Detail @argSplat -ExportPath $detailCsv -PassThru)
+ if (-not $detail) { $detail = @() }
+ $detail | ConvertTo-Json -Depth 6 | Out-File -FilePath $detailJson -Encoding utf8
+ Write-Host "Found $($detail.Count) failing health-check entry/entries." -ForegroundColor Green
+
+ # ---- Step 2: in-process SUMMARY view ----------------------------------
+ # AffectedClusters uses '; ' separator (matches cmdlet); adds positionally
+ # paired AffectedClusterPortalUrls so the markdown renderer can zip them
+ # into hyperlinks. Severity sorts FIRST (Critical before Warning).
+ $summary = @()
+ if ($detail.Count -gt 0) {
+ $summary = @(
+ $detail | Group-Object -Property FailureReason, Severity | ForEach-Object {
+ $first = $_.Group | Select-Object -First 1
+ $clusterList = @($_.Group | Select-Object -ExpandProperty ClusterName -Unique | Sort-Object)
+ $clusterPortalUrls = @(
+ foreach ($cn in $clusterList) {
+ $portalRow = $_.Group | Where-Object { $_.ClusterName -eq $cn } | Select-Object -First 1
+ if ($portalRow -and $portalRow.ClusterPortalUrl) { $portalRow.ClusterPortalUrl } else { '' }
+ }
+ )
+ $latestOcc = ($_.Group | Measure-Object -Property LastOccurrence -Maximum).Maximum
+ [pscustomobject]@{
+ FailureReason = $first.FailureReason
+ Severity = $first.Severity
+ ClusterCount = $clusterList.Count
+ FailureCount = $_.Group.Count
+ AffectedClusters = ($clusterList -join '; ')
+ AffectedClusterPortalUrls = ($clusterPortalUrls -join '; ')
+ LatestOccurrence = $latestOcc
+ Description = $first.Description
+ Remediation = $first.Remediation
+ }
+ } | Sort-Object @{Expression={ if ($_.Severity -eq 'Critical') { 1 } elseif ($_.Severity -eq 'Warning') { 2 } else { 3 } };Descending=$false},
+ @{Expression={$_.ClusterCount};Descending=$true},
+ @{Expression={$_.FailureCount};Descending=$true}
+ )
+ }
+ $summary | Export-Csv -Path $summaryCsv -NoTypeInformation -Force
+ $summary | ConvertTo-Json -Depth 6 | Out-File -FilePath $summaryJson -Encoding utf8
+
+ # ---- Step 3: OVERVIEW (one row per cluster) ---------------------------
+ Write-Host "Step 2: Collecting fleet health overview rows (one per cluster)..." -ForegroundColor Yellow
+ $overviewArgs = @{}
+ if ($Scope -eq 'by-update-ring' -and $UpdateRing) { $overviewArgs['UpdateRingTag'] = $UpdateRing }
+ $overview = @(Get-AzLocalFleetHealthOverview @overviewArgs -ExportPath $overviewCsv -PassThru)
+ if (-not $overview) { $overview = @() }
+ $overview | ConvertTo-Json -Depth 6 | Out-File -FilePath $overviewJson -Encoding utf8
+ Write-Host "Overview rows: $($overview.Count)." -ForegroundColor Green
+
+ # ---- Step 4: bucket counts -------------------------------------------
+ $criticalDetail = @($detail | Where-Object { $_.Severity -eq 'Critical' })
+ $warningDetail = @($detail | Where-Object { $_.Severity -eq 'Warning' })
+ $totalClusters = @($detail | Select-Object -ExpandProperty ClusterName -Unique).Count
+ $totalFailures = [int]$detail.Count
+ $criticalCount = [int]$criticalDetail.Count
+ $warningCount = [int]$warningDetail.Count
+ $distinctReasons = [int]$summary.Count
+ $healthyClusters = [int](@($overview | Where-Object { $_.HealthStatus -eq 'Healthy' }).Count)
+ $totalInSub = [int](@($overview).Count)
+
+ # ---- Step 5: JUnit XML via shared emitter ----------------------------
+ Write-Host "Step 3: Generating JUnit XML report..." -ForegroundColor Yellow
+ $suites = @()
+ foreach ($severityLabel in @('Critical','Warning')) {
+ $rows = if ($severityLabel -eq 'Critical') { $criticalDetail } else { $warningDetail }
+ if (-not $rows -or $rows.Count -eq 0) { continue }
+ $tcList = New-Object 'System.Collections.Generic.List[hashtable]'
+ foreach ($r in $rows) {
+ $clusterResId = if ($r.PSObject.Properties.Match('ClusterResourceId').Count -gt 0) { [string]$r.ClusterResourceId } else { '' }
+ $clusterPortalUrl = if ($r.PSObject.Properties.Match('ClusterPortalUrl').Count -gt 0) { [string]$r.ClusterPortalUrl } else { '' }
+ $targetResName = if ($r.PSObject.Properties.Match('TargetResourceName').Count -gt 0){ [string]$r.TargetResourceName }else { '' }
+ $targetResType = if ($r.PSObject.Properties.Match('TargetResourceType').Count -gt 0){ [string]$r.TargetResourceType }else { '' }
+ $msg = "{0}: {1} (last occurred {2:yyyy-MM-ddTHH:mm:ssZ})" -f $r.Severity, $r.FailureReason, $r.LastOccurrence
+ $bodyLines = @(
+ [string]$r.Description
+ [string]$r.Remediation
+ "ResourceGroup: $($r.ResourceGroup)"
+ "SubscriptionId: $($r.SubscriptionId)"
+ )
+ if ($targetResName) { $bodyLines += "TargetResourceName: $targetResName" }
+ if ($targetResType) { $bodyLines += "TargetResourceType: $targetResType" }
+ if ($clusterPortalUrl) { $bodyLines += "ClusterPortalUrl: $clusterPortalUrl" }
+ $tc = @{
+ Name = "{0} :: {1}" -f $r.ClusterName, $r.FailureReason
+ ClassName = [string]$r.ClusterName
+ Time = 0.0
+ Properties = ([ordered]@{
+ ClusterName = [string]$r.ClusterName
+ ClusterResourceId = $clusterResId
+ UpdateName = [string]$r.FailureReason # ITSM dedupe key slot
+ Status = [string]$r.Severity
+ FailureReason = [string]$r.FailureReason
+ Severity = [string]$r.Severity
+ ClusterPortalUrl = $clusterPortalUrl
+ TargetResourceName = $targetResName
+ TargetResourceType = $targetResType
+ })
+ Failure = @{
+ Type = [string]$r.Severity
+ Message = $msg
+ Body = ($bodyLines -join "`n")
+ }
+ }
+ $tcList.Add($tc) | Out-Null
+ }
+ $suites += ,@{
+ Name = "[JUnit Debug] $severityLabel Health Failures"
+ ClassName = "FleetHealth.$severityLabel"
+ TestCases = @($tcList)
+ }
+ }
+ if ($totalFailures -eq 0) {
+ $suites += ,@{
+ Name = 'Fleet Health'
+ ClassName = 'FleetHealth'
+ TestCases = @(@{
+ Name = 'No Critical or Warning health-check failures across the fleet'
+ ClassName = 'FleetHealth'
+ Time = 0.0
+ })
+ }
+ }
+ $null = New-AzLocalPipelineJUnitXml -TestSuitesName 'AzureLocalFleetHealthStatus' -Suites $suites -OutputPath $xmlPath -Timestamp $Now
+ Write-Host "JUnit XML saved to: $xmlPath" -ForegroundColor Green
+
+ # ---- Step 6: step outputs --------------------------------------------
+ Set-AzLocalPipelineOutput -Name 'total_clusters' -Value ([string]$totalClusters)
+ Set-AzLocalPipelineOutput -Name 'total_failures' -Value ([string]$totalFailures)
+ Set-AzLocalPipelineOutput -Name 'critical_count' -Value ([string]$criticalCount)
+ Set-AzLocalPipelineOutput -Name 'warning_count' -Value ([string]$warningCount)
+ Set-AzLocalPipelineOutput -Name 'distinct_reasons' -Value ([string]$distinctReasons)
+ Set-AzLocalPipelineOutput -Name 'overview_rows' -Value ([string]$overview.Count)
+ Set-AzLocalPipelineOutput -Name 'healthy_clusters' -Value ([string]$healthyClusters)
+ Set-AzLocalPipelineOutput -Name 'total_in_sub' -Value ([string]$totalInSub)
+
+ Write-Host ""
+ Write-Host "Fleet Health Collection complete:"
+ Write-Host " Total clusters in scope : $totalInSub"
+ Write-Host " Healthy clusters : $healthyClusters"
+ Write-Host " Unhealthy clusters : $totalClusters"
+ Write-Host " Total failing checks : $totalFailures (Critical=$criticalCount, Warning=$warningCount)"
+ Write-Host " Distinct failure reasons: $distinctReasons"
+ Write-Host " Overview rows : $($overview.Count)"
+
+ # ---- Step 7: markdown summary ----------------------------------------
+ $generatedUtc = $Now.ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss UTC')
+ $md = New-Object 'System.Collections.Generic.List[string]'
+ [void]$md.Add('## Fleet Health Status Summary')
+ [void]$md.Add('')
+ [void]$md.Add('| Metric | Count |')
+ [void]$md.Add('|--------|-------|')
+ [void]$md.Add("| **Total Clusters in Subscription** | $totalInSub |")
+ [void]$md.Add("| **Healthy Clusters** | $healthyClusters |")
+ [void]$md.Add("| **Unhealthy Clusters** | $totalClusters |")
+ [void]$md.Add("| **Total Failing Checks** | $totalFailures |")
+ [void]$md.Add("| **Critical** | $criticalCount |")
+ [void]$md.Add("| **Warning** | $warningCount |")
+ [void]$md.Add("| **Distinct Failure Reasons** | $distinctReasons |")
+ [void]$md.Add('')
+ [void]$md.Add('> _**Healthy** / **Unhealthy** count clusters via `Get-AzLocalFleetHealthOverview`; **Unhealthy** = at least one Critical or Warning health-check failure. **Total Failing Checks** counts individual failing checks (one cluster can contribute multiple)._')
+ [void]$md.Add('')
+
+ # ---- Fleet Health Overview table -------------------------------------
+ [void]$md.Add('### Fleet Health Overview (fleet rollup)')
+ [void]$md.Add('')
+ if ($overview.Count -eq 0) {
+ [void]$md.Add('*No clusters returned from Get-AzLocalFleetHealthOverview.*')
+ }
+ else {
+ [void]$md.Add('| Cluster | Health | Update Status | Current Version | SBE Version | Azure Connection | Last Checked | Health Check Age (days) | Node Count |')
+ [void]$md.Add('|---------|--------|---------------|------------------|--------------|------------------|---------------|--------------------------|------------|')
+ foreach ($o in (@($overview) | Select-Object -First $MaxOverviewRows)) {
+ # target="_blank" so clicking a portal link opens in a new tab
+ # and the operator does not lose the pipeline run page.
+ $clusterCell = if ($o.ClusterPortalUrl) {
+ ('{1}' -f $o.ClusterPortalUrl, $o.ClusterName)
+ }
+ else { [string]$o.ClusterName }
+ # Use literal Unicode glyphs (not GH ':name:' shortcodes) so GH +
+ # ADO render identically. Label is retained for greppability.
+ $healthTag = switch ($o.HealthStatus) {
+ 'Healthy' { "$([char]0x2705) Healthy" }
+ 'Critical' { "$([char]0x274C) Critical" }
+ 'Warning' { "$([char]0x26A0)$([char]0xFE0F) Warning" }
+ 'In progress' { "$([char]0x23F3) In progress" }
+ 'Health check failed' { "$([char]0x274C) Failed" }
+ default { '[' + [string]$o.HealthStatus + ']' }
+ }
+ [void]$md.Add(('| {0} | {1} | {2} | {3} | {4} | {5} | {6} | {7} | {8} |' -f $clusterCell, $healthTag, $o.UpdateStatus, $o.CurrentVersion, $o.SbeVersion, $o.AzureConnection, $o.LastChecked, $o.HealthResultsAgeDays, $o.NodeCount))
+ }
+ if ($overview.Count -gt $MaxOverviewRows) {
+ [void]$md.Add('')
+ [void]$md.Add(('*Showing first {0} clusters of {1}; see `{2}` artifact for the full list.*' -f $MaxOverviewRows, $overview.Count, $OverviewCsvFileName))
+ }
+ }
+ [void]$md.Add('')
+
+ # ---- Health Check Failures By Reason ----------------------------------
+ [void]$md.Add('### Health Check Failures By Reason (most widespread first)')
+ [void]$md.Add('')
+ if ($summary.Count -eq 0) {
+ [void]$md.Add('*No Critical or Warning health-check failures across the fleet.*')
+ }
+ else {
+ [void]$md.Add('| Severity | Failure Reason | Cluster Count | Failure Count | Affected Clusters | Latest |')
+ [void]$md.Add('|----------|----------------|---------------|---------------|--------------------|--------|')
+ foreach ($r in (@($summary) | Select-Object -First $MaxSummaryRows)) {
+ $sevTag = if ($r.Severity -eq 'Critical') { '[Critical]' } else { '[Warning]' }
+ # Keep @() OUTSIDE the 'if' so single-element splits do not unwrap
+ # to a bare String (PowerShell scalar-unwrap guard).
+ $names = @(if ($r.AffectedClusters) { $r.AffectedClusters -split '; ' } else { @() })
+ $urls = @(if ($r.AffectedClusterPortalUrls) { $r.AffectedClusterPortalUrls -split '; ' } else { @() })
+ $linkedParts = for ($i = 0; $i -lt $names.Count; $i++) {
+ $n = $names[$i]
+ $u = if ($i -lt $urls.Count) { $urls[$i] } else { '' }
+ if ($u) { ('{1}' -f $u, $n) } else { $n }
+ }
+ $clList = if ($linkedParts.Count -le 10) {
+ $linkedParts -join ', '
+ }
+ else {
+ (($linkedParts | Select-Object -First 10) -join ', ') + (' ... (+{0} more)' -f ($linkedParts.Count - 10))
+ }
+ [void]$md.Add(('| {0} | {1} | {2} | {3} | {4} | {5} |' -f $sevTag, $r.FailureReason, $r.ClusterCount, $r.FailureCount, $clList, $r.LatestOccurrence))
+ }
+ if ($summary.Count -gt $MaxSummaryRows) {
+ [void]$md.Add('')
+ [void]$md.Add(('*Showing top {0} failure reasons of {1}; see `{2}` artifact for the full list.*' -f $MaxSummaryRows, $summary.Count, $SummaryCsvFileName))
+ }
+ }
+ [void]$md.Add('')
+
+ # ---- Detailed Results (collapsible per-cluster) -----------------------
+ [void]$md.Add('### Detailed Results (per-cluster, per-failure)')
+ [void]$md.Add('')
+ if ($detail.Count -eq 0) {
+ [void]$md.Add('*No detail rows.*')
+ }
+ else {
+ [void]$md.Add('*Click a cluster to expand its failing health checks. Worst-affected clusters appear first.*')
+ [void]$md.Add('')
+ $detailByCluster = @(
+ $detail | Group-Object -Property ClusterName | ForEach-Object {
+ $rows = @($_.Group)
+ $crit = @($rows | Where-Object { $_.Severity -eq 'Critical' }).Count
+ $warn = @($rows | Where-Object { $_.Severity -eq 'Warning' }).Count
+ $portalRow = $rows | Where-Object {
+ $_.PSObject.Properties.Match('ClusterPortalUrl').Count -gt 0 -and $_.ClusterPortalUrl
+ } | Select-Object -First 1
+ $lastOcc = ($rows | Measure-Object -Property LastOccurrence -Maximum).Maximum
+ [pscustomobject]@{
+ ClusterName = $_.Name
+ ClusterPortalUrl = if ($portalRow) { [string]$portalRow.ClusterPortalUrl } else { '' }
+ CriticalCount = $crit
+ WarningCount = $warn
+ LastOccurrence = $lastOcc
+ Rows = @(
+ $rows | Sort-Object @{Expression={ if ($_.Severity -eq 'Critical') { 1 } else { 2 } };Descending=$false},
+ @{Expression={$_.LastOccurrence};Descending=$true}
+ )
+ }
+ } | Sort-Object @{Expression={$_.CriticalCount};Descending=$true},
+ @{Expression={$_.WarningCount};Descending=$true},
+ @{Expression={$_.LastOccurrence};Descending=$true}
+ )
+ $totalDetailClusters = $detailByCluster.Count
+ $clustersToShow = @($detailByCluster | Select-Object -First $MaxDetailClusters)
+ foreach ($cl in $clustersToShow) {
+ $sevParts = @()
+ if ($cl.CriticalCount -gt 0) { $sevParts += ('[Critical] x {0}' -f $cl.CriticalCount) }
+ if ($cl.WarningCount -gt 0) { $sevParts += ('[Warning] x {0}' -f $cl.WarningCount) }
+ $sevTally = $sevParts -join ' · '
+
+ $clusterCell = if ($cl.ClusterPortalUrl) {
+ ('{1}' -f $cl.ClusterPortalUrl, $cl.ClusterName)
+ }
+ else { [string]$cl.ClusterName }
+ $lastOccStr = if ($cl.LastOccurrence) { ('{0:yyyy-MM-ddTHH:mm:ssZ}' -f $cl.LastOccurrence) } else { '-' }
+
+ [void]$md.Add('')
+ [void]$md.Add(('{0} · {1} · last {2}
' -f $clusterCell, $sevTally, $lastOccStr))
+ [void]$md.Add('')
+ [void]$md.Add('| Severity | Failure Reason | Failure Remediation | Target Resource Name | Target Resource Type | Last Occurrence | Resource Group |')
+ [void]$md.Add('|----------|----------------|---------------------|----------------------|----------------------|------------------|----------------|')
+ foreach ($r in $cl.Rows) {
+ $sevTag = if ($r.Severity -eq 'Critical') { '[Critical]' } else { '[Warning]' }
+ $rem = if ($r.PSObject.Properties.Match('Remediation').Count -gt 0) { [string]$r.Remediation } else { '' }
+ $remCell = if ($rem -and $rem.StartsWith('https://')) { ('link' -f $rem) } else { $rem }
+ $tName = if ($r.PSObject.Properties.Match('TargetResourceName').Count -gt 0) { [string]$r.TargetResourceName } else { '' }
+ $tType = if ($r.PSObject.Properties.Match('TargetResourceType').Count -gt 0) { [string]$r.TargetResourceType } else { '' }
+ [void]$md.Add(('| {0} | {1} | {2} | {3} | {4} | {5} | {6} |' -f $sevTag, $r.FailureReason, $remCell, $tName, $tType, $r.LastOccurrence, $r.ResourceGroup))
+ }
+ [void]$md.Add(' ')
+ [void]$md.Add('')
+ }
+ if ($totalDetailClusters -gt $MaxDetailClusters) {
+ [void]$md.Add(('*Showing first {0} clusters of {1}; see `{2}` artifact for the full list.*' -f $MaxDetailClusters, $totalDetailClusters, $DetailCsvFileName))
+ [void]$md.Add('')
+ }
+ }
+
+ [void]$md.Add('### Reports Available')
+ [void]$md.Add(('- `{0}` - one row per (cluster, failing health check)' -f $DetailCsvFileName))
+ [void]$md.Add(('- `{0}` - one row per (FailureReason, Severity); ordered Critical-first, then by ClusterCount desc' -f $SummaryCsvFileName))
+ [void]$md.Add(('- `{0}` - one row per cluster (ARG-first fleet health summary)' -f $OverviewCsvFileName))
+ [void]$md.Add(('- `{0}` / `{1}` / `{2}` - same data, machine-readable' -f $DetailJsonFileName, $SummaryJsonFileName, $OverviewJsonFileName))
+ [void]$md.Add(('- `{0}` - JUnit XML for CI/CD visualisation' -f $XmlFileName))
+ [void]$md.Add('')
+ [void]$md.Add('_Note: test sections prefixed **[JUnit Debug]** in the Tests view are a diagnostic mirror of the tables above (for CI tooling/ITSM integration). For primary readability, use this summary and the CSV artifacts._')
+ [void]$md.Add('')
+ [void]$md.Add("*Generated at $generatedUtc*")
+ if ($InstalledModuleVersion) {
+ [void]$md.Add('')
+ [void]$md.Add(('_Generated by AzLocal.UpdateManagement v{0}._' -f $InstalledModuleVersion))
+ }
+
+ $summaryPath = Add-AzLocalPipelineStepSummary -Markdown ($md -join [Environment]::NewLine) -SummaryFileName $SummaryFileName
+
+ if ($criticalCount -gt 0) {
+ Write-Warning "$criticalCount Critical health-check failure(s) across the fleet. Check the detailed reports."
+ }
+
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalClusters = [int]$totalClusters
+ TotalFailures = [int]$totalFailures
+ CriticalCount = [int]$criticalCount
+ WarningCount = [int]$warningCount
+ DistinctReasons = [int]$distinctReasons
+ OverviewRows = [int]$overview.Count
+ HealthyClusters = [int]$healthyClusters
+ TotalInSub = [int]$totalInSub
+ DetailCsvPath = $detailCsv
+ DetailJsonPath = $detailJson
+ SummaryCsvPath = $summaryCsv
+ SummaryJsonPath = $summaryJson
+ OverviewCsvPath = $overviewCsv
+ OverviewJsonPath = $overviewJson
+ XmlPath = $xmlPath
+ SummaryPath = $summaryPath
+ DetailRows = $detail
+ SummaryRows = $summary
+ OverviewRowsData = $overview
+ }
+ }
+}
diff --git a/AzLocal.UpdateManagement/Public/Export-AzLocalFleetUpdateStatusReport.ps1 b/AzLocal.UpdateManagement/Public/Export-AzLocalFleetUpdateStatusReport.ps1
new file mode 100644
index 00000000..a8e7612a
--- /dev/null
+++ b/AzLocal.UpdateManagement/Public/Export-AzLocalFleetUpdateStatusReport.ps1
@@ -0,0 +1,1024 @@
+function Export-AzLocalFleetUpdateStatusReport {
+ <#
+ .SYNOPSIS
+ Snapshots fleet-wide Azure Local update status and emits the full
+ Step.8 artefact bundle (CSV + JSON + JUnit XML + markdown summary).
+
+ .DESCRIPTION
+ Public entry-point for the v0.8.5 thin-YAML refactor of the Step.8
+ fleet-update-status pipeline. Before v0.8.5 the GitHub Actions and
+ Azure DevOps Step.8 YAML files each carried ~830 lines of inline
+ PowerShell (cluster inventory + readiness + JUnit XML construction +
+ markdown summary rendering + step-output emission). This cmdlet
+ condenses that workload into a single Public PowerShell entry-point
+ that both pipeline platforms call with a thin parameter splat.
+
+ The cmdlet:
+ 1. Inventories every Azure Local cluster the caller can read
+ (or, with -Scope by-update-ring, every cluster whose UpdateRing
+ tag matches -UpdateRing).
+ 2. Computes readiness, current version, health state and update
+ state per cluster.
+ 3. Pivots clusters by CurrentVersion to produce a Fleet Version
+ Distribution view, anchored against the latest released Azure
+ Local solution version from the Microsoft Edge Updates manifest
+ (with a fleet-observed top-6 YYMM fallback when the manifest is
+ unreachable).
+ 4. Generates a 3-testsuite JUnit XML document
+ (Fleet Version Distribution + AzureLocalFleetUpdateStatus +
+ Update Run History and Error Details) using the shared
+ New-AzLocalPipelineJUnitXml emitter. Each testcase carries
+ that the optional New-AzLocalIncident ITSM
+ connector consumes to compute the SHA256 dedupe key.
+ 5. Collects supplementary fleet-wide CSVs
+ (update-summaries.csv, available-updates.csv, optional
+ update-runs.csv) and the verbose run-history bundle
+ (update-run-history.csv + .json) from
+ Get-AzLocalUpdateRunFailures -State Failed -OnlyUnresolved.
+ 6. Emits 22 step outputs (lowercase snake_case) describing fleet
+ bucket counts so downstream pipeline steps can branch.
+ 7. Renders the full markdown summary to the host's step-summary
+ surface (GitHub Actions GITHUB_STEP_SUMMARY or Azure DevOps
+ ##vso[task.uploadsummary]) including the YYMM-grouped version
+ distribution table, the Critical Health Status pass/fail table,
+ the Primary Status priority cascade table, the Actions Required
+ bullet list and the Update Run History collapsible-error table.
+
+ The cmdlet replaces the inline 'Collect Fleet Update Status' AND the
+ downstream 'Create Status Summary' steps from the pre-v0.8.5 YAML.
+
+ .PARAMETER OutputDirectory
+ Directory to write artefacts into. When omitted, defaults to
+ $env:BUILD_ARTIFACTSTAGINGDIRECTORY on Azure DevOps hosts (resolved
+ via Get-AzLocalPipelineHost) and './reports' everywhere else
+ (GitHub Actions, local interactive use).
+
+ .PARAMETER Scope
+ Fleet selector: 'all' (every cluster the caller can read) or
+ 'by-update-ring' (clusters whose UpdateRing tag matches -UpdateRing).
+
+ .PARAMETER UpdateRing
+ UpdateRing tag value to filter on when Scope='by-update-ring'.
+ Accepts a single value, a ';'-delimited list, or '***' (three stars)
+ as a wildcard. Ignored when Scope='all'.
+
+ .PARAMETER IncludeUpdateRuns
+ When $true (default), runs Step 4c (Get-AzLocalUpdateRuns -Latest
+ across the fleet) and writes update-runs.csv. Set $false to skip
+ the recent-runs collection to shorten run time on very large fleets.
+
+ .PARAMETER RunHistorySinceDays
+ How far back to look for unresolved Failed update runs when
+ building the 'Update Run History and Error Details' testsuite.
+ Default 30 days. Must be 1..365.
+
+ .PARAMETER RunHistoryTopRows
+ Maximum number of rows persisted to the run-history base64 blob
+ consumed by the markdown summary. Default 25. Must be 1..500.
+ Does NOT cap the JUnit XML or CSV emit (those include every row).
+
+ .PARAMETER InventoryCsvFileName
+ Override the default 'cluster-inventory.csv' filename.
+
+ .PARAMETER ReadinessCsvFileName
+ Override the default 'readiness-status.csv' filename.
+
+ .PARAMETER ReadinessJsonFileName
+ Override the default 'readiness-status.json' filename.
+
+ .PARAMETER XmlFileName
+ Override the default 'readiness-status.xml' JUnit filename.
+
+ .PARAMETER SummariesCsvFileName
+ Override the default 'update-summaries.csv' filename.
+
+ .PARAMETER AvailableCsvFileName
+ Override the default 'available-updates.csv' filename.
+
+ .PARAMETER RunsCsvFileName
+ Override the default 'update-runs.csv' filename.
+
+ .PARAMETER RunHistoryCsvFileName
+ Override the default 'update-run-history.csv' filename.
+
+ .PARAMETER RunHistoryJsonFileName
+ Override the default 'update-run-history.json' filename.
+
+ .PARAMETER SummaryFileName
+ Override the default 'fleet-update-status-summary.md' filename
+ (the markdown rendered into GITHUB_STEP_SUMMARY / ADO upload-summary).
+
+ .PARAMETER InstalledModuleVersion
+ Optional version string rendered in the markdown footer (e.g. v0.8.5).
+ When omitted, no footer line is appended.
+
+ .PARAMETER Now
+ Optional [datetime] used as 'snapshot time' in the markdown summary
+ (Generated at ...). Defaults to (Get-Date). Parameterised so unit
+ tests can assert against a fixed value.
+
+ .PARAMETER PassThru
+ Return a PSCustomObject describing the fleet snapshot (counts +
+ file paths + Rows + RunHistoryRows + VersionDistribution). Default
+ is no return value (the cmdlet only writes files + step outputs +
+ markdown summary).
+
+ .OUTPUTS
+ [PSCustomObject] when -PassThru is supplied. Properties:
+ - TotalClusters, CriticalHealthPassed, CriticalHealthFailed
+ - UpdateFailedCount, ActionRequiredCount, HealthFailureCount,
+ SbeBlockedCount, InProgressCount, ReadyForUpdateCount,
+ UpToDateCount, NeedsInvestigationCount
+ - HasPrerequisiteCount, RunHistoryCount
+ - VersionDistCount, SupportedClusters, UnsupportedClusters,
+ UnknownVersionClusters, SupportSource, SupportedYymmWindow,
+ LatestReleasedYymm, LatestReleasedVersion
+ - InventoryCsvPath, ReadinessCsvPath, ReadinessJsonPath,
+ XmlPath, SummariesCsvPath, AvailableCsvPath, RunsCsvPath,
+ RunHistoryCsvPath, RunHistoryJsonPath, SummaryPath
+ - Rows (readiness rows), RunHistoryRows, VersionDistribution
+
+ .EXAMPLE
+ Export-AzLocalFleetUpdateStatusReport
+ # All-cluster snapshot; writes the full artefact bundle to ./reports/.
+
+ .EXAMPLE
+ Export-AzLocalFleetUpdateStatusReport -Scope by-update-ring -UpdateRing Prod -PassThru
+ # Restricts to clusters tagged UpdateRing=Prod and returns the
+ # snapshot object for downstream PowerShell use.
+
+ .EXAMPLE
+ # Used by Step.8_fleet-update-status.yml (GitHub Actions + Azure DevOps):
+ Export-AzLocalFleetUpdateStatusReport `
+ -Scope $env:INPUT_SCOPE `
+ -UpdateRing $env:INPUT_UPDATE_RING `
+ -IncludeUpdateRuns:($env:INPUT_INCLUDE_UPDATE_RUNS -eq 'true') `
+ -InstalledModuleVersion (Get-Module AzLocal.UpdateManagement).Version
+
+ .NOTES
+ Author : Neil Bird, Microsoft
+ Version: v0.8.5
+ Added : v0.8.5 (Step.8 thin-YAML port - condenses ~830 lines of inline
+ PowerShell into a single Public entry-point).
+ Reuses : Get-AzLocalClusterInventory, Get-AzLocalClusterUpdateReadiness,
+ Get-AzLocalUpdateSummary, Get-AzLocalAvailableUpdates,
+ Get-AzLocalUpdateRuns, Get-AzLocalUpdateRunFailures,
+ Get-AzLocalLatestSolutionVersion, New-AzLocalPipelineJUnitXml,
+ Set-AzLocalPipelineOutput, Add-AzLocalPipelineStepSummary,
+ Get-AzLocalPipelineHost.
+ #>
+ [CmdletBinding()]
+ [OutputType([PSCustomObject])]
+ param(
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$OutputDirectory,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateSet('all', 'by-update-ring')]
+ [string]$Scope = 'all',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$UpdateRing,
+
+ [Parameter(Mandatory = $false)]
+ [bool]$IncludeUpdateRuns = $true,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 365)]
+ [int]$RunHistorySinceDays = 30,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateRange(1, 500)]
+ [int]$RunHistoryTopRows = 25,
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$InventoryCsvFileName = 'cluster-inventory.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReadinessCsvFileName = 'readiness-status.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$ReadinessJsonFileName = 'readiness-status.json',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$XmlFileName = 'readiness-status.xml',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummariesCsvFileName = 'update-summaries.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$AvailableCsvFileName = 'available-updates.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$RunsCsvFileName = 'update-runs.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$RunHistoryCsvFileName = 'update-run-history.csv',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$RunHistoryJsonFileName = 'update-run-history.json',
+
+ [Parameter(Mandatory = $false)]
+ [ValidateNotNullOrEmpty()]
+ [string]$SummaryFileName = 'fleet-update-status-summary.md',
+
+ [Parameter(Mandatory = $false)]
+ [AllowEmptyString()]
+ [AllowNull()]
+ [string]$InstalledModuleVersion,
+
+ [Parameter(Mandatory = $false)]
+ [datetime]$Now = (Get-Date),
+
+ [Parameter(Mandatory = $false)]
+ [switch]$PassThru
+ )
+
+ $pipelineHost = Get-AzLocalPipelineHost
+
+ if (-not $OutputDirectory) {
+ if ($pipelineHost -eq 'AzureDevOps' -and $env:BUILD_ARTIFACTSTAGINGDIRECTORY) {
+ $OutputDirectory = Join-Path -Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY -ChildPath 'reports'
+ }
+ else {
+ $OutputDirectory = './reports'
+ }
+ }
+ if (-not (Test-Path -LiteralPath $OutputDirectory)) {
+ New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
+ }
+
+ $inventoryCsv = Join-Path -Path $OutputDirectory -ChildPath $InventoryCsvFileName
+ $readinessCsv = Join-Path -Path $OutputDirectory -ChildPath $ReadinessCsvFileName
+ $readinessJson = Join-Path -Path $OutputDirectory -ChildPath $ReadinessJsonFileName
+ $readinessXml = Join-Path -Path $OutputDirectory -ChildPath $XmlFileName
+ $summariesCsv = Join-Path -Path $OutputDirectory -ChildPath $SummariesCsvFileName
+ $availableCsv = Join-Path -Path $OutputDirectory -ChildPath $AvailableCsvFileName
+ $runsCsv = Join-Path -Path $OutputDirectory -ChildPath $RunsCsvFileName
+ $runHistoryCsv = Join-Path -Path $OutputDirectory -ChildPath $RunHistoryCsvFileName
+ $runHistoryJson = Join-Path -Path $OutputDirectory -ChildPath $RunHistoryJsonFileName
+
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Fleet Update Status Collection" -ForegroundColor Cyan
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Scope: $Scope"
+ if ($UpdateRing) { Write-Host "UpdateRing Filter: $UpdateRing" }
+ Write-Host "Include Update Runs: $IncludeUpdateRuns"
+ Write-Host ""
+
+ # ---- Step 1: cluster inventory ----------------------------------------
+ Write-Host "Step 1: Getting cluster inventory..." -ForegroundColor Yellow
+ $inventory = Get-AzLocalClusterInventory -ExportPath $inventoryCsv -PassThru
+ $inventoryCount = @($inventory).Count
+ Write-Host "Found $inventoryCount total cluster(s)" -ForegroundColor Green
+
+ if ($inventoryCount -eq 0) {
+ Write-Warning "No clusters found in inventory; emitting empty artefact bundle and step outputs."
+ # Emit empty JUnit document + zero-valued step outputs so downstream
+ # pipeline steps (dorny/test-reporter, ITSM connector) don't crash.
+ $null = New-AzLocalPipelineJUnitXml -TestSuitesName 'Fleet Update Status' -Suites @(
+ @{ Name = 'Fleet Version Distribution'; ClassName = 'FleetVersionDistribution'; TestCases = @() }
+ @{ Name = 'AzureLocalFleetUpdateStatus'; ClassName = 'AzureLocalFleetUpdateStatus'; TestCases = @() }
+ @{ Name = "Update Run History and Error Details"; ClassName = 'UpdateRunHistory'; TestCases = @() }
+ ) -OutputPath $readinessXml -Timestamp $Now
+ foreach ($n in @('total_clusters','critical_health_passed','critical_health_failed','up_to_date','in_progress','ready','sbe_blocked','health_failure','update_failed','action_required','needs_investigation','failures','has_prerequisite','run_history_count','version_dist_count','supported_clusters','unsupported_clusters','unknown_version_clusters')) {
+ Set-AzLocalPipelineOutput -Name $n -Value '0'
+ }
+ foreach ($n in @('supported_yymm_window','support_source','latest_released_yymm','latest_released_version')) {
+ Set-AzLocalPipelineOutput -Name $n -Value ''
+ }
+ $emptyMd = "## Fleet Update Status Summary _(generated $($Now.ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss UTC')))_`n`n_No clusters found in inventory._"
+ Add-AzLocalPipelineStepSummary -Markdown $emptyMd -SummaryFileName $SummaryFileName | Out-Null
+ if ($PassThru) {
+ return [pscustomobject]@{
+ TotalClusters = 0
+ CriticalHealthPassed = 0
+ CriticalHealthFailed = 0
+ UpdateFailedCount = 0
+ ActionRequiredCount = 0
+ HealthFailureCount = 0
+ SbeBlockedCount = 0
+ InProgressCount = 0
+ ReadyForUpdateCount = 0
+ UpToDateCount = 0
+ NeedsInvestigationCount = 0
+ HasPrerequisiteCount = 0
+ RunHistoryCount = 0
+ VersionDistCount = 0
+ SupportedClusters = 0
+ UnsupportedClusters = 0
+ UnknownVersionClusters = 0
+ SupportedYymmWindow = ''
+ SupportSource = ''
+ LatestReleasedYymm = ''
+ LatestReleasedVersion = ''
+ InventoryCsvPath = $inventoryCsv
+ ReadinessCsvPath = $readinessCsv
+ ReadinessJsonPath = $readinessJson
+ XmlPath = $readinessXml
+ SummariesCsvPath = $summariesCsv
+ AvailableCsvPath = $availableCsv
+ RunsCsvPath = $runsCsv
+ RunHistoryCsvPath = $runHistoryCsv
+ RunHistoryJsonPath = $runHistoryJson
+ Rows = @()
+ RunHistoryRows = @()
+ VersionDistribution = @()
+ }
+ }
+ return
+ }
+
+ # ---- Step 2: readiness ------------------------------------------------
+ Write-Host ""
+ Write-Host "Step 2: Checking update readiness..." -ForegroundColor Yellow
+
+ $readinessParams = @{ ExportPath = $readinessCsv; PassThru = $true }
+ if ($Scope -eq 'by-update-ring' -and $UpdateRing) {
+ $readinessParams['ScopeByUpdateRingTag'] = $true
+ $readinessParams['UpdateRingValue'] = $UpdateRing
+ }
+ else {
+ $readinessParams['ClusterResourceIds'] = @($inventory | Select-Object -ExpandProperty ResourceId)
+ }
+ $readiness = @(Get-AzLocalClusterUpdateReadiness @readinessParams)
+ $totalTests = $readiness.Count
+
+ # ---- Status bucket classification (priority cascade) ------------------
+ # Cluster is counted exactly once. Priority (first match wins):
+ # UpdateFailed > ActionRequired > HealthFailure > SbeBlocked >
+ # InProgress > ReadyForUpdate > UpToDate > NeedsInvestigation
+ $failureStates = @('Failed','UpdateFailed','NeedsAttention','PreparationFailed')
+ $stUpdateFailed = 0
+ $stActionRequired = 0
+ $stHealthFailure = 0
+ $stSbeBlocked = 0
+ $stInProgress = 0
+ $stReadyForUpdate = 0
+ $stUpToDate = 0
+ $stOther = 0
+ foreach ($c in $readiness) {
+ if ($c.UpdateState -in @('Failed','UpdateFailed','NeedsAttention')) { $stUpdateFailed++ }
+ elseif ($c.UpdateState -eq 'PreparationFailed') { $stActionRequired++ }
+ elseif ($c.HealthState -eq 'Failure') { $stHealthFailure++ }
+ elseif ($c.HasPrerequisiteUpdates) { $stSbeBlocked++ }
+ elseif ($c.UpdateState -in @('UpdateInProgress','PreparationInProgress')){ $stInProgress++ }
+ elseif ($c.ReadyForUpdate -eq $true) { $stReadyForUpdate++ }
+ elseif ($c.UpdateState -in @('UpToDate','AppliedSuccessfully')) { $stUpToDate++ }
+ else { $stOther++ }
+ }
+ $hasPrerequisite = @($readiness | Where-Object { $_.HasPrerequisiteUpdates -ne '' -and $null -ne $_.HasPrerequisiteUpdates }).Count
+
+ # Critical Health Status = JUnit pass/fail bucket
+ $criticalHealthFailed = @($readiness | Where-Object {
+ $_.HealthState -eq 'Failure' -or
+ ($_.UpdateState -in $failureStates) -or
+ ($_.HasPrerequisiteUpdates -ne '' -and $null -ne $_.HasPrerequisiteUpdates)
+ }).Count
+ $criticalHealthPassed = $totalTests - $criticalHealthFailed
+
+ # ---- readiness-status.json --------------------------------------------
+ $readinessExport = [ordered]@{
+ Timestamp = $Now.ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss UTC')
+ TotalClusters = $totalTests
+ Summary = [ordered]@{
+ ReadyForUpdate = @($readiness | Where-Object { $_.ReadyForUpdate -eq $true }).Count
+ UpToDate = @($readiness | Where-Object {
+ $_.ReadyForUpdate -ne $true -and
+ $_.UpdateState -in @('UpToDate','AppliedSuccessfully') -and
+ [string]::IsNullOrEmpty([string]$_.AllAvailableUpdates)
+ }).Count
+ InProgress = @($readiness | Where-Object { $_.UpdateState -in @('UpdateInProgress','PreparationInProgress') }).Count
+ HealthFailures = @($readiness | Where-Object { $_.HealthState -eq 'Failure' }).Count
+ UpdateFailures = @($readiness | Where-Object { $_.UpdateState -in @('Failed','UpdateFailed','NeedsAttention') }).Count
+ ActionRequired = @($readiness | Where-Object { $_.UpdateState -eq 'PreparationFailed' }).Count
+ HasPrerequisite = $hasPrerequisite
+ NotReadyForUpdate = @($readiness | Where-Object {
+ $_.ReadyForUpdate -ne $true -and
+ ($_.UpdateState -notin @('UpdateInProgress','PreparationInProgress')) -and
+ -not ($_.UpdateState -in @('UpToDate','AppliedSuccessfully') -and [string]::IsNullOrEmpty([string]$_.AllAvailableUpdates))
+ }).Count
+ }
+ Clusters = $readiness
+ }
+ $readinessExport | ConvertTo-Json -Depth 10 | Out-File -FilePath $readinessJson -Encoding utf8
+
+ # ---- Fleet Version Distribution + support window ----------------------
+ $versionGroups = @($readiness | Group-Object {
+ if ([string]::IsNullOrWhiteSpace($_.CurrentVersion)) { '(unknown)' } else { [string]$_.CurrentVersion }
+ } | Sort-Object Count -Descending)
+ $versionDistribution = @($versionGroups | ForEach-Object {
+ $clusterNames = @($_.Group | Sort-Object ClusterName | ForEach-Object { [string]$_.ClusterName })
+ [pscustomobject]@{
+ Version = $_.Name
+ Count = $_.Count
+ Percentage = if ($totalTests -gt 0) { [math]::Round(($_.Count / $totalTests) * 100, 1) } else { 0 }
+ Clusters = ($clusterNames -join ', ')
+ }
+ })
+ $distinctVersions = $versionDistribution.Count
+ $mostCommonVersion = if ($distinctVersions -gt 0) { $versionDistribution[0].Version } else { '(none)' }
+ $mostCommonVersionPct = if ($distinctVersions -gt 0) { $versionDistribution[0].Percentage } else { 0 }
+
+ # Anchor support window on Microsoft manifest (preferred) or
+ # fleet-observed top-6 YYMM fallback when the manifest is unreachable.
+ $supportSource = 'fleet-observed'
+ $latestReleasedYymm = ''
+ $latestReleasedVersion = ''
+ $manifestFetchedAt = ''
+ $manifestUrl = 'https://aka.ms/AzureEdgeUpdates'
+ $supportedYymms = @()
+ try {
+ Write-Host "Querying $manifestUrl for the latest released Azure Local solution version..."
+ $manifestProbe = Get-AzLocalLatestSolutionVersion -ErrorAction Stop
+ $supportedYymms = @($manifestProbe.SupportedYYMMs)
+ $supportSource = 'Microsoft manifest'
+ $latestReleasedYymm = [string]$manifestProbe.LatestYYMM
+ $latestReleasedVersion = [string]$manifestProbe.LatestVersion
+ if ($manifestProbe.ManifestFetchedAt) {
+ $manifestFetchedAt = $manifestProbe.ManifestFetchedAt.ToString('o')
+ }
+ Write-Host ("Latest released solution version: {0} (YYMM={1}); support window anchored on Microsoft manifest." -f $latestReleasedVersion, $latestReleasedYymm) -ForegroundColor Green
+ }
+ catch {
+ Write-Warning "Failed to query $manifestUrl - falling back to fleet-observed top-6 YYMM window. Error: $($_.Exception.Message)"
+ $observedYymms = @($versionDistribution | ForEach-Object {
+ $parts = ([string]$_.Version) -split '\.'
+ if ($parts.Count -ge 2) { $parts[1] } else { '' }
+ } | Where-Object { $_ -match '^[0-9]{4}$' } | Sort-Object -Unique)
+ $supportedYymms = @($observedYymms | Sort-Object -Descending | Select-Object -First 6)
+ }
+ $supportedCount = 0
+ $unsupportedCount = 0
+ $unknownVersionCount = 0
+ foreach ($v in $versionDistribution) {
+ $parts = ([string]$v.Version) -split '\.'
+ $yymm = if ($parts.Count -ge 2) { $parts[1] } else { '' }
+ $supportStatus = if ($yymm -match '^[0-9]{4}$') {
+ if ($supportedYymms -contains $yymm) { 'Supported' } else { 'Unsupported' }
+ }
+ else { 'Unknown' }
+ $v | Add-Member -MemberType NoteProperty -Name Yymm -Value $yymm -Force
+ $v | Add-Member -MemberType NoteProperty -Name SupportStatus -Value $supportStatus -Force
+ switch ($supportStatus) {
+ 'Supported' { $supportedCount += [int]$v.Count }
+ 'Unsupported' { $unsupportedCount += [int]$v.Count }
+ 'Unknown' { $unknownVersionCount += [int]$v.Count }
+ }
+ }
+ $supportedYymmWindow = if ($supportedYymms.Count -gt 0) { ($supportedYymms -join ',') } else { '(none)' }
+
+ Write-Host ""
+ Write-Host "Fleet Version Distribution ($distinctVersions distinct version(s) across $totalTests cluster(s)):" -ForegroundColor Cyan
+ Write-Host ("Support source: {0}" -f $supportSource)
+ if ($latestReleasedYymm) {
+ Write-Host ("Latest released YYMM (Microsoft manifest): {0} ({1})" -f $latestReleasedYymm, $latestReleasedVersion)
+ }
+ Write-Host ("Supported YYMM window (top {0}): {1}" -f $supportedYymms.Count, $supportedYymmWindow)
+ foreach ($v in $versionDistribution) {
+ Write-Host (" {0,-30} {1,5} cluster(s) ({2,5}%) [{3}]" -f $v.Version, $v.Count, $v.Percentage, $v.SupportStatus)
+ }
+
+ # ---- Step 3b: Update Run History (must run before JUnit XML build) ---
+ Write-Host ""
+ Write-Host "Step 3b: Collecting Update Run History + Verbose Error Details (ARG-first, fleet-scale)..." -ForegroundColor Yellow
+ $runFailures = @()
+ try {
+ $runFailures = @(Get-AzLocalUpdateRunFailures -State Failed -OnlyUnresolved -Since $Now.AddDays(-1 * $RunHistorySinceDays))
+ }
+ catch {
+ Write-Warning "Get-AzLocalUpdateRunFailures threw: $($_.Exception.Message). Continuing with empty run-history section."
+ $runFailures = @()
+ }
+ $runFailures = @($runFailures | Sort-Object @{Expression='StartTime';Descending=$true}, @{Expression='ClusterName';Descending=$false})
+ $runHistoryCount = $runFailures.Count
+ Write-Host "Found $runHistoryCount unresolved Failed update run(s)." -ForegroundColor $(if ($runHistoryCount -gt 0) { 'Yellow' } else { 'Green' })
+
+ if ($runHistoryCount -gt 0) {
+ $runFailures |
+ Select-Object ClusterName, UpdateName, State, Status, CurrentStep, Duration, StartTime, LastUpdated, DeepestStepName, ErrorCategory, DeepestErrMsg, UpdateRunPortalUrl, ClusterResourceId, RunId |
+ Export-Csv -Path $runHistoryCsv -NoTypeInformation -Force
+ $runFailures | ConvertTo-Json -Depth 4 | Out-File -FilePath $runHistoryJson -Encoding utf8
+ }
+ else {
+ '' | Set-Content -LiteralPath $runHistoryCsv -Encoding utf8
+ '[]' | Set-Content -LiteralPath $runHistoryJson -Encoding utf8
+ }
+
+ # ---- Step 3: JUnit XML via the shared emitter -------------------------
+ Write-Host ""
+ Write-Host "Step 3: Generating JUnit XML report..." -ForegroundColor Yellow
+
+ # Suite 1: Fleet Version Distribution (one testcase per CurrentVersion, all passed)
+ $vdTestCases = New-Object 'System.Collections.Generic.List[hashtable]'
+ foreach ($v in $versionDistribution) {
+ $vdTestCases.Add(@{
+ Name = "Version-$($v.Version)"
+ ClassName = 'FleetVersionDistribution'
+ Time = 0.0
+ Properties = ([ordered]@{
+ Version = $v.Version
+ Yymm = $v.Yymm
+ SupportStatus = $v.SupportStatus
+ ClusterCount = $v.Count
+ Percentage = $v.Percentage
+ Clusters = $v.Clusters
+ })
+ SystemOut = "Version: $($v.Version)`nYYMM: $($v.Yymm)`nSupportStatus: $($v.SupportStatus)`nClusters: $($v.Count)`nPercentage: $($v.Percentage)%`nClusterNames: $($v.Clusters)"
+ }) | Out-Null
+ }
+ $vdSuite = @{
+ Name = 'Fleet Version Distribution'
+ ClassName = 'FleetVersionDistribution'
+ TestCases = @($vdTestCases)
+ Properties = ([ordered]@{
+ testCategory = 'FleetVersionDistribution'
+ description = "Overall Fleet Update Status - cluster count and percentage per distinct CurrentVersion. SupportStatus uses the rolling 6-month YYMM window anchored on the latest released Azure Local solution version (supportSource='Microsoft manifest' or fleet-observed fallback)."
+ scope = $Scope
+ updateRing = [string]$UpdateRing
+ totalClusters = $totalTests
+ distinctVersions = $distinctVersions
+ mostCommonVersion = [string]$mostCommonVersion
+ mostCommonVersionPercentage = $mostCommonVersionPct
+ supportSource = $supportSource
+ latestReleasedYymm = $latestReleasedYymm
+ latestReleasedVersion = $latestReleasedVersion
+ manifestUrl = $manifestUrl
+ manifestFetchedAt = $manifestFetchedAt
+ supportedYymmWindow = $supportedYymmWindow
+ supportedClusters = $supportedCount
+ unsupportedClusters = $unsupportedCount
+ unknownVersionClusters = $unknownVersionCount
+ })
+ }
+
+ # Suite 2: AzureLocalFleetUpdateStatus - one testcase per cluster.
+ # Failed clusters first (alphabetical), then passed clusters (alphabetical).
+ $failedClusters = @()
+ $passedClusters = @()
+ foreach ($c in $readiness) {
+ if ($c.HealthState -eq 'Failure' -or ($c.UpdateState -in $failureStates) -or ($c.HasPrerequisiteUpdates -ne '' -and $null -ne $c.HasPrerequisiteUpdates)) {
+ $failedClusters += $c
+ }
+ else {
+ $passedClusters += $c
+ }
+ }
+ $orderedClusters = @($failedClusters | Sort-Object ClusterName) + @($passedClusters | Sort-Object ClusterName)
+ $fsTestCases = New-Object 'System.Collections.Generic.List[hashtable]'
+ foreach ($cluster in $orderedClusters) {
+ $isFail = $false
+ $failureType = ''
+ $failureMessage = ''
+ if ($cluster.HealthState -eq 'Failure' -or ($cluster.UpdateState -in $failureStates)) {
+ $isFail = $true
+ $failureType = if ($cluster.UpdateState -eq 'PreparationFailed') { 'PreparationFailed' } else { 'UpdateFailure' }
+ $failureMessage = "UpdateState: $($cluster.UpdateState), Health: $($cluster.HealthState)"
+ if ($cluster.HealthCheckFailures) { $failureMessage += ", Issues: $($cluster.HealthCheckFailures)" }
+ }
+ elseif ($cluster.HasPrerequisiteUpdates -ne '' -and $null -ne $cluster.HasPrerequisiteUpdates) {
+ $isFail = $true
+ $failureType = 'HasPrerequisite'
+ $failureMessage = "Updates blocked by SBE prerequisite: $($cluster.HasPrerequisiteUpdates)"
+ if ($cluster.SBEDependency) { $failureMessage += " - Vendor: $($cluster.SBEDependency)" }
+ }
+
+ $systemOut = @(
+ "Cluster: $($cluster.ClusterName)"
+ "Resource Group: $($cluster.ResourceGroup)"
+ "Subscription: $($cluster.SubscriptionId)"
+ "Update State: $($cluster.UpdateState)"
+ "Health State: $($cluster.HealthState)"
+ "Ready for Update: $($cluster.ReadyForUpdate)"
+ "All Available Updates: $($cluster.AllAvailableUpdates)"
+ "Ready Updates: $($cluster.ReadyUpdates)"
+ "Has Prerequisite Updates: $($cluster.HasPrerequisiteUpdates)"
+ "SBE Dependency: $($cluster.SBEDependency)"
+ "Recommended Update: $($cluster.RecommendedUpdate)"
+ ) -join "`n"
+
+ $clusterPortalUrl = if ($cluster.ResourceId) { "https://portal.azure.com/#@/resource$($cluster.ResourceId)" } else { '' }
+ $statusValue = if ($isFail) { $failureType } else { 'Success' }
+
+ $tc = @{
+ Name = "UpdateStatus-$($cluster.ClusterName)"
+ ClassName = "AzureLocalFleetUpdateStatus.$($cluster.ResourceGroup)"
+ Time = 0.0
+ Properties = ([ordered]@{
+ ClusterName = [string]$cluster.ClusterName
+ ClusterResourceId = [string]$cluster.ResourceId
+ UpdateName = [string]$cluster.RecommendedUpdate
+ Status = $statusValue
+ ClusterPortalUrl = $clusterPortalUrl
+ })
+ SystemOut = $systemOut
+ }
+ if ($isFail) {
+ $tc['Failure'] = @{ Message = 'Critical Health Status: Failed'; Type = $failureType; Body = $failureMessage }
+ }
+ $fsTestCases.Add($tc) | Out-Null
+ }
+ $fsSuite = @{
+ Name = 'AzureLocalFleetUpdateStatus'
+ ClassName = 'AzureLocalFleetUpdateStatus'
+ TestCases = @($fsTestCases)
+ Properties = ([ordered]@{
+ testCategory = 'CriticalHealthStatus'
+ description = "Each testcase = one cluster's Critical Health Status. PASSED = healthy + no failures + not SBE-blocked. FAILED = HealthState=Failure OR UpdateState in (Failed,UpdateFailed,NeedsAttention,PreparationFailed) OR SBE prerequisite blocked."
+ scope = $Scope
+ updateRing = [string]$UpdateRing
+ totalClusters = $totalTests
+ criticalHealthPassed = $criticalHealthPassed
+ criticalHealthFailed = $criticalHealthFailed
+ primaryUpdateFailed = $stUpdateFailed
+ primaryActionRequired = $stActionRequired
+ primaryHealthFailure = $stHealthFailure
+ primarySbeBlocked = $stSbeBlocked
+ primaryInProgress = $stInProgress
+ primaryReadyForUpdate = $stReadyForUpdate
+ primaryUpToDate = $stUpToDate
+ primaryNeedsInvestigation = $stOther
+ })
+ }
+
+ # Suite 3: Update Run History and Error Details
+ $rhTestCases = New-Object 'System.Collections.Generic.List[hashtable]'
+ foreach ($f in $runFailures) {
+ $rowSec = 0
+ if ($f.PSObject.Properties['DurationMinutes'] -and $null -ne $f.DurationMinutes) {
+ try { $rowSec = [int][math]::Round([double]$f.DurationMinutes * 60, 0) } catch { $rowSec = 0 }
+ if ($rowSec -lt 0) { $rowSec = 0 }
+ }
+ $errBody = if ($f.DeepestErrMsg) {
+ if ([string]$f.DeepestErrMsg.Length -gt 4000) { ([string]$f.DeepestErrMsg).Substring(0,4000) + ' ... (truncated)' } else { [string]$f.DeepestErrMsg }
+ } else { '(no error message captured)' }
+
+ $sysOutLines = @(
+ "Cluster: $($f.ClusterName)"
+ "Update: $($f.UpdateName)"
+ "Update State: Failed"
+ "Status: $($f.Status)"
+ "Current Step: $($f.CurrentStep)"
+ "Duration: $($f.Duration)"
+ "Time Started: $($f.StartTime)"
+ "Last Updated: $($f.LastUpdated)"
+ "Error Category: $($f.ErrorCategory)"
+ "Portal Link: $($f.UpdateRunPortalUrl)"
+ )
+ if ($f.StackTracePreview) { $sysOutLines += "Stack Trace Preview: $($f.StackTracePreview)" }
+
+ $fClusterPortal = if ($f.ClusterResourceId) { "https://portal.azure.com/#@/resource$($f.ClusterResourceId)" } else { '' }
+
+ $rhTestCases.Add(@{
+ Name = "$($f.ClusterName) - $($f.UpdateName)"
+ ClassName = 'UpdateRunHistory'
+ Time = [double]$rowSec
+ Properties = ([ordered]@{
+ ClusterName = [string]$f.ClusterName
+ ClusterResourceId = [string]$f.ClusterResourceId
+ UpdateName = [string]$f.UpdateName
+ Status = 'Failed'
+ UpdateState = [string]$f.Status
+ CurrentStep = [string]$f.CurrentStep
+ Duration = [string]$f.Duration
+ ErrorCategory = [string]$f.ErrorCategory
+ UpdateRunPortalUrl = [string]$f.UpdateRunPortalUrl
+ ClusterPortalUrl = $fClusterPortal
+ })
+ SystemOut = ($sysOutLines -join "`n")
+ Failure = @{
+ Message = "$($f.ClusterName) / $($f.UpdateName) failed at: $($f.CurrentStep)"
+ Type = [string]$f.ErrorCategory
+ Body = $errBody
+ }
+ }) | Out-Null
+ }
+ $rhSuite = @{
+ Name = "Update Run History and Error Details"
+ ClassName = 'UpdateRunHistory'
+ TestCases = @($rhTestCases)
+ Properties = ([ordered]@{
+ description = "Verbose error details for each unresolved Failed update run (ARG-first, fleet-scale)."
+ sourceCmdlet = "Get-AzLocalUpdateRunFailures -State Failed -OnlyUnresolved -Since (Get-Date).AddDays(-$RunHistorySinceDays)"
+ failedRunCount = $runHistoryCount
+ })
+ }
+
+ $null = New-AzLocalPipelineJUnitXml -TestSuitesName 'Fleet Update Status' -Suites @($vdSuite, $fsSuite, $rhSuite) -OutputPath $readinessXml -Timestamp $Now
+ Write-Host "JUnit XML saved to: $readinessXml" -ForegroundColor Green
+
+ # ---- Step 4: supplementary fleet-wide CSVs ----------------------------
+ $fleetResourceIds = if ($Scope -eq 'by-update-ring' -and $UpdateRing) {
+ @($readiness | Where-Object { $_.SubscriptionId -and $_.ResourceGroup -and $_.ClusterName } | ForEach-Object {
+ "/subscriptions/$($_.SubscriptionId)/resourceGroups/$($_.ResourceGroup)/providers/Microsoft.AzureStackHCI/clusters/$($_.ClusterName)"
+ })
+ }
+ else {
+ @($inventory | Select-Object -ExpandProperty ResourceId)
+ }
+
+ Write-Host ""
+ Write-Host "Step 4a: Collecting fleet update summaries..." -ForegroundColor Yellow
+ $summaries = Get-AzLocalUpdateSummary -ClusterResourceIds $fleetResourceIds -ExportPath $summariesCsv -PassThru
+ Write-Host "Update summaries collected for $(@($summaries).Count) cluster(s)" -ForegroundColor Green
+
+ Write-Host ""
+ Write-Host "Step 4b: Collecting available updates..." -ForegroundColor Yellow
+ $available = Get-AzLocalAvailableUpdates -ClusterResourceIds $fleetResourceIds -ExportPath $availableCsv -PassThru
+ Write-Host "Found $(@($available).Count) available update(s) across fleet" -ForegroundColor Green
+
+ if ($IncludeUpdateRuns) {
+ Write-Host ""
+ Write-Host "Step 4c: Collecting recent update run history..." -ForegroundColor Yellow
+ $allRuns = Get-AzLocalUpdateRuns -ClusterResourceIds $fleetResourceIds -Latest -ExportPath $runsCsv -PassThru
+ $allRunsCount = @($allRuns).Count
+ $succeeded = @($allRuns | Where-Object { $_.State -eq 'Succeeded' }).Count
+ $inProgressRuns = @($allRuns | Where-Object { $_.State -eq 'InProgress' }).Count
+ $failedRuns = @($allRuns | Where-Object { $_.State -eq 'Failed' }).Count
+ Write-Host "Update runs collected for $allRunsCount cluster(s)" -ForegroundColor Green
+ Write-Host " Succeeded: $succeeded, In Progress: $inProgressRuns, Failed: $failedRuns"
+ }
+
+ # ---- Step 5: console summary + step outputs ---------------------------
+ Write-Host ""
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Fleet Status Summary" -ForegroundColor Cyan
+ Write-Host "========================================" -ForegroundColor Cyan
+ Write-Host "Total Clusters: $totalTests"
+ Write-Host ""
+ Write-Host "Critical Health Status (matches JUnit XML pass/fail):" -ForegroundColor White
+ Write-Host " Passed: $criticalHealthPassed" -ForegroundColor Green
+ Write-Host " Failed: $criticalHealthFailed" -ForegroundColor $(if ($criticalHealthFailed -gt 0) { 'Red' } else { 'Green' })
+ Write-Host ""
+ Write-Host "Primary Status (each cluster counted once; rows sum to Total):" -ForegroundColor White
+ Write-Host " Up to Date: $stUpToDate" -ForegroundColor Green
+ Write-Host " Ready for Update: $stReadyForUpdate" -ForegroundColor Cyan
+ Write-Host " Update In Progress: $stInProgress" -ForegroundColor Yellow
+ Write-Host " SBE Prerequisite Blocked: $stSbeBlocked" -ForegroundColor $(if ($stSbeBlocked -gt 0) { 'Yellow' } else { 'Green' })
+ Write-Host " Health Failure: $stHealthFailure" -ForegroundColor $(if ($stHealthFailure -gt 0) { 'Red' } else { 'Green' })
+ Write-Host " Update Failed: $stUpdateFailed" -ForegroundColor $(if ($stUpdateFailed -gt 0) { 'Red' } else { 'Green' })
+ Write-Host " Action Required: $stActionRequired" -ForegroundColor $(if ($stActionRequired -gt 0) { 'Red' } else { 'Green' })
+ Write-Host " Needs Investigation: $stOther" -ForegroundColor $(if ($stOther -gt 0) { 'Yellow' } else { 'Green' })
+
+ Set-AzLocalPipelineOutput -Name 'total_clusters' -Value ([string]$totalTests)
+ Set-AzLocalPipelineOutput -Name 'critical_health_passed' -Value ([string]$criticalHealthPassed)
+ Set-AzLocalPipelineOutput -Name 'critical_health_failed' -Value ([string]$criticalHealthFailed)
+ Set-AzLocalPipelineOutput -Name 'up_to_date' -Value ([string]$stUpToDate)
+ Set-AzLocalPipelineOutput -Name 'in_progress' -Value ([string]$stInProgress)
+ Set-AzLocalPipelineOutput -Name 'ready' -Value ([string]$stReadyForUpdate)
+ Set-AzLocalPipelineOutput -Name 'sbe_blocked' -Value ([string]$stSbeBlocked)
+ Set-AzLocalPipelineOutput -Name 'health_failure' -Value ([string]$stHealthFailure)
+ Set-AzLocalPipelineOutput -Name 'update_failed' -Value ([string]$stUpdateFailed)
+ Set-AzLocalPipelineOutput -Name 'action_required' -Value ([string]$stActionRequired)
+ Set-AzLocalPipelineOutput -Name 'needs_investigation' -Value ([string]$stOther)
+ Set-AzLocalPipelineOutput -Name 'failures' -Value ([string]$criticalHealthFailed)
+ Set-AzLocalPipelineOutput -Name 'has_prerequisite' -Value ([string]$hasPrerequisite)
+ Set-AzLocalPipelineOutput -Name 'run_history_count' -Value ([string]$runHistoryCount)
+ Set-AzLocalPipelineOutput -Name 'version_dist_count' -Value ([string]$distinctVersions)
+ Set-AzLocalPipelineOutput -Name 'supported_yymm_window' -Value $supportedYymmWindow
+ Set-AzLocalPipelineOutput -Name 'supported_clusters' -Value ([string]$supportedCount)
+ Set-AzLocalPipelineOutput -Name 'unsupported_clusters' -Value ([string]$unsupportedCount)
+ Set-AzLocalPipelineOutput -Name 'unknown_version_clusters' -Value ([string]$unknownVersionCount)
+ Set-AzLocalPipelineOutput -Name 'support_source' -Value $supportSource
+ Set-AzLocalPipelineOutput -Name 'latest_released_yymm' -Value $latestReleasedYymm
+ Set-AzLocalPipelineOutput -Name 'latest_released_version' -Value $latestReleasedVersion
+
+ # ---- Step 6: render markdown summary ----------------------------------
+ $generatedUtc = $Now.ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss UTC')
+ $md = New-Object 'System.Collections.Generic.List[string]'
+ [void]$md.Add("## Fleet Update Status Summary _(generated $generatedUtc)_")
+ [void]$md.Add('')
+
+ # Version distribution table (YYMM-grouped, with support-status emoji)
+ if ($distinctVersions -gt 0) {
+ try {
+ $versionSection = @()
+ $versionSection += '### Fleet Version Distribution'
+ $versionSection += ''
+ $versionSection += "_$distinctVersions distinct version(s) across $totalTests cluster(s). Anchor source: ``$supportSource``"
+ if ($latestReleasedYymm) { $versionSection[-1] += ". Latest released YYMM (Microsoft manifest): ``$latestReleasedYymm`` (``$latestReleasedVersion``)" }
+ $versionSection[-1] += "._"
+ $versionSection += ''
+ $versionSection += '| YYMM | Update Versions | Support | Clusters | % | Cluster Names (first 15 shown only) |'
+ $versionSection += '|------|-----------------|---------|----------|---|--------------------------------------|'
+ $byYymm = $versionDistribution | Group-Object Yymm | Sort-Object @{Expression={ if ($_.Name) { $_.Name } else { '' } }; Descending=$true}
+ foreach ($g in $byYymm) {
+ $groupRows = @($g.Group | Sort-Object Count -Descending)
+ $totalCount = ($groupRows | Measure-Object Count -Sum).Sum
+ $totalPct = if ($totalTests -gt 0) { [math]::Round(($totalCount / $totalTests) * 100, 1) } else { 0 }
+ $yymmDisplay = if ($g.Name) { $g.Name } else { '_(unknown)_' }
+ $supportStatusForYymm = $groupRows[0].SupportStatus
+ $supportEmoji = switch ($supportStatusForYymm) {
+ 'Supported' { ':white_check_mark: Supported' }
+ 'Unsupported' { ':warning: Unsupported' }
+ default { ':grey_question: Unknown' }
+ }
+ $updateVersionsCell = (($groupRows | ForEach-Object { '{0} x {1}' -f $_.Version, $_.Count }) -join '
')
+ $clusterNames = @()
+ foreach ($r in $groupRows) {
+ if ($r.Clusters) {
+ $clusterNames += @($r.Clusters -split ',\s*' | Where-Object { $_ })
+ }
+ }
+ $clusterNames = @($clusterNames | Sort-Object -Unique)
+ $clCell = if ($clusterNames.Count -le 15) {
+ $clusterNames -join '; '
+ }
+ else {
+ (($clusterNames | Select-Object -First 15) -join '; ') + (' ... (+{0} more)' -f ($clusterNames.Count - 15))
+ }
+ $clCell = $clCell -replace '\|','\|'
+ $versionSection += ('| {0} | {1} | {2} | {3} | {4}% | {5} |' -f $yymmDisplay, $updateVersionsCell, $supportEmoji, $totalCount, $totalPct, $clCell)
+ }
+ $versionSection += ''
+ $versionSection += "_Support roll-up: Supported = $supportedCount cluster(s), Unsupported = $unsupportedCount, Unknown = $unknownVersionCount. Anchor source: ``$supportSource``._"
+ $versionSection += "_Note: the **Clusters (first 15 shown only)** column is intentionally truncated for readability. Download ``$ReadinessCsvFileName`` from artifacts to see the full cluster-name list._"
+ $versionSection += ''
+ foreach ($line in $versionSection) { [void]$md.Add($line) }
+ }
+ catch {
+ Write-Warning "Failed to render Fleet Version Distribution markdown table: $($_.Exception.Message)"
+ }
+ }
+
+ # Critical Health Status table
+ [void]$md.Add('### Critical Health Status (matches JUnit XML pass/fail)')
+ [void]$md.Add('')
+ [void]$md.Add('| Metric | Count | Status |')
+ [void]$md.Add('|--------|-------|--------|')
+ [void]$md.Add("| **Passed** (healthy, no failures, not SBE-blocked) | $criticalHealthPassed | :white_check_mark: |")
+ $chFailedIcon = if ($criticalHealthFailed -gt 0) { ':x:' } else { ':white_check_mark:' }
+ [void]$md.Add("| **Failed** (HealthState=Failure OR UpdateState=Failed OR SBE prerequisite blocked) | $criticalHealthFailed | $chFailedIcon |")
+ [void]$md.Add('')
+
+ # Primary Status table
+ [void]$md.Add('### Primary Status (each cluster counted once; rows sum to Total Clusters)')
+ [void]$md.Add('')
+ [void]$md.Add('| Metric | Count | Status |')
+ [void]$md.Add('|--------|-------|--------|')
+ [void]$md.Add("| **Total Clusters** | $totalTests | :information_source: |")
+ [void]$md.Add("| **Up to Date** | $stUpToDate | :white_check_mark: |")
+ [void]$md.Add("| **Ready for Update** | $stReadyForUpdate | :green_circle: |")
+ [void]$md.Add("| **Update In Progress** | $stInProgress | :arrows_counterclockwise: |")
+ $sbeIcon = if ($stSbeBlocked -gt 0) { ':yellow_circle:' } else { ':white_check_mark:' }
+ [void]$md.Add("| **SBE Prerequisite Blocked** | $stSbeBlocked | $sbeIcon |")
+ $hfIcon = if ($stHealthFailure -gt 0) { ':x:' } else { ':white_check_mark:' }
+ [void]$md.Add("| **Health Failure** (HealthState=Failure) | $stHealthFailure | $hfIcon |")
+ $ufIcon = if ($stUpdateFailed -gt 0) { ':x:' } else { ':white_check_mark:' }
+ [void]$md.Add("| **Update Failed** (Failed / UpdateFailed / NeedsAttention) | $stUpdateFailed | $ufIcon |")
+ $arIcon = if ($stActionRequired -gt 0) { ':x:' } else { ':white_check_mark:' }
+ [void]$md.Add("| **Action Required** (PreparationFailed) | $stActionRequired | $arIcon |")
+ $niIcon = if ($stOther -gt 0) { ':warning:' } else { ':white_check_mark:' }
+ [void]$md.Add("| **Needs Investigation** | $stOther | $niIcon |")
+ [void]$md.Add('')
+ [void]$md.Add('Priority cascade used to bucket each cluster exactly once:')
+ [void]$md.Add('Update Failed > Action Required > Health Failure > SBE Prerequisite Blocked > Update In Progress > Ready for Update > Up to Date > Needs Investigation.')
+ [void]$md.Add('')
+
+ # Actions Required bullet list
+ $actions = @()
+ if ($stUpdateFailed -gt 0) { $actions += "- **$stUpdateFailed cluster(s) have UpdateState in (Failed, UpdateFailed, NeedsAttention)** - Review the most recent update run in Azure Portal and the ``$RunsCsvFileName`` artifact for the failure detail." }
+ if ($stActionRequired -gt 0) { $actions += "- **$stActionRequired cluster(s) have UpdateState=PreparationFailed** - Update preparation hit a blocker before the run started. Inspect the cluster activity log (most common: prerequisite-check failure, missing SBE content, ARB extension drift). Resolve before re-arming the update." }
+ if ($stHealthFailure -gt 0) { $actions += "- **$stHealthFailure cluster(s) have HealthState=Failure** - Resolve critical health check issues in Azure Portal before retrying any updates." }
+ if ($hasPrerequisite -gt 0) { $actions += "- **$hasPrerequisite cluster(s) blocked by SBE prerequisite** - Install the required Solution Builder Extension (SBE) update from the hardware vendor. See ``$AvailableCsvFileName`` for vendor details (Publisher, Family)." }
+ if ($actions.Count -gt 0) {
+ [void]$md.Add('### Actions Required')
+ [void]$md.Add('')
+ foreach ($a in $actions) { [void]$md.Add($a) }
+ [void]$md.Add('')
+ }
+
+ # Update Run History collapsible-error table
+ if ($runHistoryCount -gt 0) {
+ try {
+ # v0.7.90 dedupe: collapse same-error reruns - group by
+ # (ClusterName, UpdateName, DeepestErrMsg); canonical row = latest StartTime.
+ $groups = @($runFailures) | Group-Object -Property @{
+ Expression = { "$($_.ClusterName)|$($_.UpdateName)|$($_.DeepestErrMsg)" }
+ }
+ $renderRows = @()
+ foreach ($g in $groups) {
+ $ordered = @($g.Group | Sort-Object @{ Expression = 'StartTime'; Descending = $true })
+ $latest = $ordered[0]
+ $extras = @($ordered | Select-Object -Skip 1)
+ $latest | Add-Member -NotePropertyName 'EarlierOccurrences' -NotePropertyValue $extras -Force
+ $renderRows += $latest
+ }
+ $renderRows = @($renderRows | Sort-Object @{Expression='StartTime';Descending=$true}, @{Expression='ClusterName';Descending=$false} | Select-Object -First $RunHistoryTopRows)
+ $totalRowsCnt = $runHistoryCount
+ $groupCount = $renderRows.Count
+ $dedupSuffix = if ($groupCount -lt $totalRowsCnt) {
+ " (collapsed $totalRowsCnt run(s) into $groupCount unique failure group(s); older same-error reruns are listed inside each row's 'Show error' panel)"
+ }
+ else { '' }
+ [void]$md.Add("### :scroll: Update Run History and Error Details")
+ [void]$md.Add('')
+ [void]$md.Add("_ARG-first, fleet-scale failure-detail view. Shows up to $RunHistoryTopRows most recent unresolved Failed update runs (last $RunHistorySinceDays days). Source cmdlet: ``Get-AzLocalUpdateRunFailures -State Failed -OnlyUnresolved``.$dedupSuffix._")
+ [void]$md.Add('')
+ [void]$md.Add('| Cluster Name | Update Name | Update State | Status | Current Step | Verbose Error Details | Duration | Time Started | Last Updated |')
+ [void]$md.Add('|---|---|---|---|---|---|---|---|---|')
+ foreach ($r in $renderRows) {
+ $errCell = if ($r.DeepestErrMsg) {
+ $e = [string]$r.DeepestErrMsg
+ $e = $e -replace '&','&' -replace '<','<' -replace '>','>'
+ $e = $e -replace "`r`n",'
' -replace "`n",'
' -replace '\|','\|'
+ $extraBlock = ''
+ if ($r.EarlierOccurrences -and @($r.EarlierOccurrences).Count -gt 0) {
+ $bullets = (@($r.EarlierOccurrences) | ForEach-Object {
+ $dur = if ($_.Duration) { " (Duration: $($_.Duration))" } else { '' }
+ "• Started $($_.StartTime), Last updated $($_.LastUpdated)$dur"
+ }) -join '
'
+ $extraBlock = '
Earlier occurrences with the same error (' + (@($r.EarlierOccurrences).Count) + '):
' + $bullets
+ }
+ 'Show error
' + $e + '' + $extraBlock + '
')
+
+ $severityScore = 0.0
+ if ($hasStepError) { $severityScore += 1000 }
+ if ($r.State -eq 'Failed') { $severityScore += 800 }
+ if ($runSeverity -eq 'skull') { $severityScore += 500 }
+ elseif ($runSeverity -eq 'crit') { $severityScore += 300 }
+ elseif ($runSeverity -eq 'warn') { $severityScore += 50 }
+ if ($stepSeverity -eq 'crit') { $severityScore += 200 }
+ elseif ($stepSeverity -eq 'warn') { $severityScore += 30 }
+ $elapsedHoursForScore = if ($elapsed) { $elapsed.TotalHours } else { 0 }
+ $severityScore += [math]::Round($elapsedHoursForScore / 24, 2)
+
+ $runDurationSeconds = 0
+ if ($r.State -ne 'InProgress' -and $startDt -and $endDt) {
+ $runDurationSeconds = [int][math]::Round(($endDt - $startDt).TotalSeconds, 0)
+ }
+ elseif ($elapsed) {
+ $runDurationSeconds = [int][math]::Round($elapsed.TotalSeconds, 0)
+ }
+ if ($runDurationSeconds -lt 0) { $runDurationSeconds = 0 }
+
+ [PSCustomObject]@{
+ ClusterName = $r.ClusterName
+ ClusterPortalUrl = $clusterPortalUrl
+ UpdateName = $r.UpdateName
+ UpdateRunPortalUrl = $updateRunPortalUrl
+ State = $r.State
+ Status = $progressStatus
+ CurrentStep = $r.CurrentStep
+ Progress = $r.Progress
+ StartTimeUtc = if ($startDt) { $startDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
+ EndTimeUtc = if ($endDt) { $endDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
+ ElapsedDisplay = $elapsedDisplay
+ ElapsedHours = if ($elapsed) { [math]::Round($elapsed.TotalHours, 2) } else { '' }
+ StepStartTimeUtc = if ($stepStartDt) { $stepStartDt.ToString('yyyy-MM-dd HH:mm') } else { '' }
+ StepElapsedDisplay = $stepElapsedDisplay
+ StepElapsedHours = $stepElapsedHoursVal
+ ExceedsThreshold = $exceeds
+ ExceedsStepThreshold = $exceedsStep
+ HasStepError = $hasStepError
+ IsRecentFailure = $isRecentFailure
+ IsUnresolvedFailure = $isUnresolvedFailure
+ ThresholdHours = $LongRunningThresholdHours
+ StepThresholdHours = $LongRunningStepHours
+ CriticalElapsedDays = $CriticalElapsedDays
+ StepSeverity = $stepSeverity
+ RunSeverity = $runSeverity
+ StateIcon = $stateIcon
+ StatusIcon = $statusIcon
+ Flags = $flagDisplay
+ SeverityScore = $severityScore
+ RunDurationSeconds = $runDurationSeconds
+ RunId = $r.RunId
+ RunResourceId = if ($r.PSObject.Properties['RunResourceId']) { $r.RunResourceId } else { '' }
+ ClusterResourceId = $r.ClusterResourceId
+ Duration = $r.Duration
+ CurrentStepDetail = $r.CurrentStepDetail
+ ErrorMessage = if ($r.PSObject.Properties['ErrorMessage']) { [string]$r.ErrorMessage } else { '' }
+ }
+ }
+ $rows = @($rows)
+
+ $inFlight = @($rows | Where-Object { $_.State -eq 'InProgress' })
+ $longRunning = @($inFlight | Where-Object { $_.ExceedsThreshold })
+ $longRunningStep = @($inFlight | Where-Object { $_.ExceedsStepThreshold })
+ $stepErrored = @($inFlight | Where-Object { $_.HasStepError })
+ $recentlyFailed = @($rows | Where-Object { $_.IsRecentFailure })
+ $unresolvedFailed = @($rows | Where-Object { $_.IsUnresolvedFailure })
+
+ # ---- CSV (always emit, even if empty) ---------------------------------
+ if ($rows.Count -gt 0) {
+ $rows | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName | Export-Csv -Path $monitorCsv -NoTypeInformation -Encoding utf8
+ }
+ else {
+ '' | Set-Content -LiteralPath $monitorCsv -Encoding utf8
+ }
+
+ # ---- JUnit XML via the shared emitter ---------------------------------
+ $testCases = New-Object 'System.Collections.Generic.List[hashtable]'
+ foreach ($r in ($inFlight | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName)) {
+ $safeName = ($r.ClusterName -replace '[^A-Za-z0-9_.-]', '_')
+ $caseName = "$safeName - $($r.UpdateName) - $($r.CurrentStep)"
+ if ($r.HasStepError) {
+ $errSnippet = if ($r.ErrorMessage) { $r.ErrorMessage } else { '(no errorMessage on deepest failed step)' }
+ $msg = ('Progress status is Error (state still InProgress) - step is stuck. CurrentStep: {0}. StepElapsed: {1}. ErrorMessage: {2}' -f $r.CurrentStep, $r.StepElapsedDisplay, $errSnippet)
+ $testCases.Add(@{
+ Name = $caseName
+ ClassName = 'UpdateMonitor'
+ Time = [double]$r.RunDurationSeconds
+ Failure = @{ Message = $msg; Type = 'StepError'; Body = $msg }
+ }) | Out-Null
+ }
+ elseif ($r.ExceedsStepThreshold) {
+ $msg = ('Current step elapsed {0} exceeds per-step threshold of {1}h. CurrentStep: {2}. Overall elapsed: {3}. Progress: {4}.' -f $r.StepElapsedDisplay, $r.StepThresholdHours, $r.CurrentStep, $r.ElapsedDisplay, $r.Progress)
+ $testCases.Add(@{
+ Name = $caseName
+ ClassName = 'UpdateMonitor'
+ Time = [double]$r.RunDurationSeconds
+ Failure = @{ Message = $msg; Type = 'LongRunningStep'; Body = $msg }
+ }) | Out-Null
+ }
+ elseif ($r.ExceedsThreshold) {
+ $msg = ('Overall elapsed {0} exceeds backstop threshold of {1}h (current step within {2}h per-step budget). CurrentStep: {3}. Progress: {4}.' -f $r.ElapsedDisplay, $r.ThresholdHours, $r.StepThresholdHours, $r.CurrentStep, $r.Progress)
+ $testCases.Add(@{
+ Name = $caseName
+ ClassName = 'UpdateMonitor'
+ Time = [double]$r.RunDurationSeconds
+ Failure = @{ Message = $msg; Type = 'LongRunningOverall'; Body = $msg }
+ }) | Out-Null
+ }
+ else {
+ $testCases.Add(@{
+ Name = $caseName
+ ClassName = 'UpdateMonitor'
+ Time = [double]$r.RunDurationSeconds
+ }) | Out-Null
+ }
+ }
+ foreach ($r in ($unresolvedFailed | Sort-Object @{Expression='EndTimeUtc';Descending=$true})) {
+ $safeName = ($r.ClusterName -replace '[^A-Za-z0-9_.-]', '_')
+ $caseName = "$safeName - $($r.UpdateName) - FAILED"
+ $detail = if ($r.ErrorMessage) { $r.ErrorMessage } elseif ($r.CurrentStepDetail) { $r.CurrentStepDetail } else { $r.CurrentStep }
+ $msg = ('Run failed at {0} UTC. Step: {1}. Detail: {2}.' -f $r.EndTimeUtc, $r.CurrentStep, $detail)
+ $testCases.Add(@{
+ Name = $caseName
+ ClassName = 'UpdateMonitor'
+ Time = [double]$r.RunDurationSeconds
+ Failure = @{ Message = $msg; Type = 'RecentFailure'; Body = $msg }
+ }) | Out-Null
+ }
+ $null = New-AzLocalPipelineJUnitXml -TestSuitesName 'Update Run Monitor' -Suites @(
+ @{
+ Name = 'Update Run Monitor'
+ ClassName = 'UpdateMonitor'
+ TestCases = @($testCases)
+ }
+ ) -OutputPath $monitorXml
+
+ # ---- Step outputs -----------------------------------------------------
+ Set-AzLocalPipelineOutput -Name 'in_flight' -Value ([string]$inFlight.Count)
+ Set-AzLocalPipelineOutput -Name 'long_running' -Value ([string]$longRunning.Count)
+ Set-AzLocalPipelineOutput -Name 'long_running_step' -Value ([string]$longRunningStep.Count)
+ Set-AzLocalPipelineOutput -Name 'step_errored' -Value ([string]$stepErrored.Count)
+ Set-AzLocalPipelineOutput -Name 'recent_failures' -Value ([string]$recentlyFailed.Count)
+ Set-AzLocalPipelineOutput -Name 'unresolved_failures' -Value ([string]$unresolvedFailed.Count)
+
+ # ---- Markdown step summary -------------------------------------------
+ $md = New-Object 'System.Collections.Generic.List[string]'
+ [void]$md.Add('## In-Flight Update Monitor')
+ [void]$md.Add('')
+ $skullCount = @($inFlight | Where-Object { $_.RunSeverity -eq 'skull' }).Count
+ $critRunCount = @($inFlight | Where-Object { $_.RunSeverity -eq 'crit' }).Count
+ $critStepCount = @($inFlight | Where-Object { $_.StepSeverity -eq 'crit' }).Count
+ $hasCritical = ($stepErrored.Count -gt 0) -or ($unresolvedFailed.Count -gt 0) -or ($skullCount -gt 0) -or ($critRunCount -gt 0) -or ($critStepCount -gt 0)
+ $warnCount = @($inFlight | Where-Object { $_.StepSeverity -eq 'warn' -or $_.RunSeverity -eq 'warn' }).Count
+ $hasWarn = ($warnCount -gt 0)
+ $statusBadge = if ($hasCritical) {
+ $crits = @()
+ if ($stepErrored.Count -gt 0) { $crits += "$($stepErrored.Count) stuck step error(s)" }
+ if ($skullCount -gt 0) { $crits += "$skullCount run(s) > $($CriticalElapsedDays * 2)d" }
+ if ($critRunCount -gt 0) { $crits += "$critRunCount run(s) > ${CriticalElapsedDays}d" }
+ if ($critStepCount -gt 0) { $crits += "$critStepCount step(s) > $($LongRunningStepHours * 2)h" }
+ if ($unresolvedFailed.Count -gt 0) { $crits += "$($unresolvedFailed.Count) unresolved failure(s)" }
+ ':red_circle: **Fleet Status: CRITICAL** - ' + ($crits -join ', ')
+ }
+ elseif ($hasWarn) {
+ ":yellow_circle: **Fleet Status: WARN** - $warnCount long-running run(s)"
+ }
+ elseif ($inFlight.Count -gt 0) {
+ ":green_circle: **Fleet Status: HEALTHY** - $($inFlight.Count) in-flight run(s) within all thresholds"
+ }
+ else {
+ ':white_circle: **Fleet Status: IDLE** - no update runs currently in flight'
+ }
+ [void]$md.Add($statusBadge)
+ [void]$md.Add('')
+ $scopeLabel = if ($Scope -eq 'by-update-ring' -and $UpdateRing) { "by-update-ring (UpdateRing = $UpdateRing)" } else { 'all clusters' }
+ [void]$md.Add("**Scope**: $scopeLabel - **Per-step warn/crit**: ${LongRunningStepHours}h / $($LongRunningStepHours * 2)h - **Overall warn/crit/skull**: ${LongRunningThresholdHours}h / ${CriticalElapsedDays}d / $($CriticalElapsedDays * 2)d - **Recent-failure window**: ${RecentFailureWindowHours}h - **Snapshot (UTC)**: $($nowUtc.ToString('yyyy-MM-dd HH:mm'))")
+ [void]$md.Add('')
+ [void]$md.Add('| Metric | Count |')
+ [void]$md.Add('|--------|-------|')
+ [void]$md.Add("| Clusters scoped | $($rows.Count) |")
+ [void]$md.Add("| Update runs in flight | $($inFlight.Count) |")
+ [void]$md.Add("| Step errored (progress.status == 'Error', state still InProgress) | $($stepErrored.Count) |")
+ [void]$md.Add("| Step elapsed > ${LongRunningStepHours}h (primary) | $($longRunningStep.Count) |")
+ [void]$md.Add("| Overall elapsed > ${LongRunningThresholdHours}h (backstop) | $($longRunning.Count) |")
+ [void]$md.Add("| Unresolved-failed runs (latest run is Failed) | $($unresolvedFailed.Count) |")
+ if ($RecentFailureWindowHours -gt 0) {
+ [void]$md.Add("| Recently-failed runs (last ${RecentFailureWindowHours}h) | $($recentlyFailed.Count) |")
+ }
+ [void]$md.Add('')
+ if ($inFlight.Count -gt 0) {
+ [void]$md.Add('### In-flight runs (sorted by severity score, worst first)')
+ [void]$md.Add('')
+ [void]$md.Add('| Cluster | Update | State | Progress Status | Current Step | Progress | Step Started (UTC) | Step Elapsed | Run Started (UTC) | Run Elapsed | Flags |')
+ [void]$md.Add('|---------|--------|-------|-----------------|--------------|----------|--------------------|--------------|-------------------|-------------|-------|')
+ foreach ($r in ($inFlight | Sort-Object @{Expression='SeverityScore';Descending=$true}, ClusterName)) {
+ $cs = if ($r.CurrentStep) { $r.CurrentStep } else { '-' }
+ $pg = if ($r.Progress) { $r.Progress } else { '-' }
+ $stepStart = if ($r.StepStartTimeUtc) { $r.StepStartTimeUtc } else { '-' }
+ $stateCell = if ($r.StateIcon) { "$($r.StateIcon) $($r.State)" } else { [string]$r.State }
+ $statusCell = if (-not $r.Status) { '-' }
+ elseif ($r.StatusIcon) { "$($r.StatusIcon) $($r.Status)" }
+ else { [string]$r.Status }
+ $stepElPrefix = switch ($r.StepSeverity) { 'crit' { ':rotating_light: ' } 'warn' { ':warning: ' } default { '' } }
+ $runElPrefix = switch ($r.RunSeverity) { 'skull' { ':skull: ' } 'crit' { ':rotating_light: ' } 'warn' { ':warning: ' } default { '' } }
+ $stepEl = if ($r.StepElapsedDisplay) { $stepElPrefix + $r.StepElapsedDisplay } else { '-' }
+ $runEl = if ($r.ElapsedDisplay) { $runElPrefix + $r.ElapsedDisplay } else { '-' }
+ $flagCell = if ($r.Flags) { $r.Flags } else { '-' }
+ $clusterCell = if ($r.ClusterPortalUrl) { '' + $r.ClusterName + '' } else { $r.ClusterName }
+ $updateCell = if ($r.UpdateRunPortalUrl) { '' + $r.UpdateName + '' } else { $r.UpdateName }
+ [void]$md.Add("| $clusterCell | $updateCell | $stateCell | $statusCell | $cs | $pg | $stepStart | $stepEl | $($r.StartTimeUtc) | $runEl | $flagCell |")
+ }
+ [void]$md.Add('')
+ }
+ else {
+ [void]$md.Add('### No update runs currently in flight')
+ [void]$md.Add('')
+ [void]$md.Add('No clusters in scope have a latest run in state `InProgress`. To verify scope, see the artifact CSV (`update-monitor.csv`).')
+ [void]$md.Add('')
+ }
+ if ($unresolvedFailed.Count -gt 0) {
+ [void]$md.Add('### Failed runs (latest run is Failed, unresolved - shown regardless of age)')
+ [void]$md.Add('')
+ [void]$md.Add('| Cluster | Update | Ended (UTC) | Failed Step | Verbose Error Details | Recent |')
+ [void]$md.Add('|---------|--------|-------------|-------------|-----------------------|--------|')
+ foreach ($r in ($unresolvedFailed | Sort-Object @{Expression='EndTimeUtc';Descending=$true})) {
+ $cs = if ($r.CurrentStep) { $r.CurrentStep } else { '-' }
+ $rawDetail = if ($r.ErrorMessage) { [string]$r.ErrorMessage } elseif ($r.CurrentStepDetail) { [string]$r.CurrentStepDetail } else { '' }
+ $detailCell = if ([string]::IsNullOrWhiteSpace($rawDetail)) { '_(no error detail)_' } else {
+ $e = $rawDetail -replace '&','&' -replace '<','<' -replace '>','>'
+ $e = $e -replace "`r`n",'
' -replace "`n",'
' -replace '\|','\|'
+ 'Show error
' + $e + 'Per-cluster results ({0} rows)
" -f $total))
+ [void]$sb.AppendLine('')
+ [void]$sb.AppendLine('| Cluster | Action | Previous | New | Status | Message |')
+ [void]$sb.AppendLine('|---------|--------|----------|-----|--------|---------|')
+ foreach ($r in $results) {
+ $cn = ([string]$r.ClusterName) -replace '\|','\|'
+ $act = ([string]$r.Action) -replace '\|','\|'
+ $pv = ([string]$r.PreviousTagValue) -replace '\|','\|'
+ $nv = ([string]$r.NewTagValue) -replace '\|','\|'
+ $st = ([string]$r.Status) -replace '\|','\|'
+ $msg = (([string]$r.Message) -replace '\|','\|') -replace '\r?\n',' '
+ [void]$sb.AppendLine(("| {0} | {1} | {2} | {3} | {4} | {5} |" -f $cn, $act, $pv, $nv, $st, $msg))
+ }
+ [void]$sb.AppendLine('')
+ [void]$sb.AppendLine('