Cloud Engineer · Zürich
PowerShell module · Bicep orchestrator
Take an Azure VM from Windows Server 2016, 2019 or 2022 to 2025 without an RDP session. Read-only preflight, an OS disk snapshot and unattended Setup in one workflow.
Install-Module AzureInPlaceUpgrade -AllowPrerelease# 1. Read-only preflight — a short Run Command probe, nothing changes Test-InPlaceUpgradeReadiness -ResourceGroupName rg-apps -Name vm-app-01 -Target WS2025 Decision Eligible · 19 checks, 0 blocking # 2. Name a VM and a target: snapshot, media disk, Setup as SYSTEM $s = Start-InPlaceUpgrade -ResourceGroupName rg-apps -Name vm-app-01 -Target WS2025 Setup started · returns in minutes, $s carries the resume values # 3. Every 20 minutes until Completed or Failed — locally or from Automation Complete-InPlaceUpgrade -ResourceGroupName rg-apps -Name vm-app-01 -Target WS2025 -Snapshot $s.Snapshot vm-app-01 Completed · Windows Server 2025, build 26100
Hands on
From a workstation with PowerShell 7.2 and the Az modules. Nothing is deployed into your subscription and no tags are involved — you name the VM and the target, and the preflight refuses anything it does not like.
# Install once, from the Gallery.
Install-Module AzureInPlaceUpgrade -AllowPrerelease
Connect-AzAccount
# Nineteen read-only checks inside the guest. Nothing is created, attached or started.
Test-InPlaceUpgradeReadiness -ResourceGroupName rg-apps-prod-weu -Name vm-app-prod-weu-01 -Target WS2025
# Snapshot, media disk, Setup, and wait for the guest to report the target build. That is the whole thing.
Invoke-InPlaceUpgrade -ResourceGroupName rg-apps-prod-weu -Name vm-app-prod-weu-01 -Target WS2025
# See what it would do, without touching the VM:
Invoke-InPlaceUpgrade -ResourceGroupName rg-apps-prod-weu -Name vm-app-prod-weu-01 -Target WS2025 -WhatIf
# Inside Azure Automation a job dies after three hours, so start and check separately.
# Start returns in minutes and hands you the finished Complete line:
$s = Start-InPlaceUpgrade -ResourceGroupName rg-apps-prod-weu -Name vm-app-prod-weu-01 -Target WS2025
$s.ResumeCommand
# Which targets does a Windows Server 2016 guest (build 14393) have?
Get-InPlaceUpgradeTarget -SourceBuild 14393 | Select-Object Name, DisplayName
# Every switch:
Get-Help Invoke-InPlaceUpgrade -FullA rerun reuses the snapshot with -ReuseSnapshot, a running Setup is never started twice because the preflight sees it in the guest, and -WhatIf works everywhere. Every cmdlet and every parameter is in the command reference.
Fleet mode
One subscription-scope deployment, and the fleet upgrades itself ring by ring on a schedule you control. This is the only mode in which tags matter.
az deployment sub create -l westeurope -f deploy/main.bicep \
-p moduleVersion=0.3.1-preview targetResourceGroupName=rg-apps-prod-weu ring=Ring0 maxParallel=3Tags are the runbook's business, not the module's: it selects VMs by UpgradeTarget and UpgradeState=Pending, passes the target to the module as -Target, and writes the progress back so the next Check job knows where to resume. The runbook itself is a thin wrapper — it signs in with the identity, applies -Ring and -MaxParallel, calls the module per VM and summarises. Details in deploy/README.md.
Before you start
Compute actions rather than a built-in role, so the deployment ships a custom role with exactly this list.
Option 1
Your own account holds these, on the VMs you upgrade.
Microsoft.Compute/virtualMachines/ — read, write, instanceView/read, runCommand/actionMicrosoft.Compute/disks/ — read, write, deleteMicrosoft.Compute/snapshots/ — read, writeMicrosoft.Compute/locations/publishers/ — artifacttypes/offers/skus/versions/readOption 2
A managed identity holds these. The deployment creates the custom role and assigns it.
Microsoft.Resources/tags/writeMicrosoft.Network/networkInterfaces/join/actionMonitoring Metrics Publisher — the data collection ruleVirtual Machine Contributor covers every action above except Microsoft.Compute/snapshots/*, which is the rollback point — that gap is why the deployment ships a custom role rather than using the built-in one. To run the deployment: Owner or User Access Administrator on the subscription, to create the role definition and assign it. Test-InPlaceUpgradeReadiness needs only the read actions plus runCommand/action; the exact list per command is in the command reference.
Under the hood
Two short phases, in both modes. Start takes minutes and returns; Check runs every 20 to 30 minutes until the guest reports the target build. Where the progress is kept is the caller's choice — you hold it in a variable, the runbook holds it in tags.
Nineteen read-only checks — power state, disk type, edition, installation type, language, free space, pending reboot, domain controller, cluster, activation channel, media availability in the region.
An incremental snapshot of the OS disk. Start returns its name, and it stays until you delete it — this is the rollback point.
Microsoft's hidden upgrade image becomes a managed data disk on LUN 0. No network access needed inside the guest.
A scheduled task runs setup.exe as SYSTEM with the right /imageindex, detached from Run Command. The job returns; the VM goes on rebooting on its own.
Reads the build number from the guest registry, the task state and the Setup result. Build equals target → Completed. Task failed or timed out → Failed, with the tail of setuperr.log.
Removes the media disk and the scheduled task, sends one record per transition to Log Analytics. In fleet mode the runbook also writes the final tag.
CurrentBuildNumber in the registry does not lie.Matrix
Shipped as targets.json. A tag value that is not a key there never reaches an Azure image. Same edition, same installation type, 64-bit, en-US, Standard and Datacenter, Server and Server Core. Windows Server Azure Edition is out of scope.
| Target | Source | MediaDisk engine | FeatureUpdate engine |
|---|---|---|---|
WS2025 | Windows Server 2022 | Verified — Desktop Experience and Core | Verified once |
WS2025 | Windows Server 2019 | Verified — through Azure Automation | Documented |
WS2025 | Windows Server 2016 | Verified | Not available |
WS2025 | Windows Server 2012 R2 | Documented by Microsoft | Not available |
WS2022 | Windows Server 2016, 2019 | Documented by Microsoft | Not available |
WS2019 | Windows Server 2012 R2, 2016 | Documented by Microsoft | Not available |
"Verified" means the path ran end to end in this project's lab on a Marketplace VM; runs, timings and result objects are in docs/verification.md. The media disk finishes in 37 to 43 minutes; the feature update took two to three hours on the same image.
Limits
Microsoft's own caution applies unchanged — an in-place upgrade disconnects the VM's data plane from its control plane, and auto guest patching, automatic OS image upgrades, hotpatching and Azure Update Manager may not work afterwards. If the VM is built from code and replaceable, redeploy it on a 2025 image instead. This is for the servers that are expensive to rebuild.
| Do not use in place for | Why | Do this instead |
|---|---|---|
| Domain controllers | Microsoft advises against it; AD improvements in 2025 need a clean install | Promote new DCs, demote old ones |
| Failover cluster nodes | Not a supported in-place path | Cluster-Aware Updating or a rolling upgrade |
| Datacenter: Azure Edition | Hotpatch servicing model, different media | Redeploy on the 2025 Azure Edition image |
| Ephemeral or unmanaged OS disks | No snapshot, or not supported at all | Migrate to managed disks, or redeploy |
| Non-en-US installs | The upgrade media is en-US only | Change the system language, or redeploy |
| Retail or OEM activated guests | The media requires volume licensing | Convert to a KMS client key first |
| Anything without a tested restore | A snapshot you never restored is a hope | Restore once in a lab, then proceed |
FAQ
The module never does. Windows Setup reboots the VM several times on its own once it runs, which is why Setup is started as a scheduled task and not from Run Command. A reboot that is already pending before the start blocks the preflight — restart first, then start the upgrade.
Under /quiet, Setup cannot ask which image to install, and the upgrade media carries a Core and a Desktop Experience image per edition. Setup logs "Image selection response not found" and gives up with 0xC1900215. A product key does not help. The module lists the images in install.wim, matches EditionId and InstallationType of the guest and passes /installfrom and /imageindex every time.
With the media disk, 37 to 43 minutes end to end in the lab, on Marketplace VMs from 2016, 2019 and 2022. The feature update engine took two to three hours on the same 2022 image. Budget a 60 to 120 minute maintenance window per VM, plus reboots.
Start creates an incremental snapshot of the OS disk before anything changes and returns its name; in fleet mode the runbook also records it in the UpgradeSnapshot tag. Complete keeps it — it stays until you delete it. Restoring means creating a disk from the snapshot and swapping the OS disk; test that once in a lab before you trust it.
Microsoft's Azure documentation says the in-place upgrade causes a disconnection between the VM's data plane and control plane, and that automatic guest patching, automatic OS image upgrades, hotpatching and Azure Update Manager are not officially supported afterwards. The image reference never changes. If you need those features, Microsoft's recommendation is a new VM — and so is mine.
An incremental snapshot of the OS disk, and a managed disk for the upgrade media for the duration of the run. Complete deletes the media disk; the snapshot stays until you remove it. There is no agent, no extension and nothing that keeps running afterwards.
Parameters, permissions and versions are in the command reference
Documentation
I run this against fleets as part of an Azure engagement — preflight report first, rings and maintenance windows agreed, the failures walked through afterwards.