AzLocal.UpdateManagement

0.9.12

PowerShell module to manage Azure Local (formerly Azure Stack HCI) cluster updates using Azure Update Manager APIs. Provides functions to start updates, check update status, list available updates, and monitor update runs.

Minimum PowerShell version

5.1

Installation Options

Copy and Paste the following command to install this package using PowerShellGet More Info

Install-Module -Name AzLocal.UpdateManagement -RequiredVersion 0.9.12

Copy and Paste the following command to install this package using Microsoft.PowerShell.PSResourceGet More Info

Install-PSResource -Name AzLocal.UpdateManagement -Version 0.9.12

You can deploy this package directly to Azure Automation. Note that deploying packages with dependencies will deploy all the dependencies to Azure Automation. Learn More

Manually download the .nupkg file to your system's default download location. Note that the file won't be unpacked, and won't include any dependencies. Learn More

Owners

Copyright

(c) Microsoft. All rights reserved.

Package Details

Author(s)

  • Neil Bird Microsoft

Tags

Azure AzureLocal AzureStackHCI Updates UpdateManager HCI Automation CICD Pipeline ServiceNow ITSM Incident

Functions

Connect-AzLocalServicePrincipal Start-AzLocalClusterUpdate Invoke-AzLocalFailedUpdateRetry Get-AzLocalClusterUpdateReadiness Get-AzLocalClusterInventory Get-AzLocalClusterInfo Get-AzLocalUpdateSummary Get-AzLocalAvailableUpdates Get-AzLocalUpdateRuns Set-AzLocalClusterUpdateRingTag Invoke-AzLocalFleetOperation Get-AzLocalFleetProgress Test-AzLocalFleetHealthGate Export-AzLocalFleetState Resume-AzLocalFleetUpdate Stop-AzLocalFleetUpdate Test-AzLocalClusterHealth Get-AzLocalFleetStatusData New-AzLocalFleetStatusHtmlReport Test-AzLocalUpdateScheduleAllowed Reset-AzLocalSideloadedTag Get-AzLocalItsmConfig Test-AzLocalItsmConnection New-AzLocalIncident Copy-AzLocalPipelineExample Update-AzLocalPipelineExample Copy-AzLocalItsmSample Get-AzLocalFleetHealthFailures Test-AzLocalApplyUpdatesScheduleCoverage Get-AzLocalUpdateRunFailures Get-AzLocalApplyUpdatesScheduleConfig Resolve-AzLocalCurrentUpdateRing Get-AzLocalApplyUpdatesScheduleNextFirings New-AzLocalApplyUpdatesScheduleConfig Update-AzLocalApplyUpdatesScheduleConfig Get-AzLocalApplyUpdatesScheduleCycleCalendar Get-AzLocalFleetHealthOverview Get-AzLocalLatestSolutionVersion Sync-AzLocalClusterUpdateSummary Get-AzLocalFleetConnectivityStatus New-AzLocalFleetConnectivityStatusSummary Add-AzLocalPipelineVersionBanner Assert-AzLocalAzureSubscriptionAccess Assert-AzLocalPipelineReport Export-AzLocalAuthValidationReport Invoke-AzLocalClusterInventory Set-AzLocalClusterUpdateRingTagFromCsv Export-AzLocalUpdateRunMonitorReport Export-AzLocalFleetUpdateStatusReport Export-AzLocalClusterUpdateReadinessReport Export-AzLocalFleetConnectivityStatusReport Export-AzLocalApplyUpdatesScheduleAudit Export-AzLocalFleetHealthStatusReport Resolve-AzLocalPipelineUpdateRing Export-AzLocalClusterReadinessGateReport Invoke-AzLocalReadinessGatedClusterUpdate Invoke-AzLocalReadinessGatedFailedUpdateRetry Add-AzLocalFailedUpdateRetryHintSummary Add-AzLocalApplyUpdatesStepSummary Add-AzLocalNoReadyClustersStepSummary Invoke-AzLocalItsmTicketingFromArtifact Update-AzLocalSideloadCatalog Resolve-AzLocalSideloadPlan Invoke-AzLocalSideloadUpdate Export-AzLocalSideloadStatusReport Add-AzLocalSideloadStepSummary Get-AzLocalExcludedSubscription Set-AzLocalExcludedSubscription

PSEditions

Desktop Core

Dependencies

This module has no dependencies.

Release Notes

## Version 0.9.12 - Pipeline preflight guards: fail meaningfully (and visibly in the run summary) on zero subscriptions or missing reports. Two new Public cmdlets turn two confusing failure cascades into one clear, actionable message. (1) `Assert-AzLocalAzureSubscriptionAccess` counts the Enabled subscriptions visible to the authenticated identity (`az account list`); with none it writes a remediation block to the run summary (assign Reader/RBAC, confirm tenant/client id), sets `subscription_count`=0, and throws - replacing the cryptic "No subscriptions found for ***". (2) `Assert-AzLocalPipelineReport` verifies the collect step produced its report file(s) BEFORE the publish step fires its misleading "No test report files were found" warning; on zero output it points at the real upstream cause and throws. Both are wired into ALL 10 GitHub Actions and ALL 10 Azure DevOps templates (publish steps now skip on upstream failure). New Private helper `Write-AzLocalPipelineError`. Also: Monitor: 2 - Fleet Health Status (`Export-AzLocalFleetHealthStatusReport`) now adds an operator "Knowledge" note (shown only when >=1 health check is reported) reminding operators to re-run the system health checks (`Invoke-SolutionUpdatePrecheck -SystemHealth`) after remediating a failure so the ARM-stored health results refresh (per Step 7 of the update-troubleshooting docs). Export count 66 -> 68. `GENERATED_AGAINST_MODULE_VERSION` bumped to `'0.9.12'`.

