Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Important
Disaster recovery for Durable Task Scheduler is in public preview. Preview features are subject to the Supplemental Terms of Use for Microsoft Azure Previews, and some details might change before general availability.
This article shows you how to pair a primary and secondary Durable Task Scheduler, keep them in sync, and perform a failover. For background on how disaster recovery works, see Disaster recovery in Durable Task Scheduler.
In this article, you:
- Create a primary and secondary scheduler that meet the disaster recovery requirements.
- Enable disaster recovery between them.
- Perform a planned or forced failover.
- Redirect your app to the new primary.
- Disable disaster recovery when you no longer need it.
Prerequisites
- If you don't have an Azure account, create a free account before you begin.
- The Azure CLI, with the
durabletaskextension installed:az extension add --name durabletask. - The examples in this article use Bash. Run them in Azure Cloud Shell (Bash) or a local Bash shell.
- Two Durable Task Scheduler resources on the Dedicated SKU, each in a different Azure region. The scheduler you plan to use as the secondary must not have any task hubs on it yet. Wait until both schedulers report
provisioningStateasSucceededbefore you enable disaster recovery. - Create the task hubs you need on the primary scheduler, and leave the secondary scheduler empty of task hubs. Enabling disaster recovery copies the primary's existing task hub records to the secondary.
- Your user or deployment identity needs the Contributor role, or another Azure RBAC role with the required permissions, on both the primary and secondary schedulers. Use role assignments scoped to the schedulers or inherited from a resource group or subscription.
- For the Bicep option, your deployment identity also needs permission to create and manage deployments in the primary scheduler's resource group. For example, assign Contributor at that resource-group scope or an inherited parent scope. A role assignment on the scheduler alone doesn't grant these deployment permissions.
- Your client and worker identities need a Durable Task Scheduler data role that covers the task hubs they use on both schedulers. Most applications need Durable Task Data Contributor. Use Durable Task Worker for applications that only process orchestrations, activities, and entities, or Durable Task Data Reader for read-only applications. Assign data roles at the task hub scope for least-privilege access; use the scheduler scope only when an identity needs access to all task hubs on that scheduler.
- The Contributor role doesn't grant access to orchestration data or permission to create role assignments. To assign the data roles, use an identity with role-assignment permissions at the target scope, such as Owner or User Access Administrator. See Configure managed identity for Durable Task Scheduler.
Disaster recovery is available in Azure public cloud regions where Durable Task Scheduler is available, except: Austria East, Belgium Central, Central US EUAP, Chile Central, East US 2 EUAP, France South, Italy North, Jio India West, Northeast US 5, and Southeast US 5. Confirm region support before you choose your primary and secondary regions.
Important
You're billed for both the primary and secondary schedulers at the same time, even while the secondary is on standby. Each scheduler is billed for its provisioned capacity units (CUs) at the price for its Azure region. See Disaster recovery costs.
Sign in and set variables
Sign in to Azure and set the variables for the examples in this article:
az login
primaryRg="<primary-resource-group>"
primaryScheduler="<primary-scheduler-name>"
secondaryRg="<secondary-resource-group>"
secondaryScheduler="<secondary-scheduler-name>"
apiVersion="2026-07-01-preview"
Enable disaster recovery
Get the resource ID of each scheduler:
secondaryId=$(az durabletask scheduler show \
--resource-group $secondaryRg \
--name $secondaryScheduler \
--query id -o tsv)
primaryId=$(az durabletask scheduler show \
--resource-group $primaryRg \
--name $primaryScheduler \
--query id -o tsv)
Choose Azure CLI or Bicep to enable disaster recovery:
Call the primary scheduler's failoverInstances/default endpoint by using the secondary's resource ID as the partnerSchedulerResourceId value:
az rest --method put \
--uri "https://management.azure.com${primaryId}/failoverInstances/default?api-version=${apiVersion}" \
--body "{\"properties\": {\"partnerSchedulerResourceId\": \"$secondaryId\"}}"
Enabling disaster recovery is asynchronous. The request returns 202 Accepted while the operation finishes in the background. An accepted response doesn't mean the pairing is ready.
The remaining steps use Azure CLI to check status and manage failover, regardless of which option you used to enable disaster recovery.
Check status
Poll the same resource until provisioningState reports Succeeded:
az rest --method get \
--uri "https://management.azure.com${primaryId}/failoverInstances/default?api-version=${apiVersion}"
A successful response looks similar to:
{
"properties": {
"provisioningState": "Succeeded",
"replicationRole": "Primary",
"failoverState": "None",
"partnerSchedulerResourceId": "/subscriptions/.../resourceGroups/.../providers/Microsoft.DurableTask/schedulers/<secondary>",
"partnerSchedulerLocation": "<secondary-region>"
}
}
provisioningState can be Provisioning, Succeeded, Deleting, or Failed. failoverState is normally None after initial pairing. It describes failover progress, not whether pairing provisioning succeeded. For example, a failed attempt that didn't reach the database transition step can also reset failoverState back to None.
After provisioningState becomes Succeeded, you can't change the partner. Reissuing the same PUT is idempotent and returns 200. To pair with a different scheduler, delete the failover resource and re-enable disaster recovery.
Because primary and secondary are roles that can swap after a failover - not fixed identities - track which resource currently holds each role with its own variables. Keep them updated whenever a failover succeeds:
currentPrimaryId=$primaryId
currentSecondaryId=$secondaryId
Keep your schedulers in sync
Create the task hubs you need on the primary scheduler before you enable disaster recovery, and leave the secondary empty of task hubs. Enabling disaster recovery copies the primary's existing task hub records to the secondary as part of setting up the pairing. Task hub names stay the same after a failover; clients and workers still need to use the new primary's endpoint.
After you enable disaster recovery:
- Keep app registrations, role assignments, and any other configuration consistent on both schedulers so your workers and clients can connect to either one after a failover.
- Consider keeping the schedulers' capacity (
sku.capacity) aligned so the secondary can absorb the full workload if it's promoted.
Note
The secondary doesn't serve read-only queries or process business requests before promotion. Every data-plane business call to it - including orchestration, entity, and task hub operations - returns HTTP 503 Service Unavailable. Validate the full workload through a planned failover.
Perform a failover
Planned and forced failover are two different operations, and they're alternatives - not steps you perform in sequence. Both target the scheduler that is currently the secondary (currentSecondaryId).
Perform a planned failover
Use a planned failover when both schedulers are healthy and reachable, for example to validate your runbook or to move traffic ahead of scheduled maintenance. A planned failover stops new data-plane traffic on the current primary, performs a planned transition of the underlying database, promotes the secondary, and reverses the primary/secondary roles. It doesn't drain or wait for orchestrations that are already running. Send the request without a request body:
az rest --method post \
--uri "https://management.azure.com${currentSecondaryId}/failoverInstances/default/failover?api-version=${apiVersion}"
Replicated orchestration and entity state can resume on the newly promoted primary once your clients and workers target its endpoint.
Perform a forced failover
Use a forced failover only when the current primary is unreachable and a planned failover isn't possible. Send this action without a request body:
az rest --method post \
--uri "https://management.azure.com${currentSecondaryId}/failoverInstances/default/forceFailoverAllowDataLoss?api-version=${apiVersion}"
Because the primary is unreachable, any data that didn't already replicate before the outage isn't available after the failover. The promotion is asynchronous; check its completion the same way as shown in Confirm the failover completed.
If a forced failover request returns 409 OperationPending, check provisioningState, failoverState, and replicationRole. The scheduler might already be the primary while recovery steps are still pending. Don't reissue a forced failover. If the operation reports failure or can't complete, contact Azure support.
Confirm the failover completed
Poll the resource that is becoming the new primary and wait until the response shows both replicationRole equal to Primary and failoverState equal to Succeeded before you treat the failover as complete and redirect traffic:
az rest --method get \
--uri "https://management.azure.com${currentSecondaryId}/failoverInstances/default?api-version=${apiVersion}"
Once the failover succeeds, update your role-tracking variables so later commands target the correct scheduler:
tmp=$currentPrimaryId
currentPrimaryId=$currentSecondaryId
currentSecondaryId=$tmp
Redirect your app
Disaster recovery doesn't provide a shared or floating endpoint. After you confirm the failover succeeded, update the scheduler endpoint used by both your clients and your workers to point at the new primary (currentPrimaryId). Ensure your client and worker identities have the role assignments and network access they need on the new primary. For supported authentication and RBAC patterns, see Configure managed identity for Durable Task Scheduler.
Fail back
Disaster recovery doesn't fail back automatically. Updates to the former primary are best-effort while its region is unavailable, so before you fail back:
- Confirm the former primary's region is healthy and reachable.
- Poll its
failoverInstances/defaultresource and verifyreplicationRolereportsSecondary.
Once you verify both, fail back the same way you performed the original failover:
- Trigger a planned failover targeting the current secondary (the former primary).
- Confirm the failover completed and update your
currentPrimaryId/currentSecondaryIdvariables. - Redirect your clients and workers to the new primary's endpoint.
Stop disaster recovery
To stop replication while keeping both schedulers, disable disaster recovery on the current primary scheduler:
az rest --method delete \
--uri "https://management.azure.com${currentPrimaryId}/failoverInstances/default?api-version=${apiVersion}"
Run the delete against whichever scheduler is the current primary - deleting the failover resource on the secondary while the pairing is active isn't allowed.
This operation is asynchronous. It cleans up the failover relationship on both schedulers and returns the formerly secondary scheduler to normal standalone operation. If the partner region is unavailable when you disable, you might need to complete cleanup on the partner after the region recovers.