Migration to App Service Environment v3 using the in-place migration feature

App Service can automate migration of your App Service Environment v1 and v2 to an App Service Environment v3. There are different migration options. Review the migration path decision tree to decide which option is best for your use case. App Service Environment v3 provides advantages and feature differences over earlier versions. Make sure to review the supported features of App Service Environment v3 before migrating to reduce the risk of an unexpected application issue.

The in-place migration feature automates your migration to App Service Environment v3 by upgrading your existing App Service Environment in the same subnet. This migration option is best for customers who want to migrate to App Service Environment v3 with minimal changes to their networking configurations. You must also be able to support about one hour of application downtime. If you can't support downtime, see the manual migration options.

Supported scenarios

At this time, the in-place migration feature doesn't support migrations to App Service Environment v3 in the following regions:

Azure operated by 21Vianet

• China East 2
• China North 2

The following App Service Environment configurations can be migrated using the in-place migration feature. The table gives the App Service Environment v3 configuration when using the in-place migration feature based on your existing App Service Environment. All supported App Service Environments can be migrated to a zone redundant App Service Environment v3 using the in-place migration feature as long as the environment is in a region that supports zone redundancy. You can configure zone redundancy during the migration process.

If you want your new App Service Environment v3 to use a custom domain suffix and you aren't using one currently, custom domain suffix can be configured at any time once migration is complete. For more information, see Configure custom domain suffix for App Service Environment.

You can find the version of your App Service Environment by navigating to your App Service Environment in the Azure portal and selecting Configuration under Settings on the left-hand side.

In-place migration feature limitations

The following are limitations when using the in-place migration feature:

• Your new App Service Environment v3 is in the existing subnet that was used for your old environment.
• You can't change the region your App Service Environment is located in.
• ELB App Service Environment can't be migrated to ILB App Service Environment v3 and vice versa.
• If your existing App Service Environment uses a custom domain suffix, you have to configure custom domain suffix for your App Service Environment v3 during the migration process.
  • If you no longer want to use a custom domain suffix, you can remove it once the migration is complete.

App Service Environment v3 doesn't support the following features that you can be used with your current App Service Environment v1 or v2.

• Configuring an IP-based TLS/SSL binding with your apps.
• App Service Environment v3 doesn't fall back to Azure DNS if your configured custom DNS servers in the virtual network aren't able to resolve a given name. If this behavior is required, ensure that you have a forwarder to a public DNS or include Azure DNS in the list of custom DNS servers.

The in-place migration feature doesn't support the following scenarios. See the manual migration options if your App Service Environment falls into one of these categories.

• App Service Environment v1 in a Classic virtual network
• ELB App Service Environment v2 with IP SSL addresses
• ELB App Service Environment v1 with IP SSL addresses
• App Service Environment with a name that doesn't meet the character limits. The entire name, including the domain suffix, must be 64 characters or fewer. For example: my-ase-name.appserviceenvironment.cn for ILB and my-ase-name.p.chinacloudsites.cn for ELB must be 64 characters or fewer. If you don't meet the character limit, you must migrate manually. The character limits specifically for the App Service Environment name are as follows:
  • ILB App Service Environment name character limit: 36 characters
  • ELB App Service Environment name character limit: 42 characters

The App Service platform reviews your App Service Environment to confirm in-place migration support. If your scenario doesn't pass all validation checks, you can't migrate at this time using the in-place migration feature. If your environment is in an unhealthy or suspended state, you can't migrate until you make the needed updates.

Troubleshooting

If your App Service Environment doesn't pass the validation checks or you try to perform a migration step in the incorrect order, you can see one of the following error messages:

Overview of the migration process using the in-place migration feature

In-place migration consists of a series of steps that must be followed in order. Key points are given for a subset of the steps. It's important to understand what happens during these steps and how your environment and apps are impacted. After reviewing the following information and when you're ready to migrate, follow the step-by-step guide.

Validate that migration is supported using the in-place migration feature for your App Service Environment

The platform validates that your App Service Environment can be migrated using the in-place migration feature. If your App Service Environment doesn't pass all validation checks, you can't migrate at this time using the in-place migration feature. See the troubleshooting section for details of the possible causes of validation failure. If your environment is in an unhealthy or suspended state, you can't migrate until you make the needed updates. If you can't migrate using the in-place migration feature, see the manual migration options.

The validation also checks if your App Service Environment is on the minimum build required for migration. This build might be newer than the standard build that is deployed with the routine platform upgrade/maintenance cycle. The minimum build is updated periodically to ensure the latest bug fixes and improvements are available. If your App Service Environment isn't on the minimum build, you need to start the upgrade yourself. This upgrade is a standard process where your App Service Environment isn't impacted, but you can't scale or make changes to your App Service Environment while the upgrade is in progress. You can't migrate until the upgrade finishes. Upgrades can take 8-12 hours to complete or longer depending on the size of your environment. If you plan a specific time window for your migration, you should run the validation check 24-48 hours before your planned migration time to ensure you have time for an upgrade if one is needed.

Generate IP addresses for your new App Service Environment v3

The platform creates the new inbound IP (if you're migrating an ELB App Service Environment) and the new outbound IP addresses. While these IPs are getting created, activity with your existing App Service Environment isn't interrupted, however, you can't scale or make changes to your existing environment. This process takes about 15 minutes to complete.

When completed, you'll be given the new IPs that your future App Service Environment v3 uses. These new IPs have no effect on your existing environment. The IPs used by your existing environment continue to be used up until your existing environment is shut down during the migration step.

Update dependent resources with new IPs

Once the new IPs are created, you have the new default outbound to the internet public addresses. In preparation for the migration, you can adjust any external firewalls, DNS routing, network security groups, and any other resources that rely on these IPs. For ELB App Service Environment, you also have the new inbound IP address that you can use to set up new endpoints with services like Traffic Manager. It's your responsibility to update any and all resources that will be impacted by the IP address change associated with the new App Service Environment v3. Don't move on to the next step until you've made all required updates. This step is also a good time to review the inbound and outbound network dependency changes when moving to App Service Environment v3 including the port change for the Azure Load Balancer health probe, which now uses port 80.

Delegate your App Service Environment subnet

App Service Environment v3 requires the subnet it's in to have a single delegation of Microsoft.Web/hostingEnvironments. Migration can't succeed if the App Service Environment's subnet isn't delegated or you delegate it to a different resource.

Acknowledge instance size changes

Your App Service plans are converted from Isolated to the corresponding Isolated v2 tier as part of the migration. For example, I2 is converted to I2v2. Your apps might be over-provisioned after the migration since the Isolated v2 tier has more memory and CPU per corresponding instance size. You have the opportunity to scale your environment as needed once migration is complete. For more information, review the SKU details.

Ensure there are no locks on your resources

Virtual network locks block platform operations during migration. If your virtual network has locks, you need to remove them before migrating. The locks can be readded if needed once migration is complete. Locks can exist at three different scopes: subscription, resource group, and resource. When you apply a lock at a parent scope, all resources within that scope inherit the same lock. If you have locks applied at the subscription, resource group, or resource scope, they need to be removed before the migration. For more information on locks and lock inheritance, see Lock your resources to protect your infrastructure.

Ensure there are no Azure Policies blocking migration

Azure Policy can be used to deny resource creation and modification to certain principals. If you have a policy that blocks the creation of App Service Environments or the modification of subnets, you need to remove it before migrating. The policy can be readded if needed once migration is complete. For more information on Azure Policy, see Azure Policy overview.

Choose your App Service Environment v3 configurations

Your App Service Environment v3 can be deployed across availability zones in the regions that support it. This architecture is known as zone redundancy. Zone redundancy can only be configured during App Service Environment creation. If you want your new App Service Environment v3 to be zone redundant, enable the configuration during the migration process. Any App Service Environment that is using the in-place migration feature to migrate can be configured as zone redundant as long as you're using a region that supports zone redundancy for App Service Environment v3. If you're existing environment is using a region that doesn't support zone redundancy, the configuration option is disabled and you can't configure it. The in-place migration feature doesn't support changing regions. If you'd like to use a different region, use one of the manual migration options.

If your existing App Service Environment uses a custom domain suffix, you're prompted to configure a custom domain suffix for your new App Service Environment v3. You need to provide the custom domain name, managed identity, and certificate. For more information on App Service Environment v3 custom domain suffix including requirements, step-by-step instructions, and best practices, see Configure custom domain suffix for App Service Environment. You must configure a custom domain suffix for your new environment even if you no longer want to use it. Once migration is complete, you can remove the custom domain suffix configuration if needed.

If your migration includes a custom domain suffix, for App Service Environment v3, the custom domain isn't displayed in the Essentials section of the Overview page of the portal as it is for App Service Environment v1/v2. Instead, for App Service Environment v3, go to the Custom domain suffix page where you can confirm your custom domain suffix is configured correctly. Also, on App Service Environment v2, if you have a custom domain suffix, the default host name includes your custom domain suffix and is in the form APP-NAME.internal.contoso.com. On App Service Environment v3, the default host name always uses the default domain suffix and is in the form APP-NAME.ASE-NAME.appserviceenvironment.cn. This difference is because App Service Environment v3 keeps the default domain suffix when you add a custom domain suffix. With App Service Environment v2, there's only a single domain suffix.

Migrate to App Service Environment v3

After completing the previous steps, you should continue with migration as soon as possible.

Migration requires a three to six hour service window for App Service Environment v2 to v3 migrations. Up to a six hour service window is required depending on environment size for v1 to v3 migrations. The service window might be extended in rare cases where manual intervention by the service team is required. During migration, scaling and environment configurations are blocked and the following events occur:

• The existing App Service Environment is shut down and replaced by the new App Service Environment v3.
• All App Service plans in the App Service Environment are converted from the Isolated to Isolated v2 tier.
• All of the apps that are on your App Service Environment are temporarily down. You should expect about one hour of downtime during this period.
  • If you can't support downtime, see migration-alternatives.
• The public addresses that are used by the App Service Environment change to the IPs generated during the IP generation step.

The following statuses are available during the migration process:

As in the IP generation step, you can't scale, modify your App Service Environment, or deploy apps to it during this process. When migration is complete, the apps that were on the old App Service Environment are running on the new App Service Environment v3.

Use the in-place migration feature

Prerequisites

Ensure that you understand how migrating to App Service Environment v3 affects your applications. Review the migration process to understand the process timeline and where and when you need to get involved. Also review the FAQs, which can answer some of your questions.

Ensure that there are no locks on your virtual network, resource group, resource, or subscription. Locks block platform operations during migration.

Ensure that no Azure policies are blocking actions that are required for the migration, including subnet modifications and Azure App Service resource creations. Policies that block resource modifications and creations can cause migration to get stuck or fail.

Since scaling is blocked during the migration, you should scale your environment to the desired size before starting the migration. If you need to scale your environment after the migration, you can do so once the migration is complete. If you have auto-scaling enabled, if a scaling event occurs before the migration starts, your migration is blocked until the scaling event completes. You should disable auto-scaling before starting the migration to avoid this issue.

ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-ASE-Resource-Group>
VNET_RG=<Your-VNet-Resource-Group>
ASE_ID=$(az appservice ase show --name $ASE_NAME --resource-group $ASE_RG --query id --output tsv)

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=validation"

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=PreMigrationUpgrade"

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=premigration"

az rest --method get --uri "${ASE_ID}?api-version=2021-02-01" --query properties.status

az rest --method get --uri "${ASE_ID}/configurations/networking?api-version=2021-02-01"

az network vnet subnet update --resource-group $VNET_RG --name <subnet-name> --vnet-name <vnet-name> --delegations Microsoft.Web/hostingEnvironments

az lock list --resource-group $VNET_RG --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks

az lock delete --resource-group $VNET_RG --name <lock-name> --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westchinanorth2",
    "properties": {
        "zoneRedundant": true
    }
}

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westchinanorth2",
    "properties": {
        "zoneRedundant": true,
        "customDnsSuffixConfiguration": {
            "dnsSuffix": "internal.contoso.com",
            "certificateUrl": "https://contoso.vault.azure.cn/secrets/myCertificate",
            "keyVaultReferenceIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/asev3-migration/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ase-managed-identity"
        }
    }
}

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westchinanorth2",
    "properties": {
        "customDnsSuffixConfiguration": {
            "dnsSuffix": "internal.contoso.com",
            "certificateUrl": "https://contoso.vault.azure.cn/secrets/myCertificate",
            "keyVaultReferenceIdentity": "SystemAssigned"
        }
    }
}

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=fullmigration" --body @parameters.json

