apply-updates.yml

# AZLOCAL-PIPELINE-ID: apply-updates
# Step.07 - 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
# (Update-AzLocalPipelineExample) can correct it; only the trigger directive
# between the markers is preserved verbatim across module upgrades.
#
# PREFERRED PATTERN - drive automated update runs from a ring-aware
# schedule file (config/apply-updates-schedule.yml by default),
# not from per-window crons.
#
# How it works:
#   1. The 'Resolve UpdateRing from schedule' task in the CheckReadiness stage
#      checks $(Build.Reason). If 'Manual' / 'IndividualCI' etc. the operator's
#      manual `updateRing` parameter is used verbatim (back-compat).
#   2. If $(Build.Reason) is 'Schedule', the task reads apply-updates-schedule.yml,
#      computes the current (cycleWeek, dayOfWeek) tuple in UTC, and returns
#      the eligible UpdateRing tag value(s) for THIS firing.
#   3. If no schedule row matches today, ReadyCount=0 and the ApplyUpdates
#      stage is skipped cleanly (exit 0, no errors).
#   4. If the schedule file is MISSING and $(Build.Reason)='Schedule', the
#      resolver hard-fails with a remediation pointing at
#      New-AzLocalApplyUpdatesScheduleConfig.
#
# Generate a STRAWMAN schedule file from your fleet via:
#   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
# Settings -> Triggers -> 'Limit concurrent runs' (or Environment 'Approvals
# and checks' -> 'Exclusive lock') to ensure only one apply-updates run is
# active per environment at a time.
#
# Recommended schedule: once per day at a low-traffic time (the resolver is
# day-grain; firing more often is wasteful but harmless thanks to readiness
# idempotency). Example - 06:00 UTC every day:
#   schedules:
#     - cron: '0 6 * * *'
#       displayName: 'Daily ring-aware apply-updates'
#       branches:
#         include: [main]
#       always: true
#
# Replace `trigger: none` between the BEGIN/END markers below with your
# schedules: block. That region (and ONLY that region) is preserved verbatim
# by Update-AzLocalPipelineExample across module upgrades.
# BEGIN-AZLOCAL-CUSTOMIZE:schedule-triggers
trigger: none
# END-AZLOCAL-CUSTOMIZE:schedule-triggers

parameters:
  - name: updateRing
    # accepts a single ring (Wave1), a semicolon-delimited list (Prod;Ring2),
    # or '***' (three stars - deliberate, not a typo) to match every cluster that HAS the UpdateRing tag set.
    # The 'values:' enum was removed in to allow these new forms; type=string
    # still gives users a free-text editor in the ADO run dialog.
    # v0.8.5: ignored when useScheduleFile=true (the resolver reads the schedule file instead).
    displayName: "UpdateRing tag value (single 'Wave1', list 'Prod;Ring2', or '***' for ALL). Ignored when useScheduleFile=true."
    type: string
    default: 'Wave1'

  # v0.8.5 - manual override that runs the ring/AllowedUpdateVersions resolver against
  # apply-updates-schedule.yml exactly as a scheduled firing would. Use this 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 via the
  # resolveForDateUtc parameter below.
  - name: useScheduleFile
    displayName: 'Resolve UpdateRing & AllowedUpdateVersions from apply-updates-schedule.yml (as a scheduled run would). Overrides updateRing.'
    type: boolean
    default: false

  - name: resolveForDateUtc
    displayName: 'Only used when useScheduleFile=true. Date (UTC, YYYY-MM-DD) to resolve the schedule for. Empty = today UTC. Useful for previewing a future cycleWeek/dayOfWeek.'
    type: string
    default: ''

  - name: updateName
    displayName: 'Specific update version (leave empty for latest ready update)'
    type: string
    default: ''
  
  - name: dryRun
    displayName: 'Preview which clusters would be updated (WhatIf mode)'
    type: boolean
    default: true

  # v0.8.79 break-glass override. Only honoured when $(Build.Reason) -eq 'Manual'
  # (operator-initiated queue from the Azure DevOps UI / CLI). Schedule-triggered
  # runs deliberately ignore this flag even if a YAML edit ever sets the default
  # to true - the apply step rechecks $(Build.Reason) at runtime.
  - name: forceImmediateUpdate
    displayName: 'WARNING: FORCE IMMEDIATE UPDATE - bypass UpdateStartWindow / UpdateExclusionsWindow tags and apply updates immediately. Break-glass override for emergency / out-of-window patching. MANUAL QUEUE ONLY - schedule-triggered runs ignore this flag.'
    type: boolean
    default: false

  # --- ITSM Connector (ServiceNow) ---
  # Opt-in ticket creation. Defaults preserve the previous pipeline behaviour
  # (no ITSM calls). Secrets are wired via the variable group referenced below
  # in the Raise ITSM tickets step (`env:`), never on the PowerShell command line.
  - name: raiseItsmTicket
    displayName: 'Open ITSM tickets (ServiceNow) for clusters needing manual action'
    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

  - name: moduleVersion
    displayName: 'Pin AzLocal.UpdateManagement version (empty = latest from PSGallery). See Automation-Pipeline-Examples/README.md section 5 "Optional configuration".'
    type: string
    default: ''

