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.

• Scenario 1: Non-VNet-injected API Management instance - Migrate your instance using the portal or the Migrate to stv2 REST API.

• Scenario 2: VNet-injected API Management instance - Migrate your instance by manually updating 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.

Availability

What happens during migration?

API Management platform migration from stv1 to stv2 involves updating the underlying compute alone and has no impact on the service/API configuration persisted in the storage layer.

• The upgrade process involves creating a new compute in parallel to the old compute. The old compute takes 15-45 mins to be deleted with an option to delay it for up to 48 hours. The 48 hour delay option is only available for VNet injected services.
• The API Management status in the Portal will be "Updating".
• Azure manages the management endpoint DNS, and updates to the new compute immediately on successful migration.
• The Gateway DNS still points to the old compute if custom domain is in use.
• If custom DNS isn't in use, the Gateway and Portal DNS points to the new compute immediately.
• For an instance in internal VNet mode, customer manages the DNS, so the DNS entries continue to point to old compute until updated by the customer.
• It's the DNS that points to either the new or the old compute and hence no downtime to the APIs.
• Changes are required to your firewall rules, if any, to allow the new compute subnet reach the backends.

Prerequisites

• An API Management instance hosted on the stv1 compute platform. To confirm that your instance is hosted on the stv1 platform, see How do I know which platform hosts my API Management instance?.

• 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, migrate your instance using the Platform migration blade in the Azure portal, or invoke the Migrate to stv2 REST API.

During the migration, the VIP address of your API Management instance will be preserved.

• API requests will be unresponsive for approximately 15 minutes while the IP address is migrated to the new infrastructure.
• Infrastructure configuration (such as custom domains, locations, and CA certificates) will be locked for 45 minutes.
• No further configuration is required after migration.

#!/bin/bash
# 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 and preserve VIP address
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "PreserveIp"}'

Verify migration

To verify that the migration was successful, when the status changes to Online, check the platform version of your API Management instance. After successful migration, the value is stv2.

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 can 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.

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 can 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, when the status changes to Online, check the platform version of your API Management instance. After successful migration, the value is stv2.
• Additionally check the Network status to ensure connectivity of the instance to its dependencies. In the portal, in the left-hand menu, under Deployment and infrastructure, select Network > Network status.

Update network dependencies

On successful migration, update any network dependencies including DNS, firewall rules, and VNets to use the new VIP address/subnet address space.

Help and support

If you have a support plan and you need technical help, create a support request.

1. For Summary, type a description of your issue, for example, "stv1 retirement".
2. Under Issue type, select Technical.
3. Under Subscription, select your subscription.
4. Under Service, select My services, then select API Management Service.
5. Under Resource, select the Azure resource that you’re creating a support request for.
6. For Problem type, select Administration and Management.
7. For Problem subtype, select Upgrade, Scale or SKU Changes.

Frequently asked questions

• What information do we need to choose a migration path?

  • What is the Network mode of the API Management instance?
  • Are custom domains configured?
  • Is a firewall involved?
  • Any known dependencies taken by upstream/downstream on the IPs involved?
  • Is it a multi-geo deployment?
  • Can we modify the existing instance or is a parallel setup required?
  • Can there be downtime?
  • Can the migration be done in nonbusiness hours?

• What are the prerequisites for the migration?

  VNet-injected instances: you'll need a new subnet and public IP address to migrate (either External or Internal modes). The subnet must have an NSG attached to it following the rules for stv2 platform as described here.

  Non-VNet instances: no prerequisites are required. If you migrate preserving your public IP address, this will render your API Management instance unresponsive for approximately 15 minutes. If you can't afford any downtime, then choose the "New IP" option that makes API Management available on a new IP. Network dependencies need to be updated with the new public virtual IP address.

