Skip to content

Files

Latest commit

seesharprunseesharprun
Fix spelling errors
Jun 6, 2022
4dcddeb · Jun 6, 2022

History

History
221 lines (152 loc) · 12.5 KB

migrate-continuous-backup.md

File metadata and controls

221 lines (152 loc) · 12.5 KB
title description author ms.author ms.service ms.subservice ms.date ms.topic ms.reviewer
Migrate an Azure Cosmos DB account from periodic to continuous backup mode
Azure Cosmos DB currently supports a one-way migration from periodic to continuous mode and it’s irreversible. After migrating from periodic to continuous mode, you can apply the benefits of continuous mode.
kanshiG
govindk
cosmos-db
cosmosdb-sql
04/08/2022
how-to
mjbrown

Migrate an Azure Cosmos DB account from periodic to continuous backup mode

[!INCLUDEappliesto-all-apis-except-cassandra]

Azure Cosmos DB accounts with periodic mode backup policy can be migrated to continuous mode using Azure portal, CLI, PowerShell, or Resource Manager templates. Migration from periodic to continuous mode is a one-way migration and it’s not reversible. After migrating from periodic to continuous mode, you can apply the benefits of continuous mode.

The following are the key reasons to migrate into continuous mode:

  • The ability to do self-service restore using Azure portal, CLI, or PowerShell.
  • The ability to restore at time granularity of the second within the last 30-day window.
  • The ability to make sure that the backup is consistent across shards or partition key ranges within a period.
  • The ability to restore container, database, or the full account when it's deleted or modified.
  • The ability to choose the events on the container, database, or account and decide when to initiate the restore.

Note

The migration capability is one-way only and it's an irreversible action. Which means once you migrate from periodic mode to continuous mode, you can’t switch back to periodic mode.

You can migrate an account to continuous backup mode only if the following conditions are true. Also checkout the point in time restore limitations before migrating your account:

  • If the account is of type SQL API or API for MongoDB.
  • If the account is of type Table API or Gremlin API. These two APIs are in preview.
  • If the account has a single write region.
  • If the account isn't enabled with analytical store.

If the account is using customer-managed keys, a user-assigned managed identity must be declared in the Key Vault access policy and must be set as the default identity on the account.

Permissions

To perform the migration, you need Microsoft.DocumentDB/databaseAccounts/write permission for the account that is being migrated.

Pricing after migration

After you migrate your account to continuous backup mode, the cost with this mode is different when compared to the periodic backup mode. The continuous mode backup cost is cheaper than periodic mode. To learn more, see the continuous backup mode pricing example.

Migrate using portal

Use the following steps to migrate your account from periodic backup to continuous backup mode:

  1. Sign into the Azure portal.

  2. Navigate to your Azure Cosmos DB account and open the Features pane. Select Continuous Backup and select Enable.

    :::image type="content" source="./media/migrate-continuous-backup/enable-backup-migration.png" alt-text="Migrate to continuous mode using Azure portal" lightbox="./media/migrate-continuous-backup/enable-backup-migration.png":::

  3. When the migration is in progress, the status shows Pending. After it’s complete, the status changes to On. Migration time depends on the size of data in your account.

    :::image type="content" source="./media/migrate-continuous-backup/migration-status.png" alt-text="Check the status of migration from Azure portal" lightbox="./media/migrate-continuous-backup/migration-status.png":::

Migrate using PowerShell