## Version 0.9.11 - Readiness allow-list scope-leak fix + monitor default tuning. Bug fix: `Export-AzLocalClusterUpdateReadinessReport` leaked the opt-in `-SchedulePath` value into the shared `$scopeParams` hashtable, which was then reused for `Test-AzLocalClusterHealth` (a cmdlet with no `SchedulePath` parameter) - so the v0.9.1 assess-update-readiness pipeline died at the health step. Readiness now clones `$scopeParams` into a dedicated `$readinessParams` for the allow-list call and keeps the health calls on the clean `$scopeParams`. Behaviour change: `Export-AzLocalApplyUpdatesScheduleAudit` monitor-recommendation defaults tightened to reduce over-polling - `-MonitorTrailingDays` 3 -> 1 and `-MonitorInFlightHours` 6 -> 2 (cmdlet + GitHub/ADO `apply-updates-schedule-audit.yml` inputs; these defaults also apply to scheduled, not just manual, runs). No public function or export-count change (still 66). `GENERATED_AGAINST_MODULE_VERSION` bumped to `'0.9.11'`.

## Version 0.9.10 - Subscription-exclusion starter hardening. The starter `Excluded-Subscription-Ids.csv` dropped by `Copy-AzLocalPipelineExample` is now a CLEAN, comment-free CSV (column header only); all operator guidance moves to a new sidecar `Excluded-Subscription-Ids_README.txt`. Embedding `#` guidance lines inside the CSV broke parsing once the file was opened and re-saved in Excel: Excel re-quotes any line containing a quote, so the `#` comment lines no longer started with `#`, survived the parser comment filter, and the first was mistaken for the header - `Resolve-AzLocalExcludedSubscriptionId` then threw "does not contain a 'Subscription IDs' column" and the real GUID rows were never read. Keeping the CSV comment-free lets it round-trip through spreadsheet editors unchanged; the README (never read by the parser) carries the purpose, activation steps, rules and a worked example. Both files are default-on for `-Platform GitHub|AzureDevOps`, suppressed by the existing `-SkipStarterExclusions` switch, and neither overwrites an operator copy. ONE-TIME MIGRATION: an early adopter who already landed on the v0.9.1 commented format is healed automatically - when `Copy`/`Update-AzLocalPipelineExample` next runs, a new private helper (`Repair-AzLocalExcludedSubscriptionCsv`) detects a legacy commented CSV and rewrites it IN PLACE to the clean format, recovering real subscription-id rows via a GUID regex over the raw lines so it works even on a file Excel already mangled (a clean v0.9.10 CSV is left untouched - idempotent no-op). One new private helper; no public function, parameter or export-count change. `GENERATED_AGAINST_MODULE_VERSION` bumped to `'0.9.10'`.

