Migrating API Management platform version from stv1 to stv2

[srinipadala]

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

• Migrate API Management instance, not injected in a VNet
• Migrate a network-injected API Management instance

For side-by-side deployment of APIM:

• Create a new APIM instance in stv2 with VNet integration. Additionally review internal, application gateway integration and force tunneling.
• Backup the old APIM instance.
• Restore the backup to the new APIM instance.
• Migrate developer portal contents from the old instance to the new instance.
• Setup service configurations that are not included in the backup.
• Validate the configuration.
• Update the DNS records to point to the new instance.

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

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.