Background Information
To enhance service capabilities, the API Management service has released a new compute-platform version. A more current compute platform version (stv2) is available with additional features and improvements such as support for Azure Private Link and other networking features. We recommend all users migrate the Azure API Management service from stv1 compute platform to the stv2 compute platform to take advantage of upcoming features.
This article is to describe and compare the stv1 and stv2 compute platform to provide users with more perspectives.
In addition, this article introduces recommended migration solutions to help users on compute platform migration.
Agenda
- Compute Platform Versions on API Management Service
- Difference between stv1 and stv2
- Way to find the compute platform version of the API Management Service
- Compute platform migration plan
Compute Platform Version on API Management Service
There are 3 versions of compute platform on API Management Service, including stv2, stv1 and mtv1. The following table summarizes these compute platforms currently used for instances in the different API Management service tiers.
|
Version |
Description |
Architecture |
Tiers |
|
stv2 |
Single-tenant v2 |
Virtual machine scale sets: Azure-allocated compute infrastructure that supports availability zones, private endpoints |
· Developer · Basic · Standard · Premium |
|
stv1 |
Single-tenant v1 |
Cloud Service (classic): Azure-allocated compute infrastructure |
· Developer · Basic · Standard · Premium |
|
mtv1 |
Multi-tenant v1 |
App service: shared infrastructure that supports native autoscaling and scaling down to zero in times of no traffic |
· Consumption |
Newly created instances without virtual network in tiers of Developer, Basic, Standard, and Premium automatically adopt stv2 compute platform. Besides, some existing instances in Developer and Premium tiers configured with virtual networks and static public IP or availability zones are using stv2 compute platform as well.
Notice:
- The stv2 platform currently isn't available in the US Government cloud or in the following Azure regions: China East, China East 2, China North, China North 2.
Difference between stv1 and stv2
User can find details about the differences between STV1 and STV2 can be found at Compute Platform Versions for Azure API management service - Microsoft Community Hub
How to check compute platform version
There are two options to find the platform version of the API Management Service.
- Option 1: Find on Azure Portal
- Option 2: Query by REST API
Please refer to the blog to retrieve more details about how to find the platform version of APIM service.
Compute Platform Versions for Azure API management service - Microsoft Community Hub
Migrate the API Management Service to the stv2 platform
To migrate the API Management Service, the following migration options and the relevant advantages and disadvantages can be referred to decide your migration plan.
Pre-check
- Check the network status of the API Management Service: If an external/internal virtual network injected or not.
- The SKU of the API Management Service.
Based on the network status of the API Management Service, there are options for the APIM service which is injected in Virtual Network and for the API Management Service which is not connected to a Virtual Network. In addition, some options are only available in certain pricing tiers.
A - API Management Service which is injected in Virtual Network
Option 1: Deploy a new instance in existing tier and migrate configurations
- Available SKUs: Developer and Premium
The followings are how to backup and restore the API Management Service from the current instance hosted on stv1 platform to the new instance hosted on the stv2 platform.
- A new or existing subnet in the same region and subscription as your API Management instance. The subnet must be different from the one currently used for the instance hosted on the stv1 platform, and a network security group must be attached.
- A new or existing Standard SKU public IPv4 address resource in the same region and subscription as your API Management instance. When user creates a public IP address, a DNS label must be assigned, an "A record" that starts with the specified label and resolves to this public IP address will be registered with the Azure-provided DNS servers.
Notice: User must add the new public IP address to the access allow list on your client/backend systems (wherever the current API Management public IP address is allow-listed. This would be side-by-side). - Create a new APIM service with virtual network and the Standard SKU public IPv4 address created in previous step within the same region. The new API Management Service SKU should be the same as the current one.
Notice: It’s required to provide a new public IP address for the new API Management Service. Otherwise, the APIM will be deployed as stv1 platform. - Then to create backup of existing API Management Service and then restore the backup to the newly created APIM service. For more information, please refer to Backup and restore your Azure API Management instance for disaster recovery.
Advantages:
- No down time for the Premium SKU. But for the developer SKU, the service would be down during the migration.
- Users can own the Public IP Address which means it can remain the same for this service for as long as needed.
- The new APIM service will be based on new stv2 platform which provides better scalability.
Disadvantages:
- Service IP Address will be changed.
- Administrative overhead of creating a new subnet and NSG rules.
- Additional cost of running two API Management services in parallel.
- Constraints
- What is not backed up
Reference: Backup and restore, Migration script for the developer portal, APIOps with Azure API Management.
Option 2: Update VNet configuration/ Enable Zone-redundancy for your APIM service - to change the subnet and assign a new public IP address
- Available SKUs: Developer and Premium (Zone-redundancy is only supported for Premium tier)
- A new or existing subnet in the same region and subscription as your API Management instance. The subnet must be different from the one currently used for the instance hosted on the stv1 platform, and a network security group must be attached.
- A new or existing Standard SKU public IPv4 address resource in the same region and subscription as your API Management instance.
Notice: User must add the new public IP address to the access allow list on your client/backend systems (wherever the current API Management public IP address is allow-listed. This would be side-by-side).
To update VNet configuration
- Change the subnet and assign the Standard SKU public IPv4 address created in previous step to the API Management Service. On the Azure portal, you can navigate to the menu Network > Virtual network.
To enable Zone-redundancy
- Select Locations in the menu in the Azure portal, and then select the location to be migrated. The location must support availability zones.
- Select the number of scale Units desired in the location.
- In Availability zones, select one or more zones. The number of units selected must be distributed evenly across the availability zones. For example, if you selected 3 units, select 3 zones so that each zone hosts one unit.
- Select the new subnet and new public IP address in the location.
Advantages:
- No down time for the Premium SKU. But for the developer SKU, the service would be down during the migration.
- You can own the Public IP Address which means it can remain the same for this service for as long as needed.
- If user enables Zone-redundancy, it provides resiliency and high availability to a service instance in a specific Azure region.
Disadvantages:
- For APIM service in developer SKU the service would be down during the migration.
- Service IP Address will be changed.
- Administrative overhead of creating a new subnet and NSG rules.
Reference: Azure API Management compute platform, Migrate Azure API Management to availability zone support, Migrate Azure API Management to availability zone support | Microsoft Learn
B - APIM service which is not connected to any VNet
Option 1: Deploy a new instance in existing tier and migrate configurations
- Available SKUs: Developer, Standard, Basic and Premium
The followings are how to backup and restore the API Management Service from the current instance hosted on stv1 platform to the new instance hosted on the stv2 platform.
- Create a new API Management Service without any virtual network in the same region and its SKU should be the same as the current one.
- Then to create backup of existing API Management Service and then restore the backup to the newly created API Management Service. For more information, please refer to Backup and restore your Azure API Management instance for disaster recovery.
Advantages:
- The new APIM service will be based on a new stv2 platform which provides better scalability.
Disadvantages:
- For APIM service in developer SKU the service would be down during the migration.
- Service IP Address will be changed.
- Additional cost of running two API Management services in parallel.
- Constraints
- What is not backed up
Reference: Backup and restore, Migration script for the developer portal, APIOps with Azure API Management.
Option 2: Enable Zone-redundancy for your API Management Service
- Available SKUs: Premium only
Using this option to migrate an existing location of your API Management instance to availability zones will also migrate the instance to the stv2 platform.
- Select Locations in the menu in the Azure portal, and then select the location to be migrated. The location must support availability zones.
- Select the number of scale Units desired in the location.
- In Availability zones, select one or more zones. The number of units selected must be distributed evenly across the availability zones. For example, if you selected 3 units, select 3 zones so that each zone hosts one unit.
Advantages:
- No down time.
- The new API Management Service will be based on a new stv2 platform which provides better scalability.
- The API Management service supports Zone redundancy, which provides resiliency and high availability to a service instance in a specific Azure region.
Disadvantages:
- Service IP Address will be changed.
- Increasing cost of Zone-Redundancy if user add new instances.
Reference: Migrate Azure API Management to availability zone support
Option 3: Change the service tier (downgrade to Developer or upgrade to Premium) then follow migration options in new tier
- Available SKUs: Standard and Basic
- Navigate to your API Management instance in the Azure portal.
- Select Pricing tier in the menu.
- Select the desired service tier from the price table then select "Apply".
Notice: User can use the slider to specify the number of units for your API Management service after the change. - After the price tier change, follow above migration options for corresponding pricing tier.
Advantages:
- Scaling up/down operations from the Developer tier to higher tier or from higher tier to Developer tier, there will be downtime. Otherwise, there is no downtime.
Disadvantages:
- For changing and migrating to Developer tier, the service would be down during the migration.
- Service IP Address will be changed.
- There is increasing cost if user upgrades the APIM to Premium tier.
Reference: Migrate Azure API Management to availability zone support
C- Migration triggered by Azure backend
Option 1: Open a support case to migrate your APIM by Azure backend
- Available SKUs:
- Standard, Basic tier
- Developer and Premium, service is not connected to any virtual network and subnet
If users have any concerns about business impacts of migrating the API Management Service to new compute platform which needs technical help, we recommend users to open a support ticket with clear business justification.
The business impact of migration can help support engineer provide a suitable migration plan.
Azure API Management - Help and support | Microsoft Learn
Disadvantages:
- Downtime happens and it cannot be estimated because all migration will be progressed in backend and cannot be traced.
- Service IP Address will be changed. And users can only get the new service IP address from the portal after the operation is complete.
- The change of service IP may cause some disruptions for your clients if your client services are connecting to API Management Service by IP address. Besides, it may cause backend connectivity issue if the backend requires whitelisting of new IP address. Custom domain will also be impacted because it is pointing to the original IP address.
Consideration
- The migration can take 45 minutes or more to update the API Management instance. The Developer tier has downtime during the process. The Basic and higher SKUs don't have downtime during the process. After the migration is done, user can check the current platform version of the APIM service by checking options mentioned in previous section.
- The change of service IP may cause some disruptions for your clients if your client services are connecting to API Management Service by IP address. Besides, it may cause backend connectivity issue if the backend requires whitelisting of new IP address. Custom domain will also be impacted because it is pointing to the original IP address. Please be aware that you must add the new public IP address to the access allow list on your client/backend systems (wherever the current API Management public IP address is allow-listed. This would be side-by-side)
- If the API Management instance has auto-scale settings in the primary location, users might need to adjust the auto-scale settings after enabling zone redundancy. The number of API Management units in auto-scale rules and limits must be a multiple of the number of zones.
- Currently, the stv2 platform currently isn't available in the US Government cloud or in the following Azure regions: China East, China East 2, China North, China North 2.