• Will the migration cause a downtime?

  VNet-injected instances: since the old gateway is purged only after the new compute is healthy and online, there shouldn't be any downtime if default hostnames are in use. It's critical that all network dependencies are taken care of upfront, for the impacted APIs to be functional. However, if custom domains are in use, they'll be pointing to the purged compute until they're updated which may cause a downtime. Alternatively, you can request for the old gateway to be retained for up to 48 hours by creating a support ticket in advance. Having the old and the new compute coexist will facilitate validation, and then you can update the custom DNS entries at will.

  Non-VNet instances: there's a downtime of approximately 15 minutes only if you choose to preserve the original IP address. However, there's no downtime if you migrate with a new IP address.

• My traffic is force tunneled through a firewall. What changes are required?

  • First of all, make sure that the new subnet you created for the migration retains the following configuration (they should be already configured in your current subnet):
    • Enable service endpoints as described here
    • The UDR (user-defined route) has the hop from ApiManagement service tag set to "Internet" and not only to your firewall address
  • The requirements for NSG configuration for stv2 remain the same whether you have firewall or not; make sure your new subnet has it
  • Firewall rules referring to the current IP address range of the API Management instance should be updated to use the IP address range of your new subnet.

• Is it impossible that data or configuration losses can occur by/during the migration?

  stv1 to stv2 migration involves updating the compute platform alone and the internal storage layer isn't changed. Hence all the configuration is safe during the migration process.

• How to confirm that the migration is complete and successful?

  The migration is considered complete and successful when the status in the overview page reads "Online" along with the platform version being either 2.0 or 2.1. Also verify that the network status in the network blade shows green for all required connectivity.

• Can I do the migration using the portal?

  • Yes, the Platform migration blade in Azure portal guides through the options for non-VNet injected instances.
  • VNet-injected instances can be migrated by changing the subnet in the Network blade.

• Can I preserve the IP address of the instance?

  VNet-injected instances: there's no way currently to preserve the IP address if your instance is injected into a VNet

  Non-VNet instances: the IP address can be preserved, but there will be a downtime of approximately 15 minutes.

• Is there a migration path without modifying the existing instance?

  Yes, you need a side-by-side migration. That means you create a new API Management instance in parallel with your current instance and copy the configuration over to the new instance.

• What happens if the migration fails?

  If your API Management instance doesn't show the platform version as stv2 and status as "Online" after you initiated the migration, it probably failed. Your service is automatically rolled back to the old instance and no changes are made. If you have problems (such as if status is "Updating" for more than 2 hours), contact Azure support.

• What functionality is not available during migration?

  VNet injected instances: API requests remain responsive during migration. Infrastructure configuration (such as custom domains, locations, and CA certificates) is locked for 30 minutes. After migration, you'll need to update any network dependencies including DNS, firewall rules, and VNets to use the new VIP address.

  Non-VNet-injected instances: - If you opted to preserve the original IP address: If you preserve the VIP address, API requests are unresponsive for approximately 15 minutes while the IP address is migrated to the new infrastructure. Infrastructure configuration (such as custom domains, locations, and CA certificates) is locked for 45 minutes. - If you opted to migrate to a new IP address: API requests remain responsive during migration. Infrastructure configuration (such as custom domains, locations, and CA certificates) is locked for 30 minutes. After migration, you'll need to update any network dependencies including DNS, firewall rules, and VNets to use the new VIP address.

• How long will the migration take?

  The expected duration for the whole migration is approximately 45 minutes. The indicator to check if the migration was already performed is to check if Status of your instance is back to "Online" and not "Updating". If it says "Updating" for more than 2 hours, contact Azure support.

• Is there a way to validate the VNet configuration before attempting migration?

  You can optionally deploy a new API Management instance with the new VNet, subnet, and VIP that you use for the actual migration. Navigate to the Network status page after the deployment is completed, and verify if every endpoint connectivity status is green. If yes, you can remove this new API Management instance and proceed with the real migration with your original stv1 service.

