v0.8.87: pipeline display-name rename (Config/Monitor/Update) + connectivity output + monitor ITSM

AzLocal.UpdateManagement/Automation-Pipeline-Examples/.itsm/azurelocal-itsm.yml

@@ -48,3 +48,21 @@ triggers:
     raiseTicket: false
   NotReady:
     raiseTicket: false
+
+  # ----- Update: 4 - Monitor In-Flight Updates statuses (v0.8.87) -----
+  # Emitted by Export-AzLocalUpdateRunMonitorReport in update-monitor.xml.
+  # Wire monitor-updates.yml with raise_itsm_ticket=true to open tickets for
+  # these. Dedupe key = SHA256(ClusterResourceId|UpdateName|TriggerCategory),
+  # so a stuck/attempt-gap cluster opens at most ONE incident until it clears.
+  AttemptWithoutRun:
+    raiseTicket: true
+    severity: 3
+    category: "Update attempt with no observable updateRun"   # UpdateLastAttempt tag set, but no updateRun materialised (commonly a URP package pre-install health-check failure)
+  StepError:
+    raiseTicket: true
+    severity: 2
+    category: "Update step stuck in error"                    # progress.status == Error while state is still InProgress
+  LongRunningOverall:
+    raiseTicket: false   # informational backstop; opt-in if you want a ticket per run exceeding the overall-elapsed threshold
+  LongRunningStep:
+    raiseTicket: false   # informational; opt-in if you want a ticket per run whose current step exceeds the per-step threshold

AzLocal.UpdateManagement/Automation-Pipeline-Examples/apply-updates-schedule.example.yml

@@ -27,7 +27,7 @@
 # A cron firing that lands on a day with NO matching schedule rows is
 # logged and exits 0 - no errors, no failures.
 #
-# This file is REQUIRED for the "Fleet: 04 - Apply Updates"
+# This file is REQUIRED for the "Update: 3 - Apply Updates"
 # (apply-updates.yml) pipeline when triggered by a schedule (not
 # workflow_dispatch). If the file is missing, apply-updates.yml throws
 # with the exact remediation command.

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/apply-updates-schedule-audit.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: apply-updates-schedule-audit
-# Config: 03 - Apply-Updates Schedule Coverage Audit Pipeline
+# Config: 3 - Apply-Updates Schedule Coverage Audit Pipeline
 # This pipeline runs the read-only Test-AzLocalApplyUpdatesScheduleCoverage advisor
 # weekly to detect drift between the cron schedule(s) in your apply-updates pipeline
 # YAML and the UpdateStartWindow tags that operators have placed on Azure Local clusters.
@@ -87,7 +87,7 @@ parameters:
     default: false
 
 variables:
-  GENERATED_AGAINST_MODULE_VERSION: '0.8.86'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.87'
   REQUIRED_MODULE_VERSION: '${{ parameters.moduleVersion }}'
   reportsPath: '$(Build.ArtifactStagingDirectory)/reports'
   # v0.8.7 sideload advisor defaults. Override at the pipeline / variable-group
@@ -98,7 +98,7 @@ variables:
 
 stages:
 - stage: ScheduleCoverage
-  displayName: 'Config: 03 - Audit Apply-Updates Schedule Coverage'
+  displayName: 'Config: 3 - Audit Apply-Updates Schedule Coverage'
   jobs:
   - job: Audit
     displayName: 'Run Schedule Coverage Advisor'

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/apply-updates.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: apply-updates
-# Fleet: 04 - Apply Updates to Azure Local Clusters
+# Update: 3 - Apply Updates to Azure Local Clusters
 # This pipeline applies updates to clusters filtered by UpdateRing tag value
 
 # Author guidance lives OUTSIDE the customise markers so module refreshes
@@ -129,7 +129,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.86'
+    value: '0.8.87'
   # 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).
@@ -252,7 +252,7 @@ stages:
 
   # Stage 2: Apply Updates (with approval gate for production)
   - stage: ApplyUpdates
