Merge pull request #245101 from MicrosoftDocs/main

publish main to live, 4 PM Sundday 7/16

Author: American-Dipper

articles/migrate/concepts-migration-planning.md

@@ -6,7 +6,7 @@ ms.author: rajosh
 ms.manager: abhemraj
 ms.service: azure-migrate
 ms.topic: conceptual
-ms.date: 02/27/2023
+ms.date: 07/10/2023
 ms.custom: engagement-fy23
 ---
 
@@ -151,6 +151,16 @@ When you're ready for migration, use the Migration and modernization tool, and t
 - With the Migration and modernization tool, you can migrate on-premises VMs and servers, or VMs located in other private or public cloud (including AWS, GCP) with around zero downtime.
 - Azure DMS provides a fully managed service that's designed to enable seamless migrations from multiple database sources to Azure Data platforms, with minimal downtime.
 
+### Upgrade Windows OS
+
+Azure Migrate provides an option to customers to upgrade their Windows Server OS seamlessly during the migration. Azure Migrate OS upgrade allows you to move from an older operating system to a newer one while keeping your settings, server roles, and data intact. [Learn more](how-to-upgrade-windows.md).
+
+Azure Migrate OS upgrade uses an Azure VM [Custom script extension](../virtual-machines/extensions/custom-script-windows.md) to perform the following activities for an in-place upgrade experience:
+
+- A data disk containing Windows Server setup files is created and attached to the VM.
+- A Custom Script Extension called `InPlaceOsUpgrade` is enabled on the VM, which downloads a script from the storage account and initiates the upgrade in a quiet mode.
+
+
 ## Next steps
 
 - Investigate the [cloud migration journey](/azure/architecture/cloud-adoption/getting-started/migrate) in the Azure Cloud Adoption Framework.

articles/migrate/how-to-upgrade-windows.md

