Migrating API Management platform version from stv1 to stv2
Published Oct 18 2023 10:16 AM 11.7K Views
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.
Single-tenant v2
Azure-allocated compute infrastructure that supports availability zones, private endpoints
Developer, Basic, Standard, Premium
Single-tenant v1
Azure-allocated compute infrastructure
Developer, Basic, Standard, Premium
Multi-tenant v1
Shared infrastructure that supports native autoscaling and scaling down to zero in times of no traffic


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.



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.
Version history
Last update:
‎Jun 21 2024 09:34 AM
Updated by: