Blog Post

FastTrack for Azure
4 MIN READ

Migrating API Management platform version from stv1 to stv2

srinipadala's avatar
srinipadala
Icon for Microsoft rankMicrosoft
Oct 18, 2023
The infrastructure associated with the API Management stv1 compute platform version will be retired effective 31 August 2024 as announced here. A more current compute platform version (stv2) is already available, and provides enhanced service capabilities. This blog outlines the migration approach and options. 
 

What are the stv1 and stv2 platforms?

Azure API Management is a cloud platform-as-a-service (PaaS) that abstracts many details of the infrastructure used to host and run your service. A more current compute platform version (stv2) is already available, and provides enhanced service capabilities.
The following table summarizes the compute platforms currently used for instances in the different API Management service tiers.
 
Version
Description
Architecture
Tiers
stv2
Single-tenant v2
Azure-allocated compute infrastructure that supports availability zones, private endpoints
Developer, Basic, Standard, Premium
stv1
Single-tenant v1
Azure-allocated compute infrastructure
Developer, Basic, Standard, Premium
mtv1
Multi-tenant v1
Shared infrastructure that supports native autoscaling and scaling down to zero in times of no traffic
Consumption

 

Why should you migrate to stv2?

The stv2 compute platform comes with additional features and improvements such as support for Azure Private Link and other networking features. New instances created in service tiers other than the Consumption tier are mostly hosted on the stv2 platform already. Existing instances on the stv1 platform will continue to work normally until the retirement date, but those instances won’t receive the latest features available to the stv2 platform. Support for stv1 instances will be retired by 31 August 2024. After that date, any instance hosted on the stv1 platform won't be supported, and could experience system outages. 
 

How to migrate to stv2?

To migrate your existing instances hosted on the stv1 compute platform to the stv2 compute platform, you need to follow different steps depending on whether or not your API Management instance is currently deployed (injected) in an external, internal VNet or None.
  • For an API Management instance that’s not deployed in a VNet, you can use the portal or the REST API
  • For an API Management instance that’s deployed in a VNet, you need to manually update the VNet configuration settings.
Below is a decision tree to navigate the migration process:
 

 

 
 
Non-VNet Injected instances
  • Ability to use the portal for non-VNet injected instances.
  • Management plane operations like locations, scaling, custom domains, CA certificates will not be allowed for 30-45 mins.
  • Ability to preserve the IP (15 min downtime required) or create a new IP (No downtime required)
 
VNet injected instances
  • VNet injected instances need a public IP to be created. This IP address is used for management traffic alone and is detailed here.
  • In-place upgrade does not require downtime as the old and new gateways will be available for some time, to facilitate validation and DNS update.
  • Instances which are using the default DNS name in external mode will have the DNS auto-updated and any misconfigurations may result in a downtime.
  • Networking and DNS updates are required.
  • Side-by-side deployments facilitate validation.
  • Side-by-side deployments cannot reuse the default domain name.

For detailed instructions on the migration refer to the scenarios

For side-by-side deployment of APIM:
 

!!! UPDATE 12/13/23 - Here is a video walkthrough of the migration scenarios.

 

!!! UPDATE 05/10/24

APIM no longer needs a customer provided public IP. If no public IP is provided, APIM will automatically assign and manage the public IP

 

!!! UPDATE 06/19/24

The platform migration blade now supports migration of vnet injected instances. Select the location of choice and provide the dependencies.

 

You can self-serve the time period to keep the old and new gateways around by choosing between the below

  • Return to the original subnet as soon as possible.

Please note that this option will not move the gateway to the original subnet but just removes the old gateway immediately after the new gateway is provisioned. This ensures that the old subnet is vacated early paving way for triggering the gateway movement back

 

  • Stay in the new subnet and keep stv1 compute for 48 hours

This option will keep the old gateway for 48 hours from the time the migration is triggered. This will help validation of the new gateway and cutover on demand.

 

There is no longer a need to create a support ticket to set the retention period.

 

Conclusion

Migrating your Azure API Management instance from the stv1 platform to the stv2 platform is a necessary step to ensure proper operation of your service and take advantage of the latest features and improvements. You should plan your migration accordingly and follow the steps provided in this blog.
Updated Jun 21, 2024
Version 3.0
App

27 Comments

Sort By
Show More
  • Nish_'s avatar
    Nish_
    Copper Contributor
    Jan 05, 2024

    We have APIM instance created with vNET. We are planning to migrate to stv2 but during migration it's failing with error  "message": "Service with private link feature is not supported. Refer https://aka.ms/apim-privateendpoint". I can't create different subnet because we need to add different location for geo redundancy and we only have one region supported which is WUS-2 . In order to create different vNET we need spoke vNET and stuffs. How can we upgrade to v2 with in place upgrade and less / no impact to our existing Prod services and usage.

  • KK_ML's avatar
    KK_ML
    Copper Contributor
    Jan 04, 2024

    For VNet-injected APIM instance, the IP address will be changed after migration, as a result, clients have to update NSG rules and DNS with the new IP address. This definitely leads to challenges and downtimes of app services in the migration.

     

    Appreciate if you provide a migration option that would minimize the downtime and impact.

  • gyvkoff's avatar
    gyvkoff
    Brass Contributor
    Dec 29, 2023

    srinipadala thank you - is there a way to determine how long the migration will take, so we know when that 15 min of downtime will occur?  We don't have VNnet involved, so is it up to hour hour?

  • srinipadala's avatar
    srinipadala
    Icon for Microsoft rankMicrosoft
    Dec 05, 2023

    gyvkoff - The migration process involves standing up a parallel gateway, releasing the old gateway, reclaiming the old ip and assigning it to the SLB of the new gateway. The instance will be blocked for control plane operations throughout the process. Also, it is important to note that the default domain name will be updated with the New IP (interim) and then once the reclaimed IP is reassigned to the new SLB. If you are using the default domain, there should not be any downtime as long as the client is resolving the IP with caching DNS. If using Custom Domains, since it will stick onto the old IP, they experience a downtime of 15 minutes at the end of the migration.

  • gyvkoff's avatar
    gyvkoff
    Brass Contributor
    Dec 05, 2023

    srinipadala 

     

    The documentation says the following:

     

    https://learn.microsoft.com/en-us/azure/api-management/migrate-stv1-to-stv2?tabs=portal#:~:text=Preserve%20IP%20address,required%20after%20migration.

     

    In the azure portal, in the Platform migration settings, it also states:

    - API requests will be unresponsive for roughly 15 minutes during migration.

    - Network dependencies do not need to be updated. Infrastructure configuration will be locked for 45 mins, affecting locations, regions, custom domains, and CA certificates.

     

    From the time I click the "migrate" button, what is the total elapsed time to complete the migration, and at what point during the migration does the 15 minutes of "unresponsiveness" kick in?  This will help me determine what time to start the migration.