Install the latest version of Azure PowerShell or version higher than 6.2.0. Next, run the following steps:

  1. Connect to your Azure account:

    Connect-AzAccount

  2. Migrate your account from periodic to continuous backup mode:

    Update-AzCosmosDBAccount ` 
  -ResourceGroupName "myrg" ` 
  -Name "myAccount" `
  -BackupPolicyType Continuous

Migrate using CLI

  1. Install the latest version of Azure CLI:

    • If you don’t have CLI, install the latest version of Azure CLI or version higher than 2.26.0.
    • If you already have Azure CLI installed, use az upgrade command to upgrade to the latest version.
    • Alternatively, user can also use Cloud Shell from Azure portal.

  2. Sign in to your Azure account and run the following command to migrate your account to continuous mode:

    az login

az cosmosdb update -n <myaccount> -g <myresourcegroup> --backup-policy-type continuous

  3. After the migration completes successfully, the output shows the backupPolicy object has the type property set to Continuous.

     {
   "apiProperties": null,
   "backupPolicy": {
     "type": "Continuous"
   },
   "capabilities": [],
   "connectorOffer": null,
   "consistencyPolicy": {
     "defaultConsistencyLevel": "Session",
     "maxIntervalInSeconds": 5,
     "maxStalenessPrefix": 100
   },
 …
 }

Check the migration status

Run the following command and check the status, targetType properties of the backupPolicy object. The status shows in-progress after the migration starts:

az cosmosdb show -n "myAccount" -g "myrg"

:::image type="content" source="./media/migrate-continuous-backup/migration-status-started-powershell.png" alt-text="Check the migration status using PowerShell command":::

When the migration is complete, backup type changes to Continuous. Run the same command again to check the status:

az cosmosdb show -n "myAccount" -g "myrg"

:::image type="content" source="./media/migrate-continuous-backup/migration-status-complete-powershell.png" alt-text="Backup type changes to continuous after the migration is complete":::

Migrate using Resource Manager template

To migrate to continuous backup mode using ARM template, find the backupPolicy section of your template and update the type property. For example, if your existing template has backup policy like the following JSON object:

"backupPolicy": {
   "type": "Periodic",
   "periodicModeProperties": {
   "backupIntervalInMinutes": 240,
   "backupRetentionIntervalInHours": 8
   }
},

Replace it with the following JSON object:

"backupPolicy": {
   "type": "Continuous"
},

Next deploy the template by using Azure PowerShell or CLI. The following example shows how to deploy the template with a CLI command:

az group deployment create -g <ResourceGroup> --template-file <ProvisionTemplateFilePath>

What to expect during and after migration?

When migrating from periodic mode to continuous mode, you can't run any control plane operations that performs account level updates or deletes. For example, operations such as adding or removing regions, account failover, updating backup policy etc. can't be run while the migration is in progress. The time for migration depends on the size of data and the number of regions in your account. Restore action on the migrated accounts only succeeds from the time when migration successfully completes.

You can restore your account after the migration completes. If the migration completes at 1:00 PM PST, you can do point in time restore starting from 1:00 PM PST.

Frequently asked questions

Does the migration only happen at the account level?

Yes.

Which accounts can be targeted for backup migration?

Currently, SQL API and API for MongoDB accounts with single write region that have shared, provisioned, or autoscale provisioned throughput support migration. Table API and Gremlin API are in preview.

Accounts enabled with analytical storage and multiple-write regions aren't supported for migration.

Does the migration take time? What is the typical time?

Migration takes time and it depends on the size of data and the number of regions in your account. You can get the migration status using Azure CLI or PowerShell commands. For large accounts with tens of terabytes of data, the migration can take up to few days to complete.

Does the migration cause any availability impact/downtime?

No, the migration operation takes place in the background, so the client requests aren't impacted. However, we need to perform some backend operations during the migration, and it might take extra time if the account is under heavy load.

What happens if the migration fails? Will I still get the periodic backups or get the continuous backups?

Once the migration process is started, the account will start to become a continuous mode. If the migration fails, you must initiate migration again until it succeeds.

How do I perform a restore to a timestamp before/during/after the migration?

Assume that you started migration at t1 and finished at t5, you can’t use a restore timestamp between t1 and t5.

To restore to a time after t5 because your account is now in continuous mode, you can perform the restore using Azure portal, CLI, or PowerShell like you normally do with continuous account. This self-service restore request can only be done after the migration is complete.

To restore to a time before t1, you can open a support ticket like you normally do with the periodic backup account. After the migration, you have up to 30 days to perform the periodic restore. During these 30 days, you can restore based on the backup retention/interval of your account before the migration. For example, if the backup config was to retain 24 copies at 1 hour interval, then you can restore to anytime between [t1 – 24 hours] and [t1].

Which account level control plane operations are blocked during migration?

Operations such as add/remove region, failover, changing backup policy, throughput changes resulting in data movement are blocked during migration.

If the migration fails for some underlying issue, would it still block the control plane operation until it's retried and completed successfully?

Failed migration won't block any control plane operations. If migration fails, it’s recommended to retry until it succeeds before performing any other control plane operations.

Is it possible to cancel the migration?

It isn't possible to cancel the migration because it isn't a reversible operation.

Is there a tool that can help estimate migration time based on the data usage and number of regions?

There isn't a tool to estimate time. But our scale runs indicate single region with 1 TB of data takes roughly one and half hour.

For multi-region accounts, calculate the total data size as Number_of_regions * Data_in_single_region.

Since the continuous backup mode is now GA, would you still recommend restoring a copy of your account and try migration on the copy before deciding to migrate the production account?

It’s recommended to test the continuous backup mode feature to see it works as expected before migrating production accounts. Because migration is a one-way operation and it’s not reversible.

Next steps

To learn more about continuous backup mode, see the following articles:

Trying to do capacity planning for a migration to Azure Cosmos DB?