@@ -0,0 +1,89 @@
+---
+title: Upgrade Windows Operating System
+description: Learn how to upgrade Windows OS during migration.
+author: AnuragMehrotra
+ms.author: anuragm
+ms.manager: vijain
+ms.topic: how-to
+ms.date: 07/10/2023
+ms.custom: engagement-fy23
+---
+
+# Azure Migrate Windows Server upgrade (Preview)  
+
+This article describes how to upgrade Windows Server OS while migrating to Azure. Azure Migrate OS upgrade allows you to move from an older operating system to a newer one while keeping your settings, server roles, and data intact. You can move your on-premises server to Azure with an upgraded OS version of Windows Server using Windows upgrade.
+
+> [!NOTE]
+> This feature is currently available only for VMWare agentless migration.
+
+## Prerequisites 
+
+- Ensure you have an existing Migrate project or [create](create-manage-projects.md) a project. 
+- Ensure you have discovered the servers according to [Discover servers in VMware environment](tutorial-discover-vmware.md) and replicated the servers as described in [Migrate VMware VMs](tutorial-migrate-vmware.md#replicate-vms). 
+- Verify the operating system disk has enough [free space](https://learn.microsoft.com/windows-server/get-started/hardware-requirements#storage-controller-and-disk-space-requirements) to perform the in-place upgrade. The minimum disk space requirement is 32 GB.   
+- The upgrade feature only works for Windows Server Standard and Datacenter editions. 
+- This feature does not work for Windows Server with an evaluation license and needs a full license. If you have any server with an evaluation license, upgrade to full edition before starting migration to Azure.
+- Disable antivirus and anti-spyware software and firewalls. These types of software can conflict with the upgrade process. Re-enable antivirus and anti-spyware software and firewalls after the upgrade is completed.  
+- Ensure that your VM has the capability of adding another data disk as this feature requires the addition of an extra data disk temporarily for a seamless upgrade experience. 
+- For Private Endpoint enabled Azure Migrate projects, follow [these](migrate-servers-to-azure-using-private-link.md?pivots=agentlessvmware#replicate-vms) steps before initiating any Test migration/Migration with OS upgrade.  
+
+
+> [!NOTE]
+> In case of OS upgrade failure, Azure Migrate may download the Windows SetupDiag for error details. Ensure the VM created in Azure post the migration has access to [SetupDiag](https://go.microsoft.com/fwlink/?linkid=870142). In case there is no access to SetupDiag, you may not be able to get detailed OS upgrade failure error codes but the upgrade can still proceed.
+
+## Overview 
+
+The Windows OS upgrade capability helps you move from an older operating system to a newer one while keeping your settings, server roles, and data intact. Since both upgrade and migration operations are completed at once, this reduces duplicate planning, downtime, and test efforts. The upgrade capability also reduces the risk, as customers can first test their OS upgrade in an isolated environment in Azure using test migration without any impact on their on-premises server.    
+
+You can upgrade to up to two versions from the current version.   
+
+**Source** | **Supported target versions**
+--- | ---
+Windows Server 2012 | Windows Server 2016 
+Windows Server 2012 R2 | Windows Server 2016, Windows Server 2019 
+Windows Server 2016  | Windows Server 2019, Windows Server 2022 
+Windows Server 2019 | Windows Server 2022
+
+## Upgrade Windows OS during test migration 
+
+To upgrade Windows during the test migration, follow these steps:
+
+1. On the **Get started** page > **Servers, databases and web apps**, select **Replicate**. 
+   
+   A Start Replication job begins. When the Start Replication job finishes successfully, the machines begin their initial replication to Azure. 
+
+3. Select **Replicating servers** in **Migration and modernization** to monitor the replication status.
+
+4. In **Migration goals** > **Servers, databases and webapps** > **Migration and modernization**, select **Replicated servers** under **Replications**.  
+
+5. In the **Replicating machines** tab, right-click the VM to test and select **Test migrate**. 
+
+6. Select the **Upgrade available** option. In the pane that appears, select the target OS version that you want to upgrade to and select **Apply**. 
+
+7. Select **Test migration** to initiate the test migration followed by the OS upgrade. 
+
+8. After the migration job is successful, view the migrated Azure VM in **Virtual Machines** in the Azure portal. The machine name has the suffix *-Test*.  
+
+   You can now use this server with upgraded OS to complete any application testing. The original server continues running on-premises without any impact while you test the newly upgraded server in an isolated environment.   
+
+9. After the test is done, right-click the Azure VM in **Replicating machines**, and select **Clean up test migration**. This deletes the test VM and any resources associated with it.  
+
+## Upgrade Windows OS during migration
+
+After you've verified that the test migration works as expected, you can migrate the on-premises machines. To upgrade Windows during the migration, follow these steps:
+
+1. On the **Get started** page > **Servers, databases and web apps**, select **Replicate**. A Start Replication job begins.    
+2. In **Replicating machines**, right-click the VM and select **Migrate**.  
+3. In **Migrate** > **Shut down virtual machines and perform a planned migration with no data loss**, select **Yes** > **OK**.  
+   - By default, Azure Migrate shuts down the on-premises VM to ensure minimum data loss.  
+   - If you don't want to shut down the VM, select No.  
+4. Select the **Upgrade available** option. 
+5. In the pane that appears, select the target OS version that you want to upgrade to and select **Apply**. The upgrade available option changes to upgrade configured.
+
+5. Select **Migrate** to start the migration and the upgrade.  
+
+## Next steps 
+
+Investigate the [cloud migration journey](https://learn.microsoft.com/azure/architecture/cloud-adoption/getting-started/migrate) in the Azure Cloud Adoption Framework. 
+
+ 

articles/migrate/index.yml

@@ -79,6 +79,8 @@ landingContent:
             url: ./how-to-discover-applications.md
           - text: Add migration tools
             url: ./how-to-migrate.md
+          - text: Upgrade Windows OS
+            url: ./how-to-upgrade-windows.md
           - text: Scale VMware assessment
             url: ./scale-vmware-assessment.md
           - text: Automate and scale migration

articles/migrate/media/how-to-upgrade-windows/migrate-upgrade-available.png

@@ -265,6 +265,8 @@
         href: how-to-migrate-vmware-vms-with-cmk-disks.md
     - name: Test migration
       href: how-to-test-replicating-virtual-machines.md
+    - name: Upgrade Windows OS
+      href: how-to-upgrade-windows.md
     - name: Scale migration
       items:
       - name: How to migrate VMware VMs at scale using the agentless replication method
@@ -312,7 +314,9 @@
     - name: Troubleshoot stuck replication and slow migration issues in agentless VMware
       href: troubleshoot-replication-vmware.md
     - name: Troubleshoot web app migration issues
-      href: troubleshoot-webapps-migration.md  
+      href: troubleshoot-webapps-migration.md
+    - name: Troubleshoot Windows OS upgrade issues
+      href: troubleshoot-upgrade.md  
 - name: Reference
   items:
   - name: Azure CLI

articles/migrate/media/how-to-upgrade-windows/test-migration-options.png

@@ -0,0 +1,59 @@
+---
+title: Troubleshoot Windows upgrade issues
+description: Provides an overview of known issues in the Windows OS upgrade feature
+author: AnuragMehrotra
+ms.author: anuragm
+ms.service: azure-migrate
+ms.topic: conceptual
+ms.date: 06/08/2023
+ms.custom: engagement-fy23
+---
+
+# Troubleshoot Windows OS upgrade issues  
+
+This article describes some common issues that you might encounter when you upgrade the Windows OS using the Migration and modernization tool.  
+
+## Cannot attach the OS setup disk as VM reached maximum disk allowed
+
+The Test Migration and Migration will fail in the prerequisite stage if the VM already has the maximum number of data disks based on its SKU. Since the workflow creates an additional data disk temporarily, it's mandatory to have n-1 (n represents maximum number of disks supported for the respective SKU of the VM) disks to complete the upgrade successfully.    
+
+### Recommended action
+
+Select a different target Azure VM SKU that can attach more data disks and retry the operation. Since Azure Migrate completed the migration and created a VM in Azure, retry the operation by following these steps:    
+
+1. Clean up the migration:   
+   1. Test Migration: Right-click the Azure VM in **Replications** and select **Clean up test migration**.  
+   1. Migration: Since the VM is already migrated to Azure, follow [these](https://learn.microsoft.com/azure/virtual-machines/windows-in-place-upgrade) steps here to upgrade the OS.
+
+2. Update the target VM SKU settings:    
+   1. In the Azure portal, select the Azure Migrate project.    
+   2. Go to **Migration tools** > **Replications** > Azure VM count.    
+   3. Select the Replicating machine.    
+   4. Go to **Compute and network**.    
+   5. In **Compute**, change the VM size to support more data disks.    
+
+3. Verify that the operating system disk has enough [free space](https://learn.microsoft.com/windows-server/get-started/hardware-requirements#storage-controller-and-disk-space-requirements) to perform the in-place upgrade. The minimum disk space requirement is 32 GB. If more space is needed, follow [these](https://learn.microsoft.com/azure/virtual-machines/windows/expand-os-disk) steps to expand the operating system disk attached to the VM for a successful OS upgrade.    
+
+## Migration fails for Private endpoint enabled Azure Migrate projects  
+
+The migration fails if the storage account that you select for replicating VMs doesn't have the Firewall settings of the target VNET. 
+
+### Recommended action
+
+Add the target VNET into the firewall in the storage account that you select in the above step for replicating VMs:  
+
+1. Go to **Networking** > **Firewall and Virtual Networks** > **Public Network Access – Enabled from selected Virtual Network and IP address** > **Virtual Network** > Add existing Virtual Network and add your target VNET. Then proceed with the Test Migration/Migration.    
+
+2. Perform the initial replication by following [these](migrate-servers-to-azure-using-private-link.md?pivots=agentlessvmware#replicate-vms) steps.  
+
+## Server is migrated without OS upgrade with status “Completed with errors”  
+
+If the source OS version and the OS version to be upgraded are the same, the server migrates without an OS upgrade with the status **Completed with errors**. For example, if the source OS version is Windows 2019 and the upgrade option selected is Windows 2019, then the server is migrated without an OS upgrade with the status **Completed with errors**. 
+
+### Recommended action
+
+Ensure the current OS version is different from the target OS version.    
+
+## Next steps
+
+[Learn more](tutorial-migrate-vmware.md) about migrating VMware VMs.

articles/migrate/media/how-to-upgrade-windows/test-migration.png

@@ -40,14 +40,17 @@ Before you begin this tutorial, you should:
 3. Go to the already created project or [create a new project](./create-manage-projects.md)
 4. Verify permissions for your Azure account - Your Azure account needs permissions to create a VM, and write to an Azure managed disk.
 
+> [!NOTE]
+> If you're planning to upgrade your Windows operating system, Azure Migrate may download the Windows SetupDiag for error details in case upgrade fails. Ensure the VM created in Azure post the migration has access to [SetupDiag](https://go.microsoft.com/fwlink/?linkid=870142). In case there is no access to SetupDiag, you may not be able to get detailed OS upgrade failure error codes but the upgrade can still proceed.
+
 ## Set up the Azure Migrate appliance
 
 The Migration and modernization tool runs a lightweight VMware VM appliance that's used for discovery, assessment, and agentless migration of VMware VMs. If you follow the [assessment tutorial](./tutorial-assess-vmware-azure-vm.md), you've already set the appliance up. If  you didn't, set it up now, using one of these methods:
 
 - **OVA template**: [Set up](how-to-set-up-appliance-vmware.md) on a VMware VM using a downloaded OVA template.
 - **Script**: [Set up](deploy-appliance-script.md) on a VMware VM or physical machine, using a PowerShell installer script. This method should be used if you can't set up a VM using an OVA template, or if you're in Azure Government.
 
-After creating the appliance, you check that it can connect to Azure Migrate:Server Assessment, configure it for the first time, and register it with the Azure Migrate project.
+After creating the appliance, you check that it can connect to Azure Migrate: Server Assessment, configure it for the first time, and register it with the Azure Migrate project.
 
 ## Replicate VMs
 
@@ -103,7 +106,7 @@ Enable replication as follows:
 
 11. In **Compute**, review the VM name, size, OS disk type, and availability configuration (if selected in the previous step). VMs must conform with [Azure requirements](migrate-support-matrix-vmware-migration.md#azure-vm-requirements).
 
-    - **VM size**: If you're using assessment recommendations, the VM size dropdown shows the recommended size. Otherwise Azure Migrate picks a size based on the closest match in the Azure subscription. Alternatively, pick a manual size in **Azure VM size**.
+    - **VM size**: If you're using assessment recommendations, the VM size dropdown shows the recommended size. Otherwise, Azure Migrate picks a size based on the closest match in the Azure subscription. Alternatively, pick a manual size in **Azure VM size**.
     - **OS disk**: Specify the OS (boot) disk for the VM. The OS disk is the disk that has the operating system bootloader and installer.
     - **Availability Zone**: Specify the Availability Zone to use.
     - **Availability Set**: Specify the Availability Set to use.
@@ -175,7 +178,7 @@ Do a test migration as follows:
 4. Choose the subnet to which you would like to associate each of the Network Interface Cards (NICs) of the migrated VM.
 
     :::image type="content" source="./media/tutorial-migrate-vmware/test-migration-subnet-selection.png" alt-text="Screenshot shows subnet selection during test migration.":::
-
+1. You have an option to upgrade the Windows Server OS during test migration. To upgrade, select the **Upgrade available** option. In the pane that appears, select the target OS version that you want to upgrade to and select **Apply**. [Learn more](how-to-upgrade-windows.md).
 5. The **Test migration** job starts. Monitor the job in the portal notifications.
 6. After the migration finishes, view the migrated Azure VM in **Virtual Machines** in the Azure portal. The machine name has a suffix **-Test**.
 7. After the test is done, right-click the Azure VM in **Replicating machines**, and click **Clean up test migration**.
@@ -199,6 +202,7 @@ After you've verified that the test migration works as expected, you can migrate
 3. In **Migrate** > **Shut down virtual machines and perform a planned migration with no data loss**, select **Yes** > **OK**.
     - By default Azure Migrate shuts down the on-premises VM, and runs an on-demand replication to synchronize any VM changes that occurred since the last replication occurred. This ensures no data loss.
     - If you don't want to shut down the VM, select **No**
+1. You have an option to upgrade the Windows Server OS during migration. To upgrade, select the **Upgrade available** option. In the pane that appears, select the target OS version that you want to upgrade to and select **Apply**. [Learn more](how-to-upgrade-windows.md).
 4. A migration job starts for the VM. Track the job in Azure notifications.
 5. After the job finishes, you can view and manage the VM from the **Virtual Machines** page.