Rediger

Del via


How to implement disaster recovery using service backup and restore in Azure API Management

APPLIES TO: Developer | Basic | Standard | Premium

By publishing and managing your APIs via Azure API Management, you're taking advantage of fault tolerance and infrastructure capabilities that you'd otherwise design, implement, and manage manually. The Azure platform mitigates a large fraction of potential failures at a fraction of the cost.

To recover from availability problems that affect your API Management service, be ready to reconstitute your service in another region at any time. Depending on your recovery time objective, you might want to keep a standby service in one or more regions. You might also try to maintain their configuration and content in sync with the active service according to your recovery point objective. The API management backup and restore capabilities provide the necessary building blocks for implementing disaster recovery strategy.

Backup and restore operations can also be used for replicating API Management service configuration between operational environments, for example, development and staging. Beware that runtime data such as users and subscriptions will be copied as well, which might not always be desirable.

This article shows how to automate backup and restore operations of your API Management instance using an external storage account. The steps shown here use either the Backup-AzApiManagement and Restore-AzApiManagement Azure PowerShell cmdlets, or the Api Management Service - Backup and Api Management Service - Restore REST APIs.

Warning

Each backup expires after 30 days. If you attempt to restore a backup after the 30-day expiration period has expired, the restore will fail with a Cannot restore: backup expired message.

Important

Restore operation doesn't change custom hostname configuration of the target service. We recommend to use the same custom hostname and TLS certificate for both active and standby services, so that, after restore operation completes, the traffic can be re-directed to the standby instance by a simple DNS CNAME change.

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Prerequisites

Configure storage account access

When running a backup or restore operation, you need to configure access to the storage account. API Management supports two storage access mechanisms: an Azure Storage access key, or an API Management managed identity.

Configure storage account access key

Azure generates two 512-bit storage account access keys for each storage account. These keys can be used to authorize access to data in your storage account via Shared Key authorization. To view, retrieve, and manage the keys, see Manage storage account access keys.

Configure API Management managed identity

Note

Using an API Management managed identity for storage operations during backup and restore is supported in API Management REST API version 2021-04-01-preview or later.

  1. Enable a system-assigned or user-assigned managed identity for API Management in your API Management instance.

    • If you enable a user-assigned managed identity, take note of the identity's Client ID.
    • If you will back up and restore to different API Management instances, enable a managed identity in both the source and target instances.
  2. Assign the identity the Storage Blob Data Contributor role, scoped to the storage account used for backup and restore. To assign the role, use the Azure portal or other Azure tools.

Back up an API Management service

Sign in with Azure PowerShell.

In the following examples:

  • An API Management instance named myapim is in resource group apimresourcegroup.
  • A storage account named backupstorageaccount is in resource group storageresourcegroup. The storage account has a container named backups.
  • A backup blob will be created with name ContosoBackup.apimbackup.

Set variables in PowerShell:

$apiManagementName="myapim";
$apiManagementResourceGroup="apimresourcegroup";
$storageAccountName="backupstorageaccount";
$storageResourceGroup="storageresourcegroup";
$containerName="backups";
$blobName="ContosoBackup.apimbackup"

Access using storage access key

$storageKey = (Get-AzStorageAccountKey -ResourceGroupName $storageResourceGroup -StorageAccountName $storageAccountName)[0].Value

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName -StorageAccountKey $storageKey

Backup-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -TargetContainerName $containerName -TargetBlobName $blobName

Access using managed identity

To configure a managed identity in your API Management instance to access the storage account, see Configure a managed identity, earlier in this article.

Access using system-assigned managed identity

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Backup-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -TargetContainerName $containerName `
    -TargetBlobName $blobName -AccessType "SystemAssignedManagedIdentity"

Access using user-assigned managed identity

In this example, a user-assigned managed identity named myidentity is in resource group identityresourcegroup.

$identityName = "myidentity";
$identityResourceGroup = "identityresourcegroup";

$identityId = (Get-AzUserAssignedIdentity -Name $identityName -ResourceGroupName $identityResourceGroup).ClientId

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Backup-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -TargetContainerName $containerName `
    -TargetBlobName $blobName -AccessType "UserAssignedManagedIdentity" ` -identityClientId $identityid

Backup is a long-running operation that may take several minutes to complete. During this time the API gateway continues to handle requests, but the state of the service is Updating.

Restore an API Management service

Caution

Avoid changes to the service configuration (for example, APIs, policies, developer portal appearance) while restore operation is in progress. Changes could be overwritten.

In the following examples,

  • An API Management instance named myapim is restored from the backup blob named ContosoBackup.apimbackup in storage account backupstorageaccount.
  • The backup blob is in a container named backups.

Set variables in PowerShell:

$apiManagementName="myapim";
$apiManagementResourceGroup="apimresourcegroup";
$storageAccountName="backupstorageaccount";
$storageResourceGroup="storageresourcegroup";
$containerName="backups";
$blobName="ContosoBackup.apimbackup"

Access using storage access key

$storageKey = (Get-AzStorageAccountKey -ResourceGroupName $storageResourceGroup -StorageAccountName $storageAccountName)[0].Value

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName -StorageAccountKey $storageKey

Restore-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -SourceContainerName $containerName -SourceBlobName $blobName

Access using managed identity

To configure a managed identity in your API Management instance to access the storage account, see Configure a managed identity, earlier in this article.

Access using system-assigned managed identity

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Restore-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -SourceContainerName $containerName `
    -SourceBlobName $blobName -AccessType "SystemAssignedManagedIdentity"

Access using user-assigned managed identity

In this example, a user-assigned managed identity named myidentity is in resource group identityresourcegroup.

$identityName = "myidentity";
$identityResourceGroup = "identityresourcegroup";

$identityId = (Get-AzUserAssignedIdentity -Name $identityName -ResourceGroupName $identityResourceGroup).ClientId

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Restore-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -SourceContainerName $containerName `
    -SourceBlobName $blobName -AccessType "UserAssignedManagedIdentity" ` -identityClientId $identityid

Restore is a long-running operation that may take up to 45 minutes or more to complete.

Constraints

  • Restore of a backup is guaranteed only for 30 days since the moment of its creation.
  • While backup is in progress, avoid management changes in the service such as pricing tier upgrade or downgrade, change in domain name, and more.
  • 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.
  • Backup doesn't capture pre-aggregated log data used in reports shown on the Analytics window in the Azure portal.
  • Cross-Origin Resource Sharing (CORS) should not be enabled on the Blob service in the storage account.
  • The pricing tier of the service being restored into must match the pricing tier of the backed-up service being restored.

Storage networking constraints

If the storage account is firewall enabled, it's recommended to use the API Management instance's system-assigned managed identity for access to the account. Ensure that the storage account grants access to trusted Azure services.

What is not backed up

The frequency with which you perform service backups affects your recovery point objective. To minimize it, we recommend implementing regular backups and performing on-demand backups after you make changes to your API Management service.

Next steps

Check out the following related resources for the backup/restore process: