Replication

Vault Enterprise supports two replication modes — performance replication (read-only secondaries that can serve most reads locally) and disaster-recovery replication (warm-standby clusters) — built on top of the same WAL log. The OSS tree contains the seams where replication hooks plug in but not the implementation. Sources: vault/replication/ (one-file stub), vault/forwarded_writer_oss.go, plus dozens of _oss.go and _ce.go files across the tree.

Purpose

• Document what's visible from OSS and what's only in Enterprise, so contributors don't accidentally remove stubs that Enterprise depends on.
• Show how the codebase is sliced so that replication hooks attach cleanly without leaking Enterprise concepts into OSS.

What you'll see in OSS

vault/replication/
└── cluster.go        # tiny stub: type ClusterInfo struct {} and a few unused symbols

vault/
├── forwarded_writer_oss.go        # placeholder for the WAL forwarder
├── replication_status.go          # surfaces (mostly empty) replication state to API/CLI
└── various *_oss.go and *_ce.go   # one-line stubs that Enterprise overrides

The CLI's vault read sys/replication/status returns a payload describing replication mode (disabled in OSS) and per-secondary state. api/replication_status.go is the client-side view of the same payload.

Why the stubs exist

Every place where Enterprise needs to:

• Filter mounts during replication (mount_stubs_oss.go)
• Forward a write to the primary (forwarded_writer_oss.go)
• Resolve identity-store conflicts during merge (identity_store_conflicts.go)
• Report replication status to clients (replication_status.go)
• Apply Enterprise-only seal options (seal_stubs_oss.go, seal_rewrap_stubs_oss.go)

…the OSS tree carries an empty function or a default-return stub so the build succeeds with -tags= (default) but Enterprise can replace the file at link time when built with -tags=enterprise.

If you delete an _oss.go stub, the Enterprise build will fail to compile. Always keep them.

Two-cluster model

graph LR
    subgraph "Primary cluster"
        PA[Active] --> PSt[Storage]
        PA --> PWAL[(WAL stream)]
    end
    subgraph "Performance secondary"
        SA[Active] --> SSt[Storage]
        SWAL[(WAL apply)] --> SSt
        SA -.forwarded write.-> PA
    end
    PWAL --> SWAL

Performance secondaries serve reads locally and forward writes to the primary; DR secondaries stay warm and only become writable on promotion.

Performance vs DR replication

Aspect	Performance	Disaster Recovery
Read traffic on secondary	Yes, locally	No, all reads return errors
Writes on secondary	Forwarded to primary	Rejected
Token lookups	Local	Local read of replicated token table
Promotion	Manual or DR	Manual on failover
Tokens visible	Tokens issued on the secondary stay local; cross-cluster tokens are issued via "merkle batch tokens"	All issued centrally

These behaviors are entirely Enterprise. In OSS, every replication API endpoint returns "disabled".

Integration points

• vault.Core exposes Core.ReplicationState() returning consts.ReplicationDR | ReplicationPerformancePrimary | ReplicationPerformanceSecondary | ….
• vault/request_handling.go routes through the OSS forwardedWriter for writes; in Enterprise this becomes the WAL writer.
• helper/locking/ is used to protect replication-sensitive sections.
• vault/identity_store_conflicts.go defines the merge protocol; the OSS file just declares no-op resolvers.

Entry points for modification

If you're contributing to OSS:

• Don't try to add behavior that depends on replication being enabled — keep the OSS stub returning disabled.
• If you're touching a path that Enterprise replicates, make sure your changes don't break the tombstone/WAL contract documented in the Enterprise repo.
• New _oss.go stubs should mirror the function signatures of their Enterprise counterparts exactly.