HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Vault Home

Manage performance replication

Enterprise

Appropriate Vault Enterprise license or HCP Vault Dedicated cluster required.

Manage a running performance replication set: promote a performance secondary, revoke a secondary, change path filters, and point a secondary at a new primary. To set up performance replication, refer to Enable performance replication.

Performance replication operations use a normal Vault token. They do not need a DR operation token.

Before you start

  • Check your permissions. Run every command from the root namespace, with a token whose policy grants the endpoint you call. The secondary token endpoint also needs sudo.

  • Check the replication status. Read sys/replication/performance/status on each cluster before and after each change. Refer to Monitor replication.

Promote a performance secondary

Promote a performance secondary when you need it to replace the performance primary, for example to retire the primary's site.

Warning

Only one performance primary can be active at a time. Two active primaries can cause data loss. Demote or disable the original primary before you promote.

Clients do not keep their tokens and leases across a promotion. Each performance cluster issues its own tokens and leases, so clients must authenticate again on the new primary.

If the performance primary failed and has a DR secondary, promote the DR secondary instead. A DR secondary keeps the primary's tokens and leases. Refer to DR failover.

Step 1: Demote the original primary

Run the following command on the original performance primary. The cluster becomes a performance secondary that does not connect to any primary. It keeps its cluster ID, so you can reconnect it later without wiping its storage.

$ vault write -force sys/replication/performance/primary/demote

Refer to Demote performance primary.

Step 2: Promote the secondary

Run the following command on the performance secondary you want to promote:

$ vault write -force sys/replication/performance/secondary/promote

Parameters:

  • primary_cluster_addr (string: ""): The cluster address that the new primary gives to secondaries. Set it when a load balancer fronts the cluster port.
  • force (bool: false): Promotes the cluster even if it fails safety checks.

Warning

Do not set force unless you accept data loss. A forced promotion skips safety checks, and the promoted cluster loses any data that did not replicate.

Refer to Promote performance secondary.

Step 3: Reconnect the other clusters

For data safety and security, the other clusters need new secondary activation tokens from the new primary. For each cluster that you want in the replication set, including the demoted original primary:

  1. On the new primary, generate a secondary activation token. Refer to Step 2: Generate a secondary activation token.

  2. On the cluster, update its primary with the token. Refer to Update a secondary's primary.

  3. Re-create the cluster's path filter on the new primary, if it had one. Refer to Change a path filter.

Step 4: Update clients

Point clients that used the original primary at the new primary. Clients must authenticate again and request new leases.

Update a secondary's primary

Update a performance secondary's primary to point it at a new primary, or to help it find the primary's active node after a leader change. The update does not wipe data on the secondary.

Choose one of two methods. You cannot use both in one call.

  • Activation token: Pass a new secondary activation token from the primary in the token parameter. Use this method when the secondary connects to a different primary.
  • Cluster addresses: Pass a list of the primary's cluster addresses in the update_primary_addrs parameter. Vault tries each address in order and uses the first one that responds. Use this method when the secondary cannot find the active node of its current primary. It disrupts replication less than a new activation token.

Run one of the following commands on the performance secondary:

$ vault write sys/replication/performance/secondary/update-primary \
    token="<activation-token>"

Parameters:

  • token (string): A secondary activation token from the primary. An empty value keeps the cluster a secondary but clears its knowledge of any previous primary, so it stops trying to reconnect.
  • update_primary_addrs (array: []): Cluster addresses of the primary to try in order.
  • primary_api_addr (string): The primary's API address. Set it when the address in the token is not reachable from the secondary.
  • ca_file (string: "") and ca_path (string: ""): The CA file or directory that the secondary uses to verify the primary's API certificate when it unwraps the token.

When you update a secondary with a new activation token, re-create its path filter on the primary.

After a DR failover of the performance primary, check each performance secondary. Refer to Combine DR and performance replication.

Refer to Update performance secondary's primary.

Change a path filter

A path filter controls which mounts and namespaces replicate to one performance secondary. Identify the secondary by the secondary_id value in its replication status. Run every command in this section on the primary.

Read the filter

Read the filter's mode and paths:

$ vault read sys/replication/performance/primary/paths-filter/<secondary-id>

To see the namespace and mount paths that Vault filters dynamically for the secondary, read the dynamically generated filter:

$ vault read sys/replication/performance/primary/dynamic-filter/<secondary-id>

Replace the filter

Write the filter with every path you want filtered, not only the new ones. The paths parameter is a list, so the CLI command passes the request as JSON on stdin:

$ echo -n '{"mode": "deny", "paths": ["<mount-path>", "<namespace-path>"]}' \
    | vault write sys/replication/performance/primary/paths-filter/<secondary-id> -

Parameters:

  • mode (string: "allow"): allow replicates only the listed paths. deny replicates everything except the listed paths.
  • paths (array: []): The mount and namespace paths to filter.

Remove the filter

Delete the filter for the secondary:

$ vault delete sys/replication/performance/primary/paths-filter/<secondary-id>

Refer to the paths filter endpoints.

Revoke a secondary

Revoke a secondary to disconnect it from the primary immediately. The secondary cannot reconnect unless you give it a new activation token. Use the id value you set when you generated the secondary's activation token.

Run the following command on the primary:

$ vault write sys/replication/performance/primary/revoke-secondary \
    id="<secondary-id>"

To remove a cluster from performance replication entirely, disable performance replication on it. Refer to Disable performance secondary.

Warning

Disabling replication changes a cluster's ID. To connect the cluster to a replication set again, you must wipe its storage.

Refer to Revoke performance secondary token.

Reference

Edit this page on GitHub