Merge pull request #223512 from dlepow/migstv2

Court72 · web-flow · commit d27fb8bea883 · 2023-04-18T15:36:21.000-06:00
[APIM] Migration from stv1 to stv2
diff --git a/articles/api-management/TOC.yml b/articles/api-management/TOC.yml
@@ -91,6 +91,9 @@
       - name: Observability
         href: observability.md
         displayName: monitoring
+      - name: Compute platform
+        href: compute-infrastructure.md
+        displayName: stv1, stv2
       - name: DevOps and CI/CD
         href: devops-api-development-templates.md  
       - name: APIs
@@ -152,6 +155,8 @@
             - name: Recover a deleted instance
               displayName: soft delete
               href: soft-delete.md
+            - name: Migrate to stv2 platform
+              href: migrate-stv1-to-stv2.md
             - name: Configure networking
               items:
                 - name: Connect to a virtual network
diff --git a/articles/api-management/breaking-changes/stv1-platform-retirement-august-2024.md b/articles/api-management/breaking-changes/stv1-platform-retirement-august-2024.md
@@ -6,7 +6,7 @@ documentationcenter: ''
 author: dlepow
 ms.service: api-management
 ms.topic: reference
-ms.date: 08/26/2022
+ms.date: 01/10/2023
 ms.author: danlep
 ---
 
@@ -40,7 +40,7 @@ After 31 August 2024, any instance hosted on the `stv1` platform won't be suppor
 
 **Migrate all your existing instances hosted on the `stv1` compute platform to the `stv2` compute platform by 31 August 2024.**  
 
