Vault Enterprise Filtered Paths: Minimizing Replication Scope for Ops and Exam Prep

Vault replication is powerful, but you should not necessarily replicate everything. Compliance and data locality requirements often demand a design that intentionally narrows what gets replicated.

This article focuses on Vault Enterprise Filtered Paths (path-based filtering): how to restrict what gets replicated on performance replication, how it differs from DR replication, and practical patterns that combine it with local mounts and namespaces.

Filtered Paths: Overview and Assumptions

Filtered Paths is a Vault Enterprise mechanism for narrowing the scope of performance replication at the path level. You define include (allow) and exclude (deny) rules so that only the minimum necessary data is sent to secondaries.

A key point: Filtered Paths controls the replication layer and is distinct from policy-based access control for clients. Policies decide whether reads or writes are allowed, while Filtered Paths limits the data that actually arrives on secondaries.

Local mounts (local=true) take data under that mount out of both performance and DR replication. It is a coarser grain, but a reliable way to guarantee exclusion.

• Scope: Vault Enterprise performance replication
• Goal: Minimize the volume and surface of data sent to secondaries (lower cost and risk)
• Complementary roles: policies control access; Filtered Paths controls what is replicated
• Alternatives and complements: local mounts and namespace-scoped secondaries

Performance vs. DR Replication: Comparison and How to Restrict Each

Vault replication comes in two main forms: performance replication and DR replication. Filtered Paths is a concept used with performance replication. DR replication targets failover, so it prioritizes completeness over selective replication.

There are several ways to restrict what is replicated; pick the right one for the requirement. Use Filtered Paths for fine-grained control, local mounts to exclude entire mounts, and namespace-scoped secondaries when you want to split replication by tenant or organization.

• Performance replication: for read distribution and low latency; Filtered Paths is the center of the design
• DR replication: focused on failover; do not selectively filter as a rule, and use local mounts for the minimum necessary exclusions
• Namespace scope: effective for designs where multi-tenancy requires only a specific subtree on a secondary

Filter Design Basics: Include-First and Naming Conventions

Misconfigured path-based filters can cause data leaks or unexpected gaps. In practice, start with an include-first (allow-list) plus least-privilege approach and expand coverage gradually.

Group path names by prefix, with hierarchy that reflects team, system, and data sensitivity. That way responsibility boundaries map cleanly to filter rules. Regardless of engine type (KV, PKI, Transit, etc.), you can design with logical-path prefix matching.

Filtered Paths rules are defined and applied through dedicated settings for includes and excludes. Follow your Vault Enterprise version's documentation for evaluation order and detailed semantics, and always validate in a staging environment.

• Start from an allow-list with the minimum necessary scope
• Align path granularity to teams or boundaries (e.g., team-a/*)
• Document naming conventions and detect deviations in CI
• Roll changes out incrementally and confirm via audit logs

How Filtered Paths evaluation works

Implementation Patterns: Filtered Paths vs. Namespaces vs. Local Mounts

When you need fine-grained replication control, build the design around Filtered Paths. Organize logical paths by team or application and define an allow-list. Watch the impact with audits and metrics, and expand the scope gradually.

In tenant-isolated environments, splitting replication along organizational boundaries with namespace-scoped secondaries simplifies operations. Combine this with policies to keep each secondary holding only the minimum necessary paths.

For data that compliance forbids from leaving to a secondary (e.g., region-restricted data or experimental mounts), create or adjust the mount with local=true to exclude it from the replication layer entirely.

• Filtered Paths: fine-grained optimization; apply changes incrementally with a rollback plan
• Namespace scope: the default pattern for multi-tenant operations; boundary design is critical
• Local mount: hard exclusion; best for keeping an entire mount out of replication

Operations: Validation, Auditing, and Change Management

Always validate filter designs against a staging secondary. Inject test data into representative paths and verify both reachability and policy consistency. Continuously monitor audit logs and metrics for unexpected arrivals or omissions.

Build a workflow for changes covering request, review, implementation, and verification, with rollback procedures prepared in advance. Filtered Paths rule changes affect future replication. Agree up front on how data already present on secondaries will be handled (auto-deletion behavior and manual cleanup policy).

In DR replication environments, operations are more stable if you standardize on no filtering by default and reach for local mounts only when exclusion is truly required.

• Verify reachability in staging and cross-check with audit logs
• Apply changes in small steps with the impact scope clearly documented
• Prioritize completeness for DR; standardize exclusions on local mounts
• Continuously monitor backlogs via metrics and the status API

Minimal CLI Example: Local Exclusion and Enabling Performance Replication

Below is a minimal example that excludes some mounts via local mounts while enabling performance replication. The Filtered Paths rule configuration itself depends on Enterprise feature specifics, so follow the official procedure for the version you are running.

The key point: by creating the team-b mount as local, it is excluded from both performance and DR replication, while team-a remains replicated, which the setup lets you verify directly.

• Local mount: reliably excludes an entire mount
• Performance replication: for read distribution; Filtered Paths design is separate

Example: local exclusion + performance replication

# Primary でログイン
vault login <root>

# マウント作成（team-a は複製対象、team-b はローカル＝除外）
vault secrets enable -path=team-a kv-v2
vault secrets enable -local -path=team-b kv-v2

# サンプルデータ投入
vault kv put team-a/app foo=bar
vault kv put team-b/app baz=qux

# パフォーマンスレプリケーションを有効化（Primary 側）
vault write -f sys/replication/performance/primary/enable

# セカンダリ有効化用のトークンを作成（出力値を控える）
# 実際の出力・パラメータは利用バージョンのドキュメントに従ってください
vault write -f sys/replication/performance/primary/secondary-token

# Secondary 側で有効化（<token>は上記で取得）
vault write sys/replication/performance/secondary/enable token=<token>

# 検証: Secondary で team-a は取得可能、team-b は存在しない想定
vault kv get team-a/app     # => 存在するはず
vault kv get team-b/app     # => 見つからない（local で除外）

Exam Tips: Common Ops-Perspective Pitfalls

Do not confuse the scope: Filtered Paths is about performance replication, and DR filtering is generally not supported. A mount's local flag is an exclusive exclusion that applies to both replication types.

A policy deny does not stop replication itself. To meet a requirement of not delivering data to a secondary, use Filtered Paths or local mounts.

Namespace scope is effective for coarse-grained separation; complement it with Filtered Paths for path-level optimization.

• Path filtering is not supported on DR; design around locality
• local=true is a powerful exclusion; apply it carefully
• Access control (policies) and replication control (Filtered Paths) are different things

Check Your Understanding

Frequently Asked Questions