Migrate an API Management instance hosted on the stv1 platform to stv2
You can migrate an API Management instance hosted on the stv1
compute platform to the stv2
platform. This article provides migration steps for two scenarios, depending on whether or not your API Management instance is currently deployed (injected) in an external or internal VNet.
Non-VNet-injected API Management instance - Use the Migrate to stv2 REST API
VNet-injected API Management instance - Manually update the VNet configuration settings
For more information about the stv1
and stv2
platforms and the benefits of using the stv2
platform, see Compute platform for API Management.
Important
- Migration is a long-running operation. Your instance will experience downtime during the last 10-15 minutes of migration. Plan your migration accordingly.
- The VIP address(es) of your API Management will change if you're using scenario 2 mentioned below (service injected in a VNet). For scenario 1 (not injected in a VNet), the VIP will temporarily change during migration for up to 15 minutes, but the original VIP of the service will be restored at the end of the migration operation.
- Migration to
stv2
is not reversible.
Important
Support for API Management instances hosted on the stv1
platform will be retired by 31 August 2024. To ensure proper operation of your API Management instance, you should migrate any instance hosted on the stv1
platform to stv2
before that date.
Availability
Important
This feature is available in the Premium, Standard, Basic, and Developer tiers of API Management.
Prerequisites
- An API Management instance hosted on the
stv1
compute platform. To confirm that your instance is hosted on thestv1
platform, see How do I know which platform hosts my API Management instance?.
Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
Scenario 1: Migrate API Management instance, not injected in a VNet
For an API Management instance that's not deployed in a VNet, invoke the Migrate to stv2
REST API. For example, run the following Azure CLI commands, setting variables where indicated with the name of your API Management instance and the name of the resource group in which it was created.
Note
The Migrate to stv2
REST API is available starting in API Management REST API version 2022-04-01-preview
.
# Verify currently selected subscription
az account show
# View other available subscriptions
az account list --output table
# Set correct subscription, if needed
az account set --subscription {your subscription ID}
# Update these variables with the name and resource group of your API Management instance
APIM_NAME={name of your API Management instance}
RG_NAME={name of your resource group}
# Get resource ID of API Management instance
APIM_RESOURCE_ID=$(az apim show --name $APIM_NAME --resource-group $RG_NAME --query id --output tsv)
# Call REST API to migrate to stv2
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2022-08-01"
Scenario 2: Migrate a network-injected API Management instance
Trigger migration of a network-injected API Management instance to the stv2
platform by updating the existing network configuration to use new network settings (see the following section). After that update completes, as an optional step, you may migrate back to the original VNet and subnet you used.
You can also migrate to the stv2
platform by enabling zone redundancy.
Update VNet configuration
Update the configuration of the VNet in each location (region) where the API Management instance is deployed.
Prerequisites
A new subnet in the current virtual network. (Alternatively, set up a subnet in a different virtual network in the same region and subscription as your API Management instance). A network security group must be attached to the subnet, and NSG rules for API Management must be configured.
A Standard SKU public IPv4 address resource in the same region and subscription as your API Management instance.
Important
When you update the VNet configuration for migration to the stv2
platform, you must provide a public IP address address resource, or migration won't succeed. In internal VNet mode, this public IP address is used only for management operations.
For details, see Prerequisites for network connections.
Update VNet configuration
To update the existing external or internal VNet configuration:
- In the portal, navigate to your API Management instance.
- In the left menu, select Network > Virtual network.
- Select the network connection in the location you want to update.
- Select the virtual network, subnet, and IP address resources you want to configure, and select Apply.
- Continue configuring VNet settings for the remaining locations of your API Management instance.
- In the top navigation bar, select Save, then select Apply network configuration.
The virtual network configuration is updated, and the instance is migrated to the stv2
platform.
(Optional) Migrate back to original VNet and subnet
You may optionally migrate back to the original VNet and subnet you used in each region before migration to the stv2
platform. To do so, update the VNet configuration again, this time specifying the original VNet and subnet. As in the preceding migration, expect a long-running operation, and expect the VIP address to change.
Prerequisites
The original subnet and VNet. A network security group must be attached to the subnet, and NSG rules for API Management must be configured.
A new Standard SKU public IPv4 address resource in the same region and subscription as your API Management instance.
Update VNet configuration
- In the portal, navigate to your original VNet.
- In the left menu, select Subnets, and then the original subnet.
- Verify that the original IP addresses were released by API Management. Under Available IPs, note the number of IP addresses available in the subnet. All addresses (except for Azure reserved addresses) should be available. If necessary, wait for IP addresses to be released.
- Repeat the migration steps in the preceding section. In each region, specify the original VNet and subnet, and a new IP address resource.
Verify migration
To verify that the migration was successful, check the platform version of your API Management instance. After successful migration, the value is stv2
.
Next steps
- Learn about stv1 platform retirement.
- For instances deployed in a VNet, see the Virtual network configuration reference.
Feedback
Submit and view feedback for