Edit

Migrate an API Management instance hosted on the stv1 platform to stv2

  • Article

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

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:

  1. In the portal, navigate to your API Management instance.
  2. In the left menu, select Network > Virtual network.
  3. Select the network connection in the location you want to update.
  4. Select the virtual network, subnet, and IP address resources you want to configure, and select Apply.
  5. Continue configuring VNet settings for the remaining locations of your API Management instance.
  6. 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

  1. In the portal, navigate to your original VNet.
  2. In the left menu, select Subnets, and then the original subnet.
  3. 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.
  4. 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