Task 01: Check for Updates
DOCUMENT CATEGORY: Implementation Runbook
SCOPE: A deployed Azure Local cluster
PURPOSE: Show what the update service has discovered and what Azure offers, and say what is next for each update. Changes nothing
MASTER REFERENCE: Update Azure Local by using PowerShell
Status: Active
A freshly deployed cluster does not show its first update on its own until later. The Lifecycle Manager discovers updates by itself (it also queries the hardware vendor's online SBE manifest), the update agent checks the cluster once a day, and Learn names no command that forces a check: Get-SolutionUpdate is how you "rediscover the updates", and Azure Update Manager has a Check for updates button. This task is the check the toolkit always runs after a deployment and then on a schedule. It starts nothing.
Values from infrastructure.yml
The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.
| Key | What the script does with it |
|---|---|
cluster.name | The cluster the PowerShell script connects to (or one node, with -ComputerName); the name of the cluster resource for the Azure CLI script |
operations.updates.target_version | Optional. latest (default) or a solution version of four numbers. The report says whether that version is offered |
azure.tenant_id, azure.subscription_id, azure.resource_group | Azure CLI script only: where the cluster resource is. The sign-in must be to this tenant |
Execution Options
- PowerShell on a cluster machine
- PowerShell
- Azure CLI
- Azure portal
PowerShell on a cluster machine
When to use: One cluster, by hand
Sign in to a machine of the cluster as the deployment user, then read the update environment and the discovered updates (Learn: Update Azure Local by using PowerShell, steps 1 and 2):
Get-SolutionUpdateEnvironment | Format-List CurrentVersion, CurrentSbeVersion, State, HealthState, LastChecked
Get-SolutionUpdate | Format-Table DisplayName, PackageType, Version, SbeVersion, State
Review HealthState: Failure, Error or Warning has to be fixed before an update starts. Repeat Get-SolutionUpdate to rediscover. An update that is not listed may not be visible yet: a feature update can take a week after its release, until the hardware partner has validated it.
PowerShell
When to use: Straight after the deployment, and whenever you want the answer as a table and a JSON file
| Script | What it does |
|---|---|
scripts/deploy/08-day2-operations/task-01-check-for-updates/powershell/Get-AvailableSolutionUpdate.ps1 | Reads the update environment and polls Get-SolutionUpdate on the cluster. One row per update that is not finished, with what is next. Read only |
| Parameter | Meaning |
|---|---|
-InfrastructureFile | The infrastructure.yml (schema 5). Required |
-ComputerName | Connect to this machine instead of cluster.name |
-Credential | The deployment user. Without it the account that runs the script is used |
-WaitMinutes, -PollSeconds | Read again every -PollSeconds (default 60) until an update is offered or -WaitMinutes (0 to 240, default 0) have passed. The wait stops at once, with the verdict AttentionNeeded, when an update failed or needs a prerequisite, the health is Failure, Error or Warning, or the update environment is UpdateFailed, NeedsAttention or PreparationFailed: waiting longer fixes none of them |
-OutputPath | Also write the whole report as JSON to this file. Keep it out of the repository |
Run
# once, right after the deployment: wait up to two hours for the first update
./Get-AvailableSolutionUpdate.ps1 -InfrastructureFile ./infrastructure.yml -WaitMinutes 120 -OutputPath ./update-check.json
Azure CLI
When to use: On a schedule, from a pipeline agent or a workstation: it needs no access to a node
| Script | What it does |
|---|---|
scripts/deploy/08-day2-operations/task-01-check-for-updates/azurecli/Get-AvailableSolutionUpdate.azcli.ps1 | Reads the update summary and the updates of the cluster resource in Azure (az rest, GET only). Same table, verdict and JSON |
The Azure CLI has no az stack-hci update command, so the script reads the two operations of the Microsoft.AzureStackHCI resource provider that Learn documents (Update Summaries - Get, Updates - List). It does not sign in: run az login --tenant <azure.tenant_id> first. The signed-in identity needs read access to the cluster resource.
- Any cloud. The URL has no host (
/subscriptions/...), soaz restuses the Azure Resource Manager endpoint of the cloud thatazis set to. The script works in the public cloud and in a sovereign cloud alike. - Every page. The list of updates is followed page by page (
nextLink), at most 50 pages. A longer list stops the run with exit code 1. - Health. A health state of
Failure,ErrororWarninggivesAttentionNeeded, as in the PowerShell script. - Subscription. The script selects
azure.subscription_idwithaz account setand puts the earlier subscription back at the end. If it cannot put it back, it prints a warning and ends with exit code 1;azthen stays set to the subscription of the file. Runaz account set --subscription <your earlier subscription>. - Arguments. Every
azargument goes through the toolkit's guard (scripts/common/azure-cli/AzlAzureCliArgument.psm1). A value of the file that holds&,|,<,>,^,%,"or a line break ends the run with exit code 2 before anyazcall.
| Parameter | Meaning |
|---|---|
-InfrastructureFile | The infrastructure.yml (schema 5). Required |
-MaxCheckAgeHours | The longest time since the update service last checked (1 to 720, default 48). Longer is AttentionNeeded: the cluster is not looking for updates |
-OutputPath | Also write the whole report as JSON to this file |
az login --tenant <tenant-id>
./Get-AvailableSolutionUpdate.azcli.ps1 -InfrastructureFile ./infrastructure.yml -OutputPath ./update-check-azure.json
Azure portal
When to use: One cluster, from the browser
- Go to Azure Update Manager > Resources > Azure Local.
- Select the cluster, then Check for updates (optional: the agent checks daily).
- The status column shows Updates available when an update is offered; the Updates page of the cluster lists them.
The verdict
| Verdict | Meaning | Next |
|---|---|---|
UpToDate | No update is offered and none is running | Nothing. Check again later |
UpdateAvailable | An update is Ready or ReadyToInstall | Task 02: prepare it, then start it |
AdditionalContentRequired | An update waits for the hardware vendor's SBE files | SBE update import, then check again |
UpdateRunning | An update is Downloading, Preparing, HealthChecking or Installing | Wait. Run this task again to follow it |
AttentionNeeded | An update failed or needs a prerequisite, the health is Failure, Error or Warning, the update environment is UpdateFailed, NeedsAttention or PreparationFailed, or (Azure CLI) a critical or warning readiness check failed or the update service has not checked for too long | Read the [attention] lines. Fix them before an update is started |
Exit codes: 0 the cluster was read and nothing needs attention (an update may be offered), 1 it could not be read, the verdict is AttentionNeeded, or (Azure CLI) the earlier subscription could not be put back, 2 a value in the file is missing or not usable (nothing is sent).
Validation
- The script ends with exit code 0, or the
[attention]lines are understood - The installed version is the version you expect (
CurrentVersion) -
LastCheckedis within a day (PowerShell script: printed; Azure CLI script: in the JSON)
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
| No update is offered after the deployment | Discovery has not finished, or the release is not validated for your hardware yet | Run the script with -WaitMinutes; check again the next day. A feature update can take a week after its release to be visible |
AdditionalContentRequired | The SBE on the cluster has no download connector (or no credentials) for this cluster | Import the vendor files (SBE update import) or set the connector credentials with Set-SolutionExtensionSecretLocation |
| The Azure CLI script says the cluster resource was not found | Wrong azure.resource_group or cluster.name, or the cluster is not registered | Check both keys against the portal |
AttentionNeeded with a health of Warning | A readiness check warns | Get-SolutionHealthSummary on a machine shows the details (Learn: Troubleshoot readiness checks) |
Navigation
| Previous | Up | Next |
|---|---|---|
| Part 8: Day 2 Operations | Part 8 Index | Task 02: Start the Solution Update |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-11-15 | Azure Local Cloud | Initial release |
| 1.0.1 | 2026-11-16 | Azure Local Cloud | -WaitMinutes stops at once on something that needs attention; the Azure CLI script follows every page, uses the endpoint of the current cloud, raises AttentionNeeded on a blocking health and ends with exit code 1 when it cannot put the earlier subscription back |