Vault Mount Filters: Per-Mount Replication Control

Vault Enterprise's Performance Replication lets you scale out reads, but you often do not want every mount replicated. Mount Filters are the mechanism that lets you control, from the primary, which mounts (secrets engines / auth methods) are replicated to secondaries.

This article walks through Mount Filters from an Ops perspective: design considerations, configuration and verification steps, and troubleshooting fundamentals. We stick to stable concepts that align with the official Vault documentation.

Mount Filters: Basics and Prerequisites

Mount Filters are a Vault Enterprise feature for Performance Replication that restrict which mounts replicate from primary to secondary. In practice they are most often used to exclude sensitive mounts, or to safely narrow scope with an Allowlist mode that permits only specific mounts.

Key prerequisite: Mount Filters control Performance Replication. DR Replication assumes a consistent full copy of all data, so per-mount filtering does not apply there. Mount Filters are configured on the primary and evaluated according to the replication topology.

• Scope: secrets engines and auth methods (Vault treats both as 'mounts')
• Modes: Allowlist (explicit allow) or Denylist (explicit exclude)
• Evaluation unit: path prefix (forward match) is the basic specifier
• Where it applies: Performance Replication only — not DR
• Namespace handling: in Enterprise Namespaces environments, evaluate per-namespace (implementation/configuration dependent)

Evaluation Timing and Default Behavior

By default (with no Mount Filters configured), Performance Replication replicates ordinary mounts to secondaries. Vault's internal/system paths and explicitly-local mounts (Local Mount, discussed below) are out of scope.

Once Mount Filters are configured, the primary includes or excludes mounts according to the rules. Allowlist means 'replicate only what is listed,' and Denylist means 'exclude what is listed, replicate everything else.' Avoid complex conflicting rules — pick one consistent policy and design around it.

• Filters are evaluated on the primary (per-secondary overrides are not generally expected)
• Specify paths in clear tiers (e.g. kv/prod/) so they are neither over- nor under-inclusive
• Filter changes trigger replication re-evaluation, so make them during a planned maintenance window

Conceptual diagram of Mount Filters (Performance Replication)

Comparison: Local Mount, Namespaces, and DR

Design Mount Filters alongside Local Mount, Namespaces, and DR Replication. The comparison below clarifies the points most commonly confused on the exam and in the field.

• Local Mount is not 'excluded from replication' — it assigns 'local to the cluster' semantics. Different use case.
• DR is for failover and aims at a complete copy — partial exclusion is not how it is used.
• Namespaces are logical compartments for permission boundaries and operational separation. Mount Filters are technical control of replication scope.

Configuration and Verification: A Safe Rollout Process

The procedure below is a typical example. Actual API paths and fine-grained parameters can differ by edition and version, so check the official documentation before doing the work. For production especially, we strongly recommend rehearsing in a test environment with the same configuration.

The four key points are: 1) inventory current mounts and dependencies, 2) design the filter (Allowlist recommended), 3) apply in stages, and 4) prepare a rollback procedure in advance.

• Preconditions: confirm you are on the Performance Primary and that replication with the secondaries is healthy
• Impact analysis: enumerate clients/roles/policies that use the mounts you plan to exclude
• Apply: start with the minimum Allowlist set and expand in stages
• Verify: read locality, latency, and visibility of in-scope mounts on the secondary
• Rollback: prepare a plan and approval path to remove or loosen the filter

CLI example (conceptual — verify the actual paths/parameters against the official docs in your environment)

# 1) 現行のレプリケーション状態を確認（役割/健全性）
$ vault read -format=json sys/replication/status | jq .

# 2) 現行のマウント（シークレットエンジン）と認証メソッドを棚卸し
$ vault read -format=json sys/mounts | jq '.data | keys'
$ vault read -format=json sys/auth   | jq '.data | keys'

# 3) Mount Filters（Allowlist）の設定例
#   例: kv/prod/ と transit/ のみ複製する
#   注: 実際のエンドポイント名やフィールドはバージョンで異なる可能性あり
$ vault write sys/replication/performance/primary/mount-filter \
    mode=allowlist \
    paths=kv/prod/*,transit/*

# 4) 設定の確認（フィルタ内容）
$ vault read sys/replication/performance/primary/mount-filter

# 5) セカンダリでの結果確認（対象マウントが見える/読めること）
#    読み取りはセカンダリでローカルに終了するが、書き込みはプライマリにフォワードされる点を理解して検証
$ vault login <secondary_token>
$ vault kv get kv/prod/sample
$ vault kv get kv/pii/sample   # 期待: フィルタで除外されていれば不可視/非該当

# 6) ロールバック（フィルタの削除/緩和）
$ vault delete sys/replication/performance/primary/mount-filter

# 7) 変更後のレプリケーション健全性と遅延を再確認
$ vault read -format=json sys/replication/status | jq .

Operations, Monitoring, and Troubleshooting Essentials

Because filter changes trigger replication re-evaluation, secure a change window and a rollback plan. If the set of mounts visible from a secondary shrinks, client authorization flows and dependent jobs can fail — upfront impact analysis is mandatory.

For monitoring, watch replication lag, failure counters, and secondary error logs (permission denied, path not found) together. Understand in advance how the audit log records access attempts to excluded mounts, and bake that into your runbooks.

• Secure a planned window and apply changes in stages (canary secondary → all)
• Notify affected roles/policies/apps in advance and validate them
• Metrics/logs: replication lag, transfer failures, 404 / permission denied on the secondary
• Back-out: remove the filter → confirm health → re-run dependent jobs

Exam Cheat Sheet (Ops)

The exam frequently asks you to cleanly separate where Mount Filters apply, how they differ from DR, and how their role differs from Local Mount and Namespaces.

• Mount Filters are for Performance Replication. Partial exclusion via filters is not how DR is used.
• Allowlist replicates 'only what you list.' For least-privilege design, Allowlist is the safer default.
• Local Mount assigns a 'local' attribute — it is not a substitute for Mount Filters.
• Namespaces are permission/operational boundaries. Filters are technical control of replication scope — a different axis.
• Configure on the primary; per-secondary overrides are generally not expected.

Check Your Understanding

Frequently Asked Questions