Skip to main content
In this guide, you’ll learn how to enable and configure performance replication in Vault Enterprise. Performance replication lets you distribute Vault policies, secrets engines, authentication methods, and audit configurations across multiple clusters for active-active read scalability, while routing write operations to a single primary.
The image is an introduction to performance replication, explaining its features such as replicating configurations and servicing client read requests. It includes a diagram showing the relationship between a primary and secondary cluster, with Vault clients interacting with them.

​
Key Concepts

  • Active-Active Workloads: Read operations (authentication, secret reads, dynamic secret generation) are served locally on each replica.
  • Centralized Writes: All write requests (policy changes, configuration updates) are forwarded to the primary cluster.
  • Independent Authentication: Tokens and leases created on a performance secondary are local and are not replicated from the primary. Clients must re-authenticate on each cluster.

​
Performance vs. Disaster Recovery (DR) Replication

FeaturePerformance ReplicationDR Replication
Policies & Config✓✗
Secrets Engines & Auth✓✗
Audit Configurations✓✗
Tokens & Leases✗✓
Use CaseActive-active, low-latency readsFailover and disaster recovery
Write PathForwarded to primaryForwarded to primary
The image is a diagram comparing performance and disaster recovery (DR) replication in a system with three clusters: Perf Secondary, Primary, and DR Secondary. It shows the flow of replicated data, including Vault Policies, Secrets Engines, Auth Methods, Audit Configurations, Tokens, and Leases.

​
Example Architecture: Data Centers & Cloud Regions

​
Multi–Data Center Deployment

A primary cluster in Data Center A replicates to performance secondaries in Data Center B and a cloud region. Local applications read and authenticate against their nearest replica, while writes go to the primary.
The image illustrates a replication architecture with a primary cluster in Data Center A, connected to performance replication clusters in both Data Center B and a cloud region. It includes a certification badge and a cartoon character at the bottom.

​
Global Cloud Deployment

In a cloud setup, the primary (US-East2) replicates to secondaries in US-East and EU-West. Applications in each region authenticate to their local replica for reads; writes are sent back to the primary and propagated.
The image illustrates application communication across three cloud regions (US-East, US-East2, and EU-West) with performance replication clusters and local apps interacting with local vault clusters.

​
How Performance Replication Works

  1. Active-Active Authentication
    Each performance replica handles logins locally. Tokens and leases exist only on the cluster where they were issued.
  2. Local Dynamic Secrets
    Replicas generate dynamic credentials (e.g., database passwords, AWS keys) without contacting the primary:
The image is a slide about "Performance Replication," explaining an active/active solution for applications in multiple data centers, with details on authentication and failover processes. It includes a Vault certification badge.
The image is a slide about "Performance Replication" in Vault, explaining how replicated clusters handle secrets and dynamic credentials locally, offloading some operations from the primary cluster. It also notes that write requests are forwarded to the primary cluster.
  1. External Service Interactions
    Connections to AWS, databases, and other external services occur directly from each replica:
The image illustrates a diagram of interaction with external services, showing a primary cluster and a performance replication cluster connecting to AWS and a database, with indications of needing database and AWS credentials.

​
Setup Process

Follow these four steps to configure performance replication:
The image is a flowchart illustrating the setup process for a system, involving four steps: activating the primary, fetching a secondary token, activating the secondary, and replication. It includes brief descriptions for each step and features a Vault certification badge.
  1. Enable performance replication on the primary.
  2. Generate a secondary token.
  3. Enable the secondary using the token.
  4. Monitor the replication status.

​
CLI Commands

# 1. Enable performance replication on the primary
vault write -f sys/replication/performance/primary/enable

# 2. Generate a secondary token on the primary
vault write sys/replication/performance/primary/secondary-token id="secondary-id"

# 3. Activate the performance secondary with the token
vault write sys/replication/performance/secondary/enable token="secondary-token"
Enabling a secondary will purge its local data (including unseal and recovery keys) and sync entirely from the primary.

​
Monitoring Replication

# View overall replication status
vault read --format=json sys/replication/status

# View performance replication status
vault read --format=json sys/replication/performance/status

# View DR replication status
vault read --format=json sys/replication/dr/status
After setup, verify that changes—such as enabling a new auth method—on the primary cluster appear on each performance secondary.

​
References

Watch Video