AzLocal.UpdateManagement v0.8.7 - on-prem solution-update sideloading automation (5 new cmdlets, Step.6 pipeline, de-numbered filenames)

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

@@ -5,7 +5,7 @@
 # This is the single source of truth for "which UpdateRing(s) is/are
 # eligible to apply updates on a given UTC date". It is consumed by:
 #
-#   * Step.6_apply-updates.yml    - reads it at every cron firing and
+#   * Step.7_apply-updates.yml    - reads it at every cron firing and
 #                                   resolves the UpdateRingValue (and,
 #                                   schema v2+, the AllowedUpdateVersions
 #                                   allow-list) to use for that run.
@@ -59,13 +59,13 @@ cycleAnchorYear:      2026
 
 # ---- AllowedUpdateVersions (schema v2, MANDATORY top-level) -------
 # >>> ALLOWED-UPDATE-VERSIONS-V2 <<<
-# Fleet-wide allow-list of Azure Local update identifiers that Step.6
+# Fleet-wide allow-list of Azure Local update identifiers that Step.7
 # (apply-updates) is permitted to install.
 #
 # Default 'Latest' (case-insensitive) is a reserved sentinel meaning
 # 'no constraint - install the latest Ready update on each cluster'
 # (the historic v0.7.88 default). Leave it as 'Latest' to keep that
-# behaviour. When set to an explicit list, Step.6 only installs
+# behaviour. When set to an explicit list, Step.7 only installs
 # updates whose `name` OR `properties.version` is an EXACT
 # (case-insensitive) match for one of the entries. If a cluster has
 # no Ready update that matches, that cluster is SKIPPED with status
@@ -98,7 +98,7 @@ cycleAnchorYear:      2026
 # customer ask in v0.7.89): install ONLY the YY04 + YY10 feature
 # updates plus the cumulative updates immediately preceding each
 # feature update (YY03 + YY09). With v2 schema you list those four
-# update names here once and Step.6 ignores every other 'Ready'
+# update names here once and Step.7 ignores every other 'Ready'
 # update. Example using real Azure Local update names:
 #   allowedUpdateVersions: 'Solution12.2603.1002.15;Solution12.2604.1003.1005;Solution12.2609.1002.XX;Solution12.2610.1003.XX'
 #

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.3_apply-updates-schedule-audit.yml → AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/apply-updates-schedule-audit.yml

@@ -1,17 +1,18 @@
+# AZLOCAL-PIPELINE-ID: apply-updates-schedule-audit
 # Step.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.
 #
 # WHY THIS PIPELINE EXISTS
 # ------------------------
-# Step.6_apply-updates.yml ships with NO default schedule (trigger:none) on purpose, so
+# Step.7_apply-updates.yml ships with NO default schedule (trigger:none) on purpose, so
 # customers must consciously choose when updates fire. After you have configured
-# UpdateStartWindow tags on your clusters and added cron entries to Step.6_apply-updates.yml, this
+# UpdateStartWindow tags on your clusters and added cron entries to Step.7_apply-updates.yml, this
 # pipeline is the safety net that catches:
-#   - a new ring tagged with UpdateStartWindow that no cron in Step.6_apply-updates.yml will reach
+#   - a new ring tagged with UpdateStartWindow that no cron in Step.7_apply-updates.yml will reach
 #   - an UpdateStartWindow tag value that fails to parse (typo / wrong syntax)
-#   - Step.6_apply-updates.yml cron entries that the advisor cannot reason about
+#   - Step.7_apply-updates.yml cron entries that the advisor cannot reason about
 #     (DayOfMonth restrictions, step values) so you can audit them manually
 #
 # REPORTS GENERATED:
@@ -43,14 +44,14 @@ schedules:
 
 parameters:
   - name: pipelinePath
