Merge pull request #168954 from dlepow/apimmove

Court72 · web-flow · commit 2a0090c44ca7 · 2021-08-23T09:56:55.000-07:00
[APIM] Region move update
diff --git a/articles/api-management/TOC.yml b/articles/api-management/TOC.yml
@@ -311,7 +311,7 @@
               href: api-management-configuration-repository-git.md
             - name: Use role-based access control
               href: api-management-role-based-access-control.md
-            - name: Migrate API Management instances
+            - name: Move instances between regions
               href: api-management-howto-migrate.md
             - name: Use managed identities for Azure resources
               href: api-management-howto-use-managed-service-identity.md
diff --git a/articles/api-management/api-management-howto-disaster-recovery-backup-restore.md b/articles/api-management/api-management-howto-disaster-recovery-backup-restore.md
@@ -3,16 +3,11 @@ title: Implement disaster recovery using backup and restore in API Management
 titleSuffix: Azure API Management
 description: Learn how to use backup and restore to perform disaster recovery in Azure API Management.
 services: api-management
-documentationcenter: ''
 author: mikebudzynski
-manager: erikre
-editor: ''
 
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
 ms.topic: article
-ms.date: 12/05/2020
+ms.date: 08/20/2021
 ms.author: apimpm 
 ms.custom: devx-track-azurepowershell
 ---
