Technical details of migrating to Azure Cloud Services (extended support)
This article discusses the technical details regarding the migration tool as pertaining to Cloud Services (classic).
Details about feature / scenarios supported for migration
Extensions and plugin migration
- All enabled and supported extensions are migrated.
- Disabled extensions won't be migrated.
- Plugins are a legacy concept and should be removed before migration. They're supported for migration, but after migration, if extension needs to be enabled, the plugin needs to be removed before installing the extension. This limitation affects remote desktop plugins and extensions the most.
Certificate migration
- In Cloud Services (extended support), certificates are stored in a Key Vault. As part of migration, we create a Key Vault for the customers having the Cloud Service name and transfer all certificates from Azure Service Manager to Key Vault.
- The reference to this Key Vault is specified in the template or passed through PowerShell or Azure CLI.
Service Configuration and Service Definition files
- The .cscfg and .csdef files need to be updated for Cloud Services (extended support) with minor changes.
- The names of resources like virtual network and virtual machine (VM) SKU are different. See Translation of resources and naming convention post migration
- Customers can retrieve their new deployments through PowerShell and REST API.
Cloud Service and deployments
- Each Cloud Services (extended support) deployment is an independent Cloud Service. Deployments are no longer grouped into a cloud service using slots.
- If you have two slots in your Cloud Service (classic), you need to delete one slot (staging) and use the migration tool to move the other (production) slot to Azure Resource Manager.
- The public IP address on the Cloud Service deployment remains the same after migration to Azure Resource Manager and is exposed as a Basic SKU IP (dynamic or static) resource.
- The DNS name and domain (chinacloudapp.cn) for the migrated cloud service remains the same.
Virtual network migration
- If a Cloud Services deployment is in a virtual network, then during migration all Cloud Services and associated virtual network resources are migrated together.
- After migration, the virtual network is placed in a different resource group than the Cloud Service.
- For virtual networks with multiple Cloud Services, each Cloud Service is migrated one after the other.
Migration of deployments not in a virtual network
- In late 2018, Azure started automatically creating new deployments (without customer specified virtual network) into a platform created “default” virtual network. These default virtual networks are hidden from customers.
- As part of the migration, this default virtual network is exposed to customers once in Azure Resource Manager. To manage or update the deployment in Azure Resource Manager, customers need to add this virtual network information in the NetworkConfiguration section of the .cscfg file.
- The default virtual network, when migrated to Azure Resource Manager, is placed in the same resource group as the Cloud Service.
- Cloud Services created before this time (before end of 2018) won't be in any virtual network and can't be migrated using the tool. Consider redeploying these Cloud Services directly in Azure Resource Manager. Another approach is to migrate via creating new Staging deployment and VIPSwap Check more details here
- To check if a deployment is eligible to migrate, run the validate API on the deployment. The result of Validate API contains error message explicitly mentioning if this deployment is eligible to migrate.
Load Balancer
- For a Cloud Service using a public endpoint, a platform created load balancer associated with the Cloud Service is exposed inside the customer’s subscription in Azure Resource Manager. The load balancer is a read-only resource, and updates are restricted only through the Service Configuration (.cscfg) and Service Definition (.csdef) files.
Key Vault
- As part of migration, Azure automatically creates a new Key Vault and migrates all the certificates to it. The tool doesn't allow you to use an existing Key Vault.
- Cloud Services (extended support) requires a Key Vault located in the same region and subscription. This Key Vault is automatically created as part of the migration.
Resources and features not available for migration
This list contains the top scenarios involving combinations of resources, features, and Cloud Services. This list isn't exhaustive.
| Resource | Next steps / work-around |
|---|---|
| Auto Scale Rules | Migration goes through but rules are dropped. Recreate the rules after migration on Cloud Services (extended support). |
| Alerts | Migration goes through but alerts are dropped. Recreate the rules after migration on Cloud Services (extended support). |
| VPN Gateway | Remove the VPN Gateway before beginning migration and then recreate the VPN Gateway once migration is complete. |
| Express Route Gateway (in the same subscription as Virtual Network only) | Remove the Express Route Gateway before beginning migration and then recreate the Gateway once migration is complete. |
| Quota | Quota isn't migrated. Request new quota on Azure Resource Manager prior to migration for the validation to be successful. |
| Affinity Groups | Not supported. Remove any affinity groups before migration. |
| Virtual networks using virtual network peering | Before migrating a virtual network that is peered to another virtual network, delete the peering, migrate the virtual network to Resource Manager and re-create peering. This can cause downtime depending on the architecture. |
| Virtual networks that contain App Service environments | Not supported |
| Virtual networks with Azure Batch Deployments | Not supported |
| Virtual networks that contain HDInsight services | Not supported. |
| Virtual networks that contain Azure API Management deployments | Not supported. To migrate the virtual network, change the virtual network of the API Management deployment. This is a no downtime operation. |
| Classic Express Route circuits | Not supported. These circuits need to be migrated to Azure Resource Manager before beginning PaaS migration. To learn more, see Moving ExpressRoute circuits from the classic to the Resource Manager deployment model. |
| Role-Based Access Control | Post migration, the URI of the resource changes from Microsoft.ClassicCompute to Microsoft.Compute RBAC policies needs to be updated after migration. |
| Application Gateway | Not Supported. Remove the Application Gateway before beginning migration and then recreate the Application Gateway once migration is completed to Azure Resource Manager |
Unsupported configurations / migration scenarios
| Configuration / Scenario | Next steps / work-around |
|---|---|
| Migration of some older deployments not in a virtual network | Some Cloud Service deployments not in a virtual network aren't supported for migration. 1. Use the validate API to check if the deployment is eligible to migrate. 2. If eligible, the deployments move to Azure Resource Manager under a virtual network with prefix of “DefaultRdfeVnet” |
| Migration of deployments containing both production and staging slot deployment using dynamic IP addresses | Migration of a two slot Cloud Service requires deletion of the staging slot. Once the staging slot is deleted, migrate the production slot as an independent Cloud Service (extended support) in Azure Resource Manager. Then redeploy the staging environment as a new Cloud Service (extended support) and make it swappable with the first one. |
| Migration of deployments containing both production and staging slot deployment using Reserved IP addresses | Not supported. |
| Migration of production and staging deployment in different virtual network | Migration of a two slot cloud service requires deleting the staging slot. Once the staging slot is deleted, migrate the production slot as an independent cloud service (extended support) in Azure Resource Manager. A new Cloud Services (extended support) deployment can then be linked to the migrated deployment with swappable property enabled. Deployments files of the old staging slot deployment can be reused to create this new swappable deployment. |
| Migration of empty Cloud Service (Cloud Service with no deployment) | Not supported. |
| Migration of deployment containing the remote desktop plugin and the remote desktop extensions | Option 1: Remove the remote desktop plugin before migration. This requires changes to deployment files. The migration then goes through. Option 2: Remove remote desktop extension and migrate the deployment. Post-migration, remove the plugin and install the extension. This requires changes to deployment files. Remove the plugin and extension before migration. Plugins aren't recommended for use on Cloud Services (extended support). |
| Virtual networks with both PaaS and IaaS deployment | Not Supported Move either the PaaS or IaaS deployments into a different virtual network. This causes downtime. |
| Cloud Service deployments using legacy role sizes (such as Small or ExtraLarge). | The role sizes need to be updated before migration. Update all deployment artifacts to reference these new modern role sizes. For more information, see Available VM sizes |
| Migration of Cloud Service to different virtual network | Not supported 1. Move the deployment to a different classic virtual network before migration. This causes downtime. 2. Migrate the new virtual network to Azure Resource Manager. Or 1. Migrate the virtual network to Azure Resource Manager 2. Move the Cloud Service to a new virtual network. This causes downtime. |
| Cloud Service in a virtual network but doesn't have an explicit subnet assigned | Not supported. Mitigation involves moving the role into a subnet, which requires a role restart (downtime) |
Translation of resources and naming convention post migration
As part of migration, the resource names are changed, and few Cloud Services features are exposed as Azure Resource Manager resources. The table summarizes the changes specific to Cloud Services migration.
| Cloud Services (classic) Resource name |
Cloud Services (classic) Syntax |
Cloud Services (extended support) Resource name |
Cloud Services (extended support) Syntax |
|---|---|---|---|
| Cloud Service | cloudservicename |
Not associated | Not associated |
| Deployment (portal created) Deployment (nonportal created) |
deploymentname |
Cloud Services (extended support) | cloudservicename |
| Virtual Network | vnetname Group resourcegroupname vnetname Not associated |
Virtual Network (not portal created) Virtual Network (portal created) Virtual Networks (Default) |
vnetname group-resourcegroupname-vnetname VNet-cloudservicename |
| Not associated | Not associated | Key Vault | KV-cloudservicename |
| Not associated | Not associated | Resource Group for Cloud Service Deployments | cloudservicename-migrated |
| Not associated | Not associated | Resource Group for Virtual Network | vnetname-migrated group-resourcegroupname-vnetname-migrated |
| Not associated | Not associated | Public IP (Dynamic) | cloudservicenameContractContract |
| Reserved IP Name | reservedipname |
Reserved IP (nonportal created) Reserved IP (portal created) |
reservedipname group-resourcegroupname-reservedipname |
| Not associated | Not associated | Load Balancer | LB-cloudservicename |
Migration issues and how to handle them.
Migration stuck in an operation for a long time.
- Commit, prepare, and abort can take a long time depending on the number of deployments. Operations will time out after 24 hours.
- Commit, prepare, and abort operations are idempotent. Most issues are fixable by retrying. There could be transient errors, which can go away in few minutes, we recommend retrying after a gap. If migrating using the Azure portal and the operation is stuck in an "in-progress state", use PowerShell to retry the operation.
- Contact support to help migrate or roll back the deployment from the backend.
Migration failed in an operation.
- If validation failed, it is because the deployment or virtual network contains an unsupported scenario/feature/resource. Use the list of unsupported scenarios to find the work-around in the documents.
- Prepare operation first does validation including some expensive validations (not covered in validate). Prepare failure could be due to an unsupported scenario. Find the scenario and the work-around in the public documents. Abort needs to be called to go back to the original state and unlock the deployment for updates and delete operations.
- If abort failed, retry the operation. If retries fail, then contact support.
- If the commit failed, retry the operation. If retry fail, then contact support. Even in commit failure, there should be no data plane issue to your deployment. Your deployment should be able to handle customer traffic without any issue.
Portal refreshed after Prepare. Experience restarted and Commit or Abort not visible anymore.
- Portal stores the migration information locally and therefore after refresh, it will start from validate phase even if the Cloud Service is in the prepare phase.
- You can use portal to go through the validate and prepare steps again to expose the Abort and Commit button. It won't cause any failures.
- Customers can use PowerShell or REST API to abort or commit.
How much time can the operations take?
Validate is designed to be quick. Prepare is longest running and takes some time depending on total number of role instances being migrated. Abort and commit can also take time but takes less time compared to prepare. All operations will time out after 24 hrs.
Next steps
For assistance migrating your Cloud Services (classic) deployment to Cloud Services (extended support) see our Support and troubleshooting landing page.