-    displayName: 'Path (file or folder) to Step.6_apply-updates.yml to audit, repo-relative. REQUIRED so the Recommend view can diff its proposed crons against what is already present in Step.6 and only emit a snippet for the truly missing entries. Default `.azure-pipelines` matches the standard Azure DevOps consumer layout; for repos that keep Step.6_apply-updates.yml at the repo root pass `.`'
+    displayName: 'Path (file or folder) to Step.7_apply-updates.yml to audit, repo-relative. REQUIRED so the Recommend view can diff its proposed crons against what is already present in Step.7 and only emit a snippet for the truly missing entries. Default `.azure-pipelines` matches the standard Azure DevOps consumer layout; for repos that keep Step.7_apply-updates.yml at the repo root pass `.`'
     type: string
     default: '.azure-pipelines'
 
   - name: schedulePath
     displayName: 'Path to apply-updates-schedule.yml. When set, the audit also reports RingMissingFromSchedule (fleet ring with no schedule row) and RingOrphanedInSchedule (schedule ring no cluster carries). Leave empty to skip the schedule-file two-way diff.'
     type: string
-    default: './apply-updates-schedule.yml'
+    default: './config/apply-updates-schedule.yml'
 
   - name: leadTimeMinutes
     displayName: 'Minutes before UpdateStartWindow opens that the pipeline should fire (0-60)'
@@ -86,9 +87,14 @@ parameters:
     default: false
 
 variables:
-  GENERATED_AGAINST_MODULE_VERSION: '0.8.6'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.7'
   REQUIRED_MODULE_VERSION: '${{ parameters.moduleVersion }}'
   reportsPath: '$(Build.ArtifactStagingDirectory)/reports'
+  # v0.8.7 sideload advisor defaults. Override at the pipeline / variable-group
+  # level (set SIDELOAD_UPDATES=true to enable the recommended-sideload-schedule
+  # section). Defaults keep the audit byte-identical to v0.8.6 when unset.
+  SIDELOAD_UPDATES: 'false'
+  SIDELOAD_LEAD_DAYS: '7'
 
 stages:
 - stage: ScheduleCoverage
@@ -156,6 +162,10 @@ stages:
         INPUT_DEBUG:             ${{ lower(parameters.debug) }}
         INSTALLED_MODULE_VERSION: $(moduleVersion.installed_module_version)
         REPORTS_PATH: $(reportsPath)
+        # v0.8.7 sideload advisor (opt-in). When SIDELOAD_UPDATES=true the audit
+        # appends a "Recommended sideload schedule" section. Inert when unset/false.
+        SIDELOAD_UPDATES: $(SIDELOAD_UPDATES)
+        SIDELOAD_LEAD_DAYS: $(SIDELOAD_LEAD_DAYS)
       inputs:
         # Replace with your service connection name
         azureSubscription: 'AzureLocal-ServiceConnection'  # Update with your service connection name

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.6_apply-updates.yml → AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/apply-updates.yml

@@ -1,9 +1,10 @@
-# Step.6 - Apply Updates to Azure Local Clusters
+# AZLOCAL-PIPELINE-ID: apply-updates
+# Step.7 - Apply Updates to Azure Local Clusters
 # This pipeline applies updates to clusters filtered by UpdateRing tag value
 
 # BEGIN-AZLOCAL-CUSTOMIZE:schedule-triggers
 # PREFERRED PATTERN - drive automated update runs from a ring-aware
-# schedule file (apply-updates-schedule.yml at the repo root by default),
+# schedule file (config/apply-updates-schedule.yml by default),
 # not from per-window crons.
 #
 # How it works:
@@ -20,7 +21,7 @@
 #      New-AzLocalApplyUpdatesScheduleConfig.
 #
 # Generate a STRAWMAN schedule file from your fleet via:
-#   New-AzLocalApplyUpdatesScheduleConfig -OutputPath .\apply-updates-schedule.yml
+#   New-AzLocalApplyUpdatesScheduleConfig -OutputPath .\config\apply-updates-schedule.yml
 # Every row is commented out by default - review and uncomment to activate.
 #
 # Concurrency: ADO has no first-class YAML concurrency block; use Pipeline
@@ -114,18 +115,20 @@ 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.6'
+    value: '0.8.7'
   # 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).
   - name: REQUIRED_MODULE_VERSION
     value: '${{ parameters.moduleVersion }}'
   # Path to the ring-aware apply-updates-schedule.yml (relative to repo
   # root). The 'Resolve UpdateRing from schedule' task reads this file when
