Replication architecture: Stronghold and Stronghold EE

This page shows the architectural differences between Stronghold and Stronghold EE through the layers of a single node, and explains how the order of those layers shapes replication behavior: why the replication stream carries already-encrypted data and why each cluster owns its own seal.

Base Stronghold corresponds to Vault CE. The diagrams are simplified: they show what a node is made of and the direction of requests, not the network layout. The diagram notation is collected in the “Legend” section at the end of the page.

Comparing replication levels and variants

Replication works at several levels — within a cluster, between clusters, and per individual mount (KV). There are five variants in total; they are covered in more detail below.

Layers of a single node

A request passes through the node layers top to bottom: what sits lower is applied later and obtains the data as the layers above already processed it.

Stronghold node

In base Stronghold a node has four layers: Stronghold API → Security Barrier → Raft → Physical storage.

1. Stronghold API accepts a request and routes it to the right backend.
2. Security Barrier encrypts the data. Everything below the barrier exists only in encrypted form.
3. Raft handles consensus and storage replication between the nodes of a cluster (fault tolerance).
4. Physical storage is the on-disk backend; the data there is already encrypted.

Base Stronghold has neither a WAL Backend nor seal wrap. That is why such a cluster does not take part in cross-cluster replication and has no second encryption layer.

Stronghold EE node

Stronghold EE adds two layers, and where they sit matters: Stronghold API → Security Barrier → WAL Backend → (storage cache) → Sealwrap → Raft → Physical storage.

• WAL Backend sits right under the barrier. It records every mutation into an ordered log that serves as the data source for replication. Because it is below the barrier, the log receives values that are already barrier-encrypted.
• Sealwrap wraps the storage backend: it sits below the WAL Backend (and the storage cache) and directly above Raft, so Raft receives and replicates between nodes values that are already seal-wrapped. It is a second encryption layer for sensitive paths; the key is held by the seal (the external Sealwrapper box).

Nodes in a cluster

Several nodes form a cluster on top of shared Raft storage: one node is active, the rest are standby. Nodes sync data over Raft (orange arrows), so every node holds a full encrypted copy of the storage. A cluster has a single seal — one Sealwrapper for the whole group.

HA cluster (Stronghold)

The client reads from and writes to the active node (green R/W). In base Stronghold, standby nodes do not serve requests: they forward both reads and writes to the active node (Forward R/W). The active node syncs storage to the standby nodes over Raft — this provides fault tolerance: if the active node fails, one of the standby nodes becomes active.

Performance standby (Stronghold EE)

The same HA cluster, but in Stronghold EE the standby nodes act as performance standby: they serve reads locally and forward writes to the active node (Forward only Write). To keep the standby nodes serving fresh data, the active node streams log events to them (blue WAL arrows). Because the WAL Backend is below the barrier, these events carry already-encrypted data. The cluster still has a single seal — one shared external Sealwrapper.

See the Performance standby page for details.

Clusters between each other

Cross-cluster replication is available only in Stronghold EE. It links whole clusters: the primary streams its log to the secondary (blue Data WAL Streaming), and the secondary forwards client writes back to the primary. Each cluster has its own Sealwrapper, and it may differ.

Performance

The primary streams only non-local data to the secondary — shown on the diagram as the filtered log filtered WAL. Local mounts and data stay on each cluster and never leave it. The secondary serves reads locally and forwards writes to the primary. There can be several secondary clusters — the primary streams to all of them. You can limit the data replicated to a specific secondary with path filters. The primary and the secondary each have their own seal (Sealwrapper 1 and Sealwrapper 2).

Disaster Recovery

DR copies everything, including local data — shown on the diagram as WAL. The secondary is a full copy of the primary, but it does not serve clients and waits for a promote (Promote Request). When the primary fails, the secondary is promoted and takes over. The promote steps and how to recover the former primary are on the “Disaster recovery” page. The primary and the secondary each have their own seal (Sealwrapper 1 and Sealwrapper 2).

Why the seal can differ between clusters

The replication stream is captured at the WAL Backend level, that is above the sealwrap layer. So the seal wrap has not yet been applied to the source data, and the data encrypted by the seal is never sent across the cross-cluster link. Hence:

• the secondary applies seal wrap with its own seal, not the primary’s;
• the primary and the secondary may even use different seal types (for example, different KMS);
• seal wrap is configured per cluster and does not depend on replication.

For more, see the “Double encryption (seal wrapping)” page. For what exactly is replicated in each mode, see the “Replication overview”.

KV replication (at the API level)

KV replication stands apart from cross-cluster WAL replication. It is performed by a separate component — the KV replicator — located in the topmost node layer, Stronghold API, that is above the Security Barrier. Because of that it does not work with the encrypted WAL stream but with logical secrets through the regular public API endpoints.

How KV replication is different from performance and DR replication:

• API level, not WAL. WAL replication is captured below the barrier (at the WAL Backend layer) and carries the ciphertext of a whole cluster. KV replication works above the barrier, talking to API endpoints, and syncs only KV1/KV2 mounts.
• Configured on the slave node. A master-slave, pull model: the consumer (slave) reaches out to the source (master) and pulls the secrets. The configuration is set when mounting a KV store on the consumer side.
• Works at the node level. Since it communicates through a specific node’s API endpoints, replication is configured on a specific node of a cluster, not on the cluster as a whole.
• Compatible with other stores. The master can be a store of a different version or implementation — Vault CE, Vault EE, or any secret store with a compatible Vault KV/KV2 API. This simplifies migration and makes heterogeneous architectures possible.

KV replication can be enabled on any node that serves API endpoints, regardless of its role in performance and DR replication. The only exception is a DR secondary: it does not answer client requests until promoted, so KV replication is not available there.

KV replication is unrelated to the seal, the WAL, and cross-cluster replication, and is configured per mount.

See the “KV1/KV2 replication” page for details.

Combined topologies

The modes are independent and can be combined:

• One primary, both modes at once. A cluster can be a performance primary and a DR primary at the same time: streaming data to performance secondaries and keeping a DR standby.
• Each cluster is HA itself. Primaries and secondaries in cross-cluster topologies are full HA clusters; in Stronghold EE their standby nodes serve reads as performance standby.
• Multiple secondaries. A single primary can have many secondary clusters — both performance and DR.

Below are a few examples of such combinations. The size (HA or a single node) is chosen per cluster, KV replication can be attached to any cluster except a DR secondary, and each cluster owns its own seal — so seal wrap can be configured differently across a topology: every cluster with its own seal somewhere, one and the same seal elsewhere, or none at all (disable_sealwrap).

The primary is a DR and a Performance primary at once and consists of a single node; both secondaries are HA clusters, and a separate cluster feeds the primary over KV replication. Each cluster owns its own seal — Sealwrapper 1…4 are all different in this topology.

The same combined primary, but HA with performance standby; both secondaries are HA clusters too. KV replication is attached to a performance secondary — so it can be added not only to the primary. The clusters use different seals — Sealwrapper 1 and Sealwrapper 2.

An HA primary with performance standby streams data to single-node DR and Performance secondaries; KV replication is not used, and all clusters are configured with one and the same seal — Sealwrapper 1.

Legend

The diagrams have two levels of objects (node and cluster) and three kinds of links, distinguished by color.

There are two kinds of links:

• Raft (orange arrows) syncs nodes within a single cluster.
• replication (blue arrows between clusters) links clusters to each other.

Green arrows are client access and the forwarding of their writes.

The node layer colors: