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

• An API Management service instance. If you don't have one, see Create an API Management service instance.

• An Azure storage account. If you don't have one, see Create a storage account.

  • Create a container in the storage account to hold the backup data.

• The latest version of Azure PowerShell, if you plan to use Azure PowerShell cmdlets. If you haven't already, install Azure PowerShell.

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

PowerShell

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.

CLI

Sign in with Azure CLI.

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 Bash:

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

Access using storage access key

storageKey=$(az storage account keys list --resource-group $storageResourceGroup --account-name $storageAccountName --query [0].value --output tsv)

az apim backup --resource-group $apiManagementResourceGroup --name $apiManagementName \
    --storage-account-name $storageAccountName --storage-account-key $storageKey --storage-account-container $containerName --backup-name $backupName

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.

REST

See Azure REST API reference for information about authenticating and calling Azure REST APIs.

To back up an API Management service, issue the following HTTP request:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/backup?api-version={api-version}

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 - a valid REST API version such as 2021-08-01 or 2021-04-01-preview.

In the body of the request, specify the target storage account name, blob container name, backup name, and the storage access type. If the storage container doesn't exist, the backup operation creates it.

Access using storage access key

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessKey": "{access key for the account}"
}

Access using managed identity

Note

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

Access using system-assigned managed identity

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "SystemAssignedManagedIdentity"
}

Access using user-assigned managed identity

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "UserAssignedManagedIdentity",
    "clientId": "{client ID of user-assigned identity}"
}

Set the value of the Content-Type request header to application/json.

Backup is a long-running operation that may take several minutes to complete. If the request succeeded and the backup process began, you receive a 202 Accepted response status code with a Location header. Make GET requests to the URL in the Location header to find out the status of the operation. While the backup is in progress, you continue to receive a 202 Accepted status code. During this time the API gateway continues to handle requests, but the state of the service is Updating. A Response code of 200 OK indicates successful completion of the backup operation.

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.

PowerShell

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.

CLI

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 Bash:

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

Access using storage access key

storageKey=$(az storage account keys list --resource-group $storageResourceGroup --account-name $storageAccountName --query [0].value --output tsv)

az apim restore --resource-group $apiManagementResourceGroup --name $apiManagementName \
    --storage-account-name $storageAccountName --storage-account-key $storageKey --storage-account-container $containerName --backup-name $backupName

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

REST

To restore an API Management service from a previously created backup, make the following HTTP request:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/restore?api-version={api-version}

where:

• subscriptionId - ID of the subscription that holds the API Management service you're restoring a backup into
• resourceGroupName - name of the resource group that holds the Azure API Management service you're restoring a backup into
• serviceName - the name of the API Management service being restored into specified at its creation time
• api-version - a valid REST API version such as 2021-08-01 or 2021-04-01-preview

In the body of the request, specify the existing storage account name, blob container name, backup name, and the storage access type.

Access using storage access key

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessKey": "{access key for the account}"
}

Access using managed identity

Note

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

Access using system-assigned managed identity

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "SystemAssignedManagedIdentity"
}

Access using user-assigned managed identity

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "UserAssignedManagedIdentity",
    "clientId": "{client ID of user-assigned identity}"
}

Set the value of the Content-Type request header to application/json.

Restore is a long-running operation that may take up to 30 or more minutes to complete. If the request succeeded and the restore process began, you receive a 202 Accepted response status code with a Location header. Make GET requests to the URL in the Location header to find out the status of the operation. While the restore is in progress, you continue to receive a 202 Accepted status code. A response code of 200 OK indicates successful completion of the restore operation.

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

• Usage data used for creating analytics reports isn't included in the backup. Use Azure API Management REST API to periodically retrieve analytics reports for safekeeping.
• Custom domain TLS/SSL certificates.
• Custom CA certificates, which includes intermediate or root certificates uploaded by the customer.
• Virtual network integration settings.
• Managed identity configuration.
• Azure Monitor diagnostic configuration.
• Protocols and ciphers settings.
• Developer portal content.

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:

• Automating API Management Backup and Restore with Logic Apps
• How to move Azure API Management across regions
• API Management Premium tier also supports zone redundancy, which provides resiliency and high availability to a service instance in a specific Azure region (location).