fleet-update-status.yml

# AZLOCAL-PIPELINE-ID: fleet-update-status
# Fleet Update Status Monitoring
# This workflow monitors update status across all Azure Local clusters and generates reports
#
# USE CASES:
# - Daily/weekly health checks on cluster update status
# - Executive dashboards showing fleet-wide update adoption
# - Alerting when clusters have update failures
# - Compliance tracking for update deployments
#
# REPORTS GENERATED:
# - JUnit XML: Shows each cluster as a test case (passed/failed/skipped) for CI/CD visualization
#   (testcase bodies now include `Start Time:` and `End Time:` lines per cluster).
# - CSV: Detailed export for spreadsheet analysis (includes `EndTime` column sourced
#   from properties.progress.endTimeUtc, with fallback to properties.lastUpdatedTime - blank for InProgress runs).
# - HTML report (Recent Update Run History section): includes `End Time` column for the
#   aggregated multi-attempt row.
# - JSON: Machine-readable format for custom integrations
#
# AUTHENTICATION:
# Uses OpenID Connect (OIDC) - recommended for secretless authentication
# See: https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect

# Workflow name carries the same Step.N - prefix as the filename so the GitHub
# Actions sidebar (which sorts workflows alphabetically by this `name:` field)
# lists the eight pipelines in execution order.
name: Step.9 - Fleet Update Status

on:
  # BEGIN-AZLOCAL-CUSTOMIZE:schedule-triggers
  # Edits inside this block are preserved across Update-AzLocalPipelineExample
  # module upgrades. Add or modify `schedule:` cron blocks below.
  # Run on schedule (e.g., daily at 6 AM UTC)
  schedule:
    - cron: '0 6 * * *'  # Daily at 6:00 AM UTC
  # END-AZLOCAL-CUSTOMIZE:schedule-triggers

  # Manual trigger with options
  workflow_dispatch:
    inputs:
      scope:
        description: 'Scope of clusters to check'
        required: true
        default: 'all'
        type: choice
        options:
          - 'all'              # All clusters across all subscriptions
          - 'by-update-ring'   # Filter by UpdateRing tag
      update_ring:
        # 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.
        description: "UpdateRing tag value (only used when scope=by-update-ring). Single ring, 'Prod;Ring2', or '***'."
        required: false
        default: ''
      include_update_runs:
        description: 'Include recent update run history in report'
        required: false
        default: 'true'
        type: choice
        options:
          - 'true'
          - 'false'
      module_version:
        description: 'Pin AzLocal.UpdateManagement version (empty = latest from PSGallery). See Automation-Pipeline-Examples/README.md section 5 "Optional configuration".'
        required: false
        default: ''
      # --- ITSM Connector (ServiceNow auto-raise on fleet-update-status) ---
      # Set raise_itsm_ticket=true to open ServiceNow incidents from each unresolved
      # Failed update run reported by the '📜 Update Run History and Error Details'
      # testsuite (and any failed AzureLocalFleetUpdateStatus row). Default is false
      # so existing schedules stay byte-identical until you opt in. The connector reads
      # the JUnit file Step.7 already produces (./reports/readiness-status.xml) and
      # the trigger matrix in ./.itsm/azurelocal-itsm.yml.
      raise_itsm_ticket:
        description: 'Open ITSM tickets (ServiceNow) for fleet-update-status failures'
        required: false
        default: 'false'
        type: choice
        options:
          - 'false'
          - 'true'
      itsm_config_path:
        description: 'Path to ITSM matrix config (YAML or JSON)'
        required: false
        default: './.itsm/azurelocal-itsm.yml'
      itsm_dry_run:
        description: 'ITSM: build payloads + run read-only dedupe but do NOT create tickets'
        required: false
        default: 'false'
        type: choice
        options:
          - 'false'
          - 'true'
      itsm_force_create:
        description: 'ITSM: bypass dedupe and always create new tickets (use with caution)'
        required: false
        default: 'false'
        type: choice
        options:
          - 'false'
          - 'true'