## Version 0.9.1 - Five changes in this release. (1) READINESS ALLOW-LIST OVERRIDE: `Get-AzLocalClusterUpdateReadiness` / `Export-AzLocalClusterUpdateReadinessReport` gain an opt-in `-SchedulePath` (apply-updates schedule, schema v2) and direct `-AllowedUpdateVersions` parameter. When a constraint is supplied and a cluster is NOT pinned to the `Latest` sentinel, readiness is recomputed using ONLY the allow-listed updates: a cluster whose Ready updates all fall outside its allow-list is reported `UpdateState = UpToDate` / `ReadyForUpdate = $false` (no action under the schedule), while the raw Azure update-summary state is preserved in a new `AzureUpdateState` column alongside `AllowedUpdateVersions` and `AllowListSource` (`None`/`Latest`/`Explicit`/`TopLevel`/`RowOverride`). Per-ring overrides beat the top-level fleet default via the new private resolver `Resolve-AzLocalClusterAllowList` (a `***` rings cell is the all-rings wildcard; an untagged cluster falls back to the top-level default). The default code path (neither parameter supplied) is unchanged. The assess-update-readiness GitHub Actions + Azure DevOps examples opt in automatically when a `./config/apply-updates-schedule.yml` file is present. (2) TRANSIENT LOGIN RETRY: every read-only/idempotent task across the GitHub Actions and Azure DevOps pipeline examples now retries the transient `azure/login` / `az` OIDC token-exchange failure ("Error: JSON is invalid: Expecting value...") once - GitHub workflows pair a `continue-on-error` primary login (`id: azure_login`) with an `if: steps.azure_login.outcome == 'failure'` retry step (12 guards across 10 workflows); Azure DevOps tasks use the native `retryCountOnTaskFailure: 2` (14 across 10 pipelines). Mutating tasks (Apply Updates, Retry Failed Updates, Raise ITSM tickets) are deliberately excluded to avoid duplicate-apply / duplicate-ticket risk. (3) BUG FIX: dry-run (`-WhatIf`) pipeline runs now render their step summary + outputs. When a pipeline step ran in WhatIf / dry-run mode (e.g. "Config: 2 - Manage UpdateRing Tags" with dry-run = true), `$WhatIfPreference` cascaded from the workload cmdlet into the reporting helpers and silently suppressed their `Out-File` writes (`Out-File` itself supports ShouldProcess), so the run produced ZERO step summary and ZERO step outputs - operators had to dig through the raw runner log to see what WOULD change. The pipeline reporting/artifact writes (`Add-AzLocalPipelineStepSummary`, `Set-AzLocalPipelineOutput`, and `Set-AzLocalClusterUpdateRingTagFromCsv`'s artifact-directory + JSON sidecar) now pass `-WhatIf:$false`, so a dry run always emits its full preview - the "Dry Run | True" settings row, the per-cluster "would change" detail, and the "This was a dry run. No changes were applied." footer - straight to the run Summary, while the actual Azure tag PATCH remains correctly suppressed by ShouldProcess. Additive + bug-fix - the actual Azure tag PATCH remains correctly suppressed by ShouldProcess. (4) OPTIONAL SUBSCRIPTION-EXCLUSION LIST: a new opt-in CSV lets operators exclude entire subscriptions from EVERY AzLocal.UpdateManagement Azure Resource Graph query without editing the individual KQL. Point `AZLOCAL_EXCLUDED_SUBSCRIPTIONS_PATH` (pipeline/env variable) at a repo-relative CSV (columns `Subscription IDs,Subscription Name,Comment / Notes`; only the first read, each value GUID-validated, invalid rows skipped with a warning) and every query centrally appends `| where id !startswith '/subscriptions/<id>/'` via new private helpers injected once in `Invoke-AzResourceGraphQuery`. Two new public cmdlets `Get-AzLocalExcludedSubscription` / `Set-AzLocalExcludedSubscription` (`-Path`/`-SubscriptionId`/`-Clear`) inspect/override the list; a header-only CSV warns and excludes nothing; the default (unset, no explicit call) is a no-op. All 20 pipeline examples declare the variable and Copy/Update drop an inert header-only `config/Excluded-Subscription-Ids.csv` skeleton (never overwriting). (5) AZURE DEVOPS SHARED-SETTINGS VARIABLE GROUP: all 10 ADO example pipelines now source their shared non-secret settings (exclusion path, schedule path, monitor-delay, failed-retry toggle, full `SIDELOAD_*` family) from one `- group: AzureLocal-Pipeline-Settings` reference - the ADO equivalent of GitHub repo Variables, set once per project (7 map-form `variables:` blocks converted to list form; no member redefined inline). Azure auth stays on the WIF service connection; the group is a one-time `az pipelines variable-group create` prerequisite. Export count 64 -> 66; otherwise additive. `GENERATED_AGAINST_MODULE_VERSION` bumped to `'0.9.1'`.

## Version 0.9.0 - Managed repo README auto-drop. `Copy-AzLocalPipelineExample` and `Update-AzLocalPipelineExample` now also drop a lightweight, link-first `README.md` into the customer REPO ROOT so a freshly set-up pipelines repo explains itself (what it is, how to refresh after a module release, where the docs live). Operator content is never destroyed: the README is written only when the repo has NO usable README, and a README carrying the hidden `<!-- AZLOCAL-README-VERSION: x.y.z -->` marker is version-gate refreshed in place only when the bundled template is newer. Default-on for single-platform layouts, suppressed by `-SkipReadme`. Additive - no export-count change (still 64). `GENERATED_AGAINST_MODULE_VERSION` bumped to `'0.9.0'`.

For full release notes see:
https://github.com/NeilBird/Azure-Local/blob/main/AzLocal.UpdateManagement/CHANGELOG.md

FileList

Version History

Version Downloads Last updated
0.9.16 13 7/6/2026
0.9.15 170 7/2/2026
0.9.14 19 7/2/2026
0.9.13 18 7/2/2026
0.9.12 (current version) 58 7/1/2026
0.9.11 89 6/29/2026
0.9.10 105 6/26/2026
0.9.1 13 6/26/2026
0.9.0 52 6/25/2026
0.8.99 6 6/25/2026
0.8.98 5 6/25/2026
0.8.97 35 6/24/2026
0.8.96 34 6/23/2026
0.8.95 10 6/23/2026
0.8.94 107 6/19/2026
0.8.93 25 6/18/2026
0.8.92 10 6/18/2026
0.8.91 13 6/18/2026
0.8.90 5 6/18/2026
0.8.89 7 6/18/2026
0.8.88 41 6/17/2026
0.8.87 37 6/16/2026
0.8.86 17 6/16/2026
0.8.85 6 6/16/2026
0.8.84 34 6/15/2026
Show more