Upgrading Windows Server VMs

You can upgrade certain Windows Server 2008 R2 VMs to Windows Server 2012 while you're migrating them to Compute Engine.

Before you begin

Be sure you have the following in place before you begin a migration that will include upgrades:

  • Ensure that you have enough boot disk space to support upgrade. Upgrade is likely to require 15-20 GB for each upgrading VM.

  • Ensure that the VMs to upgrade don't use the bring-your-own-license (BYOL) process. The upgrade feature does not support VMs using BYOL. Attempts to upgrade BYOL VMs will fail with an error.

    You can instead migrate your VM, then upgrade it separately with the in-place process provided on Compute Engine.

  • Ensure adequate down time. During a migration in which you're upgrading Windows Server VMs, those VMs will be unavailable for as long as it takes to migrate and upgrade. A migration process that includes upgrade can take 1-2 hours to complete for each upgrading VM.

  • Ensure that the VMs you're upgrading are using Windows Server 2008 R2.

Validating upgraded VMs

You can validate your VM during the migrate and upgrade process by using PowerShell scripts you write. You can have your scripts execute before the upgrade begins and after it has completed. For example, you might want to confirm that applications on the VM function before and after the upgrade process.

When writing scripts, take care to avoid scripting long-running operations. The time that scripts take to execute is included in the overall timeout limit for upgrade (which defaults to 2.5 hours).

Adding validation scripts

You can provide one PowerShell script for the system to execute before upgrade, and one to be executed afterward. Providing more than one script whose name matches the naming constraints will generate an error.

To have the system execute your scripts, you give them specific names and put them in specific locations:

Purpose Name form Location
Execute before upgrade


For example, pre_upgrade_script.ps1


For example, c:\upgrade_os_scripts\pre_upgrade_script.ps1

Execute after upgrade


For example, post_upgrade_script.ps1


For example, c:\upgrade_os_scripts\post_upgrade_script.ps1

Output and errors from script execution

Messages from the upgrade process are printed to serial port 3. If your script generates the following errors, the upgrade will fail and revert to the base snapshot.

  • Multiple pre/post upgrade scripts found:

    timestamp Replatform Error: Found 2 pre-upgrade user supplied scripts only 1 allowed.
  • Non-zero exit code:

    timestamp Replatform Error: C:\upgrade_os_scripts\pre_upgrade_script.ps1 exited with the following error code: 1
  • Exception thrown while executing the script:

    timestamp Replatform Error: The following exception thrown while running user supplied post-upgrade script: "": .

For more, see the process for upgrading VMs.


You'll find errors related to upgrade in the Migrate for Compute Engine Manager or logged in Cloud Logging.

For errors you might see during upgrade, see the Troubleshooting topic.

Upgrading a Windows Server VM while migrating

You perform the upgrade while migrating the VMs using a wave.

Upgrading the VM OS occurs after the detach phase and before the cleanup phase. Once the cleanup phase has executed, it will not be possible to roll back or revert the upgrade.

Before upgrading the VM, Migrate for Compute Engine takes a snapshot of the VM. If the upgrade fails, Migrate for Compute Engine will revert to the snapshot.

To upgrade VM OSes in a wave

When you create your runbook to migrate VMs, you specify to upgrade them by entering TRUE for the runbook's UpgradeOS field. During migration, after the Detach phase and before the Cleanup phase, you can upgrade the OSes of qualified VMs.

The following describes how to upgrade while performing a full migration of your VMs.

  1. Use the Migrate for Compute Engine Manager to download a runbook CSV file.
  2. In the runbook CSV file, locate rows for the VMs you want to upgrade.
  3. For those VMs that support the upgrade process, locate the UpgradeOS column and change its value to TRUE.
  4. Edit or fill in the other columns as needed to have a functioning runbook.

    For a list of runbook fields, see the Runbook reference.

  5. In the Migrate for Compute Engine Manager, create and validate a wave from the runbook.

  6. After the wave passes validation, create a new job. For the job's operation, select Full Migration.

    Depending on the number of VMs in your wave, the migration may take anywhere from an hour to many hours.

    Screenshot of new job dialog to start full migration (click to enlarge)
    Screenshot of New Job dialog (click to enlarge)

  7. Monitor the progress of the migration, looking for a Ready to Detach status for every VM.

    Screenshot of VM migration status as ready to detach (click to enlarge)
    Screenshot of Virtual Machines tab showing Migration Status ready to detach (click to enlarge)

  8. When every VM is ready to detach, create a new job whose operation is Detach.

    Screenshot of new job dialog to detach (click to enlarge)
    Screenshot of New Job dialog with Detach operation selected (click to enlarge)

  9. When all of the VMs are in the Detached state, select the wave, then create a new job whose operation is Upgrade OS, then click Start to begin the upgrade.

    The Last Job (Status) changes to Upgrade OS (Running).

    After you've started the upgrade, you can cancel it for any of the VMs in the wave. To cancel the upgrade, select the VM in the Virtual Machines list, then click Cancel OS Upgrade.

    Screenshot of VM list with cancel OS upgrade button highlighted (click to enlarge)
    Screenshot of Virtual Machines tab with Cancel OS Upgrade button highlighted (click to enlarge)

  10. When each VM in the Virtual Machines list shows its migration status as Upgraded OS, run your tests to validate that each works as it should before finishing the migration process.

    If a VM doesn't validate correctly, you can cancel the upgrade.

  11. When you have validated VMs with upgraded OSes, complete the migration by running the clean up operation. To do this, create a new job with Cleanup specified as the operation.

Cancelling an OS upgrade in progress

You can cancel a VM OS upgrade in progress using the Migrate for Compute Engine Manager.

  1. In the Migrate for Compute Engine Manager, go to the Migration Waves page.
  2. On the Waves tab, locate the wave that includes the upgrade you want to cancel, then click its icon in the Monitor column.
  3. On the Virtual Machine tab that appears, select the row for the VM whose upgrade you want to cancel.
  4. With the row selected, click the Cancel OS Upgrade button.
    Screenshot of VM list with cancel OS upgrade button highlighted (click to enlarge)
    Screenshot of Virtual Machines tab with Cancel OS Upgrade button highlighted (click to enlarge)