variables:
  # Module version this YAML was generated against. The install step compares this to
  # 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.
  - name: GENERATED_AGAINST_MODULE_VERSION
    value: '0.8.80'
  # 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'. 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: './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
  # When raiseItsmTicket=false the Raise ITSM step is skipped and these
  # variables are not required.
  # - group: AzureLocal-ITSM-Secrets

pool:
  vmImage: 'windows-latest'

stages:
  # Stage 1: Check Readiness
  - stage: CheckReadiness
    displayName: 'Check Update Readiness'
    jobs:
      - job: ReadinessCheck
        displayName: 'Assess Cluster Readiness'

        steps:
          - checkout: self
            displayName: 'Checkout Repository'

          - task: AzureCLI@2
            displayName: 'Install Resource Graph Extension'
            inputs:
              azureSubscription: 'AzureLocal-ServiceConnection'  # Update with your service connection name
              scriptType: 'pscore'
              scriptLocation: 'inlineScript'
              inlineScript: |
                az extension add --name resource-graph --yes

          # v0.8.5 thin-YAML - install + drift detection + version banner via shared helper.
          - task: PowerShell@2
            displayName: 'Install AzLocal.UpdateManagement from PSGallery'
            env:
              REQUIRED_MODULE_VERSION: $(REQUIRED_MODULE_VERSION)
              GENERATED_AGAINST_MODULE_VERSION: $(GENERATED_AGAINST_MODULE_VERSION)
            inputs:
              targetType: 'inline'
              pwsh: true
              script: |
                $ErrorActionPreference = 'Stop'
                $installArgs = @{ Name = 'AzLocal.UpdateManagement'; Scope = 'CurrentUser'; Force = $true; AllowClobber = $true }
                if ($env:REQUIRED_MODULE_VERSION) { $installArgs.RequiredVersion = $env:REQUIRED_MODULE_VERSION }
                Install-Module @installArgs
                Import-Module AzLocal.UpdateManagement -Force
                Add-AzLocalPipelineVersionBanner -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION

          # v0.8.5 thin-YAML - Resolve UpdateRing (+ AllowedUpdateVersions) from
          # schedule file (or pass manual input through verbatim). Emits two task
          # output variables (resolveRing.RESOLVED_UPDATE_RING /
          # resolveRing.RESOLVED_ALLOWED_UPDATE_VERSIONS) for stageDependencies binding.
          - task: PowerShell@2
            displayName: 'Resolve UpdateRing from schedule'
            name: resolveRing
            env:
              MANUAL_UPDATE_RING: ${{ parameters.updateRing }}
              USE_SCHEDULE_FILE: ${{ parameters.useScheduleFile }}
              RESOLVE_FOR_DATE_UTC: ${{ parameters.resolveForDateUtc }}
              APPLY_UPDATES_SCHEDULE_PATH: $(APPLY_UPDATES_SCHEDULE_PATH)
              BUILD_REASON: $(Build.Reason)
            inputs:
              targetType: 'inline'
              pwsh: true
              script: |
                Import-Module AzLocal.UpdateManagement -Force
                $params = @{ ManualUpdateRing = $env:MANUAL_UPDATE_RING; ResolveForDateUtc = $env:RESOLVE_FOR_DATE_UTC }
                if ($env:USE_SCHEDULE_FILE -eq 'True' -or $env:USE_SCHEDULE_FILE -eq 'true') { $params['UseScheduleFile'] = $true }
                Resolve-AzLocalPipelineUpdateRing @params

          # v0.8.5 thin-YAML - readiness gate query + step outputs (PascalCase
          # on ADO so stageDependencies binding works) + per-cluster markdown
          # summary uploaded as stage Build Summary.
          - task: AzureCLI@2
            displayName: 'Check Cluster Readiness'
            name: readiness
            env:
              # resolved by the upstream 'Resolve UpdateRing from
              # schedule' task. For Manual/IndividualCI runs this is the
              # operator's parameter input verbatim; for Schedule firings it
              # is the ring(s) the resolver picked from
              # apply-updates-schedule.yml.
              RESOLVED_UPDATE_RING: $(resolveRing.RESOLVED_UPDATE_RING)
            inputs:
              azureSubscription: 'AzureLocal-ServiceConnection'  # Update with your service connection name
              scriptType: 'pscore'
              scriptLocation: 'inlineScript'
              inlineScript: |
                Import-Module AzLocal.UpdateManagement -Force
                Export-AzLocalClusterReadinessGateReport -UpdateRing $env:RESOLVED_UPDATE_RING -OutputDirectory "$(Build.ArtifactStagingDirectory)"

          # compute a UTC timestamp variable so every downloadable artifact name is unique per run.
          - pwsh: |
              $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd_HHmmss')
              Write-Host "##vso[task.setvariable variable=artifactStamp;isOutput=true]$stamp"
              Write-Host "Artifact timestamp: $stamp"
            displayName: 'Compute Artifact Timestamp'
            condition: always()
            name: stamp

          - task: PublishBuildArtifacts@1
            displayName: 'Publish Readiness Report'
            inputs:
              PathtoPublish: '$(Build.ArtifactStagingDirectory)'
              ArtifactName: 'azlocal-step.7-apply-updates-readiness-report_$(stamp.artifactStamp)'
              publishLocation: 'Container'

  # Stage 2: Apply Updates (with approval gate for production)
  - stage: ApplyUpdates
    displayName: 'Apply Updates'
    dependsOn: CheckReadiness
    condition: and(succeeded(), gt(dependencies.CheckReadiness.outputs['ReadinessCheck.readiness.ReadyCount'], 0))

    # Optional: Add environment with approval for production rings
    # Uncomment the following lines to enable manual approval
    # variables:
    #   - name: environment
    #     ${{ if eq(parameters.updateRing, 'Production') }}:
    #       value: 'Production'
    #     ${{ else }}:
    #       value: 'Development'

    jobs:
      # Optional: Manual validation job for production
      # - job: WaitForApproval
      #   displayName: 'Wait for Approval'
      #   condition: eq('${{ parameters.updateRing }}', 'Production')
      #   pool: server
      #   steps:
      #     - task: ManualValidation@0
      #       inputs:
      #         notifyUsers: 'your-approvers-email@company.com'
      #         instructions: 'Please review the readiness report and approve to proceed with Production updates.'

      - job: ApplyClusterUpdates
        displayName: 'Apply Cluster Updates'
        # dependsOn: WaitForApproval
        # condition: or(ne('${{ parameters.updateRing }}', 'Production'), succeeded('WaitForApproval'))

        variables:
          readyCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.ReadyCount'] ]
          totalCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.TotalCount'] ]
          # v0.8.78: surface the readiness gate's Up-to-Date / Not-Ready breakdown
          # in the apply-updates summary so the operator sees the FULL ring picture
          # (not just the clusters that entered Apply Updates). Up-to-Date is a
          # healthy steady state; Not-Ready includes clusters held back by a
          # previously-failed run (state=NeedsAttention / UpdateFailed), an
          # in-progress run, pending SBE prerequisites or a critical health failure.
          upToDateCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.UpToDateCount'] ]
          notReadyCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.NotReadyCount'] ]
          # pull the upstream artifact-stamp through so the download step
          # can reconstruct the timestamped artifact name produced by CheckReadiness.
          readinessArtifactStamp: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['stamp.artifactStamp'] ]
          # ring(s) resolved by the upstream 'Resolve UpdateRing from
          # schedule' task. For Manual/IndividualCI etc. this is the operator's
          # parameter input verbatim; for Schedule firings this is the ring(s)
          # the resolver picked from apply-updates-schedule.yml.
          resolvedUpdateRing: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['resolveRing.RESOLVED_UPDATE_RING'] ]
          # v0.7.89: ';'-joined allow-list resolved from apply-updates-schedule.yml
          # schema-v2 'allowedUpdateVersions' field. Empty when build was not a
          # Schedule firing or when no allow-list is configured.
          resolvedAllowedUpdateVersions: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['resolveRing.RESOLVED_ALLOWED_UPDATE_VERSIONS'] ]

        steps:
          - checkout: self
            displayName: 'Checkout Repository'

          - task: AzureCLI@2
            displayName: 'Install Resource Graph Extension'
            inputs:
              azureSubscription: 'AzureLocal-ServiceConnection'  # Update with your service connection name
              scriptType: 'pscore'
              scriptLocation: 'inlineScript'
              inlineScript: |
                az extension add --name resource-graph --yes

          # v0.8.5 thin-YAML - apply-updates stage re-installs the module (each
          # agent run is fresh). The version-banner upload is deliberately
          # skipped here (already emitted by the CheckReadiness install step)
          # to avoid duplicating the banner in the rendered run summary.
          - task: PowerShell@2
            displayName: 'Install AzLocal.UpdateManagement from PSGallery'
            env:
              REQUIRED_MODULE_VERSION: $(REQUIRED_MODULE_VERSION)
            inputs:
              targetType: 'inline'
              pwsh: true
              script: |
                $ErrorActionPreference = 'Stop'
                $installArgs = @{ Name = 'AzLocal.UpdateManagement'; Scope = 'CurrentUser'; Force = $true; AllowClobber = $true }
                if ($env:REQUIRED_MODULE_VERSION) { $installArgs.RequiredVersion = $env:REQUIRED_MODULE_VERSION }
                Install-Module @installArgs
                Import-Module AzLocal.UpdateManagement -Force
                $installed = (Get-Module AzLocal.UpdateManagement | Sort-Object Version -Descending | Select-Object -First 1).Version
                Write-Host "Installed AzLocal.UpdateManagement v$installed on ApplyUpdates stage agent."

          # Download the readiness CSV produced by the CheckReadiness stage
          # so the apply step operates on the readiness gate's decision rather than
          # re-discovering clusters by tag. Apply still re-validates each cluster
          # (defence in depth) - this just enforces the upstream gate exactly.
          - task: DownloadPipelineArtifact@2
            displayName: 'Download Readiness Report'
            inputs:
              source: 'current'
              # artifact name now carries a UTC timestamp - rebuild via the
              # readinessArtifactStamp variable mapped from the CheckReadiness stage.
              artifact: 'azlocal-step.7-apply-updates-readiness-report_$(readinessArtifactStamp)'
              path: '$(Build.ArtifactStagingDirectory)'

          # v0.8.5 thin-YAML - readiness-gated apply via shared helper. Validates
          # CSV (requires ClusterResourceId column, v0.7.62+), fans out to
          # Start-AzLocalClusterUpdate, emits 7 PascalCase task output variables
          # (Succeeded, Skipped, Failed, HealthBlocked, ScheduleBlocked,
          # SideloadedBlocked, ExcludedByTag) for stageDependencies / summary
          # binding, and writes apply-results.json next to update-results.xml.
          - task: AzureCLI@2
            displayName: 'Apply Updates'
            name: applyUpdates
            env:
              # resolved by the CheckReadiness stage's resolveRing
              # task (manual parameter for Manual/IndividualCI runs, schedule-
              # resolved ring for Schedule firings).
              RESOLVED_UPDATE_RING: $(resolvedUpdateRing)
              # v0.7.89: ';'-joined allow-list resolved from
              # apply-updates-schedule.yml schema-v2 'allowedUpdateVersions'
              # field. Empty for non-Schedule firings or when no allow-list
              # is configured. When non-empty, Start-AzLocalClusterUpdate
              # filters Ready updates to only those whose 'name' OR
              # 'properties.version' is an EXACT (case-insensitive) match;
              # clusters with no matching Ready update are skipped with
              # status 'NotInAllowList'.
              RESOLVED_ALLOWED_UPDATE_VERSIONS: $(resolvedAllowedUpdateVersions)
              # v0.8.79 break-glass override - parameter value + Build.Reason guard.
              # The runtime check below collapses force=true on Schedule/CI runs to
              # force=false so the override only ever takes effect on a Manual queue.
              FORCE_IMMEDIATE_UPDATE_PARAM: ${{ parameters.forceImmediateUpdate }}
              BUILD_REASON: $(Build.Reason)
            inputs:
              azureSubscription: 'AzureLocal-ServiceConnection'  # Update with your service connection name
              scriptType: 'pscore'
              scriptLocation: 'inlineScript'
              inlineScript: |
                Import-Module AzLocal.UpdateManagement -Force
                $params = @{
                    ReadinessCsvPath      = "$(Build.ArtifactStagingDirectory)/readiness-report.csv"
                    UpdateRing            = $env:RESOLVED_UPDATE_RING
                    UpdateName            = "${{ parameters.updateName }}"
                    AllowedUpdateVersions = $env:RESOLVED_ALLOWED_UPDATE_VERSIONS
                    OutputDirectory       = "$(Build.ArtifactStagingDirectory)"
                }
                if ([System.Convert]::ToBoolean("${{ parameters.dryRun }}")) { $params['DryRun'] = $true }
                if ($env:FORCE_IMMEDIATE_UPDATE_PARAM -eq 'True') {
                    if ($env:BUILD_REASON -eq 'Manual') {
                        $params['ForceImmediateUpdate'] = $true
                    }
                    else {
                        Write-Host "##vso[task.logissue type=warning]forceImmediateUpdate=True ignored: Build.Reason='$env:BUILD_REASON' (override is honoured only for Manual queue runs)."
                    }
                }
                Invoke-AzLocalReadinessGatedClusterUpdate @params

          # compute a UTC timestamp variable so both update-logs and itsm-results share a unique per-run suffix.
          - pwsh: |
              $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd_HHmmss')
              Write-Host "##vso[task.setvariable variable=artifactStamp;isOutput=true]$stamp"
              Write-Host "Artifact timestamp: $stamp"
            displayName: 'Compute Artifact Timestamp'
            condition: always()
            name: stamp

          - task: PublishBuildArtifacts@1
            displayName: 'Publish Update Logs'
            inputs:
              PathtoPublish: '$(Build.ArtifactStagingDirectory)'
              ArtifactName: 'azlocal-step.7-apply-updates-logs_$(stamp.artifactStamp)'
              publishLocation: 'Container'

          - task: PublishTestResults@2
            displayName: 'Publish Update JUnit Diagnostics'
            condition: always()
            inputs:
              testResultsFormat: 'JUnit'
              testResultsFiles: '$(Build.ArtifactStagingDirectory)/update-results.xml'
              testRunTitle: '[JUnit Debug] Azure Local Cluster Updates - ${{ parameters.updateRing }}'

          # --------------------------------------------------------------
          # ITSM Connector (ServiceNow)
          # Fully opt-in. Runs AFTER PublishTestResults so the apply stage
          # surfaces its own results first; ITSM is strictly additive.
          # Secrets must be wired via the 'AzureLocal-ITSM-Secrets' variable
          # group at the top of this file (uncomment when ready).
          # --------------------------------------------------------------
          - 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
                }

          # v0.8.5 thin-YAML - ITSM ticketing via Invoke-AzLocalItsmTicketingFromArtifact.
          # Wrapper auto-populates RunMetadata from ADO env vars and short-circuits
          # if ConfigPath or InputArtifactPath are missing (same behaviour as the
          # prior inline block).
          - 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
                $params = @{
                    ConfigPath        = "${{ parameters.itsmConfigPath }}"
                    InputArtifactPath = "$(Build.ArtifactStagingDirectory)/update-results.xml"
                    ExportDirectory   = "$(Build.ArtifactStagingDirectory)"
                }
                if ([System.Convert]::ToBoolean("${{ parameters.itsmDryRun }}"))      { $params['DryRun']      = $true }
                if ([System.Convert]::ToBoolean("${{ parameters.itsmForceCreate }}")) { $params['ForceCreate'] = $true }
                Invoke-AzLocalItsmTicketingFromArtifact @params

          - task: PublishBuildArtifacts@1
            displayName: 'Publish ITSM Artefacts'
            condition: and(always(), eq('${{ parameters.raiseItsmTicket }}', 'true'))
            inputs:
              PathtoPublish: '$(Build.ArtifactStagingDirectory)'
              ArtifactName: 'azlocal-step.7-apply-updates-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: '$(Build.ArtifactStagingDirectory)/itsm-results.xml'
              testRunTitle: 'ITSM Tickets - ${{ parameters.updateRing }}'
              failTaskOnFailedTests: false

          # v0.8.5 thin-YAML - Update Application Summary via shared helper.
          # Reads apply-results.json + readiness-report.csv from the artifact
          # staging directory and renders the readiness KPI table, results KPI
          # table, cluster-actions table, skipped-at-readiness-gate table, and
          # Actions Required bullets. ADO icon style = GitHub-Markdown shortcodes.
          - task: PowerShell@2
            displayName: 'Generate Summary'
            env:
              RESOLVED_UPDATE_RING: $(resolvedUpdateRing)
            inputs:
              targetType: 'inline'
              pwsh: true
              script: |
                Import-Module AzLocal.UpdateManagement -Force
                $params = @{
                    UpdateRing           = $env:RESOLVED_UPDATE_RING
                    TotalCount           = "$(totalCount)"
                    ReadyCount           = "$(readyCount)"
                    # v0.8.78: pass the readiness gate's Up-to-Date / Not-Ready breakdown
                    # so the Readiness KPI surfaces the FULL ring picture, not just the
                    # clusters that entered Apply Updates.
                    UpToDateCount        = "$(upToDateCount)"
                    NotReadyCount        = "$(notReadyCount)"
                    Succeeded            = "$(applyUpdates.Succeeded)"
                    Skipped              = "$(applyUpdates.Skipped)"
                    Failed               = "$(applyUpdates.Failed)"
                    HealthBlocked        = "$(applyUpdates.HealthBlocked)"
                    ScheduleBlocked      = "$(applyUpdates.ScheduleBlocked)"
                    SideloadedBlocked    = "$(applyUpdates.SideloadedBlocked)"
                    ExcludedByTag        = "$(applyUpdates.ExcludedByTag)"
                    ApplyResultsJsonPath = "$(Build.ArtifactStagingDirectory)/apply-results.json"
                    ReadinessCsvPath     = "$(Build.ArtifactStagingDirectory)/readiness-report.csv"
                }
                if ([System.Convert]::ToBoolean("${{ parameters.dryRun }}")) { $params['DryRun'] = $true }
                Add-AzLocalApplyUpdatesStepSummary @params

  # Stage 3: Handle no ready clusters
  - stage: NoClustersReady
    displayName: 'No Clusters Ready'
    dependsOn: CheckReadiness
    condition: and(succeeded(), eq(dependencies.CheckReadiness.outputs['ReadinessCheck.readiness.ReadyCount'], 0))

    jobs:
      - job: ReportNoReadyClusters
        displayName: 'Report Status'

        variables:
          totalCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.TotalCount'] ]
          # v0.8.74: Up-to-Date vs Not-Ready breakdown so the summary can
          # explain WHY there is nothing to apply (already-patched clusters are
          # a healthy steady state, not a failure).
          upToDateCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.UpToDateCount'] ]
          notReadyCount: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['readiness.NotReadyCount'] ]
          # report the resolved ring (not the raw parameter input) so
          # scheduled runs surface the actual ring the resolver picked.
          resolvedUpdateRing: $[ stageDependencies.CheckReadiness.ReadinessCheck.outputs['resolveRing.RESOLVED_UPDATE_RING'] ]

        steps:
          # Module install is required so the no-clusters-ready summary helper is
          # available on this stage's agent.
          - task: PowerShell@2
            displayName: 'Install AzLocal.UpdateManagement from PSGallery'
            env:
              REQUIRED_MODULE_VERSION: $(REQUIRED_MODULE_VERSION)
            inputs:
              targetType: 'inline'
              pwsh: true
              script: |
                $ErrorActionPreference = 'Stop'
                $installArgs = @{ Name = 'AzLocal.UpdateManagement'; Scope = 'CurrentUser'; Force = $true; AllowClobber = $true }
                if ($env:REQUIRED_MODULE_VERSION) { $installArgs.RequiredVersion = $env:REQUIRED_MODULE_VERSION }
                Install-Module @installArgs
                Import-Module AzLocal.UpdateManagement -Force

          # v0.8.5 thin-YAML - No-clusters-ready summary via shared helper.
          - task: PowerShell@2
            displayName: 'Generate Report'
            env:
              RESOLVED_UPDATE_RING: $(resolvedUpdateRing)
            inputs:
              targetType: 'inline'
              pwsh: true
              script: |
                Import-Module AzLocal.UpdateManagement -Force
                Add-AzLocalNoReadyClustersStepSummary -UpdateRing $env:RESOLVED_UPDATE_RING -TotalCount "$(totalCount)" -UpToDateCount "$(upToDateCount)" -NotReadyCount "$(notReadyCount)"