-If you have existing instances hosted on the `stv1` platform, you can follow our [migration guide](../compute-infrastructure.md#how-do-i-migrate-to-the-stv2-platform) which provides all the details to ensure a successful migration. 
+If you have existing instances hosted on the `stv1` platform, you can follow our [migration guide](../migrate-stv1-to-stv2.md) which provides all the details to ensure a successful migration. 
 
 ## Help and support
 
diff --git a/articles/api-management/compute-infrastructure.md b/articles/api-management/compute-infrastructure.md
@@ -1,10 +1,10 @@
 ---
 title: Azure API Management compute platform
-description: Learn about the compute platform used to host your API Management service instance
+description: Learn about the compute platform used to host your API Management service instance. Instances in the dedicated service tiers of API Management are hosted on the stv1 or stv2 compute platform.
 author: dlepow
 ms.service: api-management
 ms.topic: conceptual
-ms.date: 03/16/2022
+ms.date: 04/17/2023
 ms.author: danlep
 ms.custom: 
 ---
@@ -14,85 +14,53 @@ As a cloud platform-as-a-service (PaaS), Azure API Management abstracts many det
 
 To enhance service capabilities, we're upgrading the API Management compute platform version - the Azure compute resources that host the service - for instances in several [service tiers](api-management-features.md). This article gives you context about the upgrade and the major versions of API Management's compute platform: `stv1` and `stv2`.
 
-We've minimized impacts of this upgrade on your operation of your API Management instance. Upgrades are managed by the platform, and new instances created in service tiers other than the Consumption tier are mostly hosted on the `stv2` platform. However, for existing instances hosted on the `stv1` platform, you have options to trigger migration to the `stv2` platform.
+Most new instances created in service tiers other than the Consumption tier are hosted on the `stv2` platform. However, for existing instances hosted on the `stv1` platform, you have options to migrate to the `stv2` platform.
 
 ## What are the compute platforms for API Management?
 
 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<sup>1</sup> |
+| `stv2` | Single-tenant v2 | Azure-allocated compute infrastructure that supports added resiliency and security features. See [What are the benefits of the `stv2` platform?](#what-are-the-benefits-of-the-stv2-platform) in this article. | Developer, Basic, Standard, Premium<sup>1</sup> |
 | `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 |
 
-<sup>1</sup> Newly created instances in these tiers, created using the Azure portal or specifying API version 2021-01-01-preview or later. Includes some existing instances in Developer and Premium tiers configured with virtual networks or availability zones.
+<sup>1</sup> Newly created instances in these tiers and some existing instances in Developer and Premium tiers configured with virtual networks or availability zones.
 
 > [!NOTE]
 > Currently, the `stv2` platform isn't available in the US Government cloud or in the following Azure regions: China East, China East 2, China North, China North 2.
 
 ## How do I know which platform hosts my API Management instance?
 
-Starting with API version `2021-04-01-preview`, the API Management instance exposes a read-only `platformVersion` property that shows this platform information. 
+Starting with API version `2021-04-01-preview`, the API Management instance exposes a read-only `platformVersion` property with this platform information. 
 
-You can find this information using the portal or the API Management [REST API](/rest/api/apimanagement/current-ga/api-management-service/get).
+You can find the platform version of your instance using the portal, the API Management [REST API](/rest/api/apimanagement/current-ga/api-management-service/get), or other Azure tools.
 
-To find the `platformVersion` property in the portal:
+To find the platform version in the portal:
 
-1. Go to your API Management instance.
-1. On the **Overview** page, select **JSON view**.
-1. In **API version**, select a current version such as `2021-08-01` or later.
-1. In the JSON view, scroll down to find the `platformVersion` property.
+1. Sign in to the [portal](https://portal.azure.com) and go to your API Management instance.
+1. On the **Overview** page, under **Essentials**, the **Platform Version** is displayed.
 
-    :::image type="content" source="media/compute-infrastructure/platformversion-property.png" alt-text="platformVersion property in JSON view":::
+    :::image type="content" source="media/compute-infrastructure/platformversion-property.png" alt-text="Screenshot of the API Management platform version in the portal.":::
 
-## How do I migrate to the `stv2` platform? 
-
-The following table summarizes migration options for instances in the different API Management service tiers that are currently hosted on the `stv1` platform. See the linked documentation for detailed steps.
-
-> [!NOTE]
-> Check the [`platformVersion` property](#how-do-i-know-which-platform-hosts-my-api-management-instance) before starting migration, and after your configuration change.
-
-|Tier  |Migration options  |
-|---------|---------|
-|Premium     |  1. Enable [zone redundancy](../reliability/migrate-api-mgt.md)<br/> -or-<br/> 2. Create new [external](api-management-using-with-vnet.md) or [internal](api-management-using-with-internal-vnet.md) VNet connection<sup>1</sup><br/> -or-<br/> 3. Update existing [VNet configuration](#update-vnet-configuration)    |   
-|Developer     | 1. Create new [external](api-management-using-with-vnet.md) or [internal](api-management-using-with-internal-vnet.md) VNet connection<sup>1</sup><br/>-or-<br/> 2. Update existing [VNet configuration](#update-vnet-configuration)   |   
-| Standard | 1. [Change your service tier](upgrade-and-scale.md#change-your-api-management-service-tier) (downgrade to Developer or upgrade to Premium). Follow migration options in new tier.<br/>-or-<br/>2. Deploy new instance in existing tier and migrate configurations<sup>2</sup> |
-| Basic | 1. [Change your service tier](upgrade-and-scale.md#change-your-api-management-service-tier) (downgrade to Developer or upgrade to Premium). Follow migration options in new tier<br/>-or-<br/>2. Deploy new instance in existing tier and migrate configurations<sup>2</sup> |
-| Consumption | Not applicable |
-
-<sup>1</sup> Use Azure portal or specify API version 2021-01-01-preview or later.
- 
-<sup>2</sup> Migrate configurations with the following mechanisms: [Backup and restore](api-management-howto-disaster-recovery-backup-restore.md), [Migration script for the developer portal](automate-portal-deployments.md), [APIOps with Azure API Management](/azure/architecture/example-scenario/devops/automated-api-deployments-apiops).
-
-## Update VNet configuration
+## What are the benefits of the `stv2` platform?
 
-If you have an existing Developer or Premium tier instance that's connected to a virtual network and hosted on the `stv1` platform, trigger migration to the `stv2` platform by updating the VNet configuration. 
+The `stv2` platform infrastructure supports several resiliency and security features of API Management that aren't available on the `stv1` platform, including:
 
-### Prerequisites
+* [Availability zones](zone-redundancy.md)
+* [Private endpoints](private-endpoint.md)
+* [Protection with Azure DDoS](protect-with-ddos-protection.md)
 
-* A new or existing virtual network and subnet in the same region and subscription as your API Management instance. The subnet must be different from the one currently used for the instance hosted on the `stv1` platform, and a network security group must be attached.
 
-* A new or existing Standard SKU [public IPv4 address](../virtual-network/ip-services/public-ip-addresses.md#sku) resource in the same region and subscription as your API Management instance.
-
-To update the existing external or internal VNet configuration using the portal:
-
-1. Navigate to your API Management instance.
-1. In the left menu, select **Network** > **Virtual network**.
-1. Select the network connection in the location you want to update.
-1. Select the virtual network, subnet, and IP address resources you want to configure, and select **Apply**.
-1. Continue configuring VNet settings for the remaining locations of your API Management instance.
-1. 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. Confirm migration by checking the [`platformVersion` property](#how-do-i-know-which-platform-hosts-my-api-management-instance).
+## How do I migrate to the `stv2` platform? 
 
-> [!NOTE]
-> * Updating the VNet configuration takes from 15 to 45 minutes to complete.
-> * The VIP address(es) of your API Management instance will change.
+> [!IMPORTANT]
+> Support for API Management instances hosted on the `stv1` platform will be [retired by 31 August 2024](breaking-changes/stv1-platform-retirement-august-2024.md). To ensure proper operation of your API Management instance, you should migrate any instance hosted on the `stv1` platform to `stv2` before that date.
 
+Migration steps depend on features enabled in your API Management instance. If the instance isn't injected in a VNet, you can use a migration API. For instances that are VNet-injected, follow manual steps. For details, see the [migration guide](migrate-stv1-to-stv2.md).
 
 ## Next steps
 
-* Learn more about using a [virtual network](virtual-network-concepts.md) with API Management.
-* Learn more about enabling [availability zones](../reliability/migrate-api-mgt.md).
-
+* [Migrate an API Management instance to the stv2 platform](migrate-stv1-to-stv2.md).
+* Learn more about [upcoming breaking changes](breaking-changes/overview.md) in API Management.
diff --git a/articles/api-management/media/compute-infrastructure/platformversion-property.png b/articles/api-management/media/compute-infrastructure/platformversion-property.png
diff --git a/articles/api-management/migrate-stv1-to-stv2.md b/articles/api-management/migrate-stv1-to-stv2.md
@@ -0,0 +1,104 @@
+---
+title: Migrate Azure API Management instance to stv2 platform  | Microsoft Docs
+description: Follow the steps in this article to migrate your Azure API Management instance from the stv1 compute platform to the stv2 compute platform. Migration steps depend on whether the instance is deployed (injected) in a VNet.
+
+author: dlepow
+ms.service: api-management
+ms.topic: how-to
+ms.date: 04/17/2023
+ms.author: danlep
+
+---
+
+# 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](api-management-using-with-vnet.md) or [internal](api-management-using-with-internal-vnet.md) VNet.
+
+* **Non-VNet-injected API Management instance** - Use the [Migrate to stv2](/rest/api/apimanagement/current-ga/api-management-service/migratetostv2) 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](compute-infrastructure.md).
+
+> [!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.
+> * Migration to `stv2` is not reversible.
+
+> [!IMPORTANT]
+> Support for API Management instances hosted on the `stv1` platform will be [retired by 31 August 2024](breaking-changes/stv1-platform-retirement-august-2024.md). To ensure proper operation of your API Management instance, you should migrate any instance hosted on the `stv1` platform to `stv2` before that date.
+
+[!INCLUDE [api-management-availability-premium-dev-standard-basic](../../includes/api-management-availability-premium-dev-standard-basic.md)]
+
+## 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?](compute-infrastructure.md#how-do-i-know-which-platform-hosts-my-api-management-instance).
+
+[!INCLUDE [azure-cli-prepare-your-environment-no-header.md](~/articles/reusable-content/azure-cli/azure-cli-prepare-your-environment-no-header.md)]
+
+## 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`.
+
+
+```azurecli
+# 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 (see the following section). You can also cause migrate to the `stv2` platform by enabling [zone redundancy](../reliability/migrate-api-mgt.md).
+
+### 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.
+
+* A Standard SKU [public IPv4 address](../virtual-network/ip-services/public-ip-addresses.md#sku) resource in the same region and subscription as your API Management instance.
+
+For details, see [Prerequisites for network connections](api-management-using-with-vnet.md#prerequisites).
+
+#### Update VNet configuration
+
+To update the existing external or internal VNet configuration:
+
+1. In the [portal](https://portal.azure.com), navigate to your API Management instance.
+1. In the left menu, select **Network** > **Virtual network**.
+1. Select the network connection in the location you want to update.
+1. Select the virtual network, subnet, and IP address resources you want to configure, and select **Apply**.
+1. Continue configuring VNet settings for the remaining locations of your API Management instance.
+1. 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.
+
+## Verify migration
+
+To verify that the migration was successful, check the [platform version](compute-infrastructure.md#how-do-i-know-which-platform-hosts-my-api-management-instance) of your API Management instance. After successful migration, the value is `stv2`.
+
+## Next steps
+
+* Learn about [stv1 platform retirement](breaking-changes/stv1-platform-retirement-august-2024.md).
+* For instances deployed in a VNet, see the [Virtual network configuration reference](virtual-network-reference.md).