-  # $(Build.Reason)='Schedule'. Override at queue time if you keep the schedule
-  # outside the repo root.
+  # $(Build.Reason)='Schedule'. Default 'config/apply-updates-schedule.yml'
+  # matches where Copy-AzLocalPipelineExample drops the starter, alongside
+  # config/ClusterUpdateRings.csv. Override at queue time if you keep the
+  # schedule elsewhere.
   - name: APPLY_UPDATES_SCHEDULE_PATH
-    value: './apply-updates-schedule.yml'
+    value: './config/apply-updates-schedule.yml'
   # ITSM connector. Uncomment the group reference once you
   # have created a variable group named 'AzureLocal-ITSM-Secrets' containing:
   #   ITSM_SN_INSTANCE_URL, ITSM_SN_CLIENT_ID, ITSM_SN_CLIENT_SECRET
@@ -230,7 +233,7 @@ stages:
             displayName: 'Publish Readiness Report'
             inputs:
               PathtoPublish: '$(Build.ArtifactStagingDirectory)'
-              ArtifactName: 'azlocal-step.6-apply-updates-readiness-report_$(stamp.artifactStamp)'
+              ArtifactName: 'azlocal-step.7-apply-updates-readiness-report_$(stamp.artifactStamp)'
               publishLocation: 'Container'
 
   # Stage 2: Apply Updates (with approval gate for production)
@@ -324,7 +327,7 @@ stages:
               source: 'current'
               # artifact name now carries a UTC timestamp - rebuild via the
               # readinessArtifactStamp variable mapped from the CheckReadiness stage.
-              artifact: 'azlocal-step.6-apply-updates-readiness-report_$(readinessArtifactStamp)'
+              artifact: 'azlocal-step.7-apply-updates-readiness-report_$(readinessArtifactStamp)'
               path: '$(Build.ArtifactStagingDirectory)'
 
           # v0.8.5 thin-YAML - readiness-gated apply via shared helper. Validates
@@ -379,7 +382,7 @@ stages:
             displayName: 'Publish Update Logs'
             inputs:
               PathtoPublish: '$(Build.ArtifactStagingDirectory)'
-              ArtifactName: 'azlocal-step.6-apply-updates-logs_$(stamp.artifactStamp)'
+              ArtifactName: 'azlocal-step.7-apply-updates-logs_$(stamp.artifactStamp)'
               publishLocation: 'Container'
 
           - task: PublishTestResults@2
