Skip to main content
When your primary Vault cluster becomes unavailable, you can promote its Disaster Recovery (DR) secondary cluster to primary to minimize downtime. This tutorial walks through the steps and best practices for DR replication failover in HashiCorp Vault. The typical topology consists of:
  • A primary cluster
  • A performance replica in another data center
  • DR replicas for each cluster
If any cluster fails, its DR replica can assume the primary role in that region.
You need a DR operation token to promote a DR secondary. You can generate this token on the DR cluster using unseal or recovery keys, or pre-create a DR operation batch token on the primary to have it automatically replicate to the secondary.
The image is a slide explaining how to promote a secondary to a primary in a DR cluster, detailing the use of a DR Operation Token and the option to create a DR Operation Batch Token beforehand.

​
Comparison: Batch Token vs. Generated DR Operation Token

​
DR Operation Batch Token

A batch token is an orphan token created on the primary with permissions to promote a DR cluster. It automatically replicates to the DR secondary.
  1. Generate at the start of each shift (valid only for that period).
  2. Store securely (e.g., in an HSM or secure vault).
  3. On failure, use it immediately—no need for unseal or recovery key collection.

​
Generating a DR Operation Token

If you don’t have a valid batch token, follow these steps on the DR secondary:
The image is a flowchart explaining the process of obtaining a DR Operation Token, involving steps like initializing token generation, key holders providing keys, decoding with OTP, and promoting a cluster.

​
Step 1: Initialize DR Token Generation

Run vault operator generate-root with the -dr-token flag and -init to receive a nonce, an OTP, and progress status:
Example output:

​
Step 2: Collect Key Shares

Each key holder submits their key:
They verify the Operation nonce: 0ccf03cd-33b3-96db-577c-d5492c4cf909 and enter a unseal or recovery key. After collecting the threshold (e.g., 3 of 5), Vault returns an encoded token:

​
Step 3: Decode the Encoded Token

Use the OTP from step 1 and the encoded token to retrieve the DR operation token:
Output:
This string is your DR operation token.

​
Promote the DR Secondary

With either the batch token or generated DR operation token, run:
Example warning:
After promotion, the DR cluster will become the new primary in its data center.
During promotion, Vault will be temporarily unavailable. Plan for a brief service interruption.

Watch Video