-    displayName: 'Fleet: 04 - Apply Updates'
+    displayName: 'Update: 3 - Apply Updates'
     dependsOn: CheckReadiness
     condition: and(succeeded(), gt(dependencies.CheckReadiness.outputs['ReadinessCheck.readiness.ReadyCount'], 0))
 

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/assess-update-readiness.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: assess-update-readiness
-# Fleet: 01 - Assess Update Readiness (Pre-flight go/no-go gate)
+# Update: 1 - Assess Update Readiness (Pre-flight go/no-go gate)
 # --------------------------------------------------
 # Runs Get-AzLocalClusterUpdateReadiness and Test-AzLocalClusterHealth -BlockingOnly
 # against a target UpdateRing (or the whole fleet) BEFORE apply-updates.yml runs.
@@ -70,7 +70,7 @@ variables:
   # the version actually installed and to the latest on PSGallery, and emits a warning
   # log 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.86'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.87'
   # 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).
@@ -82,7 +82,7 @@ pool:
 
 stages:
   - stage: Assess
-    displayName: 'Fleet: 01 - Assess Update Readiness'
+    displayName: 'Update: 1 - Assess Update Readiness'
     jobs:
       - job: AssessReadiness
         displayName: 'Readiness + blocking health gate'

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/fleet-connectivity-status.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: fleet-connectivity-status
-# Fleet: 02 - Fleet Connectivity Status Monitoring Pipeline
+# Monitor: 1 - Fleet Connectivity Status Monitoring Pipeline
 # This pipeline surfaces network-connectivity issues across every Azure Local
 # cluster the service connection can read - four scopes in one pipeline:
 #
@@ -49,7 +49,7 @@
 
 # Pipeline display name carries the same Step.N - prefix as the filename so the
 # ADO pipelines list (sorts by `name:` field) lists pipelines in execution order.
-name: 'Fleet: 02 - Fleet Connectivity Status'
+name: 'Monitor: 1 - Fleet Connectivity Status'
 
 # BEGIN-AZLOCAL-CUSTOMIZE:schedule-triggers
 # Edits inside this block are preserved across Update-AzLocalPipelineExample
@@ -110,7 +110,7 @@ variables:
   # the version actually installed and to the latest on PSGallery, and emits a warning
   # log 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.86'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.87'
   # 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).

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/fleet-health-status.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: fleet-health-status
-# Fleet: 07 - Fleet Health Status Monitoring Pipeline
+# Monitor: 2 - Fleet Health Status Monitoring Pipeline
 # This pipeline surfaces 24-hour system health-check failures across every Azure Local
 # cluster the service connection can read - including clusters that are already
 # "up to date" with no available updates. The 24-hour health checks continue to run
@@ -105,7 +105,7 @@ variables:
   # the version actually installed and to the latest on PSGallery, and emits a warning
   # log 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.86'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.87'
   # 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).

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/fleet-update-status.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: fleet-update-status
-# Fleet: 06 - Fleet Update Status Monitoring Pipeline
+# Monitor: 3 - Fleet Update Status Monitoring Pipeline
 # This pipeline monitors update status across all Azure Local clusters and generates reports
 #
 # USE CASES:
@@ -93,7 +93,7 @@ variables:
   # the version actually installed and to the latest on PSGallery, and emits a warning
   # log 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.86'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.87'
   # 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).

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/manage-updatering-tags.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: manage-updatering-tags
-# Config: 02 - Manage UpdateRing Tags
+# Config: 2 - Manage UpdateRing Tags
 # This pipeline creates or updates UpdateRing tags on Azure Local clusters from a CSV file
 #
 # WORKFLOW:
@@ -46,7 +46,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.86'
+    value: '0.8.87'
   # 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).
@@ -58,7 +58,7 @@ pool:
 
 stages:
   - stage: ManageTags
-    displayName: 'Config: 02 - Manage UpdateRing Tags'
+    displayName: 'Config: 2 - Manage UpdateRing Tags'
     jobs:
       - job: ApplyTags
         displayName: 'Apply UpdateRing Tags'

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/monitor-updates.yml

@@ -1,5 +1,5 @@
 # AZLOCAL-PIPELINE-ID: monitor-updates