@@ -53,40 +48,34 @@ All of the tasks that you do on resources using the Azure Resource Manager must
 ### Create an Azure Active Directory application
 
 1. Sign in to the [Azure portal](https://portal.azure.com).
-2. Using the subscription that contains your API Management service instance, navigate to the **App registrations** tab in **Azure Active Directory** (Azure Active Directory > Manage/App registrations).
-
+1. Using the subscription that contains your API Management service instance, navigate to the [Azure portal - App registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) to register an app in Active Directory.
     > [!NOTE]
     > If the Azure Active Directory default directory isn't visible to your account, contact the administrator of the Azure subscription to grant the required permissions to your account.
+1. Select **+ New registration**.
+1. On the **Register an application** page, set the values as follows:
+    
+    * Set **Name** to a meaningful name.
+    * Set **Supported account types** to **Accounts in this organizational directory only**. 
+    * In **Redirect URI** enter a placeholder URL such as `https://resources`. It's a required field, but the value isn't used later. 
+    * Select **Register**.
 
-3. Click **New application registration**.
-
-    The **Create** window appears on the right. That's where you enter the AAD app relevant information.
-
-4. Enter a name for the application.
-5. For the application type, select **Native**.
-6. Enter a placeholder URL such as `http://resources` for the **Redirect URI**, as it's a required field, but the value isn't used later. Click the check box to save the application.
-7. Click **Create**.
+### Add permissions
 
-### Add an application
-
-1. Once the application is created, click **API permissions**.
-2. Click **+ Add a permission**.
-4. Press **Select Microsoft APIs**.
-5. Choose **Azure Service Management**.
-6. Press **Select**.
+1. Once the application is created, select **API permissions** > **+ Add a permission**.
+1. Select **Microsoft APIs**.
+1. Select **Azure Service Management**.
 
     :::image type="content" source="./media/api-management-howto-disaster-recovery-backup-restore/add-app-permission.png" alt-text="Screenshot that shows how to add app permissions."::: 
 
-7. Click **Delegated Permissions** beside the newly added application, check the box for **Access Azure Service Management (preview)**.
+1. Click **Delegated Permissions** beside the newly added application, and check the box for **Access Azure Service Management as organization users (preview)**.
 
     :::image type="content" source="./media/api-management-howto-disaster-recovery-backup-restore/delegated-app-permission.png" alt-text="Screenshot that shows adding delegated app permissions.":::
 
-8. Press **Select**.
-9. Click **Add Permissions**.
+1. Select **Add permissions**.
 
-### Configuring your app
+### Configure your app
 
-Before calling the APIs that generate the backup and restore it, you need to get a token. The following example uses the [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory) NuGet package to retrieve the token.
+Before calling the APIs that generate the backup and restore, you need to get a token. The following example uses the [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory) NuGet package to retrieve the token.
 
 ```csharp
 using Microsoft.IdentityModel.Clients.ActiveDirectory;
@@ -133,6 +122,9 @@ Replace `{tenant id}`, `{application id}`, and `{redirect uri}` using the follow
 
 The REST APIs are [Api Management Service - Backup](/rest/api/apimanagement/2020-12-01/api-management-service/backup) and [Api Management Service - Restore](/rest/api/apimanagement/2020-12-01/api-management-service/restore).
 
+> [!NOTE]
+> Backup and restore operations can also be performed with PowerShell [_Backup-AzApiManagement_](/powershell/module/az.apimanagement/backup-azapimanagement) and [_Restore-AzApiManagement_](/powershell/module/az.apimanagement/restore-azapimanagement) commands respectively.
+
 Before calling the "backup and restore" operations described in the following sections, set the authorization request header for your REST call.
 
 ```csharp
@@ -152,7 +144,7 @@ where:
 -   `subscriptionId` - ID of the subscription that holds the API Management service you're trying to back up
 -   `resourceGroupName` - name of the resource group of your Azure API Management service
 -   `serviceName` - the name of the API Management service you're making a backup of specified at the time of its creation
--   `api-version` - replace with `2020-12-01`
+-   `api-version` - replace with a supported REST API version such as `2020-12-01`
 
 In the body of the request, specify the target Azure storage account name, access key, blob container name, and backup name:
 
@@ -204,14 +196,8 @@ Restore is a long running operation that may take up to 30 or more minutes to co
 >
 > **Changes** made to the service configuration (for example, APIs, policies, developer portal appearance) while restore operation is in progress **could be overwritten**.
 
-<!-- Dummy comment added to suppress markdown lint warning -->
-
-> [!NOTE]
-> Backup and restore operations can also be performed with PowerShell [_Backup-AzApiManagement_](/powershell/module/az.apimanagement/backup-azapimanagement) and [_Restore-AzApiManagement_](/powershell/module/az.apimanagement/restore-azapimanagement) commands respectively.
-
 ## Constraints when making backup or restore request
 
--   **Container** specified in the request body **must exist**.
 -   While backup is in progress, **avoid management changes in the service** such as SKU upgrade or downgrade, change in domain name, and more.
 -   Restore of a **backup is guaranteed only for 30 days** since the moment of its creation.
 -   **Changes** made to the service configuration (for example, APIs, policies, and developer portal appearance) while backup operation is in process **might be excluded from the backup and will be lost**.
diff --git a/articles/api-management/api-management-howto-migrate.md b/articles/api-management/api-management-howto-migrate.md
@@ -1,46 +1,74 @@
 ---
-title: How to migrate Azure API Management across regions
+title: How to migrate Azure API Management between regions
 description: Learn how to migrate an API Management instance from one region to another.
 services: api-management
-documentationcenter: ''
 author: miaojiang
-manager: erikre
-editor: ''
 
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
-ms.topic: article
-ms.date: 08/26/2019
+ms.topic: how-to
+ms.date: 08/20/2021
 ms.author: apimpm
-
+ms.custom: subject-moving-resources
+#cusomerintent: As an Azure service administrator, I want to move my service resources to another Azure region.
 ---
-# How to migrate Azure API Management across regions
-To migrate API Management instances from one Azure region to another, you can use the [backup and restore](api-management-howto-disaster-recovery-backup-restore.md) feature. You should choose the same API Management pricing tier in the source and target regions. 
+
+# How to move Azure API Management across regions
+
+This article describes how to move an API Management instance to a different Azure region. You might move your instance to another region for many reasons. For example:
+
+* Locate your instance closer to your API consumers
+* Deploy features available in specific regions only
+* Meet internal policy and governance requirements
+
+To move API Management instances from one Azure region to another, use the service's [backup and restore](api-management-howto-disaster-recovery-backup-restore.md) operations. You can use a different API Management instance name or the existing name. 
 
 > [!NOTE]
-> Backup and restore won't work while migrating between different cloud types. For that, you'll need to export the resource [as a template](../azure-resource-manager/management/manage-resource-groups-portal.md#export-resource-groups-to-templates). Then, adapt the exported template for the target Azure region and re-create the resource. 
+> API Management also supports [multi-region deployment](api-management-howto-deploy-multi-region.md), which distributes a single Azure API management service across multiple Azure regions. Multi-region deployment helps reduce request latency perceived by geographically distributed API consumers and improves service availability if one region goes offline.
 
-## Option 1: Use a different API Management instance name
+[!INCLUDE [premium-dev-standard-basic.md](../../includes/api-management-availability-premium-dev-standard-basic.md)]
 
-1. In the target region, create a new API Management instance with the same pricing tier as the source API Management instance. The new instance should have a different name. 
-1. Backup existing API Management instance to a storage account.
-1. Restore the backup created in Step 2 to the new API Management instance created in the new region in Step 1.
-1. If you have a custom domain pointing to the source region API Management instance, update the custom domain CNAME to point to the new API Management instance. 
+## Considerations
 
+* Choose the same API Management pricing tier in the source and target regions. 
+* Backup and restore won't work when migrating between different cloud types. For that scenario, export the resource [as a template](../azure-resource-manager/management/manage-resource-groups-portal.md#export-resource-groups-to-templates). Then, adapt the exported template for the target Azure region and re-create the resource. 
 
-## Option 2: Use the same API Management instance name
+## Prerequisites
 
-> [!NOTE]
-> This option will result in downtime during the migration.
+* Review requirements and limitations of the API Management [backup and restore](api-management-howto-disaster-recovery-backup-restore.md) operations. 
+* See [What is not backed up](api-management-howto-disaster-recovery-backup-restore.md#what-is-not-backed-up). Record settings and data that you will need to recreate manually after moving the instance.
+* Create a [storage account](../storage/common/storage-account-create.md?tabs=azure-portal) in the source region. You will use this account to back up the source instance. 
+
+## Prepare and move
+
+### Option 1: Use a different API Management instance name
 
-1. Back up the API Management instance in the source region to a storage account.
-1. Delete the API Management in the source region. 
+1. In the target region, create a new API Management instance with the same pricing tier as the source API Management instance. Use a different name for the new instance.
+1. [Back up](api-management-howto-disaster-recovery-backup-restore.md#-back-up-an-api-management-service) the existing API Management instance to the storage account. 
+1. [Restore](api-management-howto-disaster-recovery-backup-restore.md#-restore-an-api-management-service) the source instance's backup to the new API Management instance.
+1. If you have a custom domain pointing to the source region API Management instance, update the custom domain CNAME to point to the new API Management instance. 
+
+### Option 2: Use the same API Management instance name
+
+> [!WARNING]
+> This option deletes the original API Management instance and results in downtime during the migration. Ensure that you have a valid backup before deleting the source instance.
+
+1. [Back up](api-management-howto-disaster-recovery-backup-restore.md#-back-up-an-api-management-service) the existing API Management instance to the storage account. 
+1. Delete the API Management instance in the source region. 
 1. Create a new API Management instance in the target region with the same name as the one in the source region.
-1. Restore the backup created in Step 1 to the new API Management instance in the target region.  
+1. [Restore](api-management-howto-disaster-recovery-backup-restore.md#-restore-an-api-management-service) the source instance's backup to the new API Management instance in the target region.  
+
+## Verify
+
+1. Ensure that the restore operation completes successfully before accessing your API Management instance in the target region.
+1. Configure settings that are not automatically moved during the restore operation. Examples: virtual network configuration, managed identities, developer portal content, and custom domain and custom CA certificates.
+1. Access your API Management endpoints in the target region. For example, test your APIs, or access the developer portal.
+
+## Clean up source resources
+
+If you moved the API Management instance using Option 1, after you successfully restore and configure the target instance, you may delete the source instance.
 
+## Next steps
 
-## <a name="next-steps"> </a>Next steps
 * For more information about the backup and restore feature, see [how to implement disaster recovery](api-management-howto-disaster-recovery-backup-restore.md).
-* For information on migration Azure resources, see [Azure cross-region migration guidance](https://github.com/Azure/Azure-Migration-Guidance).
+* For information on migrating Azure resources, see [Azure cross-region migration guidance](https://github.com/Azure/Azure-Migration-Guidance).
 * [Optimize and save on your cloud spending](../cost-management-billing/costs/quick-acm-cost-analysis.md?WT.mc_id=costmanagementcontent_docsacmhorizontal_-inproduct-learn).