az rest --method get --uri "${ASE_ID}/operations?api-version=2022-03-01"

az rest --method get --uri "${ASE_ID}/operations/<operation-id>/details/default?api-version=2022-09-01"

az appservice ase show --name $ASE_NAME --resource-group $ASE_RG

Pricing

There's no cost to migrate your App Service Environment. When you use the in-place migration feature, you stop being charged for your previous App Service Environment as soon as it shuts down during the migration process. You begin getting charged for your new App Service Environment v3 as soon as it gets deployed. For more information about App Service Environment v3 pricing, see the pricing details.

When you migrate to App Service Environment v3 from previous versions, there are scenarios that you should consider that can potentially reduce your monthly cost. Consider reservations and savings plans to further reduce your costs. For information on cost saving opportunities, see Cost saving opportunities after upgrading to App Service Environment v3.

Scale down your App Service plans

The App Service plan SKUs available for App Service Environment v3 run on the Isolated v2 (Iv2) tier. The number of cores and amount of RAM are effectively doubled per corresponding tier compared the Isolated tier. When you migrate, your App Service plans are converted to the corresponding tier. For example, your I2 instances are converted to I2v2. While I2 has two cores and 7-GB RAM, I2v2 has four cores and 16-GB RAM. If you expect your capacity requirements to stay the same, you're over-provisioned and paying for compute and memory you're not using. For this scenario, you can scale down your I2v2 instance to I1v2 and end up with a similar number of cores and RAM that you had previously.