-# Fleet: 05 - Monitor In-Flight Updates (Azure DevOps)
+# Update: 4 - Monitor In-Flight Updates (Azure DevOps)
 # -----------------------------------------------------------
 # Reports clusters whose latest update run is currently in flight, with the
 # CURRENT STEP each cluster is on and the ELAPSED DURATION of the run. Built
@@ -83,10 +83,54 @@ parameters:
     type: string
     default: ''
 
+  # --- ITSM Connector (ServiceNow auto-raise on in-flight monitor failures) ---
+  # Set raiseItsmTicket=true to open ServiceNow incidents (v0.8.87) from each
+  # stuck-step / failed / attempt-without-run cluster surfaced in
+  # update-monitor.xml. Default false so existing schedules stay byte-identical
+  # until you opt in. The connector reads the JUnit file this pipeline already
+  # produces (update-monitor.xml) and the trigger matrix in
+  # ./.itsm/azurelocal-itsm.yml (defaults raise AttemptWithoutRun / StepError /
+  # Failed; LongRunningStep / LongRunningOverall are opt-in).
+  - name: raiseItsmTicket
+    displayName: 'Open ITSM tickets (ServiceNow) for in-flight monitor failures'
+    type: boolean
+    default: false
+
+  - name: itsmConfigPath
+    displayName: 'Path to ITSM matrix config (YAML or JSON)'
+    type: string
+    default: './.itsm/azurelocal-itsm.yml'
+
+  - name: itsmDryRun
+    displayName: 'ITSM: build payloads + run read-only dedupe but do NOT create tickets'
+    type: boolean
+    default: false
+
+  - name: itsmForceCreate
+    displayName: 'ITSM: bypass dedupe and always create new tickets (use with caution)'
+    type: boolean
+    default: false
+
 variables:
-  GENERATED_AGAINST_MODULE_VERSION: '0.8.86'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.87'
   REQUIRED_MODULE_VERSION: '${{ parameters.moduleVersion }}'
   reportsPath: '$(Build.ArtifactStagingDirectory)/reports'
+  # ITSM connector. When raiseItsmTicket=true the Raise ITSM task below
+  # references $(ITSM_SN_INSTANCE_URL), $(ITSM_SN_CLIENT_ID),
+  # $(ITSM_SN_CLIENT_SECRET). The simplest binding is an ADO variable group
+  # named 'AzureLocal-ITSM-Secrets'. ADO does not allow mixing mapping-form
+  # variables with '- group:' entries in the same block, so to enable the
+  # group reference convert this entire 'variables:' block to list form:
+  #   variables:
+  #     - name: GENERATED_AGAINST_MODULE_VERSION
+  #       value: '0.8.87'
+  #     - name: REQUIRED_MODULE_VERSION
+  #       value: '${{ parameters.moduleVersion }}'
+  #     - name: reportsPath
+  #       value: '$(Build.ArtifactStagingDirectory)/reports'
+  #     - group: AzureLocal-ITSM-Secrets
+  # When raiseItsmTicket=false the Raise ITSM task is skipped and the secrets
+  # are not consulted, so the conversion is only required for opt-in users.
 
 stages:
 - stage: MonitorInFlight
@@ -187,3 +231,103 @@ stages:
         testRunTitle: 'In-Flight Update Monitor'
         mergeTestResults: false
         failTaskOnFailedTests: false
