Enable and Configure Disaster Recovery DR Replication

Vault Enterprise’s Disaster Recovery (DR) replication creates a warm-standby cluster that can be promoted instantly if your primary fails. In this guide, you’ll learn how Vault replication works, compare performance and DR modes, review reference architectures, and walk through both CLI and UI setup.

What Is Vault Replication?

Vault replication offers a global, consistent view of your policies, secret engines, auth methods, KV data, and audit configurations—eliminating manual duplication and ensuring high availability across data centers or cloud regions. It uses a leader-follower model with one primary (leader) cluster and one or more secondary (follower) clusters. All inter-cluster communication is end-to-end encrypted with mutual TLS.

The image explains Vault Replication, highlighting that it is available only in Vault Enterprise and operates on a leader-follower model with primary and secondary clusters. It emphasizes end-to-end encrypted communication and asynchronous data replication.

Performance vs. Disaster Recovery Replication

Vault Enterprise supports two replication modes. Select the one that matches your use case:

Feature	Performance Replication	Disaster Recovery (DR) Replication
Data & Config	Policies, Secrets engines, Auth methods, KV data, Audit logs	Same as Performance + Tokens & Leases
Read Traffic	Served locally	Not served (warm standby)
Write Traffic	Forwarded to primary	Not served
Tokens & Leases	Not replicated	Replicated
Typical Use Case	Global read scaling	Fast failover and seamless client ops

The image explains "Disaster Recovery Replication" for Vault, highlighting that it replicates configurations and data, cannot service reads from client requests, and requires client authentication with the primary cluster. It includes a diagram showing the flow between a primary and secondary cluster.

Replication Comparison

Here’s how a performance secondary, primary, and DR secondary differ. Only DR replication includes tokens and leases in the secondary:

The image is a diagram comparing three clusters: Perf Secondary Cluster, Primary Cluster, and DR Secondary Cluster, showing data replication processes and components like Vault Policies, Secrets Engines, Auth Methods, and Audit Configurations.

DR Secondary Characteristics

A DR secondary acts as a warm standby. It accepts replication logs but:

Does not serve any client operations (reads or writes).
Keeps most API paths disabled—even for admin or root tokens—until you promote it.

The image is a slide about "Disaster Recovery Replication," explaining that it provides a warm-standby cluster where everything is replicated to secondary clusters, which do not respond to clients unless promoted to a primary cluster. It also notes that most paths on a secondary cluster are disabled, even for admins.

Reference Architectures

Choose the topology that fits your environment:

Two Data Centers

Data Center A: Primary + local DR secondary
Data Center B: Performance secondary + local DR secondary
Clients talk to their local cluster; on failure, promote the DR node.

The image illustrates a replication architecture between two data centers, showing a primary cluster and a DR replication cluster in Data Center A, and a performance replication cluster and DR replication cluster in Data Center B.

AWS Regions

Northern Virginia: Primary + DR
Northern California: Performance + DR
Ideal for multi-region AWS deployments.

The image illustrates a replication architecture on a map of the United States, showing AWS data centers on the east and west coasts with arrows indicating data replication between them.

On-Prem VMware Example

Data Center A: Production primary + DR
Data Center B: Performance + DR
Separate non-prod environment mirroring production for QA/testing.

The image is a diagram illustrating a real-world customer example of data replication between two data centers, showing production and non-production environments with VMware clusters. It highlights DR (Disaster Recovery) and performance replication processes.

On-Prem to AWS Example

On-prem DC: Production primary + DR
AWS: Performance + DR
Dedicated non-prod and QA clusters.

The image is a diagram showing a real-world customer example of an on-premises datacenter setup with production, non-production, and QA environments, and their replication to AWS.

Networking Requirements

Bidirectional Vault-to-Vault on ports 8200 (cluster bootstrap/API) and 8201 (replication/Raft forwarding).
DNS resolution between clusters must be configured.

Warning

Open these ports only between trusted Vault clusters. Exposing replication ports publicly can lead to security risks.

Enabling DR Replication

Follow these three steps to set up DR replication via the CLI:

The image is a flowchart illustrating the setup process for a system, involving steps like activating a primary, fetching a secondary token, activating a secondary, and replication. It includes icons and brief descriptions for each step, with a Vault certification badge in the corner.

1. Activate DR on the Primary

Vault generates an internal CA and mutual-TLS certificates for secure inter-cluster links. If you’re behind a TLS-terminating load balancer, pass through port 8201.

The image is a slide about activating DR replication in Vault, detailing the need to enable replication on each cluster, use an internal root CA, and establish mutual TLS connections. It also notes potential issues with load balancers terminating TLS.

vault write -f sys/replication/dr/primary/enable

2. Generate the Secondary Token

Create a one-time, response-wrapped token to authorize the DR secondary. It includes the CA cert, client cert/key, and primary’s API address.

The image is a slide discussing the concept of a "Secondary Token" used for permitting a secondary cluster to replicate from a primary cluster, highlighting its sensitivity, single-use nature, and the information it includes. It features a Vault certification badge and a cartoon character at the bottom right.

vault write sys/replication/dr/primary/secondary-token id="us-east-2-dr"

Inspect the unwrapped token to see embedded details:

{
  "data": {
    "ca_cert": "...",
    "client_cert": "...",
    "client_key": { "type": "p521", "x": "...", "y": "...", "d": "..." },
    "cluster_id": "0d127970-99ce-152f-0311-3b081d126d43",
    "id": "secondary",
    "primary_cluster_addr": "https://vault-pr.hvcop.com:8201"
  }
}

Warning

Treat the secondary token like a password. It’s single-use and grants high privileges.

How the Token Is Used

The secondary submits the wrapped token to the primary API (:8200).
It unwraps the token and retrieves certs and cluster info.
Replication over port 8201 then begins automatically.

The image illustrates the process of how a secondary token is used, showing steps like token creation, submission, and unwrapping via an API address. It includes icons and a flowchart on a yellow background, with a Vault certification badge in the corner.

The image is a flowchart illustrating the process of using a secondary token, showing steps from token creation to secondary cluster readiness. It includes labeled icons and a certification badge for a Vault Certified Operations Professional.

3. Activate DR on the Secondary

vault write sys/replication/dr/secondary/enable token="<response-wrapped-token>"

Once the secondary connects, replication starts immediately.

Configuring DR via the UI

You can also enable DR replication through Vault’s web interface:

Primary
- Navigate to Status → Replication → Enable Replication
- Choose Disaster Recovery – Primary, then click Enable
- Click Add Secondary, assign a name, and Generate Token. Copy the token.
Secondary
- Go to Status → Replication → Enable Replication
- Select Disaster Recovery – Secondary
- Paste the activation token and click Enable

Monitoring Replication

Use the Vault CLI to verify replication health and status:

vault read -format=json sys/replication/status
vault read -format=json sys/replication/performance/status
vault read -format=json sys/replication/dr/status

sys/replication/status: Shows both performance and DR replication
sys/replication/performance/status: Performance only
sys/replication/dr/status: DR only

Now you’re ready to deploy DR replication in your Vault Enterprise environment or practice these steps for the Vault Certified Operations Professional exam.

References

Watch Video

Watch video content