• Can I roll back the migration if required?

  VNet-injected instances: Yes, you can. If there's a failure during the migration process, the instance will automatically roll back to the stv1 platform. However, if you encounter any other issues post migration, you can roll back only if you have requested an extension to the old gateway purge. By default, the old gateway is purged in 15 mins that can be extended up to 48 hours by contacting support in advance. You should make sure to contact support before the old gateway is purged, if a rollback is required.

  Non-VNet injected instances: If there is a failure during the migration process, the instance will automatically roll back to the stv1 platform. If the migration completes successfully, a rollback is not possible.

• Is there any change required in custom domain/private DNS zones?

  VNet-injected instances: you'll need to update the private DNS zones to the new VNet IP address acquired after the migration. Pay attention to update non-Azure DNS zones too (for example your on-premises DNS servers pointing to API Management private IP address). However, in external mode, the migration process will automatically update the default domains if in use.

  Non-VNet injected instances: No changes are required if the IP is preserved. If opted for a new IP, custom domains referring to the IP should be updated.

• My stv1 instance is deployed to multiple Azure regions (multi-geo). How do I upgrade to stv2?

  Multi-geo deployments include more managed gateways deployed in other locations. Each location should be migrated separately by providing a new subnet and a new public IP. Navigate to the Locations blade and perform the changes on each listed location. The instance is considered migrated to the new platform only when all the locations are migrated. Both gateways continue to operate normally throughout the migration process.

• Do we need a public IP even if the API Management instance is VNet injected in internal mode only?

  API Management stv1 uses an Azure managed public IP even in an internal mode for management traffic. However stv2 requires a user managed public IP for the same purpose. This public IP is only used for Azure internal management operations and not to expose your instance to the internet. More details here.

• Can I upgrade my stv1 instance to the same subnet?

  • You can't migrate the stv1 instance to the same subnet in a single pass without downtime. However, you can optionally move your migrated instance back to the original subnet. More details here.
  • The old gateway takes between 15 mins to 45 mins to vacate the subnet, so that you can initiate the move. However, you can request to increase this time to up to 48 hours by a support ticket.
  • Releasing the old subnet calls for a purge of the old gateway, which forfeits the rollback to the old gateway if desired.
  • A new public IP is required for each switch
  • Ensure that the old subnet networking for NSG and firewall is updated for stv2 dependencies.

• Can I test the new gateway before switching the live traffic?

  • By default, the old and the new managed gateways coexist for 15 mins, which is a small window of time to validate the deployment. You can request to increase this time to up to 48 hours through a support ticket. This change keeps the old and the new managed gateways active to receive traffic and facilitate validation.
  • The migration process automatically updates the default domain names, and if being used, the traffic routes to the new gateways immediately.
  • If custom domain names are in use, the corresponding DNS records might need to be updated with the new IP address if not using CNAME. Customers can update their host file to the new API Management IP and validate the instance before making the switch. During this validation process, the old gateway continues to serve the live traffic.

• Are there any considerations when using default domain name?

  Instances that are using the default DNS name in external mode have the DNS autoupdated by the migration process. Moreover, the management endpoint, which always uses the default domain name is automatically updated by the migration process. Since the switch happens immediately on a successful migration, the new instance starts receiving traffic immediately, and it's critical that any networking restrictions/dependencies are taken care of upfront to avoid impacted APIs being unavailable.

• What should we consider for self hosted gateways?

  You don't need to do anything in your self-hosted gateways. You just need to migrate API Management instances running in Azure that are impacted by the stv1 platform retirement. Note that there could be a new IP for the Configuration endpoint of the API Management instance, and any networking restrictions pinned to the IP should be updated.

• How is the developer portal impacted by migration?

  There's no impact on developer portal. If custom domains are used, the DNS record should be updated with the effective IP, post migration. However, if the default domains are in use, they're automatically updated on successful migration. There's no downtime for the developer portal during the migration.

• Is there any impact on cost once we migrated to stv2?

  The billing model remains the same for stv2 and there won't be any more cost incurred after the migration.

• How can we get help during migration?

  Check details here.

Related content

• Learn about stv1 platform retirement.
• Learn about IP addresses of API Management
• For instances deployed in a VNet, see the Virtual network configuration reference.