env:
  # Module version this workflow YAML was generated against. The install step compares
  # 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.71'
  # 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).
  REQUIRED_MODULE_VERSION: ${{ github.event.inputs.module_version || vars.REQUIRED_MODULE_VERSION || '' }}
  # v0.8.4 - opt this workflow into Node.js 24 for all JavaScript actions
  # (actions/checkout, actions/download-artifact, actions/upload-artifact,
  # azure/login, dorny/test-reporter, etc). Per GitHub's 2025-09-19 deprecation
  # notice Node 20 is forced off by default on 2026-06-16 and removed from the
  # runner on 2026-09-16. Setting this env var silences the deprecation warnings
  # and exercises Node 24 ahead of the cut-over. To temporarily opt back out,
  # set ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true.
  # https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  fleet-status:
    name: Collect Fleet Update Status
    runs-on: windows-latest
    permissions:
      id-token: write
      contents: read
      checks: write  # Required for test reporter
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v5
    
    # OIDC Authentication - recommended
    - name: Azure CLI Login (OIDC)
      uses: azure/login@v3
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ vars.AZURE_TENANT_ID }}
        # AZURE_SUBSCRIPTION_ID is a repository *Variable* (vars.*), not a Secret. It
        # is consumed ONLY here: azure/login@v3 runs `az account set --subscription
        # <id>` after the OIDC token exchange so the runner has a default
        # `az account` context. It is NOT used to scope Azure Resource Graph queries
        # (those run fleet-wide across every subscription the federated identity can
        # read) and is NOT interpolated into Azure portal deep-link URLs (those use
        # the per-row `subscriptionId` returned by ARG).
        # Set it via: gh variable set AZURE_SUBSCRIPTION_ID --body <subId>
        subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
    
    - name: Install Azure CLI Resource Graph Extension
      shell: pwsh
      run: |
        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 }
        if ($env:REQUIRED_MODULE_VERSION) {
            $installArgs.RequiredVersion = $env:REQUIRED_MODULE_VERSION
            Write-Host "REQUIRED_MODULE_VERSION is set - pinning install to v$($env:REQUIRED_MODULE_VERSION)."
        } else {
            Write-Host "REQUIRED_MODULE_VERSION is empty - installing the latest version from PSGallery (default fix-forward behaviour)."
        }
        Install-Module @installArgs
        Import-Module AzLocal.UpdateManagement -Force
        Add-AzLocalPipelineVersionBanner `
            -GeneratedAgainstVersion $env:GENERATED_AGAINST_MODULE_VERSION `
            -PinnedVersion $env:REQUIRED_MODULE_VERSION
    
    - name: Collect Fleet Update Status
      # v0.8.5 thin-YAML: the inline run block (cluster inventory, readiness
      # cascade, version distribution with Microsoft-manifest support window,
      # 3-suite JUnit XML, supplementary CSV/JSON exports, run history collection,
      # 22 step outputs, and the full markdown step summary written to
      # GITHUB_STEP_SUMMARY) has been condensed into the Public cmdlet
      # Export-AzLocalFleetUpdateStatusReport. The cmdlet writes
      # ./reports/*.{json,csv,xml} for the upload-artifact step and sets all
      # 22 step outputs consumed by downstream jobs (e.g. ITSM connector).
      id: fleet-status
      shell: pwsh
      env:
        INPUT_SCOPE: ${{ github.event.inputs.scope || 'all' }}
        INPUT_UPDATE_RING: ${{ github.event.inputs.update_ring }}
        INPUT_INCLUDE_UPDATE_RUNS: ${{ github.event.inputs.include_update_runs || 'true' }}
        INSTALLED_MODULE_VERSION: ${{ steps.module-version.outputs.installed_module_version }}
      run: |
        $ErrorActionPreference = 'Stop'
        Import-Module AzLocal.UpdateManagement -Force
        $params = @{
            Scope                  = if ($env:INPUT_SCOPE) { $env:INPUT_SCOPE } else { 'all' }
            IncludeUpdateRuns      = ($env:INPUT_INCLUDE_UPDATE_RUNS -ne 'false')
            InstalledModuleVersion = $env:INSTALLED_MODULE_VERSION
        }
        if ($env:INPUT_UPDATE_RING) { $params['UpdateRing'] = $env:INPUT_UPDATE_RING }
        Export-AzLocalFleetUpdateStatusReport @params
    
    - name: Compute Artifact Timestamp
      if: always()
      id: artifact-stamp
      shell: pwsh
      # every downloadable artifact gets a UTC timestamp suffix so multiple runs on
      # the same day produce distinct zip names (e.g. azlocal-step.9-fleet-update-status-report_20260518_143217.zip).
      run: |
        $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd_HHmmss')
        "timestamp=$stamp" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
        Write-Host "Artifact timestamp: $stamp"

    - name: Upload Fleet Status Reports
      uses: actions/upload-artifact@v6
      with:
        name: azlocal-step.9-fleet-update-status-report_${{ steps.artifact-stamp.outputs.timestamp }}
        path: ./reports/
        retention-days: 90
    
    # Publish JUnit test results AFTER the markdown summary so the "Fleet
    # Update 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 with 200+ clusters (only failing rows are shown).
    - name: Publish Test Results
      uses: dorny/test-reporter@v3
      if: always()
      with:
        name: Fleet Update Status Report
        path: ./reports/readiness-status.xml
        reporter: java-junit
        fail-on-error: false  # Don't fail the action on test failures
        list-suites: failed    # collapse passing suites (compact view for large fleets)
        list-tests: failed     # within failed suites, only render failed tests

    # ----------------------------------------------------------------------
    # ITSM Connector (ServiceNow auto-raise on fleet failures)
    #
    # Fully opt-in (gated on inputs.raise_itsm_ticket == 'true'). Runs AFTER
    # the JUnit file is uploaded + test results published, so a) failing
    # clusters are already surfaced via dorny/test-reporter and the run
    # summary, and b) the ITSM action is strictly additive - failures here
    # never affect the fleet-update-status exit code.
    #
    # Reads the same readiness-status.xml that powers the run summary. The
    # JUnit emitter writes per-testcase <properties> (ClusterName /
    # ClusterResourceId / UpdateName / Status / ErrorCategory /
    # CurrentStep / Duration / UpdateRunPortalUrl / ClusterPortalUrl) so
    # New-AzLocalIncident can compute the SHA256 dedupe key and the
    # Mustache body template can deep-link straight into the Azure portal
    # SingleInstanceHistoryDetails ReactView for the failed update run.
    # ----------------------------------------------------------------------
    - name: Install powershell-yaml (ITSM config parser)
      if: ${{ github.event.inputs.raise_itsm_ticket == 'true' }}
      shell: pwsh
      run: |
        if (-not (Get-Module -ListAvailable -Name powershell-yaml)) {
            Install-Module powershell-yaml -Scope CurrentUser -Force -AllowClobber
        }

    - name: Raise ITSM tickets
      if: ${{ github.event.inputs.raise_itsm_ticket == 'true' }}
      shell: pwsh
      id: itsm
      env:
        # BEGIN-AZLOCAL-CUSTOMIZE:itsm-secrets
        # Bind your ITSM connector secrets here. Defaults match the
        # ServiceNow OAuth client_credentials naming used by azurelocal-itsm.yml.
        # Preserved by Update-AzLocalPipelineExample across module upgrades.
        ITSM_SN_INSTANCE_URL: ${{ secrets.ITSM_SN_INSTANCE_URL }}
        ITSM_SN_CLIENT_ID:    ${{ secrets.ITSM_SN_CLIENT_ID }}
        ITSM_SN_CLIENT_SECRET: ${{ secrets.ITSM_SN_CLIENT_SECRET }}
        # END-AZLOCAL-CUSTOMIZE:itsm-secrets
        INPUT_ITSM_CONFIG_PATH:  ${{ github.event.inputs.itsm_config_path }}
        INPUT_ITSM_DRY_RUN:      ${{ github.event.inputs.itsm_dry_run }}
        INPUT_ITSM_FORCE_CREATE: ${{ github.event.inputs.itsm_force_create }}
      run: |
        Import-Module AzLocal.UpdateManagement -Force

        $configPath = $env:INPUT_ITSM_CONFIG_PATH
        $dryRun     = $env:INPUT_ITSM_DRY_RUN -eq 'true'
        $force      = $env:INPUT_ITSM_FORCE_CREATE -eq 'true'

        if (-not (Test-Path $configPath)) {
            Write-Host "::warning::ITSM config not found at '$configPath' - skipping ticket creation."
            exit 0
        }

        $cfg = Get-AzLocalItsmConfig -Path $configPath

        $junitInput = './reports/readiness-status.xml'
        if (-not (Test-Path $junitInput)) {
            Write-Host "::warning::No readiness-status.xml found at '$junitInput' - skipping ticket creation."
            exit 0
        }

        $params = @{
            InputArtifactPath = $junitInput
            Config            = $cfg
            RunMetadata       = @{
                Platform = 'github'
                RunId    = $env:GITHUB_RUN_ID
                RunUrl   = "$env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID"
                Branch   = $env:GITHUB_REF
            }
            DryRun            = $dryRun
            ForceCreate       = $force
            ExportPath        = './reports/itsm-results.csv'
            ExportJUnitPath   = './reports/itsm-results.xml'
        }

        $results = New-AzLocalIncident @params
        $results | Format-Table ClusterName, Action, TicketId, Severity -AutoSize

    - name: Upload ITSM Artefacts
      if: ${{ github.event.inputs.raise_itsm_ticket == 'true' }}
      uses: actions/upload-artifact@v6
      with:
        name: azlocal-step.9-fleet-update-status-itsm-results_${{ steps.artifact-stamp.outputs.timestamp }}
        path: ./reports/itsm-*.*
        retention-days: 30
      continue-on-error: true

    - name: Publish ITSM Test Results
      if: ${{ github.event.inputs.raise_itsm_ticket == 'true' }}
      uses: dorny/test-reporter@v3
      with:
        name: ITSM Tickets (Step.9)
        path: ./reports/itsm-results.xml
        reporter: java-junit
      continue-on-error: true