+
+    # ----------------------------------------------------------------------
+    # ITSM Connector (ServiceNow auto-raise on in-flight monitor failures)
+    #
+    # Fully opt-in (gated on parameters.raiseItsmTicket == true). Runs AFTER
+    # the JUnit file is published, so the ITSM task is strictly additive -
+    # failures here never affect the monitor result (which is always green;
+    # this is a report-only pipeline). Reads the same update-monitor.xml that
+    # powers the summary. The JUnit emitter writes per-testcase <properties>
+    # (ClusterName / ClusterResourceId / UpdateName / Status / CurrentStep /
+    # ClusterPortalUrl / UpdateRunPortalUrl) so New-AzLocalIncident can compute
+    # the SHA256 dedupe key (one incident per stuck/failed/attempt-gap cluster
+    # until it clears) and the Mustache body template can deep-link into the
+    # Azure portal.
+    # ----------------------------------------------------------------------
+    - task: PowerShell@2
+      displayName: 'Install powershell-yaml (ITSM config parser)'
+      condition: and(succeeded(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
+      inputs:
+        targetType: 'inline'
+        pwsh: true
+        script: |
+          if (-not (Get-Module -ListAvailable -Name powershell-yaml)) {
+              Install-Module powershell-yaml -Scope CurrentUser -Force -AllowClobber
+          }
+
+    - task: AzureCLI@2
+      displayName: 'Raise ITSM tickets'
+      name: itsm
+      condition: and(succeeded(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
+      env:
+        # BEGIN-AZLOCAL-CUSTOMIZE:itsm-secrets
+        # Bind your ITSM connector secrets from the variable group above.
+        # Defaults assume the ServiceNow OAuth client_credentials naming used
+        # by azurelocal-itsm.yml (env://ITSM_SN_*). If your secret names differ,
+        # update them here - this block is preserved by
+        # Update-AzLocalPipelineExample across module upgrades.
+        ITSM_SN_INSTANCE_URL: $(ITSM_SN_INSTANCE_URL)
+        ITSM_SN_CLIENT_ID: $(ITSM_SN_CLIENT_ID)
+        ITSM_SN_CLIENT_SECRET: $(ITSM_SN_CLIENT_SECRET)
+        # END-AZLOCAL-CUSTOMIZE:itsm-secrets
+      inputs:
+        azureSubscription: 'AzureLocal-ServiceConnection'  # Update with your service connection name
+        scriptType: 'pscore'
+        scriptLocation: 'inlineScript'
+        inlineScript: |
+          Import-Module AzLocal.UpdateManagement -Force
+
+          $configPath = "${{ parameters.itsmConfigPath }}"
+          $dryRun     = [System.Convert]::ToBoolean("${{ parameters.itsmDryRun }}")
+          $force      = [System.Convert]::ToBoolean("${{ parameters.itsmForceCreate }}")
+
+          if (-not (Test-Path $configPath)) {
+              Write-Host "##vso[task.logissue type=warning]ITSM config not found at '$configPath' - skipping ticket creation."
+              exit 0
+          }
+
+          $cfg = Get-AzLocalItsmConfig -Path $configPath
+
+          $junitInput = "$(reportsPath)/update-monitor.xml"
+          if (-not (Test-Path $junitInput)) {
+              Write-Host "##vso[task.logissue type=warning]No update-monitor.xml found at '$junitInput' - skipping ticket creation."
+              exit 0
+          }
+
+          $params = @{
+              InputArtifactPath = $junitInput
+              Config            = $cfg
+              RunMetadata       = @{
+                  Platform = 'azure-devops'
+                  RunId    = $env:BUILD_BUILDID
+                  RunUrl   = "$($env:SYSTEM_COLLECTIONURI)$($env:SYSTEM_TEAMPROJECT)/_build/results?buildId=$($env:BUILD_BUILDID)"
+                  Branch   = $env:BUILD_SOURCEBRANCH
+              }
+              DryRun            = $dryRun
+              ForceCreate       = $force
+              ExportPath        = "$(reportsPath)/itsm-results.csv"
+              ExportJUnitPath   = "$(reportsPath)/itsm-results.xml"
+          }
+
+          $results = New-AzLocalIncident @params
+          $results | Format-Table ClusterName, Action, TicketId, Severity -AutoSize
+
+    - task: PublishBuildArtifacts@1
+      displayName: 'Publish ITSM Artefacts'
+      condition: and(always(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
+      inputs:
+        PathtoPublish: '$(reportsPath)'
+        ArtifactName: 'azlocal-step.8-update-monitor-itsm-results_$(stamp.artifactStamp)'
+        publishLocation: 'Container'
+      continueOnError: true
+
+    - task: PublishTestResults@2
+      displayName: 'Publish ITSM Test Results'
+      condition: and(always(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
+      inputs:
+        testResultsFormat: 'JUnit'
+        testResultsFiles: '$(reportsPath)/itsm-results.xml'
+        testRunTitle: 'ITSM Tickets (Update: 4 Monitor) - $(Build.BuildNumber)'
+        failTaskOnFailedTests: false