Frequently asked questions

• What if migrating my App Service Environment is not currently supported?
  You can't migrate using the in-place migration feature at this time. If you have an unsupported environment and want to migrate immediately, see the manual migration options.
• How do I choose which migration option is right for me?
  Review the migration path decision tree to decide which option is best for your use case.
• How do I know if I should use the in-place migration feature?
  The in-place migration feature is best for customers who want to migrate to App Service Environment v3 with minimal changes to their networking configurations and can support about one hour of application downtime. If you can't support downtime, see the manual migration options. The in-place migration feature creates your App Service Environment v3 in the same subnet as your existing environment and uses the same networking infrastructure. You might have to account for the inbound and outbound IP address changes if you have any dependencies on these specific IPs.
• Will I experience downtime during the migration?
  Yes, you should expect about one hour of downtime during the three to six hour service window during the migration step, so plan accordingly. If you have a different App Service Environment that you can point traffic to while you migrate using the in-place migration feature, you can eliminate application downtime. If you don't have another App Service Environment and you can't support downtime, see the manual migration options.
• Will I need to do anything to my apps after the migration to get them running on the new App Service Environment?
  No, all of your apps running on the old environment are automatically migrated to the new environment and run like before. No user input is needed.
• What if my App Service Environment has a custom domain suffix?
  The in-place migration feature supports this migration scenario.
• What if my App Service Environment is zone pinned?
  Zone pinned App Service Environment v2 is now a supported scenario for migration using the migration feature. App Service Environment v3 doesn't support zone pinning. When migrating to App Service Environment v3, you can choose to configure zone redundancy or not.
• What if my App Service Environment has IP SSL addresses? IP SSL isn't supported on App Service Environment v3. You must remove all IP SSL bindings before migrating using the migration feature or one of the manual options. If you intend to use the in-place migration feature, once you remove all IP SSL bindings, you pass that validation check and can proceed with the automated migration.
• What properties of my App Service Environment will change?
  You're on App Service Environment v3 so be sure to review the features and feature differences compared to previous versions. For ILB App Service Environment, you keep the same ILB IP address. For internet facing App Service Environment, the public IP address and the outbound IP address change. Note for ELB App Service Environment, previously there was a single IP for both inbound and outbound. For App Service Environment v3, they're separate. For more information, see App Service Environment v3 networking. For a full comparison of the App Service Environment versions, see App Service Environment version comparison.
• What happens if migration fails or there is an unexpected issue during the migration?
  If there's an unexpected issue, support teams are on hand. You should migrate dev environments before touching any production environments to learn about the migration process and see how it impacts your workloads.
• What happens to my old App Service Environment?
  If you decide to migrate an App Service Environment using the in-place migration feature, the old environment gets shutdown, deleted, and all of your apps are migrated to a new environment. Your old environment is no longer accessible. A rollback to the old environment isn't possible.
• What will happen to my App Service Environment v1/v2 resources after 31 August 2024?
  After 31 August 2024, if you don't to App Service Environment v3, your App Service Environment v1/v2s and the apps deployed in them will no longer be available. App Service Environment v1/v2 is hosted on App Service scale units running on Cloud Services (classic) architecture that will be retired on 31 August 2024. Because of this, App Service Environment v1/v2 will no longer be available after that date. Migrate to App Service Environment v3 to keep your apps running or save or back up any resources or data that you need to maintain.

Next steps