@@ -447,7 +450,7 @@ stages:
             condition: and(always(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
             inputs:
               PathtoPublish: '$(Build.ArtifactStagingDirectory)'
-              ArtifactName: 'azlocal-step.6-apply-updates-itsm-results_$(stamp.artifactStamp)'
+              ArtifactName: 'azlocal-step.7-apply-updates-itsm-results_$(stamp.artifactStamp)'
               publishLocation: 'Container'
             continueOnError: true
 

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.5_assess-update-readiness.yml → AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/assess-update-readiness.yml

@@ -1,7 +1,8 @@
+# AZLOCAL-PIPELINE-ID: assess-update-readiness
 # Step.5 - 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 Step.6_apply-updates.yml runs.
+# against a target UpdateRing (or the whole fleet) BEFORE Step.7_apply-updates.yml runs.
 #
 # Publishes two JUnit XML diagnostic results to the Azure DevOps Tests tab:
 #   - readiness.xml       (one test per cluster; fails if ReadyForUpdate = $false)
@@ -14,7 +15,7 @@
 # does NOT block downstream runs. In large fleets, day-to-day environmental issues
 # (transient storage noise, a single node out, etc.) routinely affect a small subset of
 # clusters; blocking the entire wave for one unhealthy cluster is rarely the desired
-# behavior. Step.6_apply-updates.yml is itself per-cluster scoped, so clusters that are not
+# behavior. Step.7_apply-updates.yml is itself per-cluster scoped, so clusters that are not
 # ready will simply no-op there too.
 #
 # If you want a hard pass/fail signal for a chained gate, read the output variables
@@ -69,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.6'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.7'
   # 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/Step.0_authentication-test.yml → AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/authentication-test.yml

@@ -1,3 +1,4 @@
+# AZLOCAL-PIPELINE-ID: authentication-test
 # Step.0 - Authentication Validation and Subscription Scope Report
 #
 # PURPOSE:
@@ -59,7 +60,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.6'
+    value: '0.8.7'
   # 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/Step.4_fleet-connectivity-status.yml → AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/fleet-connectivity-status.yml

@@ -1,3 +1,4 @@
+# AZLOCAL-PIPELINE-ID: fleet-connectivity-status
 # Step.4 - 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:
@@ -12,7 +13,7 @@
 # - Find clusters where Arc agent or ARB has dropped off and updates / management calls will fail
 # - Catch Disconnected physical NICs that still have a real IP (likely cable / driver / port issues -
 #   Disconnected adapters with no IP or APIPA self-assignment are intentionally excluded as noise)
-# - Triage hand-off into ITSM (wired identically to Step.8 / Step.9 - opt-in via parameter)
+# - Triage hand-off into ITSM (wired identically to Step.9 / Step.10 - opt-in via parameter)
 #
 # REPORTS GENERATED:
 # - Pipeline run summary (uploaded via ##vso[task.uploadsummary]): one section per
@@ -56,7 +57,7 @@ name: Step.4 - Fleet Connectivity Status
 trigger: none  # Manual or scheduled only
 
 schedules:
-  # Daily at 05:30 UTC - offset 30 min ahead of Step.8 (06:00) and Step.9 (07:00)
+  # Daily at 05:30 UTC - offset 30 min ahead of Step.9 (06:00) and Step.10 (07:00)
   # so the three fleet-scope read pipelines stagger their ARG calls.
   - cron: '30 5 * * *'
     displayName: 'Daily Fleet Connectivity Check'
@@ -109,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.6'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.7'
   # 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).
@@ -121,7 +122,7 @@ variables:
   # 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 (see
-  # Step.9 for the conversion recipe). When raiseItsmTicket=false the Raise
+  # Step.10 for the conversion recipe). When raiseItsmTicket=false the Raise
   # ITSM task is skipped and the secrets are not consulted.
 
 stages:
@@ -228,7 +229,7 @@ stages:
     # ----------------------------------------------------------------------
     # ITSM Connector (ServiceNow auto-raise on connectivity failures)
     # Opt-in (gated on parameters.raiseItsmTicket == true). Mirrors the
-    # Step.8 / Step.9 wiring - reads the JUnit file produced above, uses
+    # Step.9 / Step.10 wiring - reads the JUnit file produced above, uses
     # the same azurelocal-itsm.yml trigger matrix, same dedupe key.
     # ----------------------------------------------------------------------
     - task: PowerShell@2

AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/Step.9_fleet-health-status.yml → AzLocal.UpdateManagement/Automation-Pipeline-Examples/azure-devops/fleet-health-status.yml

@@ -1,4 +1,5 @@
-# Step.9 - Fleet Health Status Monitoring Pipeline
+# AZLOCAL-PIPELINE-ID: fleet-health-status
+# Step.10 - 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
@@ -104,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.6'
+  GENERATED_AGAINST_MODULE_VERSION: '0.8.7'
   # 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).
@@ -217,7 +218,7 @@ stages:
       condition: always()
       inputs:
         PathtoPublish: '$(reportsPath)'
-        ArtifactName: 'azlocal-step.9-fleet-health-status-report_$(stamp.artifactStamp)'
+        ArtifactName: 'azlocal-step.10-fleet-health-status-report_$(stamp.artifactStamp)'
         publishLocation: 'Container'
 
     # Publish JUnit test results LAST so the Test Results tab is populated but the
@@ -321,7 +322,7 @@ stages:
       condition: and(always(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
       inputs:
         PathtoPublish: '$(reportsPath)'
-        ArtifactName: 'azlocal-step.9-fleet-health-status-itsm-results_$(stamp.artifactStamp)'
+        ArtifactName: 'azlocal-step.10-fleet-health-status-itsm-results_$(stamp.artifactStamp)'
         publishLocation: 'Container'
       continueOnError: true
 
@@ -331,5 +332,5 @@ stages:
       inputs:
         testResultsFormat: 'JUnit'
         testResultsFiles: '$(reportsPath)/itsm-results.xml'
-        testRunTitle: 'ITSM Tickets (Step.9) - $(Build.BuildNumber)'
+        testRunTitle: 'ITSM Tickets (Step.10) - $(Build.BuildNumber)'
         failTaskOnFailedTests: false