Task 02: Start the Solution Update
DOCUMENT CATEGORY: Implementation Runbook
SCOPE: A deployed Azure Local cluster that has an update in the stateReadyorReadyToInstall
PURPOSE: Start the solution update thatinfrastructure.ymlchooses, with the safety checks of Learn, and return
MASTER REFERENCE: Update Azure Local by using PowerShell
Status: Active
Run Task 01 first: it says whether an update is ready. If it says AdditionalContentRequired, do the SBE update import first. Microsoft supports two ways to install an update, PowerShell on the cluster and Azure Update Manager in the portal; this script is the PowerShell way, so this task has no Azure CLI script (the Azure CLI has no update command).
The script reads the update environment and the discovered updates, chooses the solution update, refuses to start while the health of the update environment is Failure, Error or Warning, and calls Start-SolutionUpdate. It does not wait: an update takes about four hours for one machine and six for four, and the machines restart. It never resumes or retries an update that is in a failed state.
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 to connect to (or one node, with -ComputerName) |
operations.updates.install_after_deployment | Mode AfterDeployment only: true starts the first update, false (default) starts nothing and exits 0. Mode OnDemand does not read it |
operations.updates.target_version | latest (default: the highest solution update that is ready) or a solution version of four numbers, for example 12.2610.1004.50, which the update service must list. Standalone SBE updates are never chosen |
Execution Options
- PowerShell on a cluster machine
- PowerShell
- Azure portal
PowerShell on a cluster machine
When to use: You choose the update yourself and run the commands of Learn
- Sign in to a machine of the cluster as the deployment user and note the
ResourceIdof the update (Get-SolutionUpdate). - Recommended: download the update and run the readiness checks before the window. When the state is
ReadyToInstall, the update is prepared. - Inside the window, start it and keep the returned instance id for troubleshooting.
Get-SolutionUpdate -Id <ResourceId> | Start-SolutionUpdate -PrepareOnly
Get-SolutionUpdate -Id <ResourceId> | Format-Table Version, State, UpdateStateProperties, HealthState
$InstanceId = Get-SolutionUpdate -Id <ResourceId> | Start-SolutionUpdate
An update that was prepared with -PrepareOnly has to be installed from PowerShell, not from the portal (Learn).
PowerShell
When to use: The first update after the deployment, or the monthly update, with the checks of the toolkit
| Script | What it does |
|---|---|
scripts/deploy/08-day2-operations/task-02-start-solution-update/powershell/Start-AzureLocalSolutionUpdate.ps1 | Chooses the solution update, checks the health, starts it (or only prepares it) and returns. -WhatIf reads the cluster and starts nothing |
| Parameter | Meaning |
|---|---|
-InfrastructureFile | The infrastructure.yml (schema 5). Required |
-Mode | AfterDeployment (default): starts only when install_after_deployment is true. OnDemand: the monthly update, the switch is not read. Everything else is the same |
-PrepareOnly | Download and readiness checks only, nothing is installed. Run again without it to install |
-ComputerName, -Credential | One machine instead of cluster.name; the deployment user |
-LogPath | Also append the progress lines to this file |
Run
# the monthly update, step by step
./Start-AzureLocalSolutionUpdate.ps1 -InfrastructureFile ./infrastructure.yml -Mode OnDemand -WhatIf # what would be started
./Start-AzureLocalSolutionUpdate.ps1 -InfrastructureFile ./infrastructure.yml -Mode OnDemand -PrepareOnly # before the window
./Start-AzureLocalSolutionUpdate.ps1 -InfrastructureFile ./infrastructure.yml -Mode OnDemand # inside the window
The script is idempotent. It reports and exits 0, starting nothing, when the switch is off (AfterDeployment), when the cluster already runs the target version or has no newer update ready, when an update is already running, and, with -PrepareOnly, when the update is already ReadyToInstall.
How the script reads the update states (the states Learn lists for the update resource):
| State | What the script does |
|---|---|
Ready, ReadyToInstall, HealthCheckExpired | Can be started |
Downloading, Preparing, HealthChecking, Installing, of any package type (a standalone SBE update counts too) | AlreadyRunning, exit 0. The same when the update environment state is UpdateInProgress or PreparationInProgress. Never reported as AlreadyAtTarget |
Installed, Obsolete, Invalid, Recalled | Nothing to do |
Every other state: ScanFailed, ScanInProgress, NotApplicableBecauseAnotherUpdateIsInProgress, PendingOEMValidation, the failed states, AdditionalContentRequired, HasPrerequisite, and a state the script does not know | Failed, exit 1. Also in latest mode when no update is ready: such an update is never read as "at target" |
In latest mode with no update ready, an update environment state of UpdateFailed, NeedsAttention or PreparationFailed is also Failed (exit 1): the cluster is not known to be at the target, so look at it first (Get-SolutionUpdateEnvironment, Get-SolutionUpdateRun).
Row Action | Meaning |
|---|---|
Started, Prepared | The call was made; the detail holds the run and the ResourceId. The update runs on its own |
AlreadyRunning, AlreadyAtTarget, AlreadyPrepared | Nothing was started (exit 0) |
WouldStart, WouldPrepare | -WhatIf plan |
Failed | The update is in a failed, waiting or unknown state, needs content or a prerequisite, the update environment failed, the health blocks it, a newer update is stuck, or the call failed (exit 1) |
Exit codes: 0 started, prepared, nothing to start, or planned; 1 the cluster could not be read, the system is not ready or the update cannot be started; 2 a value in the file is missing or not usable (nothing is sent).
Azure portal
When to use: The update was not prepared with
-PrepareOnly, and you prefer the portal
Go to Azure Update Manager > Resources > Azure Local, select the cluster, review the readiness checks, then Install now (or Prepare first, from release 12.2604 and later). Track it in History; it can take up to 15 minutes for the run to appear.
Follow the update
Run Task 01 again (verdict UpdateRunning), or Get-SolutionUpdate -Id <ResourceId> | Format-Table Version, State, UpdateStateProperties, HealthState on a machine, or watch Update Manager. To monitor from PowerShell, connect to the last machine of the cluster: the sessions drop as machines restart. When the state is Installed, check Get-SolutionUpdateEnvironment | Format-Table State, CurrentVersion (AppliedSuccessfully is the goal).
Validation
- The row says
StartedorPrepared, or the reason it did not - The update state moves through
Downloading,Preparing,HealthCheckingtoInstalling - After the run: state
Installed,CurrentVersionis the target, the checks of Part 7 pass again
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
operations.updates.install_after_deployment is not true | Mode AfterDeployment and the switch is off | Use -Mode OnDemand, or set the key to true |
The update environment health is Warning | A readiness check warns | Get-SolutionHealthSummary; fix it. To resume an update that failed on warnings, Learn names Start-SolutionUpdate -IgnoreWarnings; the script does not use it |
AdditionalContentRequired | The vendor content is missing | SBE update import |
| A newer update is in a failed state | The script never starts an older update past a failed newer one | Fix the newer update (Learn: Troubleshoot updates), or name the version to install in operations.updates.target_version |
No solution update is ready to install with a state such as ScanFailed or PendingOEMValidation | An update is failed or waiting, so the script cannot say the cluster is at the target | Read the advice in the row. For a scan or a validation that is still running, try again later; for a failed one, see Learn: Troubleshoot updates |
The update service lists no update <version> | A feature update can take a week after its release to be visible | Check again later, or Add-SolutionUpdate imports one by hand |
Navigation
| Previous | Up | Next |
|---|---|---|
| Task 01: Check for Updates | Part 8 Index | Task 03: Node Maintenance |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-11-15 | Azure Local Cloud | Initial release. The script was Start-SolutionUpdateAfterDeployment.ps1; it now also runs the monthly update (-Mode OnDemand) and can prepare (-PrepareOnly) |
| 1.0.1 | 2026-11-16 | Azure Local Cloud | Every update state is handled: failed, waiting and unknown states are Failed (exit 1); a running update of any package type, or a running update environment, is AlreadyRunning |