You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ranger.apache.org by ra...@apache.org on 2026/06/23 08:46:34 UTC

(ranger) 01/13: RANGER: Add dynamic Kafka partition plan for audit ingestor.

This is an automated email from the ASF dual-hosted git repository.

ramackri pushed a commit to branch ranger-kafka-dynamic-partition-plan
in repository https://gitbox.apache.org/repos/asf/ranger.git

commit 3837be90325c0fab482ee08d7b3628840167bfe3
Author: ramk <ra...@cloudera.com>
AuthorDate: Tue Jun 16 19:16:44 2026 +0530

    RANGER: Add dynamic Kafka partition plan for audit ingestor.
    
    Introduce registry-backed partition allocation, REST management, bootstrap,
    and Docker E2E verification scripts; ship disabled by default in site XML.
    
    Co-authored-by: Cursor <cu...@cursor.com>
---
 audit-server/DESIGN-KAFKA-DYNAMIC-PARTITIONING.md  |  803 +++++++++++
 .../README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md     |  559 ++++++++
 .../README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md      |  667 +++++++++
 .../README-KAFKA-DYNAMIC-PARTITION-PLAN.md         |  253 ++++
 .../README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md     |  594 ++++++++
 ...ME-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md |  345 +++++
 .../README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md   |  216 +++
 .../README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md  |  223 +++
 .../README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md  |  461 ++++++
 .../README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md     |  272 ++++
 .../README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md   | 1476 ++++++++++++++++++++
 ...DME-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md |  497 +++++++
 audit-server/README-KAFKA-PLUGIN-PARTITIONING.md   |  307 ++++
 .../ranger/audit/server/AuditServerConstants.java  |   11 +
 .../ranger/audit/utils/AuditMessageQueueUtils.java |  140 +-
 .../audit/utils/AuditMessageQueueUtilsTest.java    |   13 +
 .../audit/producer/kafka/AuditMessageQueue.java    |   30 +
 .../audit/producer/kafka/AuditPartitioner.java     |  133 +-
 .../partition/KafkaAuditTopicPartitionGrower.java  |   32 +
 .../partition/KafkaPartitionPlanRegistry.java      |  129 ++
 .../kafka/partition/PartitionPlanAllocator.java    |  129 ++
 .../kafka/partition/PartitionPlanBootstrap.java    |  105 ++
 .../partition/PartitionPlanBootstrapConfig.java    |  120 ++
 .../kafka/partition/PartitionPlanHolder.java       |   60 +
 .../kafka/partition/PartitionPlanKafkaConfig.java  |  106 ++
 .../kafka/partition/PartitionPlanRegistry.java     |   34 +
 .../partition/PartitionPlanRegistryFactory.java    |   30 +
 .../kafka/partition/PartitionPlanService.java      |  176 +++
 .../kafka/partition/PartitionPlanValidator.java    |  105 ++
 .../kafka/partition/PartitionPlanWatcher.java      |  189 +++
 .../constants/PartitionPlanConstants.java          |   33 +
 .../exception/PartitionPlanConflictException.java  |   38 +
 .../exception/PartitionPlanException.java          |   35 +
 .../kafka/partition/model/PartitionPlan.java       |  209 +++
 .../model/PartitionPlanReplaceRequest.java         |   79 ++
 .../partition/model/PluginPartitionAssignment.java |   93 ++
 .../partition/model/PromotePluginRequest.java      |   49 +
 .../kafka/partition/model/ScalePluginRequest.java  |   49 +
 .../org/apache/ranger/audit/rest/AuditREST.java    |  162 ++-
 .../ranger/audit/server/AuditServerConfig.java     |   10 +-
 .../resources/conf/ranger-audit-ingestor-site.xml  |   61 +
 .../kafka/AuditPartitionerDynamicTest.java         |  159 +++
 .../partition/PartitionPlanAllocatorTest.java      |   81 ++
 .../PartitionPlanBootstrapSupportTest.java         |  152 ++
 .../partition/PartitionPlanBootstrapTest.java      |   73 +
 .../partition/PartitionPlanKafkaConfigTest.java    |   73 +
 .../PartitionPlanServiceMutationTest.java          |  219 +++
 .../kafka/partition/PartitionPlanServiceTest.java  |   95 ++
 .../partition/PartitionPlanValidatorTest.java      |   70 +
 .../partition/model/PartitionPlanJsonTest.java     |   48 +
 ...GER-KAFKA-DYNAMIC-PARTITION-PLAN-PR-TEMPLATE.md |  622 +++++++++
 .../scripts/audit/partition-plan-e2e-lib.sh        |  499 +++++++
 .../audit/verify-partition-plan-brownfield-e2e.sh  |  141 ++
 .../scripts/audit/verify-partition-plan-e2e-all.sh |   84 ++
 .../scripts/audit/verify-partition-plan-e2e.sh     |  235 ++++
 .../audit/verify-partition-plan-kafka-down-e2e.sh  |  122 ++
 .../audit/verify-partition-plan-multipod-e2e.sh    |  128 ++
 57 files changed, 11800 insertions(+), 34 deletions(-)

diff --git a/audit-server/DESIGN-KAFKA-DYNAMIC-PARTITIONING.md b/audit-server/DESIGN-KAFKA-DYNAMIC-PARTITIONING.md
new file mode 100644
index 000000000..80f44a9d9
--- /dev/null
+++ b/audit-server/DESIGN-KAFKA-DYNAMIC-PARTITIONING.md
@@ -0,0 +1,803 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic Kafka partitioning for Ranger audit plugins — design document
+
+**Purpose:** Single consolidated design for runtime dynamic plugin onboarding and partition scaling in the Ranger audit ingestor.
+
+**Audience:** Operators, architects, and reviewers who need a shared mental model of *what* the system does and *how* it behaves — without implementation detail.
+
+**Related deep dives (superseded for day-to-day review by this document):**
+
+| Source doc | Content absorbed here |
+|------------|----------------------|
+| [README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md](README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md) | Goals, architecture, append-only rules |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | Control plane, flows, REST semantics |
+| [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) | Phased rollout concept (high level only) |
+| [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) | Operator workflows |
+| [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) | Migration paths |
+
+**Related (orthogonal proposal):** [README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md §3](README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md#3-why-dynamic-partition-mapping-does-not-remove-allowedusers) — why dynamic partition mapping does **not** remove `service.<repo>.allowed.users` on `POST /access` (403 authz); separate from partition plan.
+
+**Baseline (static mode today):** [README-KAFKA-PLUGIN-PARTITIONING.md](README-KAFKA-PLUGIN-PARTITIONING.md)
+
+---
+
+## 1. Executive summary
+
+Ranger plugins (HDFS, Hive, Trino, etc.) send audit events to **audit-ingestor**, which writes them to Kafka topic **`ranger_audits`**. To isolate hot plugins, ingestor can route each plugin to dedicated Kafka partitions; unknown plugins share a **buffer** pool.
+
+**Today (static mode):** Plugin → partition mapping is computed once at startup from XML. Changing assignments requires config edits, topic partition growth, and **ingestor restart**. Early-plugin changes can **reshuffle** later plugins because allocation uses contiguous ranges.
+
+**Proposed (dynamic mode):** A durable **partition plan** stored in a Kafka compacted config topic drives routing at runtime. Operators change the plan via **REST** (no restart). New capacity is added only at the **tail** of the topic (append-only), so existing plugin assignments stay stable.
+
+No new infrastructure (Postgres, ZooKeeper) is required — Kafka and AdminClient are already part of the audit stack.
+
+---
+
+## 2. Problem statement
+
+| Limitation (static mode) | Impact |
+|--------------------------|--------|
+| Mapping fixed at startup | Onboard or scale a plugin → downtime (restart) |
+| Contiguous-range allocation | Changing one plugin’s size can move others’ partitions |
+| No durable shared plan | Multi-replica ingestors cannot safely update routing via pod-local config |
+| No control-plane API | Automation and ops lack a single, auditable change path |
+
+---
+
+## 3. Goals and non-goals
+
+### Goals
+
+| ID | Goal |
+|----|------|
+| **G1** | **Stable allocations** — onboarding or scaling one plugin must not unnecessarily move traffic for others |
+| **G2** | **Runtime updates** — change mapping without restarting audit-ingestor |
+| **G3** | **Append-only growth** — allocate only from newly added tail partitions (Kafka cannot shrink topics) |
+| **G4** | **Backward compatibility** — dynamic mode is opt-in; default behavior remains static XML at startup |
+
+### Non-goals
+
+- Decreasing Kafka partition count (not supported by Kafka)
+- Strict global ordering of audits across all plugins (never guaranteed with multi-partition plugins)
+- Shared cross-replica audit retry / recovery redesign (per-pod spool unchanged)
+
+---
+
+## 4. Core concepts
+
+### 4.1 Two Kafka topics, two jobs
+
+| Topic | Role | Volume | Who reads/writes |
+|-------|------|--------|------------------|
+| **`ranger_audits`** | Audit **data** | Very high | Plugins → ingestor produces; Solr/HDFS dispatchers consume **all** partitions |
+| **`ranger_audit_partition_plan`** | Partition **config** | Very low (ops events) | Ingestor only — REST writes, background watcher reads |
+
+The plan topic is a **compacted** topic (one partition, `cleanup.policy=compact`): each write appends a record; compaction retains the **latest value per key** (audit topic name, e.g. `ranger_audits`).
+
+### 4.2 Partition plan
+
+A partition plan is a versioned JSON document that answers:
+
+- Which partition IDs does each **known plugin** use?
+- Which partition IDs form the **buffer** for unknown / unconfigured plugins?
+- What is the current **`topicPartitionCount`** (must match Kafka)?
+
+**Example (conceptual):**
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 5,
+  "topicPartitionCount": 28,
+  "plugins": {
+    "hdfs":        { "partitions": [0, 1, 2, 3] },
+    "hiveServer2": { "partitions": [4, 5, 6, 7, 8, 9] },
+    "trino":       { "partitions": [10, 11, 12, 13, 14, 15, 16, 17, 18] }
+  },
+  "buffer": { "partitions": [19, 20, 21, 22, 23, 24, 25, 26, 27] }
+}
+```
+
+Every partition ID from `0` through `N-1` appears **exactly once** across plugins and buffer.
+
+### 4.3 Routing rules (audit hot path)
+
+When a plugin sends an audit (identified by **plugin id** / agent id):
+
+1. If plugin id is in the plan → pick a partition from that plugin’s list (**round-robin** within the list).
+2. If not in the plan → hash into the **buffer** partition list.
+3. Write the event to **`ranger_audits`**.
+
+The hot path reads the plan from **memory only** — never the plan topic per audit.
+
+### 4.4 Append-only allocation
+
+To avoid reshuffling existing plugins:
+
+- **Never** recompute everyone’s ranges from plugin list order.
+- **Promote** a new plugin → take partitions from the front of buffer, or grow the topic tail if buffer is insufficient.
+- **Scale** a hot plugin → append new partition IDs from the **tail** only; other plugins’ lists stay unchanged.
+
+**Example:** `hdfs` has `[0,1,2]`; scale to 4 partitions → add partition `3` from tail after topic growth. `hiveServer2` and `trino` lists are **unchanged**.
+
+---
+
+## 5. Architecture
+
+### 5.1 Control plane vs data plane
+
+```mermaid
+flowchart TB
+  subgraph ops [Ops / automation]
+    Admin[Admin REST client]
+  end
+
+  subgraph ingestor [audit-ingestor pods A, B, C ...]
+    REST[Partition-plan REST API]
+    Svc[Plan service]
+    Watcher[Background plan watcher]
+    Mem[(In-memory partition plan)]
+    Part[Partition router]
+    Queue[Audit message queue]
+
+    REST --> Svc
+    Svc --> PlanTopic
+    Watcher --> PlanTopic
+    Watcher --> Mem
+    Mem --> Part
+    Plugin[Plugin POST /access] --> Queue --> Part
+    Part --> AuditTopic
+  end
+
+  subgraph kafka [Kafka]
+    PlanTopic[(ranger_audit_partition_plan<br/>compacted config)]
+    AuditTopic[(ranger_audits<br/>audit data)]
+  end
+
+  subgraph consumers [Downstream — unchanged]
+    Solr[Solr dispatcher]
+    HDFS[HDFS dispatcher]
+  end
+
+  Admin -->|any pod via LB| REST
+  Svc -->|createPartitions if needed| AuditTopic
+  AuditTopic --> Solr
+  AuditTopic --> HDFS
+```
+
+**Takeaway:** Plan topic = slow, rare **configuration**. Audit topic = high-volume **data**. Only REST + watcher touch the plan topic.
+
+### 5.2 Who talks to what
+
+| Actor | Plan topic | Audit topic |
+|-------|------------|-------------|
+| Plugin audit POST | No | Produce |
+| Background watcher | Read | No |
+| REST GET / PUT / promote / scale | Read + write (mutations) | Grow partitions only (AdminClient) |
+| Solr / HDFS dispatcher | No | Consume **all** partitions |
+
+---
+
+## 6. Operational flows
+
+### 6.1 Flow 1 — Admin changes the plan
+
+**When:** Onboard a plugin (e.g. Trino) or scale a hot plugin (e.g. Hive).  
+**How often:** Rare — human or automation, not per audit.
+
+| Step | What happens |
+|------|----------------|
+| 1 | Admin calls REST on **any** ingestor pod (behind load balancer). |
+| 2 | Pod reads current plan from **`ranger_audit_partition_plan`** (e.g. version 4). |
+| 3 | If more partitions needed → grow **`ranger_audits`** via Kafka AdminClient (**before** publishing plan that references new IDs). |
+| 4 | Pod writes new plan (version 5) to compacted topic. |
+| 5 | Returns **200 OK** (or **409 Conflict** if another writer won — client retries with new version). |
+| 6 | Every ingestor pod’s watcher loads version 5 into memory (~30s default, or on Kafka message). |
+| 7 | Solr / HDFS dispatchers — no config change; rebalance only if audit topic partition count grew. |
+
+```mermaid
+flowchart TB
+  Admin[Admin / automation]
+
+  subgraph step1 [Ingestor pod handles REST]
+    REST[Ingestor REST]
+    PlanRW[(Plan topic<br/>read + write)]
+    Grow[(ranger_audits<br/>grow if needed)]
+    REST --> PlanRW
+    REST --> Grow
+  end
+
+  subgraph step2 [All ingestor pods sync]
+    Watcher[Watcher on each pod]
+    Mem[Memory updated]
+    Same[Same routing everywhere]
+    Watcher --> Mem --> Same
+  end
+
+  subgraph step3 [Dispatchers unchanged]
+    SolrHDFS[Solr / HDFS]
+    Consume[Keep consuming ranger_audits]
+    SolrHDFS --> Consume
+  end
+
+  Admin --> REST
+  PlanRW --> Watcher
+  Grow -.->|rebalance only if partitions grew| SolrHDFS
+```
+
+#### REST mutations (summary)
+
+| Method | Purpose |
+|--------|---------|
+| `GET /api/audit/partition-plan` | Read current plan |
+| `PUT /api/audit/partition-plan` | Full plan replace (`expectedVersion` required) |
+| `POST .../promote` | Move plugin from buffer → dedicated partitions |
+| `POST .../scale` | Append tail partitions to existing plugin |
+
+Mutations use **optimistic concurrency**: client sends `expectedVersion`; stale requests get **409** with current plan in the body. Client refreshes and retries.
+
+```mermaid
+flowchart TD
+  Admin[Admin PUT / promote / scale] --> Auth[Authenticate]
+  Auth --> Load[Load plan vN]
+  Load --> Check1{expectedVersion = N?}
+  Check1 -->|No| R409a[409 + current plan]
+  Check1 -->|Yes| Valid[Validate + allocate]
+  Valid --> Grow{Need more partitions?}
+  Grow -->|Yes| CP[createPartitions ranger_audits]
+  Grow -->|No| Reread[Re-read plan]
+  CP --> Reread
+  Reread --> Check2{Still vN?}
+  Check2 -->|No| R409b[409 peer won]
+  Check2 -->|Yes| Produce[Produce vN+1]
+  Produce --> Back[Read-back verify]
+  Back --> Check3{Matches intent?}
+  Check3 -->|No| R409c[409 lost race]
+  Check3 -->|Yes| OK[200 + plan]
+```
+
+### 6.2 Flow 2 — Plugin sends an audit (hot path)
+
+**When:** Every access audit from a Ranger plugin.  
+**How often:** High volume.
+
+| Step | What happens |
+|------|----------------|
+| 1 | Plugin sends POST to ingestor (any pod via LB). |
+| 2 | Ingestor reads plan **already in memory** (not from Kafka). |
+| 3 | Resolves partition list for plugin id. |
+| 4 | Round-robin within that list (or hash into buffer if unknown). |
+| 5 | Produces to **`ranger_audits`**. |
+
+```mermaid
+flowchart LR
+  Plugin[Plugin] --> Access[POST /access]
+  Access --> Mem[(Memory<br/>plan)]
+  Mem --> Pick[Pick partition<br/>for plugin id]
+  Pick --> Audit[(ranger_audits)]
+
+  Watcher[Watcher<br/>Flow 1 or 3] -.->|fills memory| Mem
+```
+
+### 6.3 Flow 3 — Pod startup and restart
+
+**Prerequisite:** `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=true`. If `false` or absent → legacy static XML mode; plan topic unused.
+
+| Situation | Pod behavior |
+|-----------|--------------|
+| **First pod ever** — plan topic empty | Read XML → build plan **v1** → **publish to plan topic** → load into memory |
+| **Later pods** — plan already in Kafka | Read plan from Kafka only; **XML not used for routing** |
+| **Any pod restart** | Same as later pods — plan survives in Kafka |
+
+```mermaid
+flowchart TB
+  subgraph pod1 [First pod — plan topic empty]
+    direction LR
+    XML[XML config] --> Kafka1[(plan topic v1)]
+    Kafka1 --> Mem1[Memory]
+  end
+
+  subgraph podN [Later pods — plan in Kafka]
+    direction LR
+    Kafka2[(plan topic)] --> Mem2[Memory]
+    XML2[XML ignored for routing]
+    XML2 -.->|not used| Mem2
+  end
+
+  subgraph podR [Crash / restart]
+    direction LR
+    Kafka3[(plan survives in Kafka)] --> Mem3[Memory]
+  end
+```
+
+**Rule:** After v1 exists in Kafka, **Kafka is the source of truth** — not XML on the pod filesystem.
+
+#### Multi-pod startup races (handled automatically)
+
+| Race | Scenario | Resolution |
+|------|----------|------------|
+| **A** | Several pods create plan topic at once | Idempotent topic create; “already exists” = success |
+| **B** | Several pods publish v1 when topic is empty | Re-read before/after produce; mandatory read-back; all pods adopt same v1 |
+
+```mermaid
+sequenceDiagram
+  participant A as pod A
+  participant B as pod B
+  participant Plan as ranger_audit_partition_plan
+
+  A->>Plan: read → empty
+  B->>Plan: read → empty
+  A->>Plan: produce v1
+  B->>Plan: produce v1 or re-read sees v1
+  A->>Plan: read-back → install v1
+  B->>Plan: read-back → install same v1
+  Note over A,B: both pods same routing
+```
+
+### 6.4 Plugin onboarding lifecycle
+
+```mermaid
+stateDiagram-v2
+  [*] --> Buffer: Unknown plugin sends audits
+  Buffer --> Dedicated: Admin promote-plugin
+  Dedicated --> Scaled: Admin scale-plugin
+  Scaled --> Scaled: More scale-plugin calls
+
+  note right of Buffer
+    Routes to buffer partition pool
+    Monitor volume / metrics
+  end note
+
+  note right of Dedicated
+    Dedicated partition list
+    No ingestor restart
+  end note
+
+  note right of Scaled
+    Append-only tail growth
+    Other plugins unchanged
+  end note
+```
+
+| Stage | Behavior |
+|-------|----------|
+| **0 — Unknown** | Plugin id not in plan → buffer partitions |
+| **1 — Promote** | REST assigns dedicated partitions from buffer (or tail growth) |
+| **2 — Scale** | REST appends more tail partitions to that plugin only |
+
+---
+
+## 7. Worked example
+
+**Initial plan (v1)** — bootstrap or first REST:
+
+| Plugin | Partitions |
+|--------|------------|
+| hdfs | [0, 1, 2] |
+| hiveServer2 | [3, 4, 5] |
+| buffer | [6 … 14] |
+
+Topic: **15** partitions.
+
+1. Unknown plugin **trino** sends audits → routes to buffer (hash among 6–14).
+2. **Promote trino** (3 partitions) → trino gets [6,7,8]; buffer shrinks to [9…14]; plan **v2**; no restart.
+3. **Scale hiveServer2** (+3 partitions) → topic grows 15→18; hive gets [3,4,5,15,16,17] append-only; hdfs and trino **unchanged**; plan **v3**.
+
+This fixes the static-mode problem where changing an early plugin’s override reshuffles everyone downstream.
+
+---
+
+## 8. Feature flag and backward compatibility
+
+```mermaid
+flowchart TD
+  Flag{dynamic.enabled?}
+  Flag -->|false or absent| Legacy[Legacy mode]
+  Flag -->|true| Dynamic[Dynamic mode]
+
+  Legacy --> L1[Mapping from XML at startup]
+  Legacy --> L2[No plan topic / no watcher]
+  Legacy --> L3[Change = XML + restart]
+
+  Dynamic --> D1[Plan from Kafka compacted topic]
+  Dynamic --> D2[Watcher + REST enabled]
+  Dynamic --> D3[XML seeds v1 once if plan topic empty]
+```
+
+| Area | Static (default) | Dynamic (`dynamic.enabled=true`) |
+|------|------------------|----------------------------------|
+| Partition mapping | XML at startup | Runtime plan from Kafka |
+| Changes | Edit XML + restart | REST → plan topic; watcher syncs all pods |
+| Plan topic | Not used | Source of truth after v1 |
+| REST partition-plan | Disabled (503) | Enabled (authenticated) |
+
+**Configuration (bootstrap):**
+
+| Property | Default | Role |
+|----------|---------|------|
+| `kafka.partition.plan.dynamic.enabled` | `false` | Feature flag |
+| `kafka.partition.plan.topic` | `ranger_audit_partition_plan` | Compacted registry topic |
+| `kafka.partition.plan.refresh.interval.ms` | `30000` | Watcher poll interval |
+
+XML properties (`configured.plugins`, overrides, buffer size) seed **v1 only** when plan topic is empty. **Do not** edit XML expecting live routing changes when dynamic mode is on.
+
+---
+
+## 9. Brownfield migration (static → dynamic)
+
+### Goal (one sentence)
+
+Turn on dynamic mode so **each plugin keeps sending audits to the same Kafka partitions** it uses today — no surprise rerouting on cutover day.
+
+---
+
+### Pre-flight — know your real layout *before* you flip the switch
+
+You have three places that *might* describe routing. Only two of them tell the truth in production.
+
+| Source | What it is | Trust it? |
+|--------|------------|-----------|
+| **XML config** | What you *think* you configured | Maybe — good starting point only |
+| **Ingestor logs** | What each pod *actually* uses at startup | **Yes** — ground truth |
+| **Kafka topic** | How many partitions exist on `ranger_audits` | **Yes** — ground truth |
+
+**Simple rule:** If XML disagrees with logs or Kafka, **believe logs + Kafka**, not XML.
+
+#### Three checks (do these while still on static mode)
+
+```mermaid
+flowchart LR
+  subgraph step1 [1. Save the map]
+    Log[Ingestor startup log<br/>plugin → partitions + buffer]
+  end
+
+  subgraph step2 [2. Count partitions]
+    Kafka[kafka-topics describe<br/>ranger_audits]
+  end
+
+  subgraph step3 [3. Sanity check]
+    Compare{Does XML match<br/>logs + Kafka?}
+  end
+
+  Log --> Compare
+  Kafka --> Compare
+  Compare -->|Yes| Ready[Safe for Path B]
+  Compare -->|No| Seed[Use Path A pre-seed]
+```
+
+| Step | What to do | What you get |
+|------|------------|--------------|
+| **1. Save the map** | After ingestor restart, copy the **AuditPartitioner Configuration** block from logs on **each** replica | A table: `hdfs → 0–2`, `hiveServer2 → 3–5`, `buffer → 6–14`, etc. |
+| **2. Count partitions** | `kafka-topics --describe --topic ranger_audits` | Total partition count (e.g. **15** → IDs `0` … `14`) |
+| **3. Sanity check** | Compare step 1 + 2 with your XML | If all three agree → simpler cutover. If not → pre-seed (Path A) |
+
+**Example worksheet** (fill from logs, not from memory):
+
+| Plugin / pool | Partition IDs | Count |
+|---------------|---------------|-------|
+| hdfs | 0, 1, 2 | 3 |
+| hiveServer2 | 3, 4, 5 | 3 |
+| buffer | 6 … 14 | 9 |
+| **Topic total** | **0 … 14** | **15** |
+
+#### When XML is wrong (common drift)
+
+If `kafka.topic.partitions` is set to a **fixed total**, the running system may use a different buffer size than XML suggests. In that case, **do not** rely on auto-bootstrap from XML — **pre-seed the plan** (Path A) using your log worksheet.
+
+---
+
+### Pick a migration path
+
+```mermaid
+flowchart TD
+  Start[Still on static mode<br/>traffic running] --> Preflight[Pre-flight:<br/>logs + Kafka describe]
+  Preflight --> Q{XML matches<br/>logs + Kafka?}
+
+  Q -->|Not sure or NO| A[Path A — Pre-seed<br/>recommended for brownfield]
+  Q -->|Yes, all match| B[Path B — Auto-bootstrap]
+
+  A --> A1[Write plan v1 to plan topic<br/>while dynamic still OFF]
+  A1 --> On[Turn dynamic ON + rolling restart]
+
+  B --> On
+
+  On --> Check{GET plan matches<br/>saved logs?}
+  Check -->|Yes| Done[Cutover done]
+  Check -->|No| C[Path C — Fix with PUT]
+  C --> Done
+```
+
+| Path | When | What you do (plain English) |
+|------|------|-------------------------------|
+| **A — Pre-seed** | XML might be stale, topic was grown manually, or you are not 100% sure | Build plan v1 from your **log worksheet** → publish to `ranger_audit_partition_plan` **before** enabling dynamic → enable dynamic → rolling restart |
+| **B — Auto-bootstrap** | Pre-flight proved XML = logs = Kafka | Enable dynamic → first pod creates v1 from XML → rolling restart → verify |
+| **C — Fix plan** | Dynamic is on but routing looks wrong | `GET` current plan → `PUT` corrected lists with `expectedVersion` → pause rollout until all pods match |
+
+**Path A in four steps:**
+
+1. Complete pre-flight worksheet from logs.
+2. Publish plan v1 JSON to the plan topic (key = `ranger_audits`).
+3. Set `dynamic.enabled=true` on all ingestor replicas.
+4. Rolling restart → each pod reads your seeded plan (no guesswork from XML).
+
+**After cutover — quick verify:**
+
+- Same `version` on every pod (`GET /api/audit/partition-plan`).
+- Plugin lists match your saved log worksheet.
+- Spot-check: test audit per major plugin still lands on expected partition.
+
+---
+
+### Rollback (if needed)
+
+1. Export current plan with `GET` (save the JSON).
+2. Set `dynamic.enabled=false`.
+3. Rolling restart — routing returns to static XML at startup.
+4. Align XML with the saved plan if you want the same layout after rollback.
+
+The plan topic can stay in Kafka; it is ignored when dynamic mode is off.
+
+---
+
+## 10. Impact on other components
+
+### Solr / HDFS dispatchers
+
+- **Do not** read the partition plan.
+- Subscribe to **all** partitions of `ranger_audits`.
+- When audit topic grows → consumer groups **rebalance** → more parallelism (up to partition count).
+- No dispatcher config change for plugin onboarding; may need capacity tuning if partition count grows significantly.
+
+### Audit recovery / spool
+
+- Per-pod retry behavior **unchanged**.
+- Retries use same plugin id key; partition may differ if plan changed since original send — acceptable for audit pipelines.
+
+---
+
+## 11. Failure modes
+
+| Failure | Behavior |
+|---------|----------|
+| Plan topic unreadable at runtime | Keep **last known good** plan in memory; log error |
+| Invalid plan JSON on write | Reject at REST; do not apply on read |
+| AdminClient partition increase fails | Do **not** publish new plan; return 503; caller retries |
+| Concurrent REST mutations | `expectedVersion` + re-read + read-back → one 200, one 409; client retries |
+| Plan swap during audit POST | Atomic in-memory swap; brief mix of old/new routing acceptable |
+| Kafka unreachable at startup (dynamic on) | **Fail startup** — do not silently fall back to XML (would split routing across pods) |
+
+---
+
+## 12. Design rationale
+
+### Why this design fits Ranger
+
+| Principle | How delivered |
+|-----------|---------------|
+| No new infra | Kafka compacted topic + existing AdminClient |
+| Hot path stays fast | Memory-only plan on every audit POST |
+| Multi-replica consistency | All pods read same compacted plan |
+| Safe rollout | `dynamic.enabled` defaults to `false` |
+| Append-only lists | Avoids static contiguous-range reshuffle |
+| Clean consumer boundary | Dispatchers unaware of producer-side routing |
+
+### Acceptable tradeoffs
+
+| Concern | Mitigation |
+|---------|------------|
+| Kafka required at startup when dynamic on | Fail fast with clear error |
+| Watcher lag (~30s default) | Acceptable for infrequent ops; tunable interval |
+| Ops editing XML expecting live effect | Runbook: use REST when dynamic on |
+| `createPartitions` succeeds but plan write fails | Grow topic **before** plan publish; retry PUT idempotently |
+
+### When dynamic mode is a poor fit
+
+- Plan changes every few seconds (watcher lag + rebalance churn)
+- Kafka not part of the stack
+- Requirement for strict ordering across plan migrations without operational care
+
+### Alternatives considered
+
+| Option | Tradeoff |
+|--------|----------|
+| XML + restart only (today) | Simple; requires downtime for changes |
+| Postgres / ZooKeeper registry | Strong CRUD; extra infra deliberately avoided |
+| K8s ConfigMap + watch | K8s-centric; weak for multi-cluster REST automation |
+| Pod-local XML writes | Breaks with multiple replicas — rejected |
+
+---
+
+## 13. Operator golden rules
+
+1. **Runtime routing changes → REST only** when dynamic mode is on.
+2. **No ingestor restart** for promote/scale — watcher refreshes all pods.
+3. **Grow `ranger_audits` before** publishing a plan that references new partition IDs (REST does this automatically).
+4. **Never shrink** Kafka partition count.
+5. **Solr/HDFS dispatchers** — no config change for plan updates.
+
+### Enable checklist (production)
+
+- [ ] XML bootstrap layout reviewed (for first v1 only)
+- [ ] Kafka ACLs: WRITE on plan topic; ALTER on `ranger_audits`
+- [ ] Ops trained on REST promote/scale and **409 retry**
+- [ ] Brownfield: pre-flight audit + correct migration path chosen
+- [ ] Dispatcher capacity reviewed if scaling hot plugins
+
+---
+
+## 14. Questions and answers (Q&A)
+
+### Concepts and motivation
+
+**Q: Why do we need plugin-based partitioning at all?**  
+A: Hot plugins (Hive, Trino, HDFS) can dominate a shared topic. Dedicated partitions isolate throughput and let you scale one plugin without starving others.
+
+**Q: What is the difference between static and dynamic mode?**  
+A: Static mode computes plugin → partition mapping once from XML at startup; changes need restart. Dynamic mode stores the mapping in a Kafka compacted topic and updates it at runtime via REST without restart.
+
+**Q: Why can’t we just edit XML on the ingestor pod?**  
+A: Each replica has its own filesystem. A local XML edit is invisible to other pods, lost on reschedule, and may be overwritten by ConfigMap rollouts. Runtime changes must use **durable shared storage** (the plan topic).
+
+**Q: Do we need Postgres or ZooKeeper for the partition plan?**  
+A: **No.** Kafka compacted topic + AdminClient is the recommended registry — both are already required for audit-ingestor.
+
+**Q: Can we decrease Kafka partition count?**  
+A: **No.** Kafka only supports increasing partitions. The design is append-only.
+
+---
+
+### Architecture and data flow
+
+**Q: What are the two Kafka topics and why separate them?**  
+A: `ranger_audits` carries high-volume audit events. `ranger_audit_partition_plan` carries low-volume configuration. Separating config from data keeps the audit hot path off Kafka reads and matches Kafka’s compacted-config pattern.
+
+**Q: Does every audit POST read the plan topic?**  
+A: **No.** Each audit uses the plan held **in memory**. Only the background watcher and REST handlers read/write the plan topic.
+
+**Q: How do all ingestor pods stay in sync?**  
+A: Each pod runs a background watcher that polls or consumes the compacted plan topic (default ~30s). On new version → validate → swap in-memory plan. No restart required.
+
+**Q: What happens when a pod crashes?**  
+A: In-memory plan is lost, but the plan in Kafka survives. On restart, the pod reads the latest compacted plan and resumes the same routing as peers.
+
+**Q: Do Solr and HDFS dispatchers need the partition plan?**  
+A: **No.** They consume **all** partitions of `ranger_audits`. They rebalance when partition count grows but do not need plan API access.
+
+---
+
+### Partition plan and allocation
+
+**Q: What is in a partition plan?**  
+A: Audit topic name, monotonic `version`, `topicPartitionCount`, a map of plugin id → partition ID list, and a buffer partition list for unknown plugins.
+
+**Q: What is the buffer?**  
+A: A pool of partition IDs shared by plugins not yet promoted into the plan. New or trial plugins land here until ops assign dedicated partitions.
+
+**Q: What does “append-only” mean?**  
+A: Existing plugin partition lists are never reshuffled or shrunk. New capacity comes only from the **tail** of the topic (new partition IDs). Scaling hdfs from 3→4 partitions adds one new ID at the end of hdfs’s list without moving hive or trino.
+
+**Q: Why did static mode reshuffle plugins when one override changed?**  
+A: Static mode used **contiguous ranges** based on plugin order in XML. Changing an early plugin’s size shifted range boundaries for all following plugins. Dynamic mode uses **explicit partition lists** and append-only tail growth.
+
+**Q: How is a partition chosen within a plugin’s list?**  
+A: **Round-robin** across that plugin’s assigned partition IDs for throughput. Strict per-plugin ordering across partitions is not guaranteed (same as static multi-partition plugins).
+
+---
+
+### REST API and concurrency
+
+**Q: Which REST endpoints exist?**  
+A: `GET` and `PUT` on `/api/audit/partition-plan`, plus `POST` promote and scale convenience endpoints. All require authentication; admin allow-list is planned for a follow-up phase.
+
+**Q: What is `expectedVersion`?**  
+A: Optimistic locking. The client declares which plan version its change is based on. If another writer already published a newer version, the server returns **409 Conflict** with the current plan so the client can retry.
+
+**Q: What should I do on HTTP 409?**  
+A: Read the current plan (from 409 body or `GET`), note the new `version`, recompute your change against the latest lists, and retry with updated `expectedVersion`. Do not retry with the stale version.
+
+**Q: Can two admins update the plan at the same time on different pods?**  
+A: Yes. Kafka’s single-partition plan topic orders writes. One mutation wins; the other gets 409 and must retry. No silent overwrite.
+
+**Q: Why grow `ranger_audits` before publishing the plan?**  
+A: The plan must not reference partition IDs that do not exist yet. AdminClient increases the topic first; then the new plan is written.
+
+**Q: Can I change routing by editing XML while dynamic mode is on?**  
+A: **No** for live effect. XML only seeds v1 when the plan topic is empty. Runtime changes go through REST.
+
+---
+
+### Bootstrap and migration
+
+**Q: When does XML populate the plan topic?**  
+A: Only when `dynamic.enabled=true` **and** the plan topic has **no** message for the audit topic key. The first pod builds v1 from XML and publishes it. Later pods and restarts read Kafka only.
+
+**Q: What is the simplest pre-flight checklist?**  
+A: (1) Copy plugin → partition ranges from ingestor startup logs. (2) Note partition count from `kafka-topics --describe`. (3) If XML matches both → Path B; if not (or unsure) → **Path A pre-seed** from the log worksheet.
+
+**Q: Which migration path should brownfield clusters use?**  
+A: **When in doubt, Path A.** Use Path B only when XML, logs, and Kafka describe all agree. Use Path C if you enabled dynamic and routing does not match your saved logs.
+
+**Q: Can I seed the plan before enabling dynamic mode?**  
+A: **Yes** — recommended for brownfield. Publish v1 to `ranger_audit_partition_plan` with key = audit topic name while dynamic is still off, then enable and rolling restart.
+
+**Q: How do I verify cutover succeeded?**  
+A: `GET /api/audit/partition-plan` on every pod (same `version`); compare lists to saved static logs; confirm `topicPartitionCount` matches Kafka describe; spot-check audit routing per major plugin.
+
+**Q: How do I roll back to static mode?**  
+A: Export current plan via `GET`, align XML to that layout, set `dynamic.enabled=false`, rolling restart. The plan topic remains but is ignored.
+
+---
+
+### Operations and troubleshooting
+
+**Q: Do I need to restart ingestor after promote or scale?**  
+A: **No.** Watcher propagates the new plan to all pods within the refresh interval.
+
+**Q: Do dispatchers need reconfiguration after scale?**  
+A: **No.** They automatically rebalance when `ranger_audits` partition count increases. Tune consumer threads/replicas if sustained lag appears.
+
+**Q: Ingestor fails startup after enabling dynamic — what now?**  
+A: Usually Kafka unreachable or ACL denied on plan topic create/write. Fix connectivity/ACLs; keep dynamic off until Kafka is healthy. Dynamic mode must not silently fall back to per-pod XML.
+
+**Q: Pods show different plan versions — what now?**  
+A: Check watcher logs and plan topic with `kafka-console-consumer`. Wait one refresh interval after a mutation. If persistent, investigate Kafka read failures on the lagging pod.
+
+**Q: `PUT` returns 400 — what now?**  
+A: Usually invalid plan: overlapping partition IDs, missing IDs, or append-only violation (attempt to reshuffle existing assignments). Compare proposed body to current `GET`.
+
+**Q: Does audit recovery/spool behavior change?**  
+A: **No.** Per-pod spool and retry are unchanged. Retried audits may land on a different partition if the plan changed — acceptable for audit use cases.
+
+---
+
+### Security and permissions
+
+**Q: What Kafka ACLs does ingestor need for dynamic mode?**  
+A: **WRITE** on `ranger_audit_partition_plan` (in addition to existing produce on `ranger_audits`); **ALTER** / create-partitions on `ranger_audits` (same as today for topic growth at startup).
+
+**Q: Who can call partition-plan REST?**  
+A: Authenticated principals per ingestor security config. A dedicated admin allow-list (separate from plugin `/access` users) is planned; until then, restrict ingestor admin credentials at the network/ops layer.
+
+---
+
+### Design decisions summary
+
+| Question | Answer |
+|----------|--------|
+| Postgres/ZK needed? | **No** — Kafka compacted topic + AdminClient |
+| Update XML in pod for runtime? | **No** — XML is bootstrap only |
+| REST control plane? | **Yes** — writes plan + grows audit topic |
+| Pod crash/restart? | Re-read plan from Kafka |
+| Other pods notified? | All pods watch same plan topic |
+| Dispatchers affected? | Rebalance only when partition count grows |
+| Default behavior? | **Unchanged** — dynamic is opt-in (`dynamic.enabled=false`) |
+
+---
+
+## 15. Document map (supplementary detail)
+
+For implementation phases, E2E test scripts, producer tuning, and static-mode baseline, see:
+
+- [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) — engineering phases
+- [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) — operator commands and examples
+- [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) — cutover worksheets
+- [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) — shorter plain-language guide
+- [README-KAFKA-DISPATCHERS.md](README-KAFKA-DISPATCHERS.md) — Solr/HDFS consumer tuning
diff --git a/audit-server/README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md b/audit-server/README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md
new file mode 100644
index 000000000..dcebc000e
--- /dev/null
+++ b/audit-server/README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md
@@ -0,0 +1,559 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic service allowlist for audit-ingestor — design proposal
+
+**Status:** Proposal (not implemented). Complements dynamic partition plan work; does **not** replace authorization on `POST /api/audit/access`.
+
+**Audience:** Architects, operators, and reviewers planning runtime plugin onboarding without ingestor restart.
+
+**Operator guide (everyone):** [README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md](README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md) — plain-language companion to this design doc (mirrors [partition plan guide](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md)).
+
+**Related docs:**
+
+| Doc | Relationship |
+|-----|----------------|
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Dynamic **Kafka routing** (partition plan) — orthogonal; companion operator guide |
+| [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) | Partition plan architecture |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | Partition-plan Kafka topic + REST |
+| [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) | Phase 6: **partition-plan admin** allowlist (separate surface) |
+| [DESIGN-KAFKA-AUDIT-SERVER.md](DESIGN-KAFKA-AUDIT-SERVER.md) | End-to-end audit pipeline |
+| Apache Ranger PR [#1017](https://github.com/apache/ranger/pull/1017) (RANGER-5645) | Static Docker `service.<repo>.allowed.users` fix |
+
+---
+
+## 1. Executive summary
+
+Plugins POST audits to **`POST /api/audit/access?serviceName=<repo>&appId=<agent>`**. After Kerberos/JWT/basic **authentication** (401 on failure), ingestor performs **authorization**: the authenticated short username must appear in **`ranger.audit.ingestor.service.<repo>.allowed.users`**.
+
+Today that map is loaded **once at JVM startup** from `ranger-audit-ingestor-site.xml`. Adding a new Ranger service repo (e.g. `dev_trino`) requires XML edits and **ingestor restart** — even when partition routing is already dynamic via the partition-plan topic.
+
+**Proposal:** Mirror the partition-plan control plane: durable registry + in-memory cache + admin REST + optional seed from Policy Manager `policy.download.auth.users`. Optionally bundle with partition-plan changes in a single **onboard plugin** API.
+
+**Important:** Dynamic partition mapping answers *“which Kafka partition?”* Dynamic service allowlist answers *“may this Kerberos principal claim audits for this repo?”* Both checks remain required; only the **update path** becomes runtime-friendly. See [§3](#3-why-dynamic-partition-mapping-does-not-remove-allowedusers) for the full rationale.
+
+---
+
+## 2. Problem statement
+
+### Current behavior
+
+```java
+// AuditREST.java — loaded in static {} block at class init
+private static final Map<String, Set<String>> allowedServiceUsers;
+static {
+    allowedServiceUsers = initializeAllowedUsers();  // scans site XML once
+}
+```
+
+| Limitation | Impact |
+|------------|--------|
+| Allowlist fixed at startup | New repo → edit XML → rolling restart all ingestor pods |
+| No shared durable store | Multi-replica ingestors cannot update allowlist via one pod-local file |
+| Decoupled from Policy Manager | `dev_trino` in Admin UI does not auto-create ingestor allowlist entry |
+| Partition plan is dynamic; allowlist is not | Ops must do **two** onboarding steps (plan + XML) |
+
+### What dynamic partition plan does **not** fix
+
+The compacted topic **`ranger_audit_partition_plan`** stores plugin → partition ranges. It is read **after** `/access` accepts a batch and ingestor publishes to Kafka. A 403 on `/access` happens **before** any partition logic runs. Making partition routing dynamic does **not** relax or remove the plugin allowlist — see [§3](#3-why-dynamic-partition-mapping-does-not-remove-allowedusers).
+
+---
+
+## 3. Why dynamic partition mapping does not remove `allowed.users`
+
+**Correct:** dynamic partition mapping does **not** remove the `allowed.users` check, and that is **intentional**. [PR #1017](https://github.com/apache/ranger/pull/1017) (RANGER-5645) and the partition-plan work solve **different problems**. They share the same ingestor process but operate on **different request paths** at **different times**.
+
+### Two problems, two fixes
+
+| Work | Tracker | Question it answers | What it changes |
+|------|---------|---------------------|-----------------|
+| **Service allowlist** ([#1017](https://github.com/apache/ranger/pull/1017) / RANGER-5645) | Static XML today; dynamic Kafka/REST in this doc | *May this Kerberos principal POST audits claiming to be repo `R`?* | `ranger.audit.ingestor.service.<repo>.allowed.users` |
+| **Partition plan** (dynamic partitioning design) | Partition-plan phases | *After accept, which Kafka partition should repo `R` use?* | `ranger_audit_partition_plan` topic + `AuditPartitioner` |
+
+Partition plan being dynamic only means ops can change **routing** without restart. It does **not** mean plugins are trusted to pick any `serviceName` or that Kerberos alone is enough.
+
+### Surface 1: `ranger.audit.ingestor.service.<repo>.allowed.users`
+
+This is the authorization gate on **`POST /api/audit/access`** — the high-volume path every plugin uses.
+
+| Item | Detail |
+|------|--------|
+| **Property** | `ranger.audit.ingestor.service.<repo>.allowed.users` (comma-separated short names) |
+| **Example** | `ranger.audit.ingestor.service.dev_hive.allowed.users` = `hive` |
+| **Caller** | Service daemons (`hive`, `hdfs`, `om`, `trino`, …) |
+| **When checked** | On **every** audit POST, **before** Kafka produce |
+| **Code path** | `AuditREST.isAllowedServiceUser(serviceName, authenticatedUser)` |
+| **Failure** | **403** (authentication already succeeded) |
+| **Aligns with Admin** | Values should be ⊆ `policy.download.auth.users` for that repo (ops discipline; Option C Phase 1) |
+
+**What it prevents:** any principal with a valid Kerberos ticket from forging audits for a repo it does not own. Without this check, a compromised `kafka` daemon could POST events as `serviceName=dev_hive` and pollute Hive’s audit stream.
+
+**What #1017 fixed:** Docker E2E hit **403** because ingestor XML lacked entries (e.g. `dev_ozone` needed `om` in addition to `ozone`). That is **Surface 1** configuration — unrelated to partition assignment.
+
+### Surface 2: partition plan (orthogonal)
+
+| Item | Detail |
+|------|--------|
+| **Store** | Kafka compacted topic `ranger_audit_partition_plan` |
+| **Question** | *Which partition range in `ranger_audits` should plugin type / repo use?* |
+| **When applied** | **After** `/access` returns 200/202 and ingestor publishes to Kafka |
+| **Code path** | `AuditPartitioner` reads `PartitionPlanService` cache |
+| **Admin API** | `GET/PUT /api/audit/partition-plan` (ops only; Phase 6 admin allowlist) |
+
+A plugin can have a valid partition range and still get **403** on `/access` if its short name is not in Surface 1. Conversely, Surface 1 can allow `hive` for `dev_hive` while partition plan still controls **where** those events land in Kafka.
+
+### Surface 3: admin APIs (do not merge with Surface 1)
+
+| Surface | Endpoint | Who | Allowlist property |
+|---------|----------|-----|-------------------|
+| **Service allowlist admin** (proposed) | `GET/PUT /api/audit/service-allowlist` | Ops | `service.allowlist.admin.users` |
+| **Partition plan admin** | `GET/PUT /api/audit/partition-plan` | Ops | `partition.plan.allowed.users` (Phase 6) |
+
+Plugins must **not** call these. One combined “admin” list would let a daemon change routing or impersonate other repos.
+
+### Request order (why Surface 1 is mandatory)
+
+```text
+Plugin POST /api/audit/access?serviceName=dev_hive&appId=hiveServer2
+        │
+        ├─ 401  Authentication failed (Kerberos / JWT / basic)
+        │
+        ├─ 403  Surface 1: auth_to_local(principal) → "hive"
+        │         "hive" ∉ allowed set for dev_hive  → STOP (partition plan never consulted)
+        │
+        └─ 200/202  Surface 1 passed → AuditDestinationMgr → Kafka producer
+                          │
+                          └─ Surface 2: AuditPartitioner picks partition from plan
+```
+
+```mermaid
+flowchart TB
+  subgraph plugins [Plugin daemons]
+    HS2[HiveServer2]
+    OM[Ozone OM]
+  end
+
+  subgraph ops [Ops / automation]
+    AdminClient[Admin client]
+  end
+
+  subgraph ingestor [audit-ingestor]
+    Access["POST /api/audit/access"]
+    Plan["GET/PUT /api/audit/partition-plan"]
+    Allow["GET/PUT /api/audit/service-allowlist proposed"]
+
+    S1["Surface 1: service.repo.allowed.users"]
+    S3a["Surface 3: partition.plan.allowed.users"]
+    S3b["Surface 3: service.allowlist.admin.users"]
+
+    Access --> S1
+    Plan --> S3a
+    Allow --> S3b
+  end
+
+  HS2 -->|serviceName=dev_hive| Access
+  OM -->|serviceName=dev_ozone| Access
+  AdminClient --> Plan
+  AdminClient --> Allow
+```
+
+Dynamic partition plan changes only the **bottom** branch (Surface 2). Surface 1 stays in force whether allowlist is static XML, dynamic Kafka, or both.
+
+### Principal matrix (intended separation)
+
+| Principal | `POST /access?serviceName=dev_hive` | `PUT /partition-plan` | `PUT /service-allowlist` |
+|-----------|--------------------------------------|------------------------|---------------------------|
+| `hive` (plugin) | **200** if in `dev_hive.allowed.users` | **403** | **403** |
+| `admin` (ops) | **403** (not a plugin user) | **200** when Phase 6 live | **200** |
+
+### Practical summary
+
+| If you see… | Layer | Fix |
+|-------------|-------|-----|
+| **401** on `/access` | Authentication | Plugin / ingestor Kerberos, keytabs, SPNEGO |
+| **403** on `/access` | **Surface 1** — `allowed.users` | Add short name to `service.<repo>.allowed.users` (XML, REST, or Kafka allowlist topic) |
+| Audits accepted but wrong/missing Kafka partition | **Surface 2** — partition plan | Update partition plan registry / onboard plugin range |
+| **403** on `PUT /partition-plan` | **Surface 3** | Add principal to `partition.plan.allowed.users` |
+| New repo in Admin UI, audits still 403 | **Surface 1 not onboarded** | Partition plan alone is insufficient — add allowlist entry for that repo |
+| New repo, allowlist OK, audits in buffer partition | **Surface 2 not onboarded** | Allowlist alone is insufficient — add partition plan entry |
+
+**Takeaways:**
+
+1. **Dynamic partition mapping ≠ dynamic trust.** Routing can change at runtime; **who may claim a repo** still requires Surface 1.
+2. **#1017 and partition plan are complementary**, not substitutes — ship both for full plugin onboarding.
+3. **Onboard two things per repo:** allowlist (Surface 1) + partition range (Surface 2). Option C Phase 1: ops maintain both via XML seed + dynamic REST/Kafka; no Ranger Admin sync.
+4. **Consistency rule:** `allowedUsers(R) ⊆ shortNames(policy.download.auth.users for R)`.
+
+---
+
+## 4. Authentication vs authorization (403 vs 401)
+
+Kerberos (or JWT/basic) success does **not** imply authorization. Surface 1 (`allowed.users`) runs after authentication and before Kafka produce — see [§3](#3-why-dynamic-partition-mapping-does-not-remove-allowedusers) for the full pipeline.
+
+| HTTP | Layer | Meaning |
+|------|-------|---------|
+| **401** | Authentication | Who are you? — failed before Surface 1 |
+| **403** | Authorization (Surface 1) | Known user, not allowed for this `serviceName` |
+| **200/202** | Accepted | Surface 1 passed → then Surface 2 (partition plan) applies on publish |
+
+---
+
+## 5. Proposed architecture
+
+### 5.1 High-level (mirror partition plan)
+
+| Component | Partition plan (exists / planned) | Service allowlist (proposed) |
+|-----------|-----------------------------------|------------------------------|
+| **Durable store** | Kafka compacted `ranger_audit_partition_plan` | Kafka compacted `ranger_audit_service_allowlist` (name TBD) |
+| **In-memory cache** | `PartitionPlanService` + watcher | `ServiceAllowlistService` + watcher |
+| **Bootstrap** | Seed v1 from site XML if topic empty | Seed from site XML `service.*.allowed.users` if topic empty |
+| **Admin REST** | `GET/PUT /api/audit/partition-plan` | `GET/PUT /api/audit/service-allowlist` |
+| **Request path** | `AuditPartitioner` reads cache | `AuditREST.isAllowedServiceUser()` reads cache |
+| **AuthZ on REST** | `partition.plan.allowed.users` (Phase 6) | `service.allowlist.admin.users` (proposed) |
+
+### 5.2 Control plane vs data plane
+
+```mermaid
+flowchart LR
+  subgraph control [Control plane — rare updates]
+    AdminREST[Admin REST]
+    AllowTopic[(ranger_audit_service_allowlist compacted)]
+    PlanTopic[(ranger_audit_partition_plan compacted)]
+    Watcher[ServiceAllowlistWatcher]
+    Mem[(In-memory allowlist map)]
+
+    AdminREST --> AllowTopic
+    Watcher --> AllowTopic
+    Watcher --> Mem
+  end
+
+  subgraph data [Data plane — high volume]
+    Plugin[Plugin POST /access]
+    REST[AuditREST]
+    Kafka[(ranger_audits)]
+
+    Plugin --> REST
+    REST -->|isAllowedServiceUser| Mem
+    REST -->|on success| Kafka
+  end
+```
+
+**Takeaway:** Allowlist topic = small, rare config (like partition plan). Audit events still flow through `ranger_audits`; dispatchers unchanged.
+
+### 5.3 Registry document shape (proposed JSON)
+
+Key: audit topic name or fixed key `default` (single global allowlist document).
+
+```json
+{
+  "version": 3,
+  "updatedAt": "2026-06-15T12:00:00Z",
+  "updatedBy": "admin",
+  "services": {
+    "dev_hive": {
+      "allowedUsers": ["hive"],
+      "source": "policy-manager",
+      "notes": "synced from dev_hive policy.download.auth.users"
+    },
+    "dev_trino": {
+      "allowedUsers": ["trino"],
+      "source": "rest",
+      "notes": "onboarded via PUT /service-allowlist"
+    },
+    "dev_ozone": {
+      "allowedUsers": ["om", "ozone"],
+      "source": "rest"
+    }
+  }
+}
+```
+
+**Rules:**
+
+- `version` monotonic; `PUT` uses optimistic concurrency (`expectedVersion`) like partition plan.
+- `allowedUsers` = short names **after** `auth_to_local` (same semantics as today’s XML values).
+- Empty or missing repo entry → **403** for that `serviceName` (fail closed).
+
+---
+
+## 6. Reload path (replace static map)
+
+### Today
+
+```text
+site XML → initializeAllowedUsers() → static Map (never refreshed)
+```
+
+### Proposed
+
+```text
+site XML (bootstrap only)
+    ↓ first pod / empty topic
+Kafka allowlist topic
+    ↓ watcher (background thread, same pattern as PartitionPlanWatcher)
+In-memory ConcurrentHashMap<repo, Set<shortName>>
+    ↓ per request
+AuditREST.isAllowedServiceUser(serviceName, authenticatedUser)
+```
+
+**Implementation notes:**
+
+- Remove `static final allowedServiceUsers`; inject `ServiceAllowlistService` (same pattern as `PartitionPlanService`).
+- Watcher polls or consumes compacted topic; on change, swap in-memory map atomically.
+- **Read path:** O(1) map lookup; no Kafka read per audit POST.
+- **Fallback:** If dynamic mode disabled (`service.allowlist.dynamic.enabled=false`), keep current static XML behavior.
+
+---
+
+## 7. Admin REST API (proposed)
+
+### Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/api/audit/service-allowlist` | Admin allowlist | Return current document + version |
+| `PUT` | `/api/audit/service-allowlist` | Admin allowlist | Replace or merge; write to Kafka topic |
+| `PUT` | `/api/audit/service-allowlist/services/{repo}` | Admin allowlist | Upsert one repo (convenience) |
+| `DELETE` | `/api/audit/service-allowlist/services/{repo}` | Admin allowlist | Remove repo (optional; fail-closed for plugins) |
+
+**PUT body (full replace example):**
+
+```json
+{
+  "expectedVersion": 2,
+  "services": {
+    "dev_trino": {
+      "allowedUsers": ["trino"]
+    }
+  }
+}
+```
+
+**Responses:** Same patterns as partition plan — `200` OK, `409` version conflict, `401` unauthenticated, `403` not admin.
+
+### Unified **onboard plugin** API (optional Phase 2)
+
+Single operation for ops when adding `dev_trino`:
+
+```http
+POST /api/audit/onboard-plugin
+```
+
+```json
+{
+  "repo": "dev_trino",
+  "appIds": ["trino"],
+  "allowedUsers": ["trino"],
+  "partitionCount": 3,
+  "expectedPlanVersion": 5,
+  "expectedAllowlistVersion": 2
+}
+```
+
+**Atomic intent (best-effort across two topics):**
+
+1. Upsert `dev_trino` in service allowlist registry.
+2. Append/allocate partition range for `trino` in partition plan.
+3. Optionally grow `ranger_audits` partition count.
+
+If step 2 succeeds and step 1 fails, return `207 Multi-Status` with rollback guidance (ops retry allowlist). True distributed transaction is **not** required for v1; document ordering: **allowlist first, then plan** (fail closed: no audits accepted until allowlist exists).
+
+---
+
+## 8. Seeding from Policy Manager (optional integration)
+
+**Goal:** When an operator creates service `dev_trino` in Ranger Admin, ingestor allowlist stays aligned with **`policy.download.auth.users`**.
+
+### Option A — Push from Ranger Admin (recommended long term)
+
+On service create/update REST handler in `security-admin`:
+
+1. Read `policy.download.auth.users` for the service.
+2. Map Kerberos principals → short names (same rules as ingestor `auth_to_local`, or store short names only in service def).
+3. Call ingestor `PUT /api/audit/service-allowlist/services/{repo}` (internal HTTP, service account).
+
+**Pros:** Single source of truth in Policy Manager.  
+**Cons:** Requires Admin → ingestor coupling and credentials.
+
+### Option B — Pull from Ranger Admin (ingestor poll)
+
+Ingestor periodically fetches service definitions from Admin REST and refreshes allowlist cache.
+
+**Pros:** No Admin code change.  
+**Cons:** Lag, credentials, harder to reason about conflicts with manual REST edits.
+
+### Option C — Bootstrap from XML only (Phase 1)
+
+Dynamic REST/Kafka for ops; no Admin sync. Matches partition plan Phase 1 rollout.
+
+**Consistency rule (all options):**
+
+```text
+allowedUsers for repo R ⊆ { short names derived from policy.download.auth.users for R }
+```
+
+Ingestor may **reject** PUT that adds users not present on the service definition (strict mode) or **warn** (permissive mode).
+
+---
+
+## 9. `auth_to_local` consistency
+
+Allowlist stores **short names** (`hive`, `om`, `trino`). Ingestor maps Kerberos principal → short name via `ranger.audit.ingestor.auth.to.local` before `isAllowedServiceUser()`.
+
+**Onboard checklist (manual or automated):**
+
+| Check | Example |
+|-------|---------|
+| RULE exists for plugin principal | `RULE:[2:$1/$2@$0](trino/.*@.*)s/.*/trino/` |
+| Short name in allowlist | `dev_trino.allowed.users` contains `trino` |
+| Plugin uses matching keytab principal | `trino/ranger-trino@REALM` |
+| `serviceName` query param matches Admin repo name | `dev_trino` |
+
+Proposed **onboard-plugin** API may validate RULE presence (warn if `DEFAULT` already covers the case).
+
+---
+
+## 10. Configuration properties (proposed)
+
+```xml
+<!-- Enable dynamic service allowlist (default false for backward compatibility) -->
+<property>
+  <name>ranger.audit.ingestor.service.allowlist.dynamic.enabled</name>
+  <value>false</value>
+</property>
+
+<property>
+  <name>ranger.audit.ingestor.service.allowlist.topic</name>
+  <value>ranger_audit_service_allowlist</value>
+  <description>Compacted Kafka topic; single partition recommended</description>
+</property>
+
+<property>
+  <name>ranger.audit.ingestor.service.allowlist.refresh.interval.ms</name>
+  <value>30000</value>
+</property>
+
+<!-- Who may call GET/PUT service-allowlist REST (NOT plugin users) -->
+<property>
+  <name>ranger.audit.ingestor.service.allowlist.admin.users</name>
+  <value>admin,ops</value>
+</property>
+
+<!-- Static bootstrap entries remain valid when dynamic.enabled=false -->
+<property>
+  <name>ranger.audit.ingestor.service.dev_hive.allowed.users</name>
+  <value>hive</value>
+</property>
+```
+
+When `dynamic.enabled=true`:
+
+- Static `service.*.allowed.users` used only to **seed** empty Kafka topic on first startup.
+- Runtime changes via REST only (same ops discipline as partition plan).
+
+---
+
+## 11. Phased implementation plan
+
+| Phase | Deliverable | Depends on |
+|-------|-------------|------------|
+| **0** | Static XML allowlist (today) + [#1017](https://github.com/apache/ranger/pull/1017) Docker entries | — |
+| **1** | `ServiceAllowlistService` + Kafka topic + watcher; `AuditREST` reads cache; bootstrap from XML | Kafka, existing ingestor |
+| **2** | `GET/PUT /api/audit/service-allowlist` + admin allowlist authZ | Phase 6 pattern from partition plan |
+| **3** | Ops runbook + brownfield migration (export XML → seed topic) | Phase 1–2 |
+| **4** | `POST /api/audit/onboard-plugin` (bundle allowlist + partition plan) | Dynamic partition plan stable |
+| **5** | Ranger Admin push sync from `policy.download.auth.users` | Admin REST + credentials |
+
+**Explicit non-goals for Phase 1–3:**
+
+- Removing authorization check on `/access`
+- Merging plugin allowlist with partition-plan admin allowlist
+- Storing allowlist in Postgres (Kafka-first to match partition plan)
+
+---
+
+## 12. Migration and brownfield
+
+### Pre-flight
+
+1. Export effective allowlist from running ingestor config or `GET /service-allowlist` (after Phase 2).
+2. Document `auth_to_local` rules for each repo.
+3. Ensure compacted topic created with `cleanup.policy=compact`, **1 partition**.
+
+### Cutover steps
+
+1. Seed `ranger_audit_service_allowlist` with JSON v1 (all current `service.*.allowed.users`).
+2. Set `service.allowlist.dynamic.enabled=true`.
+3. Rolling restart ingestor pods (loads watcher; picks up topic).
+4. Verify: plugin POST still **200**; remove a user via REST → **403**; restore via REST → **200** (no second restart).
+
+### Rollback
+
+Set `dynamic.enabled=false` and restart; static XML values apply again. Kafka topic can remain (ignored).
+
+---
+
+## 13. Security considerations
+
+| Topic | Guidance |
+|-------|----------|
+| **Fail closed** | Unknown repo or empty allowlist → 403 |
+| **Separate admin list** | Plugins must not mutate allowlist or partition plan |
+| **Audit admin actions** | Log all PUT/POST to allowlist REST (who changed which repo) |
+| **Kafka ACLs** | Restrict produce on allowlist topic to ingestor service account |
+| **No wildcard allow** | Avoid `*` for `allowed.users`; explicit short names per repo |
+| **Tag / non-resource services** | Do not add allowlist for repos that never POST resource audits (e.g. tag services per RANGER-2481) |
+
+---
+
+## 14. Comparison: static vs dynamic allowlist
+
+| Aspect | Static (today) | Dynamic (proposed) |
+|--------|----------------|---------------------|
+| New repo `dev_trino` | Edit site XML + restart | REST or Admin sync; no restart |
+| Multi-replica consistency | Same XML on all pods | Kafka compacted topic |
+| Relation to partition plan | Independent step | Can bundle in onboard-plugin API |
+| Authorization on `/access` | Required | **Still required** |
+| Plugin access to admin API | Denied | Denied |
+
+---
+
+## 15. Open questions for review
+
+1. **Topic naming:** `ranger_audit_service_allowlist` vs single document key in an existing config topic?
+2. **Strict vs permissive Admin sync:** Reject allowlist users not in `policy.download.auth.users`?
+3. **Delete repo:** Should DELETE remove partition plan entry too (onboard-plugin rollback)?
+4. **JWT/basic auth:** Allowlist still keyed by short username; document that JWT subjects must match allowlist entries.
+5. **Phase ordering:** Ship dynamic allowlist before or after partition plan Phase 6 admin authZ?
+
+---
+
+## 16. References (code)
+
+| Item | Location |
+|------|----------|
+| `/access` authorization | `audit-ingestor/.../AuditREST.java` — `isAllowedServiceUser()` |
+| Static allowlist load | `AuditREST.initializeAllowedUsers()` |
+| Shipped XML entries | `audit-ingestor/.../ranger-audit-ingestor-site.xml` |
+| Partition plan pattern | `PartitionPlanService`, `KafkaPartitionPlanRegistry`, `PartitionPlanWatcher` |
+| `auth_to_local` | `ranger.audit.ingestor.auth.to.local` in same site XML |
+
+---
+
+*Proposal document. Implementation tracked separately from dynamic partition plan phases.*
diff --git a/audit-server/README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md b/audit-server/README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md
new file mode 100644
index 000000000..d05befd8e
--- /dev/null
+++ b/audit-server/README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md
@@ -0,0 +1,667 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic service allowlist for Ranger audit-ingestor — guide for everyone
+
+This guide explains **why** and **how** Ranger can move from a **static** per-repo allowlist (loaded once at ingestor startup) to a **dynamic** allowlist (change at runtime without restarting the audit ingestor).
+
+It is written for operators, architects, and reviewers who need a shared mental model — **without reading the codebase**.
+
+**Confluence:** [Dynamic Service Allowlist Guide (Ranger Audit Ingestor)](https://cloudera.atlassian.net/wiki/spaces/ENG/pages/12055576591/Dynamic+Service+Allowlist+Guide+Ranger+Audit+Ingestor) (child of [Ranger Engineering](https://cloudera.atlassian.net/wiki/spaces/ENG/pages/759726545/Ranger+Engineering))
+
+**Status:** Proposal (not fully implemented). Complements [Dynamic Kafka Partitioning Guide](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) ([Confluence](https://cloudera.atlassian.net/wiki/spaces/ENG/pages/12043681813/Dynamic+Kafka+Partitioning+Guide+Ranger+Audit+Plugins)); does **not** replace authorization on `POST /api/audit/access`.
+
+**Related design doc:** [README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md](README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md)
+
+---
+
+## 1. What problem are we solving?
+
+Ranger plugins (HDFS, Hive, Ozone OM, Trino, etc.) POST audit events to **audit-ingestor**:
+
+```http
+POST /api/audit/access?serviceName=<repo>&appId=<agent>
+```
+
+After Kerberos/JWT/basic **authentication** (401 on failure), ingestor performs **authorization**: the authenticated short username must appear in the allowlist for that repo.
+
+**Today (static mode):**
+
+- Who may POST audits for repo `dev_hive` is defined in **XML** at startup:
+  - `ranger.audit.ingestor.service.dev_hive.allowed.users` = `hive`
+- Adding a new Ranger service repo (e.g. `dev_trino`) means: edit `ranger-audit-ingestor-site.xml` → **restart ingestor** on every pod.
+- [PR #1017](https://github.com/apache/ranger/pull/1017) (RANGER-5645) added missing static entries for Docker E2E (e.g. `dev_ozone` needed `om`).
+
+**Goal (dynamic mode):**
+
+- Change **who may claim audits for a repo** while ingestor is running.
+- Onboard a new repo without rolling restart.
+- Keep all ingestor replicas consistent via a shared durable registry (same pattern as the partition plan).
+
+**What this does *not* solve:** Kafka partition routing. That is the [partition plan guide](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) ([Confluence](https://cloudera.atlassian.net/wiki/spaces/ENG/pages/12043681813/Dynamic+Kafka+Partitioning+Guide+Ranger+Audit+Plugins)). Dynamic partition mapping does **not** remove the allowlist check — and that is **intentional**.
+
+---
+
+## 2. Core ideas (plain language)
+
+### Service repo name (`serviceName`)
+
+The `serviceName` query parameter on `/access` is the **Ranger Policy Manager service name** — e.g. `dev_hive`, `dev_ozone`, `dev_trino`. It must match the repo name in Ranger Admin, not the service *type* (`hive`, `ozone`).
+
+### Short username (after `auth_to_local`)
+
+Ingestor maps the Kerberos principal to a **short name** before checking the allowlist — e.g. `hive/ranger-hive.rangernw@EXAMPLE.COM` → `hive`.
+
+Allowlist values are **short names**, not full principals.
+
+### Service allowlist: `ranger.audit.ingestor.service.<repo>.allowed.users`
+
+This is the authorization gate on every plugin audit POST.
+
+| Item | Detail |
+|------|--------|
+| **Property** | `ranger.audit.ingestor.service.<repo>.allowed.users` |
+| **Example** | `ranger.audit.ingestor.service.dev_hive.allowed.users` = `hive` |
+| **Caller** | Service daemons (`hive`, `hdfs`, `om`, `trino`, …) |
+| **When checked** | On **every** audit POST, **before** Kafka produce |
+| **Failure** | **403** (authentication already succeeded) |
+
+**What it prevents:** any principal with a valid Kerberos ticket from forging audits for a repo it does not own. Without this check, a compromised `kafka` daemon could POST events as `serviceName=dev_hive`.
+
+### Partition plan (orthogonal — different guide)
+
+After the service allowlist check passes, ingestor publishes to Kafka and the **partition plan** decides *which partition*. See [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md).
+
+A plugin can have a valid partition range and still get **403** on `/access` if its short name is not in the service allowlist.
+
+### Service allowlist registry (proposed source of truth)
+
+The live allowlist lives in **durable shared storage** that all ingestor replicas read — a Kafka **compacted** topic (`ranger_audit_service_allowlist`).
+
+- No new database dependency.
+- Survives pod restarts.
+- All replicas see the same latest allowlist document.
+
+### Consistency rule (ops discipline — Phase 1)
+
+```text
+allowedUsers for repo R ⊆ { short names from policy.download.auth.users for R in Ranger Admin }
+```
+
+Ranger Admin does **not** sync this automatically in Phase 1 (Option C). Operators copy the right short names when onboarding. Ingestor may **reject** REST writes that violate the subset rule (strict mode).
+
+### Three layers — do not merge
+
+| Layer | Who | Purpose |
+|---------|-----|---------|
+| **Service allowlist** (plugin POST) | Daemons (`hive`, `om`, …) | May this principal POST audits for repo `R`? |
+| **Partition plan** (Kafka routing) | Ingestor internal | Which Kafka partition after accept? |
+| **Admin REST APIs** | Ops (`admin`, `ops`, …) | Who may change allowlist or partition plan via REST? |
+
+Plugins must **not** call allowlist-admin or partition-plan REST. One combined list would let a daemon rewire routing or impersonate other repos.
+
+---
+
+## 3. Today vs proposed (at a glance)
+
+| | Static (today) | Dynamic (proposed) |
+|---|----------------|---------------------|
+| **Where allowlist lives** | XML on each pod at startup | Shared document in Kafka compacted topic |
+| **Change allowlist** | Edit XML + restart | REST API; no restart |
+| **Add new repo `dev_trino`** | New XML property + restart all pods | `PUT /service-allowlist` or seed topic |
+| **Multi-replica ingestor** | Same XML if synced via ConfigMap | All pods watch same Kafka topic |
+| **Relation to partition plan** | Separate manual step | Still separate; optional `onboard-plugin` bundles both later |
+| **Authorization on `/access`** | Required | **Still required** |
+| **Feature flag** | Default behavior | `ranger.audit.ingestor.service.allowlist.dynamic.enabled=true` |
+
+---
+
+## 4. Request path — why partition plan does not replace allowlist
+
+```text
+Plugin POST /api/audit/access?serviceName=dev_hive&appId=hiveServer2
+        │
+        ├─ 401  Authentication failed (Kerberos / JWT / basic)
+        │
+        ├─ 403  Service allowlist: auth_to_local(principal) → "hive"
+        │         "hive" ∉ allowed set for dev_hive  → STOP
+        │         (partition plan is never consulted)
+        │
+        └─ 200/202  Allowlist passed → Kafka producer
+                          │
+                          └─ Partition plan: router picks partition
+```
+
+| If you see… | Layer | Fix |
+|-------------|-------|-----|
+| **401** on `/access` | Authentication | Plugin / ingestor Kerberos, keytabs, SPNEGO |
+| **403** on `/access` | **Service allowlist** | Add short name to `service.<repo>.allowed.users` |
+| Audits accepted but wrong Kafka partition | **Partition plan** | Update partition plan ([partition guide](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md)) |
+| New repo in Admin, audits still **403** | Service allowlist not onboarded | Partition plan alone is **not** enough |
+| Allowlist OK, audits in buffer partition | Partition plan not onboarded | Allowlist alone is **not** enough |
+
+**Takeaway:** Onboard **two things** per repo — **service allowlist** and **partition range**.
+
+---
+
+## 5. Static → dynamic cutover — direct answers
+
+**Goal:** Turn on dynamic mode so every plugin keeps the **same** authorization behavior it has today — no surprise 403s on cutover day.
+
+### When dynamic mode is off
+
+| Question | Answer |
+|----------|--------|
+| Is `ranger_audit_service_allowlist` created? | **No** — the allowlist topic is not created or used. |
+| How is authz decided? | From XML at startup (`initializeAllowedUsers()`), same as today. |
+| Is there a background allowlist sync? | **No**. |
+
+### When dynamic mode is on
+
+| Question | Answer |
+|----------|--------|
+| Is the allowlist topic created? | **Yes** — on first startup that needs the registry. |
+| Where does every ingestor get the allowlist? | From `ranger_audit_service_allowlist` (compacted topic), kept in memory on each pod. |
+| Can XML edits change live authz? | **No** (once a document exists in Kafka). Runtime changes go through REST. |
+
+### How “same allowed users per repo” is achieved on cutover
+
+Preservation works because the **first published document** is built from the **same XML properties** used today:
+
+| Piece | Static today | Dynamic (first document from XML) |
+|-------|--------------|-------------------------------------|
+| Repo key | `service.<repo>.allowed.users` property name | Same repo name in JSON `services` map |
+| User values | Comma-separated short names in XML | Same names in `allowedUsers` array |
+| Unknown repo | No XML entry → **403** | No registry entry → **403** (fail closed) |
+| Per-request check | `isAllowedServiceUser()` | Same method; reads in-memory cache |
+
+**Brownfield:** Export current `service.*.allowed.users` from `ranger-audit-ingestor-site.xml`, seed JSON v1 into the allowlist topic **before** or during cutover, then enable dynamic mode and verify plugin POSTs still return **200**.
+
+### Allowlist already in Kafka vs empty registry
+
+```mermaid
+sequenceDiagram
+  participant Pod as Ingestor pod
+  participant Allow as ranger_audit_service_allowlist
+  participant XML as site.xml
+
+  Pod->>Allow: create topic if missing (Race A)
+  Pod->>Allow: read allowlist document
+  alt document exists
+    Allow-->>Pod: use stored allowlist — skip XML bootstrap
+  else registry empty
+    Pod->>XML: build first document from service.*.allowed.users
+    Pod->>Allow: re-read (Race B — peer may have published)
+    Pod->>Allow: publish first document if still empty
+    Pod->>Allow: mandatory read-back
+  end
+  Pod->>Pod: install map in memory
+```
+
+| Situation | What each pod does |
+|-----------|-------------------|
+| Document **already** in `ranger_audit_service_allowlist` | Read and use it; **do not** publish a new document from XML |
+| Topic exists but **no message** yet | One pod publishes the first document; others re-read and adopt (**Race B**) |
+| Several pods create the topic at once | Idempotent create — **Race A** |
+
+After the first document is stored in Kafka, **Kafka is the source of truth** for the allowlist.
+
+---
+
+## 6. How dynamic mode works (end-to-end)
+
+| Plane | Kafka topic | Traffic | Who reads/writes |
+|-------|-------------|---------|------------------|
+| **Data** | `ranger_audits` | High — every audit event | Plugins → ingestor → dispatchers |
+| **Control (allowlist)** | `ranger_audit_service_allowlist` (compacted) | Low — rare allowlist changes | Admin REST + background sync on ingestor pods |
+| **Control (partition plan)** | `ranger_audit_partition_plan` (compacted) | Low — rare routing changes | Separate admin REST ([partition guide](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md)) |
+
+The service allowlist is **configuration**, not audit data. Ingestor keeps the current map **in memory**; only the background sync thread and REST handlers touch the allowlist topic.
+
+### Architecture (control plane vs data plane)
+
+```mermaid
+flowchart TB
+  subgraph plugins [Ranger plugins]
+    HS2[HiveServer2]
+    OM[Ozone OM]
+  end
+
+  subgraph ops [Ops or automation]
+    Admin[Admin REST client]
+  end
+
+  subgraph ingestor [Each audit-ingestor pod]
+    Access["POST /api/audit/access"]
+    AllowREST["GET/PUT /api/audit/service-allowlist"]
+    Svc[Allowlist update service]
+    Watcher[Background allowlist sync]
+    Mem[(In-memory allowlist map)]
+    Part[Partition router]
+    KafkaProd[Kafka producer]
+
+    AllowREST --> Svc
+    Svc --> AllowTopic
+    Watcher -->|poll / consume| AllowTopic
+    Watcher -->|atomic swap| Mem
+    HS2 -->|serviceName=dev_hive| Access
+    OM -->|serviceName=dev_ozone| Access
+    Access -->|isAllowedServiceUser| Mem
+    Access -->|on 200/202| KafkaProd
+    KafkaProd --> Part
+    Part --> AuditTopic
+  end
+
+  subgraph kafka [Kafka]
+    AllowTopic[(ranger_audit_service_allowlist<br/>compacted, low volume)]
+    AuditTopic[(ranger_audits<br/>high volume)]
+  end
+
+  Admin -->|GET / PUT via load balancer| AllowREST
+```
+
+### First startup — seeding the allowlist (once per cluster)
+
+When dynamic mode starts and the allowlist registry is **empty**:
+
+1. Ingestor enables dynamic allowlist mode.
+2. Background sync finds no document in `ranger_audit_service_allowlist`.
+3. Ingestor scans XML for `ranger.audit.ingestor.service.*.allowed.users` properties.
+4. Ingestor builds and publishes the **first document** to the compacted topic.
+5. Ingestor loads that map into memory and begins enforcing authz on `/access`.
+
+**After that:** additional pods and restarts **read Kafka only** — they do not re-build from XML.
+
+### Every audit — the hot path
+
+The allowlist topic is **not** read on this path.
+
+1. Plugin POSTs audit to ingestor (Kerberos/JWT/basic auth).
+2. Ingestor maps principal → short name (`auth_to_local`).
+3. `isAllowedServiceUser(serviceName, shortName)` reads the **in-memory** map.
+4. If allowed → accept → Kafka produce → partition router.
+5. If denied → **403**.
+
+### Changing the allowlist — admin or automation
+
+**On the pod that receives the REST call:**
+
+1. Read current document from Kafka.
+2. Validate change (subset rule if strict mode enabled).
+3. Write new document **version** to compacted topic.
+4. Return **200 OK** or **409 Conflict** (stale `expectedVersion`).
+
+**On every ingestor pod (~30s sync interval):**
+
+1. Background sync picks up new document version.
+2. Swaps map in memory — **no restart**.
+
+```mermaid
+sequenceDiagram
+  participant Ops as Ops / automation
+  participant REST as Ingestor REST (one pod)
+  participant Allow as ranger_audit_service_allowlist
+  participant W as Background sync (each pod)
+  participant Mem as In-memory allowlist
+  participant Plugin as Plugin POST /access
+
+  Ops->>REST: PUT service-allowlist (add dev_trino)
+  REST->>Allow: read current version
+  REST->>Allow: write new version
+  REST-->>Ops: 200 OK
+
+  loop Every ingestor pod
+    W->>Allow: poll latest document
+    W->>Mem: atomic swap
+    Plugin->>Mem: isAllowedServiceUser?
+  end
+```
+
+### Rules to remember
+
+- **Allowlist topic = who may POST**; audit topic = audit data.
+- **Memory on the hot path** — no per-audit read of the allowlist topic.
+- **Kafka is the source of truth** after the first document is published.
+- **Fail closed** — unknown repo or empty allowlist → **403**.
+- **All pods must agree** — every ingestor syncs from the same compacted topic.
+- **Partition plan is separate** — changing routing does not change who may POST.
+
+---
+
+## 7. Admin REST API (control plane)
+
+When dynamic mode is on, operators change the allowlist through the **ingestor admin API** on **any** pod (usually via load balancer). Mutations are written to `ranger_audit_service_allowlist`; every pod picks up changes through background sync (~30s).
+
+**Auth:** Kerberos or JWT. Caller must be in **`service.allowlist.admin.users`** — **not** the same list as plugin users. Dynamic mode off → allowlist REST returns **503**.
+
+### Endpoints (proposed)
+
+| Method | Path | Use when |
+|--------|------|----------|
+| `GET` | `/api/audit/service-allowlist` | Read current document + version |
+| `PUT` | `/api/audit/service-allowlist` | Replace or merge full document |
+| `PUT` | `/api/audit/service-allowlist/services/{repo}` | Upsert one repo (convenience) |
+| `DELETE` | `/api/audit/service-allowlist/services/{repo}` | Remove repo (plugins get **403** for that repo) |
+
+Base URL example: `https://<ingestor-host>:7081/api/audit/service-allowlist`
+
+### Registry document shape
+
+```json
+{
+  "version": 3,
+  "updatedAt": "2026-06-15T12:00:00Z",
+  "updatedBy": "admin",
+  "services": {
+    "dev_hive": {
+      "allowedUsers": ["hive"]
+    },
+    "dev_ozone": {
+      "allowedUsers": ["om", "ozone"]
+    },
+    "dev_trino": {
+      "allowedUsers": ["trino"]
+    }
+  }
+}
+```
+
+### `expectedVersion` (all writes)
+
+Every `PUT` must include the **version** you read from the last `GET`. If another admin changed the allowlist first, the server returns **409 Conflict** with the current document — refresh and retry.
+
+### Common operations
+
+**Read allowlist**
+
+```http
+GET /api/audit/service-allowlist
+→ 200 + JSON document (note the "version" field)
+```
+
+**Onboard repo** — e.g. allow `trino` for `dev_trino`:
+
+```json
+PUT /api/audit/service-allowlist
+{
+  "expectedVersion": 2,
+  "services": {
+    "dev_trino": {
+      "allowedUsers": ["trino"]
+    }
+  }
+}
+```
+
+Or upsert one repo:
+
+```http
+PUT /api/audit/service-allowlist/services/dev_trino
+{
+  "expectedVersion": 2,
+  "allowedUsers": ["trino"]
+}
+```
+
+Success → **200** + updated document (version incremented).  
+Stale version → **409** + current document in body.  
+Strict subset violation → **400**.
+
+### What happens inside one REST call
+
+| Step | What the ingestor does |
+|------|------------------------|
+| 1 | Authenticate caller; check `service.allowlist.admin.users` |
+| 2 | Read current document from `ranger_audit_service_allowlist` |
+| 3 | Reject if `expectedVersion` does not match |
+| 4 | Validate `allowedUsers` ⊆ `policy.download.auth.users` (strict mode, optional) |
+| 5 | Publish new document version to Kafka |
+| 6 | Return updated JSON |
+
+**GET** is cheap (memory). **PUT** always goes through Kafka so all pods converge on the same allowlist.
+
+---
+
+## 8. Operator workflow: onboarding a new repo
+
+Use this **in addition to** the [partition plan onboarding workflow](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md#7-operator-workflow-onboarding-a-plugin).
+
+### Stage 0 — Create service in Ranger Admin
+
+1. Create service `dev_trino` in Policy Manager.
+2. Set `policy.download.auth.users` = `trino` (comma-separated short names).
+3. Configure plugin audit destination → ingestor URL (`:7081`).
+
+Ranger Admin does **not** push to ingestor in Phase 1. You must onboard the allowlist separately.
+
+### Stage 1 — Add allowlist entry
+
+**Static mode (today):**
+
+```xml
+<property>
+  <name>ranger.audit.ingestor.service.dev_trino.allowed.users</name>
+  <value>trino</value>
+</property>
+```
+
+Restart all ingestor pods.
+
+**Dynamic mode (proposed):**
+
+```http
+PUT /api/audit/service-allowlist/services/dev_trino
+{ "expectedVersion": N, "allowedUsers": ["trino"] }
+```
+
+All ingestors apply within ~30s. **No restart** required.
+
+### Stage 2 — Verify plugin POST
+
+```bash
+# From plugin host (after kinit as trino)
+curl --negotiate -u : -X POST \
+  "http://<ingestor>:7081/api/audit/access?serviceName=dev_trino&appId=trino" \
+  -H "Content-Type: application/json" \
+  -d '[...]'
+```
+
+Expect **200/202**, not **403**.
+
+### Stage 3 — Partition plan
+
+Promote or scale in the partition plan if dedicated partitions are needed. See [partition plan onboarding workflow](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md#7-operator-workflow-onboarding-a-plugin) ([Confluence](https://cloudera.atlassian.net/wiki/spaces/ENG/pages/12043681813/Dynamic+Kafka+Partitioning+Guide+Ranger+Audit+Plugins)).
+
+### Onboard checklist
+
+| Check | Example |
+|-------|---------|
+| Admin `policy.download.auth.users` | `trino` |
+| Ingestor allowlist ⊆ Admin download users | `dev_trino` → `{trino}` |
+| `auth_to_local` maps plugin principal | `trino/host@REALM` → `trino` |
+| Plugin `serviceName` query param | `dev_trino` (Admin repo name) |
+| Partition plan entry (if needed) | `trino` promoted from buffer |
+
+**Do not** edit `ranger-audit-ingestor-site.xml` on one pod for runtime changes when dynamic mode is on. XML is only for **initial bootstrap** when the allowlist registry is empty.
+
+---
+
+## 9. Configuration (dynamic mode)
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `ranger.audit.ingestor.service.allowlist.dynamic.enabled` | Turn dynamic allowlist on/off | `false` (default) = static XML |
+| `ranger.audit.ingestor.service.allowlist.topic` | Compacted allowlist topic name | `ranger_audit_service_allowlist` |
+| `ranger.audit.ingestor.service.allowlist.refresh.interval.ms` | How often pods reload allowlist | `30000` |
+| `ranger.audit.ingestor.service.allowlist.admin.users` | Who may call allowlist REST | `admin,ops` |
+| `ranger.audit.ingestor.service.<repo>.allowed.users` | Static bootstrap per repo | `hive`, `om,ozone`, … |
+| `ranger.audit.ingestor.auth.to.local` | Principal → short name rules | Same as Hadoop `hadoop.security.auth_to_local` |
+
+When dynamic is **off**, authz is fixed from XML at startup and the allowlist topic is not used.
+
+When dynamic is **on** and the registry is **empty**, the first ingestor pod seeds the document from XML. Later pods and restarts read **Kafka only**.
+
+---
+
+## 10. FAQ
+
+### Basics
+
+**Why do we need an allowlist if Kerberos already authenticates the plugin?**  
+Authentication proves *who* connected. Authorization proves they may **claim audits for this repo**. Kerberos success alone would let any daemon POST as any `serviceName`.
+
+**What is the difference between static and dynamic allowlist?**  
+Static: map loaded once from XML at startup; changes need restart. Dynamic: map lives in Kafka; ops change it via REST while ingestor keeps running.
+
+**Does dynamic partition plan remove the allowlist check?**  
+**No.** Partition routing runs **after** `/access` accepts the batch. **403** on `/access` is always a **service allowlist** failure.
+
+**How does this relate to PR #1017 (RANGER-5645)?**  
+#1017 added missing **static** XML entries for Docker (service allowlist). Partition plan work is orthogonal.
+
+**Why not store the allowlist in Ranger Admin or Postgres?**  
+Phase 1 (Option C): no Admin → ingestor coupling. Kafka compacted topic matches the partition-plan pattern ingestor already uses.
+
+**Why not edit XML on a running pod?**  
+Each pod has its own copy; edits are not shared, not durable, and are lost on restart. Runtime changes belong in the allowlist topic via REST.
+
+### Two topics and sync
+
+**What are the Kafka topics involved?**  
+`ranger_audits` = audit data (high volume). `ranger_audit_service_allowlist` = allowlist config (low volume, compacted). Partition plan uses a third topic — see partition guide.
+
+**Does every audit POST read the allowlist topic?**  
+No. Each audit uses the map already in **memory** on that pod. Only background sync and REST mutations touch the allowlist topic.
+
+**How do all ingestor pods stay in sync?**  
+Every pod watches the same compacted allowlist topic (default every 30s) and swaps the new map into memory.
+
+**What happens when a pod restarts?**  
+It reads the latest document from Kafka (if dynamic is on). The allowlist survives in Kafka across crashes.
+
+### Allowlist content
+
+**What goes in `allowedUsers`?**  
+Short names after `auth_to_local` — same values as `policy.download.auth.users` on the Ranger service (or a subset).
+
+**What if a repo is missing from the allowlist?**  
+**403** for that `serviceName`. Fail closed.
+
+**Can I use `*` as a wildcard?**  
+Not recommended. Use explicit short names per repo.
+
+**Should tag services get an allowlist entry?**  
+No for repos that never POST resource audits (e.g. tag services per RANGER-2481).
+
+### REST and concurrency
+
+**Do I need to restart ingestor after PUT allowlist?**  
+No. Background sync applies the new map within about one refresh interval (~30s).
+
+**What is `expectedVersion`?**  
+The document `version` you believe is current when you write. Stale version → **409**.
+
+**What should I do on HTTP 409?**  
+Another writer published a newer document. Use the body from the 409 response (or `GET` again), note the new `version`, and retry.
+
+**Who can call service-allowlist REST?**  
+Ops principals in `service.allowlist.admin.users` (Kerberos/JWT). Plugin users (`hive`, `om`) send audits via `/access` — they must **not** mutate the allowlist.
+
+**Who can call `POST /access`?**  
+Only principals in `service.<repo>.allowed.users` for the given `serviceName`.
+
+### Cutover and bootstrap
+
+**When is `ranger_audit_service_allowlist` created?**  
+Only when dynamic allowlist mode is enabled.
+
+**Can I publish the allowlist to Kafka before enabling dynamic mode?**  
+Yes — recommended for brownfield. Ingestor will read your pre-loaded document and will not replace it with a fresh XML bootstrap.
+
+**How do I verify cutover succeeded?**  
+`GET /api/audit/service-allowlist` on every pod (same `version`); plugin POSTs still **200**; remove a user via REST → plugin gets **403** → restore → **200** without restart.
+
+**How do I roll back to static mode?**  
+Export current document via `GET`, align XML to that layout, set `dynamic.enabled=false`, rolling restart. Allowlist topic remains but is ignored.
+
+### Troubleshooting
+
+**Plugin gets 401 on `/access`**  
+Authentication problem — keytabs, SPNEGO, ingestor Kerberos config. Not an allowlist issue.
+
+**Plugin gets 403 on `/access` but Kerberos works**  
+Service allowlist: short name not in `service.<repo>.allowed.users`, or wrong `serviceName`, or `auth_to_local` mismatch.
+
+**New repo in Admin UI, still 403**  
+Service allowlist not onboarded. Creating the service in Admin does not auto-update ingestor (Phase 1).
+
+**Audits accepted but not in expected Solr partition**  
+Partition plan issue, not allowlist. See [partition guide](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md).
+
+**Pods show different allowlist versions**  
+Wait one refresh interval. If still mismatched, check allowlist topic readability and watcher logs on the lagging pod.
+
+**Does Ranger Admin need the audit-ingestor URL?**  
+No. Admin reads audits from Solr (or DB/ES). Plugins point at ingestor; allowlist is ingestor-local config.
+
+### Relation to partition plan
+
+**Do I need both allowlist and partition plan for a new plugin?**  
+Yes for full production onboarding. Allowlist = may POST; partition plan = where in Kafka.
+
+**Is there a bundled API?**  
+Proposed Phase 4: `POST /api/audit/onboard-plugin` updates allowlist **first**, then partition plan (fail closed if allowlist missing).
+
+**What order on partial failure?**  
+Allowlist first, then plan. No audits accepted until allowlist exists for the repo.
+
+---
+
+## 11. Phased rollout (summary)
+
+| Phase | Deliverable |
+|-------|-------------|
+| **0** | Static XML ([#1017](https://github.com/apache/ranger/pull/1017) Docker entries) — **today** |
+| **1** | Kafka topic + watcher; `AuditREST` reads cache; bootstrap from XML |
+| **2** | `GET/PUT /api/audit/service-allowlist` + admin authZ |
+| **3** | Ops runbook + brownfield migration |
+| **4** | Optional `POST /api/audit/onboard-plugin` (allowlist + partition plan) |
+| **5** | Optional Ranger Admin push sync — **out of scope for Phase 1–3** |
+
+**Explicit non-goals for Phase 1–3:**
+
+- Removing authorization on `/access`
+- Merging plugin allowlist with partition-plan admin allowlist
+- Ranger Admin automatic sync (Option C only)
+
+---
+
+## Docs
+
+| Doc | Purpose |
+|-----|---------|
+| [README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md](README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md) | Full design proposal (authorization layers, security, API detail) |
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Partition plan operator guide |
+| [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) | Partition plan architecture |
+| [DESIGN-KAFKA-AUDIT-SERVER.md](DESIGN-KAFKA-AUDIT-SERVER.md) | End-to-end audit pipeline |
+| [PR #1017](https://github.com/apache/ranger/pull/1017) (RANGER-5645) | Static Docker allowlist fix |
+
+---
+
+*Operator guide for the dynamic service allowlist proposal. Implementation tracked separately from partition plan phases.*
diff --git a/audit-server/README-KAFKA-DYNAMIC-PARTITION-PLAN.md b/audit-server/README-KAFKA-DYNAMIC-PARTITION-PLAN.md
new file mode 100644
index 000000000..d6e2dd5f2
--- /dev/null
+++ b/audit-server/README-KAFKA-DYNAMIC-PARTITION-PLAN.md
@@ -0,0 +1,253 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic Kafka partition plan — feature README
+
+Runtime dynamic plugin-to-partition routing for **audit-ingestor**. Operators can promote plugins from a shared buffer pool or grow tail partitions through REST while ingestor keeps running.
+
+**Feature flag (default off):** `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=false`
+
+---
+
+## When to use this
+
+| Use dynamic mode when… | Stay on static mode when… |
+|------------------------|---------------------------|
+| You run multiple ingestor replicas and need one shared routing plan | Single ingestor, rare config changes, restart is acceptable |
+| You onboard new plugins without reshuffling existing partition assignments | You are fine editing XML and restarting ingestor |
+| You scale hot plugins by appending tail partitions only | Partition layout is fixed at install time |
+
+Static behavior is documented in [README-KAFKA-PLUGIN-PARTITIONING.md](README-KAFKA-PLUGIN-PARTITIONING.md).
+
+---
+
+## Architecture (30-second view)
+
+```mermaid
+flowchart LR
+  REST[AuditREST /partition-plan]
+  PS[PartitionPlanService]
+  REG[KafkaPartitionPlanRegistry]
+  PT[(ranger_audit_partition_plan\n1 partition compacted)]
+  W[PartitionPlanWatcher]
+  H[PartitionPlanHolder]
+  AP[AuditPartitioner]
+  AT[(ranger_audits)]
+
+  REST --> PS
+  PS --> REG
+  REG --> PT
+  W --> REG
+  W --> H
+  AP --> H
+  AP --> AT
+```
+
+1. **Registry topic** `ranger_audit_partition_plan` stores the latest `PartitionPlan` JSON (key = audit topic name, e.g. `ranger_audits`).
+2. **Watcher** refreshes the in-memory plan on each ingestor pod.
+3. **Partitioner** reads `PartitionPlanHolder` on every produce (no Kafka I/O on hot path).
+4. **REST** mutates the plan (grow audit topic first, then write registry, then read-back verify).
+
+The registry topic always has **exactly one partition** — enough because traffic is rare admin updates and compaction keeps one value per key.
+
+---
+
+## Enable dynamic mode
+
+Add to `ranger-audit-ingestor-site.xml` (or uncomment the block already in the sample file):
+
+```xml
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled</name>
+  <value>true</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.topic</name>
+  <value>ranger_audit_partition_plan</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms</name>
+  <value>30000</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.consumer.poll.timeout.ms</name>
+  <value>500</value>
+</property>
+```
+
+On first startup with an empty registry, the **first ingestor pod** publishes an **initial bootstrap plan** derived from the same XML properties used by static mode (`kafka.configured.plugins`, partition counts, buffer). Later pods only consume Kafka.
+
+---
+
+## Partition plan JSON
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 1,
+  "topicPartitionCount": 15,
+  "updatedAt": "2026-06-09T12:00:00Z",
+  "updatedBy": "bootstrap",
+  "plugins": {
+    "hdfs":        { "partitions": [0, 1, 2] },
+    "hiveServer2": { "partitions": [3, 4, 5] }
+  },
+  "buffer": { "partitions": [6, 7, 8, 9, 10, 11, 12, 13, 14] }
+}
+```
+
+- **`version`** — increments on every successful REST mutation; clients send `expectedVersion` for optimistic locking.
+- **`topicPartitionCount`** — must match Kafka partition count for `ranger_audits`.
+- **`buffer`** — sticky hash target for plugins not yet promoted.
+
+---
+
+## REST API
+
+Base: `https://<ingestor-host>:<port>/api/audit`
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/partition-plan` | Read in-memory plan on this pod |
+| `PUT` | `/partition-plan` | Replace full plan (advanced) |
+| `POST` | `/partition-plan/promote` | Promote plugin from buffer to dedicated partitions |
+| `POST` | `/partition-plan/scale` | Add tail partitions to an existing plugin |
+
+Example promote:
+
+```bash
+curl -s -X POST "https://ingestor:7182/api/audit/partition-plan/promote" \
+  -H "Content-Type: application/json" \
+  -d '{"pluginId":"trino","partitionCount":3,"expectedVersion":1}'
+```
+
+| Response | Meaning |
+|----------|---------|
+| `200` | Plan updated; body is new plan JSON |
+| `409` | `expectedVersion` stale — re-`GET` and retry |
+| `503` | Dynamic mode disabled or plan/Kafka not ready |
+
+Full request schemas: [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md).
+
+---
+
+## Routing rules (`AuditPartitioner`)
+
+| Case | Behavior |
+|------|----------|
+| Plugin in `plan.plugins` | Round-robin across that plugin's partition id list (`nextRoundRobinIndex`) |
+| Plugin not in plan | Sticky hash into `buffer.partitions` |
+| Plan not loaded | Error log + topic-wide hash fallback |
+| Topic smaller than plan during grow | `boundPartitionToTopic` clamps planned id to live metadata |
+
+Message **key** = plugin id (`hdfs`, `hiveServer2`, …).
+
+---
+
+## Java package layout
+
+```
+audit-ingestor/.../producer/kafka/partition/
+├── model/          PartitionPlan, PluginPartitionAssignment, REST DTOs
+├── exception/      PartitionPlanException, PartitionPlanConflictException
+├── constants/      PartitionPlanConstants
+├── PartitionPlanHolder.java
+├── PartitionPlanWatcher.java
+├── KafkaPartitionPlanRegistry.java
+├── PartitionPlanBootstrap.java
+├── PartitionPlanAllocator.java
+├── PartitionPlanValidator.java
+├── PartitionPlanService.java
+└── KafkaAuditTopicPartitionGrower.java
+```
+
+`audit-common`: `AuditMessageQueueUtils.createPartitionPlanTopicIfNotExists()` creates the registry topic (1 partition, compacted).
+
+---
+
+## Build and test
+
+### Unit tests and quality gates
+
+```bash
+cd ranger
+export MAVEN_OPTS="-Xmx4g"
+mvn verify -pl audit-server/audit-common,audit-server/audit-ingestor -Drat.skip=true
+```
+
+| Gate | Expected |
+|------|----------|
+| Unit tests | 46 passed (`audit-common` 4 + `audit-ingestor` 42) |
+| Checkstyle | 0 violations |
+| PMD | 0 rule violations |
+
+Key test classes: `AuditPartitionerDynamicTest`, `PartitionPlanAllocatorTest`, `PartitionPlanValidatorTest`, `PartitionPlanServiceMutationTest`, `PartitionPlanBootstrapTest`.
+
+### Manual testing (Docker Tier 3)
+
+Validated on the Tier 3 Docker lab (Kerberos, Kafka, Solr, HDFS plugin, ingestor). **31 E2E checks — all passed.**
+
+```bash
+cd dev-support/ranger-docker
+./scripts/audit/wait-for-audit-health.sh --tier 3
+./scripts/audit/verify-partition-plan-e2e-all.sh
+```
+
+| Scenario | What was verified |
+|----------|-------------------|
+| Static mode (`dynamic.enabled=false`) | Health **200**; `GET /partition-plan` → **503**; HDFS audits OK |
+| Greenfield dynamic on | Plan topic **1 partition** compacted; bootstrap **v1**; 13 plugins / 48 partitions |
+| REST promote / scale | **200** + version bump; **409** on stale version; **400** on double-promote |
+| Multi-pod (:7081 + :7082) | Replica converges within ~35s after promote on primary |
+| Brownfield pre-seed | Pre-loaded Kafka plan not overwritten by XML bootstrap |
+| Kafka down at startup | Ingestor unhealthy with dynamic on; recovers in static mode |
+
+Narrative report: [README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md](README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md). Scenario catalog: [README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md](README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md).
+
+PR copy-paste template: [dev-support/RANGER-KAFKA-DYNAMIC-PARTITION-PLAN-PR-TEMPLATE.md](../dev-support/RANGER-KAFKA-DYNAMIC-PARTITION-PLAN-PR-TEMPLATE.md).
+
+---
+
+## Operations
+
+| Task | Doc |
+|------|-----|
+| Day-2 promote / scale procedures | [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) |
+| Cutover from static XML | [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) |
+| E2E validation plan | [README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md](README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md) |
+
+---
+
+## Related documentation
+
+| Document | Content |
+|----------|---------|
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Plain-language guide for architects and reviewers |
+| [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) | Phased implementation status |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | Registry design + REST contracts |
+| [README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md](README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md) | Original design goals |
+| [dev-support/RANGER-KAFKA-DYNAMIC-PARTITION-PLAN-PR-TEMPLATE.md](../dev-support/RANGER-KAFKA-DYNAMIC-PARTITION-PLAN-PR-TEMPLATE.md) | GitHub PR description template |
+
+---
+
+## Limitations (current)
+
+- REST auth follows general ingestor authentication; **dedicated admin allow-list is deferred**.
+- Plan registry topic partition count is fixed at **1** (by design).
+- Kafka topic partition count cannot shrink; plan validator enforces append-only growth.
diff --git a/audit-server/README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md b/audit-server/README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md
new file mode 100644
index 000000000..a0d26aa7f
--- /dev/null
+++ b/audit-server/README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md
@@ -0,0 +1,594 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic Kafka partitioning for Ranger audit plugins — guide for everyone
+
+This guide explains **why** and **how** Ranger can move from **static** plugin-to-partition mapping (set once at startup) to **dynamic** mapping (change at runtime without restarting the audit ingestor).
+
+It is written for operators, architects, and reviewers who need a shared mental model — **without reading the codebase**.
+
+---
+
+## 1. What problem are we solving?
+
+Ranger plugins (HDFS, Hive, Trino, etc.) send audit events to **audit-ingestor**, which writes them to a Kafka topic (default: `ranger_audits`).
+
+To keep high-volume plugins from starving others, ingestor can assign **dedicated Kafka partitions** per plugin. Unlisted plugins share a **buffer** pool of partitions.
+
+**Today (static mode):**
+
+- Which plugin uses which partitions is defined in **XML config** at startup.
+- Adding a plugin or giving a hot plugin more partitions usually means: edit config → increase topic partitions → **restart ingestor**.
+
+**Goal (dynamic mode):**
+
+- Change partition assignments **while ingestor is running**.
+- Onboard a new plugin without reshuffling partitions already used by other plugins.
+- Grow capacity by adding **new partitions at the end** of the topic (append-only), not by recomputing everyone’s ranges.
+
+---
+
+## 2. Core ideas (plain language)
+
+### Kafka topic partitions
+
+Think of a Kafka topic as a queue split into numbered lanes: partition `0`, `1`, `2`, …
+
+- Each audit event is routed to **one** partition based on the plugin id (Kafka record **key**).
+- More partitions → more parallel consumption downstream (Solr/HDFS dispatchers).
+
+Kafka allows **increasing** partition count; it does **not** support shrinking.
+
+### Plugin id
+
+The plugin id (also called agent id / app id) identifies the source of the audit — e.g. `hdfs`, `hiveServer2`, `trino`.
+
+### Partition plan
+
+A **partition plan** is a versioned JSON document that answers:
+
+- For each known plugin: **which partition numbers** may receive its audits?
+- Which partition numbers are reserved for **unknown / new** plugins (the buffer)?
+- What is the current **`topicPartitionCount`** (must match Kafka)?
+
+Example (simplified):
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 12,
+  "topicPartitionCount": 48,
+  "plugins": {
+    "hdfs":        { "partitions": [0, 1, 2, 3, 4, 5] },
+    "hiveServer2": { "partitions": [6, 7, 8, 9, 10, 11] }
+  },
+  "buffer": { "partitions": [12, 13, 14, "... through 47 ..."] }
+}
+```
+
+The `version` field increments on every successful admin change (optimistic locking).
+
+Every ingestor pod uses the **same** plan so routing stays consistent.
+
+### Partition registry (source of truth)
+
+The live plan lives in **durable shared storage** that all ingestor replicas read — a Kafka **compacted** topic (`ranger_audit_partition_plan`).
+
+- No new database or ZooKeeper dependency.
+- Survives pod restarts.
+- All replicas see the same latest plan.
+
+### Append-only growth
+
+When a plugin needs more capacity:
+
+1. Increase the audit topic’s partition count (add lanes at the **tail**).
+2. Assign **only the new** partition numbers to that plugin.
+3. **Do not** move partitions away from other plugins.
+
+### Buffer partitions
+
+Plugins not yet in the plan (or newly appearing in the fleet) go to **buffer** partitions until an operator **promotes** them to dedicated partitions.
+
+---
+
+## 3. Today vs proposed (at a glance)
+
+| | Static (today) | Dynamic (proposed) |
+|---|----------------|---------------------|
+| **Where mapping lives** | XML on each pod at startup | Shared plan in Kafka compacted topic |
+| **Change mapping** | Edit XML + restart | REST API; no restart |
+| **Add new plugin** | Edit `configured.plugins`, often reshuffles ranges | Promote from buffer; allocate from tail only |
+| **Scale hot plugin** | Edit overrides + restart | Add tail partitions + update plan |
+| **Multi-replica ingestor** | Same XML if synced via ConfigMap | All pods watch same Kafka plan |
+| **Feature flag** | Default behavior | `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=true` |
+
+---
+
+## 4. Static → dynamic cutover — direct answers
+
+**Goal:** Turn on dynamic mode so each plugin keeps sending audits to the **same Kafka partitions** it uses today — no surprise rerouting on cutover day.
+
+### When dynamic mode is off
+
+| Question | Answer |
+|----------|--------|
+| Is `ranger_audit_partition_plan` created? | **No** — the plan topic is not created or used. |
+| How is routing decided? | From XML at startup (static mode), same as today. |
+| Is there a background plan sync? | **No**. |
+
+### When dynamic mode is on
+
+| Question | Answer |
+|----------|--------|
+| Is the plan topic created? | **Yes** — on first startup that needs the registry. |
+| Where does every ingestor get the plan? | From `ranger_audit_partition_plan` (compacted topic), kept in memory on each pod. |
+| Can XML edits change live routing? | **No** (once a plan message exists in Kafka). Runtime changes go through REST. |
+
+### How “same partitions per plugin” is achieved on cutover
+
+Ingestor does **not** read Kafka to discover which plugin owns which partition. Kafka stores audit **records**, not plugin ownership.
+
+Preservation works because the **first published plan** uses the **same layout rules as static mode**:
+
+| Piece | Static today | Dynamic (first plan from XML) |
+|-------|--------------|-------------------------------|
+| Plugin order | `configured.plugins` list | Same list |
+| Partitions per plugin | Default + per-plugin overrides | Same |
+| Layout | Contiguous ranges (hdfs → 0–2, next → 3–5, … buffer tail) | Same ranges as explicit partition ID lists |
+| Within-plugin pick | Round-robin per plugin id | Same round-robin |
+| Unknown plugin | Hash into buffer | Same buffer pool |
+
+**What Kafka is used for at bootstrap:**
+
+| Step | Reads from | Purpose |
+|------|------------|---------|
+| Build first plan (empty registry) | **XML only** | Plugin list, overrides, buffer → partition lists |
+| Install plan (every pod) | **Kafka AdminClient** on `ranger_audits` | **Total** partition count only — must match `topicPartitionCount` in plan |
+| Route each audit | **In-memory plan** | No per-event Kafka read |
+
+**Brownfield (existing production cluster):** Auto-bootstrap from XML is safe only when **XML, ingestor startup logs, and `kafka-topics --describe ranger_audits` all agree**. If they differ, **pre-load the plan into Kafka before enabling dynamic** (operator publishes JSON to the plan topic while dynamic is still off).
+
+### Plan already in Kafka vs empty registry
+
+```mermaid
+sequenceDiagram
+  participant Pod as Ingestor pod
+  participant Plan as ranger_audit_partition_plan
+  participant Audits as ranger_audits
+  participant XML as site.xml
+
+  Pod->>Plan: create plan topic if missing (Race A)
+  Pod->>Plan: read plan for key ranger_audits
+  alt plan message exists
+    Plan-->>Pod: use stored plan — skip XML bootstrap
+  else registry empty
+    Pod->>XML: build first plan from XML layout
+    Pod->>Plan: re-read (Race B — peer may have published)
+    Pod->>Plan: publish first plan if still empty
+    Pod->>Plan: mandatory read-back
+  end
+  Pod->>Audits: describe topic — partition count
+  Pod->>Pod: validate count matches plan → load into memory
+```
+
+| Situation | What each pod does |
+|-----------|-------------------|
+| Plan **message** already in `ranger_audit_partition_plan` | Read and use it; **do not** publish a new plan from XML |
+| Plan topic exists but **no message** yet | One pod publishes the first plan; others re-read and adopt the same plan (**Race B**) |
+| Several pods create the plan **topic** at once | Idempotent create — **Race A**; “already exists” is success |
+
+**Bootstrap logic (summary):** read plan → if missing, build from XML → re-read → publish if still missing → mandatory read-back → validate partition count → install in memory.
+
+After the first plan is stored in Kafka, **Kafka is the source of truth** for routing.
+
+### Multi-pod race — is it implemented?
+
+| Race | Scenario | Resolution |
+|------|----------|------------|
+| **A** | Several pods create `ranger_audit_partition_plan` topic together | Idempotent topic create |
+| **B** | Several pods publish the **first** plan when registry is empty | Re-read before and after publish; all pods install the same plan from Kafka |
+
+**Your rule:** *If the plan topic exists but no plan message → add the plan; otherwise use the plan from the topic* — **Yes, implemented** via the bootstrap flow above.
+
+---
+
+## 5. How dynamic mode works (end-to-end)
+
+| Plane | Kafka topic | Traffic | Who reads/writes |
+|-------|-------------|---------|------------------|
+| **Data** | `ranger_audits` | High — every audit event | Plugins → ingestor → dispatchers |
+| **Control** | `ranger_audit_partition_plan` (compacted) | Low — rare plan changes | Admin REST + background sync on ingestor pods |
+
+The partition plan is **configuration**, not audit data. Ingestor keeps the current plan **in memory**; only the background sync thread and REST handlers touch the plan topic.
+
+### Architecture (control plane vs data plane)
+
+```mermaid
+flowchart TB
+  subgraph plugins [Ranger plugins]
+    PluginIn[HDFS / Hive / new plugins]
+  end
+
+  subgraph ops [Ops or automation]
+    Admin[Admin REST client]
+  end
+
+  subgraph ingestor [Each audit-ingestor pod]
+    REST[Partition-plan REST API]
+    Svc[Plan update service]
+    Watcher[Background plan sync]
+    Mem[(In-memory plan)]
+    Part[Partition router]
+    Queue[Audit queue]
+
+    REST --> Svc
+    Svc --> PlanTopic
+    Watcher -->|poll / consume| PlanTopic
+    Watcher -->|atomic swap| Mem
+    Mem --> Part
+    PluginIn -->|POST /access| Queue
+    Queue --> Part
+    Part -->|Kafka produce key=plugin id| AuditTopic
+  end
+
+  subgraph kafka [Kafka]
+    PlanTopic[(ranger_audit_partition_plan<br/>compacted, low volume)]
+    AuditTopic[(ranger_audits<br/>high volume)]
+  end
+
+  subgraph consumers [Downstream — unchanged]
+    Solr[Solr dispatcher]
+    HDFSdisp[HDFS dispatcher]
+  end
+
+  Admin -->|GET / PUT via load balancer| REST
+  Svc -->|createPartitions if needed| AuditTopic
+  AuditTopic --> Solr
+  AuditTopic --> HDFSdisp
+```
+
+### First startup — seeding the plan (once per cluster)
+
+When dynamic mode starts and the plan registry is **empty**:
+
+1. Ingestor enables dynamic mode.
+2. Background sync finds no plan in `ranger_audit_partition_plan`.
+3. Ingestor reads XML (`configured.plugins`, overrides, buffer).
+4. Ingestor builds and publishes the **first plan** to the compacted topic.
+5. Ingestor loads that plan into memory and begins routing audits.
+
+**After that:** additional pods and restarts **read Kafka only** — they do not re-build from XML.
+
+### Every audit — the hot path
+
+The plan topic is **not** read on this path.
+
+1. Plugin POSTs audit to ingestor.
+2. Partition router reads the **in-memory** plan.
+3. Known plugin → round-robin within its partition list.
+4. Unknown plugin → buffer partition.
+5. Record written to `ranger_audits`.
+
+### Changing the plan — admin or automation
+
+**On the pod that receives the REST call:**
+
+1. Read current plan from Kafka.
+2. Validate append-only rules.
+3. Grow `ranger_audits` tail if needed (Kafka AdminClient).
+4. Write new plan **version** to compacted topic.
+5. Return **200 OK** or **409 Conflict** (stale `expectedVersion`).
+
+**On every ingestor pod (~30s sync interval):**
+
+1. Background sync picks up new plan version.
+2. Validates against live `ranger_audits` partition count.
+3. Swaps plan in memory — **no restart**.
+
+```mermaid
+sequenceDiagram
+  participant Admin as Admin / automation
+  participant REST as Ingestor REST (one pod)
+  participant Plan as ranger_audit_partition_plan
+  participant Audit as ranger_audits
+  participant W as Background sync (each pod)
+  participant Mem as In-memory plan
+  participant Part as Partition router
+
+  Admin->>REST: promote / scale / PUT plan
+  REST->>Plan: read current plan version
+  REST->>Audit: createPartitions (if needed)
+  REST->>Plan: write new plan version
+  REST-->>Admin: 200 OK
+
+  loop Every ingestor pod
+    W->>Plan: poll latest plan
+    W->>Mem: atomic swap
+    Note over Part,Mem: Hot path reads memory only
+    Part->>Audit: produce audit (key = plugin id)
+  end
+```
+
+### Rules to remember
+
+- **Two topics, two jobs** — plan topic = config; audit topic = data.
+- **Memory on the hot path** — no per-audit read of the plan topic.
+- **Kafka is the source of truth** after the first plan is published.
+- **Append-only growth** — new partitions only at the tail of `ranger_audits`.
+- **All pods must agree** — every ingestor syncs from the same compacted topic.
+
+---
+
+## 6. Admin REST API (control plane)
+
+When dynamic mode is on, operators change routing through the **ingestor admin API** on **any** pod (usually via load balancer). Mutations are written to `ranger_audit_partition_plan`; every pod picks up changes through background sync (~30s).
+
+**Auth:** Kerberos or JWT (same ingestor admin pattern as other audit APIs). Dynamic mode off → all partition-plan calls return **503**.
+
+### Endpoints
+
+| Method | Path | Use when |
+|--------|------|----------|
+| `GET` | `/api/audit/partition-plan` | Read current plan (from in-memory copy on that pod) |
+| `PUT` | `/api/audit/partition-plan` | Replace the full plan (advanced / corrections) |
+| `POST` | `/api/audit/partition-plan/promote` | Give a **new** plugin dedicated partitions (from buffer) |
+| `POST` | `/api/audit/partition-plan/scale` | Add more partitions to a plugin **already** in the plan |
+
+Base URL example: `https://<ingestor-host>:7081/api/audit/partition-plan`
+
+### `expectedVersion` (all writes)
+
+Every `PUT` / `POST` must include the plan **version** you read from the last `GET`. If another admin changed the plan first, the server returns **409 Conflict** with the current plan — refresh and retry.
+
+### Common operations
+
+**Read plan**
+
+```http
+GET /api/audit/partition-plan
+→ 200 + JSON plan (note the "version" field)
+```
+
+**Promote** — e.g. onboard `trino` from buffer with 3 dedicated partitions:
+
+```json
+POST /api/audit/partition-plan/promote
+{
+  "pluginId": "trino",
+  "partitionCount": 3,
+  "expectedVersion": 4
+}
+```
+
+**Scale** — e.g. add 2 tail partitions to `hiveServer2`:
+
+```json
+POST /api/audit/partition-plan/scale
+{
+  "pluginId": "hiveServer2",
+  "additionalPartitions": 2,
+  "expectedVersion": 5
+}
+```
+
+Success → **200** + updated plan JSON (version incremented).  
+Invalid request (e.g. promote a plugin already dedicated) → **400**.  
+Stale version → **409** + current plan in body.
+
+### What happens inside one REST call
+
+```mermaid
+flowchart LR
+  Admin[Admin or script] --> REST[Ingestor REST]
+  REST --> Read[Read plan from Kafka]
+  Read --> Check{expectedVersion OK?}
+  Check -->|No| R409[409 + current plan]
+  Check -->|Yes| Valid[Validate append-only change]
+  Valid --> Grow{Need more audit partitions?}
+  Grow -->|Yes| Topic[Grow ranger_audits tail]
+  Grow -->|No| Write[Write new plan to Kafka]
+  Topic --> Write
+  Write --> OK[200 + new plan]
+  OK --> Sync[All pods sync within ~30s]
+```
+
+| Step | What the ingestor does |
+|------|------------------------|
+| 1 | Authenticate the caller |
+| 2 | Read current plan from `ranger_audit_partition_plan` |
+| 3 | Reject if `expectedVersion` does not match |
+| 4 | Compute new plugin lists (append-only — no reshuffling existing slots) |
+| 5 | If new partition IDs are needed → grow `ranger_audits` **first** |
+| 6 | Publish new plan version to Kafka |
+| 7 | Return updated plan JSON |
+
+**GET** is cheap (memory). **PUT / POST** always goes through Kafka so all pods converge on the same plan.
+
+---
+
+## 7. Operator workflow: onboarding a plugin
+
+### Stage 0 — Plugin appears (unknown)
+
+- Audits use **buffer** partitions.
+- Monitor volume per plugin id.
+
+### Stage 1 — Promote plugin
+
+- Call `POST /api/audit/partition-plan/promote` (see [§6](#6-admin-rest-api-control-plane)).
+- All ingestors apply within ~30s. **No restart** required.
+
+### Stage 2 — Scale a hot plugin
+
+- Call `POST /api/audit/partition-plan/scale`.
+- Dispatchers rebalance automatically when the audit topic grows.
+
+**Do not** edit `ranger-audit-ingestor-site.xml` on one pod for runtime changes. XML is only for **initial bootstrap** when the plan registry is empty.
+
+---
+
+## 8. Configuration (dynamic mode)
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled` | Turn dynamic mode on/off | `false` (default) = static XML |
+| `ranger.audit.ingestor.kafka.partition.plan.topic` | Compacted plan topic name | `ranger_audit_partition_plan` |
+| `ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms` | How often pods reload plan | `30000` |
+
+When dynamic is **off**, routing is fixed from XML at startup and the plan topic is not used.
+
+When dynamic is **on** and the registry is **empty**, the first ingestor pod seeds the plan from XML. Later pods and restarts read **Kafka only**.
+
+---
+
+## 9. FAQ
+
+### Basics
+
+**Why plugin-based partitioning?**  
+Hot plugins (HDFS, Hive) can get dedicated Kafka lanes so they do not starve others. Unknown plugins share a buffer until you promote them.
+
+**What is the difference between static and dynamic mode?**  
+Static: routing is computed once from XML at startup; changes need restart. Dynamic: routing lives in Kafka; admins change it via REST while ingestor keeps running.
+
+**Why not store the plan in Postgres or ZooKeeper?**  
+Ingestor already requires Kafka. A compacted plan topic adds no new infrastructure.
+
+**Why not edit XML on a running pod?**  
+Each pod has its own copy; edits are not shared, not durable, and are lost on restart. Runtime changes belong in the plan topic via REST.
+
+**Can I change routing by editing XML while dynamic mode is on?**  
+No for live routing. Ingestor uses the Kafka plan in memory, not XML edits on disk. Update XML only when preparing static rollback or documenting the intended layout.
+
+**Can I decrease `ranger_audits` partition count?**  
+No. Kafka does not support shrinking partitions. You can only add partitions at the tail.
+
+### Two topics and sync
+
+**What are the two Kafka topics?**  
+`ranger_audits` = audit data (high volume). `ranger_audit_partition_plan` = routing config (low volume, compacted).
+
+**Does every audit POST read the plan topic?**  
+No. Each audit uses the plan already in **memory** on that pod. Only background sync and REST mutations touch the plan topic.
+
+**How do all ingestor pods stay in sync?**  
+Every pod watches the same compacted plan topic (default every 30s) and swaps the new plan into memory.
+
+**What happens when a pod restarts?**  
+It reads the latest plan from Kafka (if dynamic is on). The plan survives in Kafka across crashes.
+
+**Do Solr and HDFS dispatchers need the partition plan?**  
+No. They consume **all** partitions of `ranger_audits`. Only ingestor uses the plan to **choose** which partition to write to.
+
+**Will changing the plan break consumers?**  
+Adding partitions triggers normal consumer rebalance. Existing plugin slots keep the same partition numbers if you follow append-only promote/scale rules.
+
+### Plan content and routing
+
+**What is the buffer?**  
+Partitions reserved for plugins that are not yet promoted (or newly seen plugin ids). Promote moves a plugin from buffer to dedicated slots.
+
+**What does append-only mean?**  
+When scaling, only **new** partition numbers at the end of `ranger_audits` are assigned. Existing plugins keep the same partition IDs in the same order.
+
+**How is a partition chosen inside a plugin’s list?**  
+Round-robin per plugin id — same behavior as static mode.
+
+**Where does an unknown plugin send audits?**  
+To the buffer partition pool (hash-based pick within buffer list in dynamic mode).
+
+### REST and concurrency
+
+**Do I need to restart ingestor after promote or scale?**  
+No. Background sync applies the new plan within about one refresh interval (~30s).
+
+**What is `expectedVersion`?**  
+The plan `version` you believe is current when you write. If someone else published first, your version is stale and you get **409**.
+
+**What should I do on HTTP 409?**  
+Another writer published a newer plan. Use the plan in the 409 response (or `GET` again), note the new `version`, and retry your change with that `expectedVersion`.
+
+**Why grow `ranger_audits` before publishing a new plan?**  
+The plan must not reference partition IDs that do not exist yet. The server grows the audit topic tail first, then writes the plan.
+
+**Why does promote return 400?**  
+Common cases: plugin already has dedicated partitions, invalid partition count, or plugin id missing. Scale returns 400 if the plugin is not in the plan yet (promote it first).
+
+**What do the HTTP status codes mean?**  
+**503** — dynamic mode is off, or the server could not grow `ranger_audits` (Kafka admin failure). **400** — validation failed (bad shape, append-only violation, `topicPartitionCount` ≠ Kafka). **409** — version conflict; retry with the plan body returned in the response.
+
+**Do dispatchers need reconfiguration after scale?**  
+No. Consumer groups rebalance automatically when partition count increases. Tune consumer threads only if you see sustained lag.
+
+### Cutover and bootstrap
+
+**When is `ranger_audit_partition_plan` created?**  
+Only when dynamic mode is enabled. With dynamic off, the topic is not created or used.
+
+**Does bootstrap read Kafka to learn plugin → partition mapping?**  
+No. The first plan is built from XML (same layout as static mode). Kafka is used for **total** partition count validation and as the durable registry.
+
+**Can I publish the plan to Kafka before enabling dynamic mode?**  
+Yes — recommended for brownfield clusters. Ingestor will read your pre-loaded plan and will not replace it with a fresh XML bootstrap.
+
+**Greenfield vs brownfield cutover — what is different?**  
+Greenfield: enable dynamic on an empty registry; first pod seeds from XML. Brownfield: export static layout, pre-seed the plan topic (or rely on bootstrap matching XML), then enable dynamic and verify every pod shows the same plan.
+
+**Does the `configured.plugins` XML list still matter in dynamic mode?**  
+Yes for **bootstrap only** when the registry is empty. After the first plan exists, runtime routing changes go through REST, not by editing that list.
+
+**How do I verify cutover succeeded?**  
+`GET /api/audit/partition-plan` on every pod (same `version`); plugin lists match your saved static logs; `topicPartitionCount` matches `kafka-topics --describe ranger_audits`.
+
+**How do I roll back to static mode?**  
+Export current plan via `GET`, align XML to that layout if needed, set `dynamic.enabled=false`, rolling restart. Plan topic remains but is ignored.
+
+**What if multiple pods start together with an empty registry?**  
+Race A: idempotent plan-topic create. Race B: re-read before/after first publish; all pods install the same plan. See [§4](#4-static--dynamic-cutover--direct-answers).
+
+### Troubleshooting
+
+**Ingestor fails startup after enabling dynamic — what now?**  
+Often Kafka unreachable or cannot create/read the plan topic. Fix Kafka connectivity; keep dynamic off until Kafka is healthy. With Kafka down at startup, ingestor should **not** come up healthy in dynamic mode.
+
+**Pods show different plan versions — what now?**  
+Wait one refresh interval after a change. If still mismatched, check plan topic readability and watcher logs on the lagging pod.
+
+**Does audit recovery / local spool behavior change?**  
+No. Per-pod spool and retry when Kafka is briefly unavailable works as today.
+
+**Does this replace producer throughput tuning?**  
+No. Batch size, linger, and compression are separate settings.
+
+**Who can call partition-plan REST?**  
+Authenticated admin callers on ingestor (Kerberos/JWT). Plugin audit POST users are a different path — they send audits, not plan changes.
+
+---
+
+## Docs
+
+| Doc | Purpose |
+|-----|---------|
+| [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) | Partition plan architecture |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | Partition-plan Kafka topic + REST |
+| [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) | Partition-plan implementation phases |
+| [README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md](README-DYNAMIC-SERVICE-ALLOWLIST-GUIDE.md) | **Service allowlist** operator guide (Surface 1 — orthogonal to partition routing) |
+| [README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md](README-DYNAMIC-SERVICE-ALLOWLIST-DESIGN.md) | Service allowlist design proposal |
+| [DESIGN-KAFKA-AUDIT-SERVER.md](DESIGN-KAFKA-AUDIT-SERVER.md) | End-to-end audit pipeline |
diff --git a/audit-server/README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md b/audit-server/README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md
new file mode 100644
index 000000000..eef9578f1
--- /dev/null
+++ b/audit-server/README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md
@@ -0,0 +1,345 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Brownfield migration — static XML to dynamic partition plan
+
+> **Consolidated design (start here for review):** [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) — see **§9 Brownfield migration** for simplified pre-flight, path decision diagram, and Q&A. This README is the full cutover worksheet and command examples.
+
+Cutover guide for clusters **already running** legacy static routing (`kafka.partition.plan.dynamic.enabled=false` or unset) with a live `ranger_audits` topic and production traffic.
+
+**Related docs:**
+
+| Doc | Use when |
+|-----|----------|
+| [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) | Consolidated design — §9 brownfield (simplified) |
+| [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) | Day-2 REST operations after cutover |
+| [README-KAFKA-PLUGIN-PARTITIONING.md](README-KAFKA-PLUGIN-PARTITIONING.md) | How static XML layout works today |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | Plan JSON schema + REST semantics |
+| [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) | Engineering phases |
+
+---
+
+## Goal
+
+Enable dynamic mode **without changing** which Kafka partition each plugin uses on cutover day. After migration, runtime changes use REST (see [ops runbook](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md)); XML is bootstrap-only when the plan topic is empty.
+
+---
+
+## When auto-bootstrap is safe vs not
+
+On first startup with `dynamic.enabled=true`, if `ranger_audit_partition_plan` has **no** message for your audit topic key, ingestor runs **Race B** bootstrap: it builds plan **v1** from current site XML (`PartitionPlanBootstrap` — same contiguous layout as static `AuditPartitioner` when only `configured.plugins`, per-plugin overrides, and `kafka.topic.partitions.buffer` drive allocation).
+
+| Cluster profile | Recommended path |
+|-----------------|------------------|
+| XML matches production; `ranger_audits` partition count = XML-calculated sum; no `kafka.topic.partitions` override | **Path B** — auto-bootstrap on enable |
+| Topic grown manually; overrides changed without XML update; `kafka.topic.partitions` set to a fixed total; any doubt about effective routing | **Path A** — pre-seed plan v1 in Kafka **before** rolling enable |
+| Auto-bootstrap ran but GET shows wrong ranges | **Path C** — `PUT` correction immediately (before wide rollout) |
+
+**Rule:** Treat **ingestor startup logs** and **`kafka-topics --describe`** as ground truth — not XML alone.
+
+---
+
+## Pre-flight audit (do this while still on static mode)
+
+### 1. Capture effective routing from a running ingestor
+
+At startup (static mode), ingestor logs an **AuditPartitioner Configuration** block with plugin ranges and buffer. Save this output from **each** replica (they should match).
+
+```bash
+# Example: grep recent ingestor log after restart
+grep -A30 'AuditPartitioner Configuration' /var/log/ranger/audit-ingestor.log
+```
+
+Record:
+
+- Each configured plugin → partition ID list (or start–end range)
+- Buffer partition range
+- Implied high-water partition ID (= `topicPartitionCount - 1`)
+
+### 2. Confirm actual Kafka topic size
+
+```bash
+kafka-topics.sh --bootstrap-server <broker:9092> \
+  --describe --topic ranger_audits
+```
+
+Note **PartitionCount**. It must equal `topicPartitionCount` in plan v1 (IDs `0 .. N-1`).
+
+### 3. Compare XML-calculated sum vs reality
+
+Relevant properties (prefix `ranger.audit.ingestor.`):
+
+| Property | Role |
+|----------|------|
+| `kafka.configured.plugins` | Ordered plugin list |
+| `kafka.topic.partitions.per.configured.plugin` | Default partitions per listed plugin |
+| `kafka.plugin.partition.overrides.<pluginId>` | Per-plugin override |
+| `kafka.topic.partitions.buffer` | Buffer size used by **bootstrap** |
+| `kafka.topic.partitions` | **Static-only** fixed total — can change effective buffer |
+
+**Bootstrap formula** (when no `kafka.topic.partitions` involvement):
+
+```
+topicPartitionCount = sum(per-plugin counts) + kafka.topic.partitions.buffer
+```
+
+**Static partitioner** when `kafka.topic.partitions` **is** set:
+
+```
+buffer = max(1, kafka.topic.partitions - sum(per-plugin counts))
+```
+
+If your cluster uses `kafka.topic.partitions` as a fixed cap, bootstrap from XML **will not** reproduce static routing unless you align or remove that property before cutover. Prefer **Path A** using log-exported ranges.
+
+### 4. Drift checklist
+
+| Check | Pass criteria |
+|-------|---------------|
+| Log ranges vs XML | Same partition IDs per plugin |
+| `describe` partition count vs log | Equal |
+| All ingestor replicas | Same layout in logs |
+| Solr/HDFS dispatchers | Consuming all `ranger_audits` partitions (no custom partition filter) |
+| Kafka ACLs | Ingestor can CREATE/WRITE plan topic + ALTER `ranger_audits` (same as today for topic growth) |
+
+---
+
+## Build plan v1 JSON
+
+Plan v1 must:
+
+- Set `"version": 1`
+- Set `"topic": "ranger_audits"` (or your audit topic name)
+- Set `"topicPartitionCount"` = actual Kafka partition count
+- List **every** partition ID `0 .. N-1` exactly once across `plugins` + `buffer`
+- Use contiguous plugin lists matching production (order in `plugins` map should follow `configured.plugins` order for human readability; routing uses explicit lists)
+
+**Example** — `hdfs` + `hiveServer2`, 3 each, buffer 9, topic **15** partitions (matches `PartitionPlanBootstrapTest`):
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 1,
+  "topicPartitionCount": 15,
+  "updatedAt": "2026-06-09T12:00:00Z",
+  "updatedBy": "brownfield-migration",
+  "plugins": {
+    "hdfs": { "partitions": [0, 1, 2] },
+    "hiveServer2": { "partitions": [3, 4, 5] }
+  },
+  "buffer": { "partitions": [6, 7, 8, 9, 10, 11, 12, 13, 14] }
+}
+```
+
+**Worksheet** (fill from logs):
+
+| Plugin / pool | Partition IDs | Count |
+|---------------|---------------|-------|
+| hdfs | 0–2 | 3 |
+| hiveServer2 | 3–5 | 3 |
+| buffer | 6–14 | 9 |
+| **Total** | **0–14** | **15** |
+
+For hot layouts with overrides (e.g. hdfs=4, hiveServer2=6, trino=9, buffer=9 → 28 partitions), transcribe exact lists from logs — do not re-derive from stale XML.
+
+---
+
+## Migration paths
+
+### Path A — Pre-seed Kafka (recommended for brownfield)
+
+Use when production layout may differ from XML bootstrap.
+
+| Step | Action |
+|------|--------|
+| 1 | Complete [pre-flight audit](#pre-flight-audit-do-this-while-still-on-static-mode) |
+| 2 | Build v1 JSON (above) |
+| 3 | Create plan topic if missing (or let first pod create it — 1 partition, compacted, `cleanup.policy=compact`) |
+| 4 | Publish v1 **while dynamic mode is still off** via Kafka producer |
+
+```bash
+# Key MUST be the audit topic name (default: ranger_audits)
+PLAN_JSON='{"topic":"ranger_audits","version":1,...}'
+
+kafka-console-producer.sh --bootstrap-server <broker:9092> \
+  --topic ranger_audit_partition_plan \
+  --property parse.key=true \
+  --property key.separator=: \
+  <<< "ranger_audits:${PLAN_JSON}"
+```
+
+| 5 | Verify compacted value (optional) |
+
+```bash
+kafka-console-consumer.sh --bootstrap-server <broker:9092> \
+  --topic ranger_audit_partition_plan \
+  --from-beginning --max-messages 10 \
+  --property print.key=true
+```
+
+| 6 | Set `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=true` on **all** ingestor replicas |
+| 7 | **Rolling restart** (one pod at a time). Each pod reads seeded v1 — **no** Race B bootstrap |
+| 8 | [Verify cutover](#post-cutover-verification) |
+
+**Why pre-seed while dynamic is off:** REST `PUT` requires `dynamic.enabled=true` and an existing plan in Kafka (`expectedVersion` must match current). Seeding via Kafka avoids a bootstrap race on multi-replica rollout.
+
+---
+
+### Path B — Auto-bootstrap on enable
+
+Use only when pre-flight confirms XML layout == logs == `describe` partition count.
+
+| Step | Action |
+|------|--------|
+| 1 | Ensure `ranger_audit_partition_plan` does **not** already contain a plan for your audit topic |
+| 2 | Align XML: correct `configured.plugins`, overrides, `kafka.topic.partitions.buffer`; remove or reconcile `kafka.topic.partitions` if it distorts buffer |
+| 3 | Enable `dynamic.enabled=true` + rolling restart |
+| 4 | First pod to win Race B writes v1 from XML; peers read it |
+| 5 | `GET /api/audit/partition-plan` on each pod — compare to saved static log ranges |
+| 6 | If mismatch → stop rollout → [Path C](#path-c--correct-after-bootstrap) or rollback |
+
+**Tip:** Scale to **one** ingestor replica for the first enable window to make bootstrap deterministic, verify `GET`, then scale back up.
+
+---
+
+### Path C — Correct after bootstrap
+
+Use when dynamic is already on but v1 is wrong (or you enabled Path B and caught drift early).
+
+| Step | Action |
+|------|--------|
+| 1 | `GET /api/audit/partition-plan` → note `version` (usually `1`) |
+| 2 | Build corrected full plan body with same plugin/buffer lists but `topicPartitionCount` matching Kafka |
+| 3 | `PUT` with `expectedVersion` = current version |
+
+```bash
+curl -s -u admin:password -X PUT \
+  -H 'Content-Type: application/json' \
+  "https://audit-ingestor:7182/api/audit/partition-plan" \
+  -d '{
+    "expectedVersion": 1,
+    "topicPartitionCount": 28,
+    "plugins": {
+      "hdfs": { "partitions": [0, 1, 2, 3] },
+      "hiveServer2": { "partitions": [4, 5, 6, 7, 8, 9] },
+      "trino": { "partitions": [10, 11, 12, 13, 14, 15, 16, 17, 18] }
+    },
+    "buffer": { "partitions": [19, 20, 21, 22, 23, 24, 25, 26, 27] }
+  }' | jq .
+```
+
+**Constraints:** `PUT` must satisfy append-only rules relative to current plan. Replacing v1 entirely is allowed when correcting a fresh bootstrap — keep lists identical to production intent. Handler grows `ranger_audits` if `topicPartitionCount` increases.
+
+Pause further replica restarts until all pods show the corrected version (≤ refresh interval, default 30s).
+
+---
+
+## Post-cutover verification
+
+| # | Check | How |
+|---|-------|-----|
+| 1 | Same plan version on all pods | `GET /api/audit/partition-plan` from each ingestor URL |
+| 2 | Plan matches pre-cutover logs | Compare plugin/buffer lists to saved static log block |
+| 3 | `topicPartitionCount` matches Kafka | `kafka-topics --describe` |
+| 4 | Routing unchanged | Produce test audit per major plugin; confirm partition in ingestor debug/metrics |
+| 5 | Dispatchers healthy | Solr/HDFS consumer lag normal; rebalance only if partition count grew |
+| 6 | Watcher active | Log line: partition plan version loaded / refreshed |
+
+```bash
+# Compare versions across pods
+for host in ingestor-1 ingestor-2 ingestor-3; do
+  echo -n "$host: "
+  curl -s -u admin:password "https://${host}:7182/api/audit/partition-plan" | jq -r .version
+done
+```
+
+---
+
+## Rollback to static mode
+
+| Step | Action |
+|------|--------|
+| 1 | **Before disabling:** update site XML so static layout would reproduce **current** effective routing (plugins, overrides, buffer or `kafka.topic.partitions` as you used historically) |
+| 2 | Set `kafka.partition.plan.dynamic.enabled=false` |
+| 3 | Rolling restart all ingestor pods |
+| 4 | Confirm startup logs show static AuditPartitioner ranges matching pre-migration logs |
+| 5 | Plan topic in Kafka is harmless leftover; not read when disabled |
+
+**Risk:** If XML does not match the plan you ran under dynamic mode, rollback reshuffles plugin traffic to different partitions — usually acceptable for audits but causes temporary dispatcher skew. Export plan JSON via `GET` before rollback and align XML to it.
+
+---
+
+## Post-migration XML hygiene
+
+After successful cutover:
+
+- Keep `configured.plugins` and overrides as **documentation** of the initial layout (used only if plan topic is wiped and bootstrap runs again).
+- Do **not** expect XML edits to change live routing while dynamic is on.
+- Optional: add a comment in site XML pointing to [ops runbook](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) for promote/scale.
+- Record plan `version` and export JSON in your change ticket.
+
+---
+
+## Common failure scenarios
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Plugin audits land on wrong partition after enable | Bootstrap ≠ production | Path C `PUT` or rollback + Path A pre-seed |
+| `topicPartitionCount` < Kafka `PartitionCount` | Plan JSON too small | Increase in `PUT`; IDs must cover all used partitions |
+| `topicPartitionCount` > Kafka count | Topic not grown | REST handler grows on mutate; or grow topic manually before seed |
+| Pods show different versions | Rolling restart mid-`PUT` | Wait 30s; `GET` each pod; retry mutation with fresh `expectedVersion` |
+| Ingestor startup fails | Kafka/ACL unreachable with dynamic on | Fix connectivity; keep dynamic off until Kafka healthy |
+| `PUT` returns 400 | Overlapping/missing partition IDs | Rebuild JSON — every ID 0..N-1 exactly once |
+| `PUT` returns 409 | Stale `expectedVersion` | `GET` and retry ([runbook](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md#handle-http-409-version-conflict)) |
+
+---
+
+## End-to-end timeline (Path A — typical brownfield)
+
+```mermaid
+flowchart TD
+  Static[Static mode production traffic] --> Audit[Pre-flight: logs + describe + worksheet]
+  Audit --> JSON[Build plan v1 JSON]
+  JSON --> Seed[Pre-seed ranger_audit_partition_plan]
+  Seed --> Enable[Enable dynamic.enabled=true]
+  Enable --> Roll[Rolling restart all pods]
+  Roll --> Verify[GET + spot-check audits]
+  Verify --> Ops[Day-2: REST promote/scale per runbook]
+```
+
+---
+
+## Quick decision tree
+
+```
+Is XML + describe + ingestor log layout identical?
+├── YES → Path B (auto-bootstrap), verify GET after first pod
+└── NO  → Path A (pre-seed Kafka), then enable + rolling restart
+
+After enable, does GET match saved static logs?
+├── YES → Done
+└── NO  → Path C PUT correct (pause rollout) or rollback
+```
+
+---
+
+## Related implementation notes
+
+- Bootstrap code: `PartitionPlanBootstrap.createInitialPlan*` — must match static contiguous allocation when only standard properties apply.
+- Race B: `PartitionPlanBootstrapSupport.bootstrapPlanIfEmpty` — skipped when plan topic already has a value for the audit topic key.
+- REST mutations require `dynamic.enabled=true`; initial seed for brownfield is via Kafka producer or bootstrap, not `PUT` on an empty registry.
diff --git a/audit-server/README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md b/audit-server/README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md
new file mode 100644
index 000000000..4016fa745
--- /dev/null
+++ b/audit-server/README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md
@@ -0,0 +1,216 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic partition plan — E2E test plan
+
+End-to-end validation for **Phases 1–5 and 8** (dynamic Kafka partition plan). Phase 6 (admin allow-list + `/status` metadata) is **deferred**.
+
+**Automated subset:** [dev-support/ranger-docker/scripts/audit/verify-partition-plan-e2e.sh](../dev-support/ranger-docker/scripts/audit/verify-partition-plan-e2e.sh)
+
+**Related:**
+
+| Doc | Use |
+|-----|-----|
+| [README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md](README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md) | **What was tested** — plain-language validation report (start here if you do not have the codebase) |
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Static→dynamic preservation, bootstrap, multi-pod races (§3.1) |
+| [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) | REST operations |
+| [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) | Cutover scenarios |
+| [dev-support/RANGER-AUDIT-TIER3-VALIDATION-PLAN.md](../dev-support/RANGER-AUDIT-TIER3-VALIDATION-PLAN.md) | Full audit pipeline |
+| [.cursor/skills/ranger-audit-tier3-e2e/SKILL.md](../.cursor/skills/ranger-audit-tier3-e2e/SKILL.md) | Docker bring-up |
+
+---
+
+## 1. Scope
+
+| In scope | Out of scope |
+|----------|--------------|
+| Plan topic, watcher, partitioner, REST API | Phase 6 plugin-user **403** on partition-plan |
+| Multi-ingestor consistency (manual / 2nd replica) | Shrinking `ranger_audits` partitions |
+| Audit pipeline after promote/scale | Admin `audit_store=db` |
+
+---
+
+## 2. Environments
+
+| Layer | Command / stack |
+|-------|-----------------|
+| **Unit** | `mvn test -pl audit-server/audit-ingestor -Dtest=PartitionPlan*Test,AuditPartitionerDynamicTest -Drat.skip=true` |
+| **Tier 3 Docker** | `./dev-support/ranger-docker/setup-audit-e2e.sh up` or `audit-stack.sh up --tier 3` |
+| **Partition plan E2E** | `./scripts/audit/verify-partition-plan-e2e.sh` (from `ranger-docker/`) |
+
+**Pre-flight (every E2E run):**
+
+1. Tier 3 healthy: `./scripts/audit/wait-for-audit-health.sh --tier 3`
+2. Baseline audit path (optional): `./scripts/audit/verify-audit-tier3-e2e.sh`
+3. Record: `kafka-topics --describe ranger_audits`; ingestor `AuditPartitioner Configuration` log
+
+---
+
+## 3. Automated scripts
+
+| Script | Covers |
+|--------|--------|
+| `verify-partition-plan-e2e.sh` | POS-A*, POS-C*, NEG-1–8 (core REST) |
+| `verify-partition-plan-multipod-e2e.sh` | POS-D1 (replica on :7082, watcher convergence) |
+| `verify-partition-plan-brownfield-e2e.sh` | POS-F1, POS-F2 (pre-seed + rollback) |
+| `verify-partition-plan-kafka-down-e2e.sh` | NEG-9 (startup with Kafka down) |
+| `verify-partition-plan-e2e-all.sh` | Runs all of the above |
+
+```bash
+cd dev-support/ranger-docker
+chmod +x scripts/audit/verify-partition-plan-*.sh
+
+# Full suite (recommended after Tier 3 is up)
+./scripts/audit/verify-partition-plan-e2e-all.sh
+
+# Or run individually:
+./scripts/audit/verify-partition-plan-e2e.sh --static-only
+./scripts/audit/verify-partition-plan-e2e.sh --dynamic --restore-static
+./scripts/audit/verify-partition-plan-multipod-e2e.sh
+./scripts/audit/verify-partition-plan-brownfield-e2e.sh --restore-static
+./scripts/audit/verify-partition-plan-kafka-down-e2e.sh
+
+# With audit pipeline smoke after REST mutations
+./scripts/audit/verify-partition-plan-e2e-all.sh --with-audit-smoke
+```
+
+---
+
+## 4. Positive scenarios
+
+### A. Static mode regression
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| POS-A1 | `dynamic.enabled` false / absent | No `PartitionPlanWatcher` in logs |
+| POS-A2 | `GET /api/audit/partition-plan` | **503** feature disabled |
+| POS-A3 | `GET /api/audit/health` | **200** |
+| POS-A4 | HDFS plugin audits | Solr count increases (Tier 3 smoke) |
+
+### B. Greenfield dynamic enable
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| POS-B1 | Enable `dynamic.enabled=true`; restart | Ingestor starts; watcher ready |
+| POS-B2 | Empty plan topic → Race B | v1 in `ranger_audit_partition_plan` |
+| POS-B3 | `GET /partition-plan` | JSON v1; `topicPartitionCount` matches `describe` |
+| POS-B4 | Ingestor log | `Mode=dynamic`, plan version shown |
+| POS-B5 | HDFS audits after enable | Pipeline still OK |
+
+### C. REST (no ingestor restart)
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| POS-C1 | `POST .../promote` new plugin (e.g. `storm`) | **200**; version+1; plugin in `plugins` |
+| POS-C2 | `POST .../scale` existing plugin | **200**; tail IDs appended; topic grown if needed |
+| POS-C3 | `PUT` full plan + valid `expectedVersion` | **200** |
+| POS-C4 | Wait ≤ refresh interval | Same plan on repeated `GET` without restart |
+| POS-C5 | 409 retry | Re-`GET` version; retry succeeds |
+
+### D. Multi-pod
+
+| ID | Scenario | Expected | Script |
+|----|----------|----------|--------|
+| POS-D1 | `GET` from 2 ingestor pods | Same `version` within 30s after promote | `verify-partition-plan-multipod-e2e.sh` |
+| POS-D2 | Parallel cold start on empty plan topic | Single v1; both pods aligned | Manual (scale 2 replicas on empty topic) |
+
+### E. Audit pipeline
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| POS-E1 | HDFS audits after promote/scale | Solr + HDFS dispatchers healthy |
+| POS-E2 | Dispatcher rebalance after scale | Consumer groups rebalance; no sustained lag |
+
+### F. Brownfield
+
+| ID | Scenario | Expected | Script |
+|----|----------|----------|--------|
+| POS-F1 | Pre-seed v1 in Kafka; then enable | `updatedBy` preserved; no XML bootstrap | `verify-partition-plan-brownfield-e2e.sh` |
+| POS-F2 | Rollback to static | **503** on partition-plan API | `--restore-static` on brownfield script |
+
+---
+
+## 5. Negative scenarios
+
+### REST / validation
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| NEG-1 | Partition-plan API with feature off | **503** |
+| NEG-2 | Unauthenticated `GET` partition-plan | **401** |
+| NEG-3 | Stale `expectedVersion` | **409** + current plan body |
+| NEG-4 | Promote plugin already in plan (e.g. `hdfs`) | **400** |
+| NEG-5 | Scale plugin only in buffer | **400** |
+| NEG-6 | `PUT` reshuffles existing plugin IDs | **400** |
+| NEG-7 | Invalid / overlapping partition lists | **400** |
+| NEG-8 | `partitionCount: 0` | **400** |
+
+### Infrastructure
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| NEG-9 | Kafka down at startup with dynamic on | Health fail or plan error in logs | `verify-partition-plan-kafka-down-e2e.sh` |
+| NEG-10 | Cannot ALTER `ranger_audits` | Scale/promote needing growth → **503** |
+| NEG-11 | Corrupt JSON on plan topic | Watcher ignores; last good plan kept |
+
+### Concurrency
+
+| ID | Scenario | Expected |
+|----|----------|----------|
+| NEG-12 | Two promotes same `expectedVersion` | One **200**, one **409** |
+
+### Deferred (Phase 6)
+
+| ID | Scenario | When Phase 6 lands |
+|----|----------|-------------------|
+| NEG-13 | Plugin service user calls partition-plan | **403** |
+| NEG-14 | `/status` includes `partitionPlan` block | JSON metadata present |
+
+---
+
+## 6. Release gate
+
+| Gate | Criteria |
+|------|----------|
+| G1 | All unit tests pass |
+| G2 | `verify-partition-plan-e2e.sh --static-only` pass |
+| G3 | `verify-partition-plan-e2e.sh --dynamic` pass on Tier 3 |
+| G4 | `verify-audit-tier3-e2e.sh` pass after dynamic promote |
+| G5 | Manual POS-D1 if multi-ingestor available |
+
+---
+
+## 7. Suggested execution order
+
+```text
+Unit tests → Tier 3 up → static-only script → enable dynamic → dynamic script
+  → optional verify-audit-tier3-e2e → optional brownfield / rollback
+```
+
+---
+
+## 8. Test layouts (XML)
+
+| Layout | `configured.plugins` | Buffer | Total partitions |
+|--------|---------------------|--------|------------------|
+| L1 minimal | `hdfs` | 3 | 6 |
+| L2 standard (site XML default) | `hdfs,yarn,knox,hiveServer2,hiveMetastore,kafka,hbaseRegional,hbaseMaster,solr,trino,ozone,kudu,nifi` (13 plugins) | 9 | **48** (13×3+9) |
+| L3 hot | + per-plugin overrides | 9 | varies |
+
+Shipped `ranger-audit-ingestor-site.xml` uses **L2** — do not shorten the plugin list for E2E. Automated promote uses a **buffer** plugin such as **`storm`** (not in `configured.plugins`).
diff --git a/audit-server/README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md b/audit-server/README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md
new file mode 100644
index 000000000..53964f5ee
--- /dev/null
+++ b/audit-server/README-KAFKA-PARTITION-PLAN-E2E-VALIDATION.md
@@ -0,0 +1,223 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic partition plan — what we validated (plain-language report)
+
+This document explains **what was tested and what passed**, for people who do not have the Ranger source tree open. It is a validation report, not a runbook.
+
+**Want the product story first?** Read [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) §3.1 (static → dynamic cutover).
+
+---
+
+## In 60 seconds
+
+Ranger audit-ingestor can route each plugin’s audits to specific Kafka partitions. **Dynamic mode** stores that routing map in Kafka so you can change it at runtime (promote a new plugin, add partitions) **without restarting** ingestor.
+
+We validated on a **full test lab** (Docker, Kerberos, Kafka, Solr, HDFS, Hadoop):
+
+| Area | Plain question | Answer |
+|------|----------------|--------|
+| **Off by default** | Does old behavior still work when dynamic mode is off? | **Yes** — health OK; admin partition API returns “not enabled”. |
+| **Turn dynamic on** | Does first startup build a correct routing map? | **Yes** — 13 plugins, 48 partitions, matches Kafka. |
+| **Change routing live** | Can an admin promote/scale via REST without restart? | **Yes** — version bumps; bad requests rejected (409/400). |
+| **Several ingestors** | Do two ingestor pods see the same map after a change? | **Yes** — second pod catches up within ~35 seconds. |
+| **Existing clusters** | If we pre-load the map in Kafka before cutover, is it respected? | **Yes** — ingestor does not overwrite it from XML. |
+| **Kafka down** | If Kafka is down at startup with dynamic on, do we fail safely? | **Yes** — ingestor does not come up healthy; logs show Kafka/plan errors. |
+
+**Overall: 31 end-to-end checks — all passed.**
+
+---
+
+## Words you will see in the tables
+
+| Term | Meaning (no code required) |
+|------|----------------------------|
+| **Ingestor** | Ranger service that receives audits from plugins and writes them to Kafka. |
+| **Plugin** | Source of audits (e.g. HDFS, Hive). Identified by a short name like `hdfs`, `storm`. |
+| **Partition** | A numbered “lane” inside the Kafka topic `ranger_audits`. More lanes = more parallel consumption. |
+| **Partition plan** | A JSON document: which plugin may use which partition numbers, plus a **buffer** pool for unknown plugins. |
+| **Plan topic** | Kafka topic `ranger_audit_partition_plan` — durable copy of the plan all ingestors read. |
+| **Dynamic mode** | Feature on when `kafka.partition.plan.dynamic.enabled=true`. Live routing comes from the plan topic, not from editing XML on disk. |
+| **Static mode** | Default. Routing fixed at startup from XML config. Plan topic is not used. |
+| **Buffer** | Shared partitions for plugins that do not have dedicated slots yet (e.g. a new `storm` plugin). |
+| **Promote** | Admin action: move a plugin from buffer to its own dedicated partitions. |
+| **Scale** | Admin action: add more partitions to a plugin that already has dedicated slots. |
+| **Version** | Integer on the plan; every successful change increments it (like optimistic locking). |
+| **expectedVersion** | Client sends “I think the plan is version N”; server rejects with **409** if someone else already published N+1. |
+| **Watcher** | Background process on each ingestor that reloads the plan from Kafka every ~30 seconds. |
+| **Greenfield** | Brand-new setup: empty plan topic, first ingestor creates version 1 from XML layout. |
+| **Brownfield / pre-seed** | Existing cluster: operator writes version 1 into Kafka **before** enabling dynamic mode so cutover does not guess wrong. |
+
+---
+
+## Where testing happened
+
+| Item | Detail |
+|------|--------|
+| **Environment** | Ranger audit “Tier 3” lab stack in Docker (Kerberos, ZooKeeper, Kafka, Solr + HDFS dispatchers, Hadoop, Ranger Admin). |
+| **Main ingestor** | Port **7081**. |
+| **Second ingestor** (multi-pod only) | Port **7082**, separate hostname and Kerberos identity. |
+| **Audit Kafka topic** | `ranger_audits` — actual audit events. |
+| **Plan Kafka topic** | `ranger_audit_partition_plan` — routing configuration only. |
+| **Standard plugin layout** | 13 plugins in config, 3 partitions each, plus 9 buffer partitions → **48** partitions total on a clean topic. |
+
+Before each block of tests, the lab was checked: Admin UI up, ingestor health up, Solr/HDFS path healthy.
+
+---
+
+## 1. Static mode still works (2 checks)
+
+**Situation:** Dynamic feature is **off** (normal default for existing deployments).
+
+| # | Scenario | What we did | Success means | Result |
+|---|----------|-------------|---------------|--------|
+| 1 | Admin API disabled | Called read partition-plan API | Response **503** — feature not enabled | **Pass** |
+| 2 | Audits still served | Called ingestor health API | Response **200** — service healthy | **Pass** |
+
+**Takeaway:** Turning the feature off does not break the ingestor. The partition-plan admin API is simply unavailable.
+
+---
+
+## 2. Enabling dynamic mode on a clean cluster (6 checks)
+
+**Situation:** Fresh plan topic (no prior routing map). Audit topic reset to **48** partitions to match config. Dynamic mode turned **on**, ingestor restarted.
+
+| # | Scenario | What we did | Success means | Result |
+|---|----------|-------------|---------------|--------|
+| 1 | Service starts | Wait for ingestor to finish startup | Healthy; background sync reports “plan ready” | **Pass** |
+| 2 | First plan published | Inspect Kafka plan topic | Topic exists; plan **version 1** (or higher) stored | **Pass** |
+| 3 | Correct plugin list | Read plan via admin API | **13** configured plugins listed (hdfs, yarn, hive, … per site config) | **Pass** |
+| 4 | Partition count honest | Compare plan’s total vs Kafka topic size | Numbers **match** (48 on clean run) | **Pass** |
+| 5 | Plan topic created | List Kafka topics | `ranger_audit_partition_plan` present | **Pass** |
+
+---
+
+## 3. Changing the plan without restart (6 checks)
+
+**Situation:** Dynamic mode on; plan already loaded. Changes made only through the **admin REST API** (authenticated).
+
+| # | Scenario | What we did | Success means | Result |
+|---|----------|-------------|---------------|--------|
+| 1 | Onboard new plugin | **Promote** a plugin that only used buffer (e.g. `storm`) — give it 2 dedicated partitions | **200 OK**; version increases; plugin appears in plan | **Pass** |
+| 2 | Stale edit rejected | Promote again but claim plan is still **version 1** (wrong) | **409 Conflict** — forces admin to refresh | **Pass** |
+| 3 | No double-promote | Try to promote **hdfs** (already has dedicated partitions) | **400 Bad Request** | **Pass** |
+| 4 | Grow hot plugin | **Scale** the newly promoted plugin (+1 partition) | **200 OK**; version increases again | **Pass** |
+| 5 | Plan stays in memory | Read plan again **without** restarting ingestor | Same version as last change; data consistent | **Pass** |
+
+**Takeaway:** Operators can change routing live. The API blocks obvious mistakes (stale version, promoting twice).
+
+---
+
+## 4. Two ingestor pods stay in sync (7 checks)
+
+**Situation:** Primary ingestor on 7081 (dynamic on). Second ingestor started on 7082 with its own Kerberos identity but the **same** Kafka plan topic.
+
+| # | Scenario | What we did | Success means | Result |
+|---|----------|-------------|---------------|--------|
+| 1 | Second pod starts | Bring up replica ingestor | Replica healthy; plan sync ready | **Pass** |
+| 2 | Same map at start | Read plan version on **both** pods | **Identical version number** | **Pass** |
+| 3 | Change on one pod only | **Promote** a buffer plugin on **primary only** | Primary returns new version | **Pass** |
+| 4 | Other pod catches up | Wait up to **35 seconds** (one sync cycle) | Replica shows **same new version** without anyone calling API on replica | **Pass** |
+| 5 | Primary unchanged | Read plan on primary again | Still on new version (no drift) | **Pass** |
+
+**Takeaway:** In a real cluster with multiple ingestors behind a load balancer, a routing change on any pod propagates to all pods automatically.
+
+---
+
+## 5. Brownfield cutover — pre-load plan in Kafka (8 checks)
+
+**Situation:** Mimics a **production cluster** moving from static to dynamic. Operator puts the routing map into Kafka **first**, then enables dynamic mode — ingestor must **not** replace it with a fresh guess from XML.
+
+| Step | Scenario | What we did | Success means | Result |
+|------|----------|-------------|---------------|--------|
+| 1 | Save real layout | Read current plan while dynamic is briefly on | Valid JSON captured | **Pass** |
+| 2 | Simulate “still on static” | Turn dynamic off; delete plan topic | Ingestor healthy; plan topic gone | **Pass** |
+| 3 | Operator pre-seed | Write plan to Kafka with marker `updatedBy=brownfield-e2e-seed`, version **1** | Message on plan topic | **Pass** |
+| 4 | Enable dynamic | Turn dynamic on; restart ingestor | Plan still shows **brownfield-e2e-seed** (not auto-`bootstrap`) | **Pass** |
+| 5 | Version respected | Read plan | **version = 1** | **Pass** |
+| 6 | Kafka alignment | Compare plan total partitions vs `ranger_audits` | **Match** | **Pass** |
+| 7 | Rollback API | Turn dynamic off again | Partition-plan API returns **503** | **Pass** |
+| 8 | Rollback health | Health check | **200** — audits path still OK in static mode | **Pass** |
+
+**Takeaway:** Pre-seeding (Path A in the migration guide) works. Rollback to static mode is safe.
+
+---
+
+## 6. Kafka unavailable when dynamic starts (3 checks)
+
+**Situation:** Dynamic mode enabled in config, but **Kafka broker stopped**, then ingestor restarted. This must **not** silently pretend everything is fine.
+
+| # | Scenario | What we did | Success means | Result |
+|---|----------|-------------|---------------|--------|
+| 1 | Unhealthy startup | Restart ingestor with Kafka down | Health endpoint **not** OK | **Pass** |
+| 2 | Clear failure in logs | Read ingestor logs from that restart | Errors mention Kafka connection failure and/or inability to start plan sync | **Pass** |
+| 3 | Recovery | Start Kafka; disable dynamic; restart ingestor | Health **200** in static mode | **Pass** |
+
+**Takeaway:** Dynamic mode depends on Kafka at startup. Fix Kafka (or leave dynamic off) before expecting a healthy ingestor.
+
+---
+
+## 7. Automated unit tests (companion, not Tier 3 Docker)
+
+These run in CI / developer machines — no full cluster. They prove individual pieces before the lab tests above.
+
+| Area | What was proven |
+|------|-----------------|
+| **First-time plan layout** | Version 1 from XML matches the same partition ranges static mode would use. |
+| **Multi-pod race (logic)** | If two startups see an empty plan topic, only one writes; the other adopts the winner’s plan. |
+| **Plan JSON** | Serialize/deserialize; reject garbage input. |
+| **Validation rules** | No duplicate partition IDs; total must match Kafka; changes cannot reshuffle existing plugin slots (append-only). |
+| **Promote / scale math** | Buffer → dedicated; grow topic tail when needed; reject illegal promote/scale. |
+| **REST service** | Feature flag; reads from memory; **409** when two writers conflict. |
+| **Audit routing** | With dynamic on, partitioner uses in-memory plan; unknown plugins → buffer. |
+
+---
+
+## 8. Not tested in this pass
+
+| Topic | Why |
+|-------|-----|
+| Two pods starting **at the same time** on an empty plan topic | Needs choreographed parallel rollout; logic covered in unit tests |
+| End-to-end “HDFS audit → Solr” after every promote | Optional smoke; lab path validated separately |
+| Admin **403** for non-admin users | Planned for a later phase |
+| Shrinking Kafka partition count | Not supported by Kafka |
+
+---
+
+## 9. Quick reference — numbers used in the lab
+
+| Setting | Value |
+|---------|--------|
+| Configured plugins (13) | hdfs, yarn, knox, hiveServer2, hiveMetastore, kafka, hbaseRegional, hbaseMaster, solr, trino, ozone, kudu, nifi |
+| Partitions per configured plugin | 3 |
+| Buffer partitions | 9 |
+| **Total on clean topic** | **48** |
+| Plan sync interval | 30 seconds (default) |
+| Promote examples in tests | Plugins **not** in the list above (e.g. storm, ambari, impala) |
+
+---
+
+## Related documents
+
+| Document | Audience |
+|----------|----------|
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Everyone — concepts and diagrams |
+| [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) | Operators cutting over live clusters |
+| [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) | Day-2 promote/scale procedures |
+| [README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md](README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md) | QA — full scenario catalog with IDs (POS-*, NEG-*) |
diff --git a/audit-server/README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md b/audit-server/README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md
new file mode 100644
index 000000000..117e4ac66
--- /dev/null
+++ b/audit-server/README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md
@@ -0,0 +1,461 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic partition plan — phased implementation guide
+
+> **Consolidated design (start here for review):** [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) — architecture, flows, diagrams, and Q&A (no code-level detail). This README is the phased engineering implementation plan.
+
+This document is the **engineering implementation plan** for runtime dynamic plugin onboarding and partition scaling in `audit-ingestor`. It turns the design docs into reviewable phases, file-level deliverables, and test expectations.
+
+**Design (read first):**
+
+| Doc | Role |
+|-----|------|
+| [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) | **Consolidated** architecture + flows + Q&A |
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Plain-language overview |
+| [README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md](README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md) | Goals, architecture, checklist |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | Kafka registry + REST API (detailed) |
+| [README-KAFKA-PLUGIN-PARTITIONING.md](README-KAFKA-PLUGIN-PARTITIONING.md) | Current static behavior (baseline) |
+| [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) | Operator runbook (Phase 7) |
+| [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) | Brownfield cutover (Phase 8) |
+| [README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md](README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md) | E2E test plan + Docker script |
+
+**Feature flag (all phases):** `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled` — default **`false`** (legacy XML at startup unchanged).
+
+---
+
+## Summary
+
+| Phase | Deliverable | Status |
+|-------|-------------|--------|
+| **1** | Core model + allocator + bootstrap + unit tests | **Done** |
+| **2** | Kafka registry + `createPartitionPlanTopicIfNotExists` | **Done** (unit tests; Kafka E2E in Phase 3+) |
+| **3** | Plan-aware `AuditPartitioner` + `PartitionPlanWatcher` | **Done** (unit tests; Docker E2E deferred) |
+| **4** | REST `GET /api/audit/partition-plan` | **Done** (unit tests) |
+| **5** | REST `PUT` / promote / scale + AdminClient | **Done** (unit tests) |
+| **6** | AuthZ + `/status` plan metadata | **Deferred** (auth via `AuditDelegationTokenFilter` today; allow-list + `/status` block later) |
+| **7** | Ops runbook + sample XML | **Done** |
+| **8** | Brownfield migration procedure | **Done** |
+
+```mermaid
+flowchart LR
+  P1[Phase 1 Model] --> P2[Phase 2 Registry]
+  P2 --> P3[Phase 3 Partitioner + Watcher]
+  P3 --> P4[Phase 4 REST GET]
+  P4 --> P5[Phase 5 REST mutate]
+  P5 --> P6[Phase 6 AuthZ + status]
+  P6 --> P7[Phase 7 Runbook]
+  P7 --> P8[Phase 8 Migration]
+```
+
+**Suggested PR split:** one PR per phase (or combine 4+5+6 after 3). Phases 1–2 can merge without enabling dynamic mode in production configs.
+
+---
+
+## Phase 1 — Core model + allocator
+
+**Goal:** Immutable plan model, append-only allocation rules, XML→v1 bootstrap (same layout as static `AuditPartitioner`), and unit tests. No Kafka, no REST, no runtime wiring yet.
+
+### New package
+
+`audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/`
+
+| Class | Responsibility |
+|-------|----------------|
+| `PartitionPlan` | JSON model: `topic`, `version`, `topicPartitionCount`, `plugins`, `buffer`, `updatedAt`, `updatedBy` |
+| `PluginPartitionAssignment` | `{ "partitions": [0,1,2] }` wrapper |
+| `PartitionPlanConstants` | `INITIAL_PLAN_VERSION`, `BOOTSTRAP_UPDATED_BY` |
+| `PartitionPlanBootstrapConfig` | Bootstrap inputs (audit topic, plugins, overrides) |
+| `PartitionPlanException` | Invalid plan / allocation failures |
+| `PartitionPlanValidator` | Every partition assigned once; append-only transition checks |
+| `PartitionPlanAllocator` | `promotePlugin`, `scalePlugin`, `replacePlan` (append-only tail growth) |
+| `PartitionPlanBootstrap` | `createInitialPlan*` from XML / producer config (contiguous ranges → explicit lists) |
+
+### Tests
+
+`audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/`
+
+| Test class | Covers |
+|------------|--------|
+| `PartitionPlanBootstrapTest` | Initial plan matches static partitioner layout; overrides; `createInitialPlanFromProducerConfig` |
+| `PartitionPlanAllocatorTest` | Promote from buffer; grow topic when buffer exhausted; scale tail-only; error cases |
+| `PartitionPlanValidatorTest` | Duplicates, Kafka count mismatch, append-only reject reshuffle / accept tail growth |
+
+### Allocation rules (locked for later phases)
+
+- **Promote:** take partition IDs from the **front** of `buffer.partitions`; if insufficient, append new tail IDs and bump `topicPartitionCount`.
+- **Scale:** append new tail IDs to the plugin’s existing list only; never reorder or remove existing IDs.
+- **Replace (PUT):** `validateAppendOnly(current, proposed)`; server assigns `version = current + 1`.
+
+### Verify locally
+
+```bash
+cd /path/to/ranger
+mvn install -pl audit-server/audit-ingestor -am -DskipTests -Drat.skip=true
+mvn test -pl audit-server/audit-ingestor \
+  -Dtest=PartitionPlanBootstrapTest,PartitionPlanAllocatorTest,PartitionPlanValidatorTest \
+  -Drat.skip=true
+```
+
+### Out of scope (Phase 1)
+
+- `AuditPartitioner` changes
+- REST endpoints
+
+---
+
+## Phase 2 — Kafka registry + plan topic create
+
+**Goal:** Durable read/write of `PartitionPlan` JSON to compacted topic `ranger_audit_partition_plan`; idempotent topic creation (Race A).
+
+### New / extended code
+
+| Component | Location | Notes |
+|-----------|----------|-------|
+| `PartitionPlanRegistry` | `audit-ingestor/.../partition/` | `readPlan`, `writePlan`, `getPlanTopicName` |
+| `KafkaPartitionPlanRegistry` | same | Kafka producer/consumer on compacted plan topic |
+| `PartitionPlanJson` | same | JSON serde via `MiscUtil.getMapper()` |
+| `PartitionPlanKafkaConfig` | same | Resolve topic name, flags, producer/consumer props |
+| `createPartitionPlanTopicIfNotExists()` | `audit-common/.../AuditMessageQueueUtils.java` | 1 partition, `cleanup.policy=compact`; **already-exists = success** |
+| `buildAdminClientConfig()` | same | Shared AdminClient bootstrap (audits + plan topics) |
+
+### Reuse (do not rewrite)
+
+- `AuditMessageQueueUtils.createAuditsTopicIfNotExists()` — AdminClient bootstrap, JAAS, retries
+- `AuditMessageQueueUtils.updateExistingTopicPartitions()` — pattern for Phase 5 partition growth
+- `kafka-clients` **3.9.1** — `AdminClient` already on ingestor classpath
+
+### Constants (`audit-common` / `AuditServerConstants`)
+
+| Property | Default |
+|----------|---------|
+| `kafka.partition.plan.topic` | `ranger_audit_partition_plan` |
+| `kafka.partition.plan.refresh.interval.ms` | `30000` |
+| `kafka.partition.plan.dynamic.enabled` | `false` |
+
+### Tests
+
+| Test class | Covers |
+|------------|--------|
+| `PartitionPlanJsonTest` | JSON round-trip; reject invalid JSON |
+| `PartitionPlanKafkaConfigTest` | Topic name, dynamic flag, refresh interval defaults |
+| `AuditMessageQueueUtilsTest` | `buildAdminClientConfig` |
+
+Kafka registry read/write integration tests deferred to Phase 3 Docker E2E (no Testcontainers in repo today).
+
+### Verify locally
+
+```bash
+mvn test -pl audit-server/audit-common,audit-server/audit-ingestor \
+  -Dtest=AuditMessageQueueUtilsTest,PartitionPlanJsonTest,PartitionPlanKafkaConfigTest,PartitionPlanBootstrapTest,PartitionPlanAllocatorTest,PartitionPlanValidatorTest \
+  -Drat.skip=true
+```
+
+### Kafka ACLs (document for ops)
+
+- Ingestor principal: **WRITE** on `ranger_audit_partition_plan`
+- Existing: **ALTER** / create-partitions on `ranger_audits` (already used at startup)
+
+### Compacted topic: append, retention, performance (design note)
+
+**Full design write-up:** [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md → Compacted topic semantics](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#compacted-topic-semantics-append-retention-and-performance)
+
+Summary for reviewers:
+
+| Question | Answer |
+|----------|--------|
+| Does `writePlan` update one record? | **No** — each write **appends** a new record (same key, new offset). |
+| How is it a “update”? | `cleanup.policy=compact` keeps **latest value per key**; old versions are compacted away. |
+| Phase 2 `readPlan` | Scans partition 0 from start; **last matching key wins** (safe before compaction runs). |
+| Impact on audit throughput? | **None** — plugin POST uses in-memory plan only. |
+| Record growth concern? | **Low** — writes are rare; typical deployment has **one key**; ~1 record retained after compaction. |
+| Phase 3 watcher | **Incremental** consume after initial load — do **not** full-scan every 30s. |
+
+---
+
+## Phase 3 — Plan-aware partitioner + watcher
+
+**Goal:** Runtime routing from in-memory plan; background sync from Kafka; first-pod XML bootstrap (Race B). **No restart** when plan changes.
+
+### Modified code
+
+| File | Change |
+|------|--------|
+| `AuditPartitioner.java` | When `dynamic.enabled=false`: keep today’s static ranges. When `true`: reads `PartitionPlanHolder`; hot path has no Kafka I/O |
+| `PartitionPlanHolder` | Shared singleton: `AtomicReference<PartitionPlan>` + version metadata |
+| `PartitionPlanWatcher` | Startup: registry bootstrap (Race B) → install plan → incremental consumer poll every `refresh.interval.ms` |
+| `PartitionPlanBootstrapSupport` | Race B: read → build v1 → re-read → write → mandatory read-back |
+| `AuditMessageQueue.java` | `startPartitionPlanWatcherIfEnabled()` before producer create; stop on shutdown |
+
+### Bootstrap Race B (mandatory)
+
+1. Read plan → empty  
+2. Build v1 from XML (`PartitionPlanBootstrap`)  
+3. Re-read — if peer published, adopt theirs  
+4. Produce local v1  
+5. Mandatory read-back — install Kafka value, not local object only  
+
+### Routing (dynamic mode)
+
+1. Lookup `agentId` in `plan.plugins` → round-robin within list  
+2. Else → hash into `plan.buffer.partitions`  
+3. Validate partition IDs against `cluster.partitionsForTopic(topic)` before applying plan swap  
+
+### Tests
+
+| Type | Cases |
+|------|-------|
+| Unit | `AuditPartitionerDynamicTest` — plan routing; legacy flag off unchanged; concurrent swap |
+| Unit | `PartitionPlanBootstrapSupportTest` — Race B: existing plan, publish v1, adopt peer |
+| Integration | Two parallel bootstraps → same v1 on both pods (Docker tier3 E2E — deferred) |
+| Failure | Plan topic unreadable at runtime → keep last known good plan (watcher logs warn, continues) |
+
+### Misconfiguration
+
+`dynamic.enabled=true` + Kafka unreachable at startup → **fail startup** (no silent fallback to XML).
+
+---
+
+## Phase 4 — REST GET
+
+**Goal:** Admin read of current plan (in-memory; optional force read from Kafka for debug).
+
+### Endpoints
+
+| Method | Path | Behavior |
+|--------|------|----------|
+| `GET` | `/api/audit/partition-plan` | Return current in-memory plan |
+
+### Code
+
+| File | Change |
+|------|--------|
+| `AuditREST.java` | New `@GET` method(s) |
+| New `PartitionPlanService` | Delegates to `PartitionPlanHolder` / registry |
+
+When `dynamic.enabled=false`: return **404** or **503 Feature disabled**; do not register mutating routes.
+
+### Tests
+
+| Test class | Covers |
+|------------|--------|
+| `PartitionPlanServiceTest` | Flag off/on; in-memory GET; not loaded |
+
+**Status:** `PartitionPlanService` + `AuditREST.getPartitionPlan()` implemented.
+
+---
+
+## Phase 5 — REST PUT / promote / scale + AdminClient
+
+**Goal:** Control plane mutations with optimistic concurrency; grow `ranger_audits` **before** publishing plan that references new partition IDs.
+
+### Endpoints
+
+| Method | Path | Body (summary) |
+|--------|------|----------------|
+| `PUT` | `/api/audit/partition-plan` | Full plan + `expectedVersion` |
+| `POST` | `/api/audit/partition-plan/promote` | `pluginId`, `partitionCount`, `expectedVersion` |
+| `POST` | `/api/audit/partition-plan/scale` | `pluginId`, `additionalPartitions`, `expectedVersion` |
+
+### Handler order (do not reorder)
+
+1. AuthZ (Phase 6 — deferred; authentication only today)  
+2. Load plan vN from Kafka  
+3. `expectedVersion != N` → **409** + current plan body  
+4. `PartitionPlanAllocator` / `replacePlan`  
+5. If needed → `AdminClient.createPartitions(ranger_audits)`  
+6. Re-read plan — still vN? else **409**  
+7. Produce vN+1 to plan topic  
+8. Read-back verify → **200** or **409**  
+
+### Code
+
+| File | Change |
+|------|--------|
+| `PartitionPlanService` | Orchestrates GET/PUT/promote/scale |
+| `AuditMessageQueueUtils` | Reuse `updateExistingTopicPartitions` for audit topic growth |
+
+### Tests
+
+| Test class | Covers |
+|------------|--------|
+| `PartitionPlanServiceMutationTest` | Promote, scale, PUT replace; stale `expectedVersion` → conflict; peer publish before write; topic grow failure |
+
+**Status:** `PartitionPlanService` mutations + `AuditREST` PUT/POST endpoints; `AuditMessageQueueUtils.ensureTopicPartitionCount()`.
+
+---
+
+## Phase 6 — AuthZ + `/status`
+
+**Status:** **Deferred** — implement in a follow-up PR. Phases 1–5, 7, and 8 are sufficient for initial dynamic-mode rollout.
+
+**Today:** `security-applicationContext.xml` requires authentication for `/api/audit/partition-plan/**`; `AuditDelegationTokenFilter` skips auth only for `/health` and `/status`. Any authenticated principal can call partition-plan (no separate admin allow-list yet). Use `GET /api/audit/partition-plan` for plan health until `/status` is extended.
+
+**Goal:** Restrict partition-plan API to admin users; expose plan health on status endpoint.
+
+### AuthZ (proposed property)
+
+```xml
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.allowed.users</name>
+  <value>admin,ops</value>
+</property>
+```
+
+- Pattern: same as `/access` (`isAllowedServiceUser` style), but **separate** allow-list (plugin users must not call partition-plan).  
+- `security-applicationContext.xml`: `/api/audit/partition-plan/**` requires authentication.  
+- `AuditDelegationTokenFilter`: health/status stay permitAll; partition-plan does not.
+
+### `/status` extensions
+
+```json
+{
+  "partitionPlan": {
+    "dynamicEnabled": true,
+    "version": 5,
+    "topicPartitionCount": 28,
+    "lastUpdated": "2026-06-02T12:00:00Z",
+    "watcherStatus": "OK"
+  }
+}
+```
+
+### Tests
+
+- Unauthenticated → 401  
+- Authenticated, not in allow-list → 403  
+- Plugin service user → 403 on partition-plan, still OK on `/access`  
+
+---
+
+## Phase 7 — Ops runbook + sample XML
+
+**Goal:** Document operator workflow when `dynamic.enabled=true`.
+
+**Status:** Done — [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md)
+
+### Deliverables
+
+| Item | Location |
+|------|----------|
+| Ops runbook | [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) — enablement, REST examples, 409 retry, dispatchers, troubleshooting |
+| Sample XML | `audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml` — `partition.plan.dynamic.enabled=false` (active); optional topic/refresh commented |
+
+### Runbook highlights
+
+- Runtime changes via **REST only**, not pod-local XML edits  
+- After enable: first pod seeds v1 from XML if plan topic empty  
+- On **409**: GET plan, retry with new `expectedVersion`  
+- Solr/HDFS dispatchers: no config change; rebalance when `ranger_audits` partition count grows  
+
+---
+
+## Phase 8 — Brownfield migration
+
+**Status:** **Done** — [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md)
+
+**Goal:** Safe cutover for clusters already running static XML + existing `ranger_audits` partition count.
+
+**Deliverable:** Operator migration guide with three paths (pre-seed Kafka, auto-bootstrap, post-bootstrap `PUT` correction), pre-flight drift checklist (`kafka.topic.partitions` vs buffer), verification and rollback.
+
+**Summary:**
+
+1. Capture effective routing from ingestor startup logs + `kafka-topics --describe`.  
+2. Prefer **pre-seed** plan v1 in `ranger_audit_partition_plan` when XML may not match production.  
+3. Enable `dynamic.enabled=true` + rolling restart.  
+4. Verify `GET /partition-plan` on all pods; spot-check plugin routing.
+
+---
+
+## Explicitly out of scope
+
+| Area | Reason |
+|------|--------|
+| Solr/HDFS dispatcher code | Consume all `ranger_audits` partitions; rebalance only |
+| `AuditRecoveryManager` | Per-pod spool/retry unchanged |
+| Postgres / ZooKeeper registry | Design chooses Kafka compacted topic |
+| Decrease partition count | Kafka does not support shrink |
+| Pod-local XML writes for runtime updates | Multi-replica unsafe |
+
+---
+
+## Testing matrix (all phases)
+
+| Layer | What to run |
+|-------|-------------|
+| **Unit** | Allocator, validator, bootstrap, partitioner (mock plan), service (mock registry) |
+| **Integration** | Testcontainers Kafka: registry, Race A/B, REST flow |
+| **Manual / Docker E2E** | [README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md](README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md) — `dev-support/ranger-docker/scripts/audit/verify-partition-plan-e2e.sh` on Tier 3 |
+| **Regression** | `dynamic.enabled` absent/false → identical to [README-KAFKA-PLUGIN-PARTITIONING.md](README-KAFKA-PLUGIN-PARTITIONING.md) |
+| **Security** | Partition-plan AuthZ vs plugin `/access` users |
+
+---
+
+## Open decisions (resolve before Phase 5+)
+
+| # | Topic | Recommendation |
+|---|--------|----------------|
+| 1 | Admin allow-list property name | `kafka.partition.plan.allowed.users` |
+| 2 | Watcher: consumer vs poll | Consumer for faster convergence; interval as backstop |
+| 3 | First PR with mutating REST | Phase 4 GET alone, or 4+5 together |
+| 4 | Brownfield import tool | Optional CLI: XML + `describeTopics` → PUT body |
+| 5 | Testcontainers in `audit-ingestor` CI | Align with parent POM / module policy |
+
+---
+
+## Code map (target end state)
+
+```mermaid
+flowchart TB
+  subgraph exists [Exists today]
+    RESTA[AuditREST /access]
+    PartStatic[AuditPartitioner static]
+    Utils[AuditMessageQueueUtils]
+    Queue[AuditMessageQueue]
+  end
+
+  subgraph phase1 [Phase 1 done]
+    Plan[PartitionPlan]
+    Alloc[PartitionPlanAllocator]
+    Boot[PartitionPlanBootstrap]
+    Valid[PartitionPlanValidator]
+  end
+
+  subgraph phase2to6 [Phases 2-6]
+    Reg[KafkaPartitionPlanRegistry]
+    Watch[PartitionPlanWatcher]
+    Svc[PartitionPlanService]
+    RESTP[AuditREST /partition-plan]
+    PartDyn[AuditPartitioner dynamic]
+  end
+
+  Boot --> Plan
+  Alloc --> Valid
+  Reg --> Plan
+  Watch --> PartDyn
+  Svc --> Reg
+  Svc --> Utils
+  RESTP --> Svc
+  Queue --> Watch
+  PartDyn --> Plan
+```
+
+---
+
+## Related sizing note
+
+Partition count planning is independent of this feature. For audit payload sizing (e.g. **~2 KB average uncompressed JSON** for heavy workloads, **~1.2 KB after LZ4**), see [README-KAFKA-DISPATCHERS.md](README-KAFKA-DISPATCHERS.md) § disk sizing.
diff --git a/audit-server/README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md b/audit-server/README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md
new file mode 100644
index 000000000..095664213
--- /dev/null
+++ b/audit-server/README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md
@@ -0,0 +1,272 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic partition plan — operations runbook
+
+> **Consolidated design (start here for review):** [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) — architecture, flows, and Q&A. This README is the day-2 operator runbook (REST examples, troubleshooting, checklists).
+
+Operator guide for **`ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=true`**.
+
+**Related docs:**
+
+| Doc | Use when |
+|-----|----------|
+| [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) | Consolidated design — architecture, flows, Q&A |
+| [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md) | Shorter conceptual overview |
+| [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) | REST API + Kafka registry design |
+| [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) | Engineering phases |
+| [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) | Cutover from static XML (brownfield) |
+| [README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md](README-KAFKA-PARTITION-PLAN-E2E-TEST-PLAN.md) | E2E validation (Docker script) |
+| [README-KAFKA-PLUGIN-PARTITIONING.md](README-KAFKA-PLUGIN-PARTITIONING.md) | Legacy static mode (default today) |
+| [README-KAFKA-DISPATCHERS.md](README-KAFKA-DISPATCHERS.md) | Solr/HDFS consumers |
+
+---
+
+## Golden rules
+
+1. **Runtime routing changes → REST only.** Do not edit `configured.plugins` / overrides in XML expecting live effect when dynamic mode is on. XML seeds **bootstrap v1 only** when the plan topic is empty.
+2. **No ingestor restart** for promote/scale — watcher refreshes in-memory plan on every pod (~30s default).
+3. **Grow `ranger_audits` before** publishing a plan that references new partition IDs (REST handler does this automatically).
+4. **Never shrink** Kafka partition count — not supported.
+5. **Solr/HDFS dispatchers** — no config change; they consume all `ranger_audits` partitions and rebalance when partition count grows.
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|--------|
+| Kafka reachable from all ingestor pods | Startup **fails** if `dynamic.enabled=true` and Kafka/plan topic is unreachable |
+| Ingestor principal ACLs | **WRITE** on `ranger_audit_partition_plan`; **ALTER** / create-partitions on `ranger_audits` (same as today) |
+| Plugin XML layout correct | Used once for bootstrap v1 if plan topic has no message |
+| Brownfield clusters | Follow [brownfield migration guide](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) — pre-seed plan v1 when XML may not match production |
+
+### Kafka topics
+
+| Topic | Purpose | Created by |
+|-------|---------|------------|
+| `ranger_audits` | Audit events | Existing `createAuditsTopicIfNotExists` |
+| `ranger_audit_partition_plan` | Compacted plan registry (1 partition) | First ingestor pod (`createPartitionPlanTopicIfNotExists`) |
+
+---
+
+## Sample XML (defaults off)
+
+Shipped in `audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml` as a **commented block**. Uncomment only when ready to enable dynamic mode.
+
+```xml
+<!-- Dynamic partition plan (Kafka compacted registry). Default: disabled = legacy XML routing. -->
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled</name>
+  <value>false</value>
+  <description>
+    false or absent = legacy XML AuditPartitioner at startup (today's behavior).
+    true = Kafka registry + REST + PartitionPlanWatcher. Runtime changes via REST only.
+  </description>
+</property>
+<!-- Optional when dynamic=true (built-in defaults shown): -->
+<!--
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.topic</name>
+  <value>ranger_audit_partition_plan</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms</name>
+  <value>30000</value>
+</property>
+-->
+```
+
+**Leave `dynamic.enabled=false`** until plan topic exists and ops are trained on REST workflow.
+
+---
+
+## Enable dynamic mode (greenfield)
+
+| Step | Action |
+|------|--------|
+| 1 | Verify `configured.plugins`, overrides, and buffer in XML match desired **initial** layout |
+| 2 | Set `kafka.partition.plan.dynamic.enabled` to `true` on **all** ingestor replicas (rolling restart once) |
+| 3 | First pod: creates `ranger_audit_partition_plan` if missing, runs **Race B** bootstrap (XML → v1) if topic empty |
+| 4 | Later pods: read existing plan from Kafka — **ignore XML** for routing |
+| 5 | `GET /api/audit/partition-plan` — confirm same `version` on each pod after ~30s |
+| 6 | Spot-check: produce test audit per plugin; confirm partition routing in ingestor logs |
+
+```mermaid
+flowchart LR
+  XML[XML bootstrap once] --> PlanTopic[ranger_audit_partition_plan]
+  PlanTopic --> Mem[In-memory plan all pods]
+  REST[REST promote/scale] --> PlanTopic
+  Mem --> Audits[ranger_audits produce]
+```
+
+---
+
+## REST API quick reference
+
+Base path: `/api/audit/partition-plan` (requires authentication per `security-applicationContext.xml`). Admin-only allow-list (Phase 6) is **not** implemented yet — restrict who receives ingestor credentials at the network/ops layer until then.
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/audit/partition-plan` | Current in-memory plan |
+| `PUT` | `/api/audit/partition-plan` | Full plan replace (`expectedVersion` required) |
+| `POST` | `/api/audit/partition-plan/promote` | Move plugin from buffer → dedicated partitions |
+| `POST` | `/api/audit/partition-plan/scale` | Append tail partitions to existing plugin |
+
+**E2E:** from `dev-support/ranger-docker`: `./scripts/audit/verify-partition-plan-e2e.sh --dynamic --with-audit-smoke`
+
+When `dynamic.enabled=false`: partition-plan endpoints return **503** (feature disabled).
+
+### Inspect current plan
+
+```bash
+curl -s -u admin:password \
+  "https://audit-ingestor:7182/api/audit/partition-plan" | jq .
+```
+
+### Promote a new plugin (example: trino, 3 partitions)
+
+```bash
+curl -s -u admin:password -X POST \
+  -H 'Content-Type: application/json' \
+  "https://audit-ingestor:7182/api/audit/partition-plan/promote" \
+  -d '{
+    "pluginId": "trino",
+    "partitionCount": 3,
+    "expectedVersion": 1
+  }' | jq .
+```
+
+### Scale a hot plugin (example: hiveServer2, +2 partitions)
+
+```bash
+curl -s -u admin:password -X POST \
+  -H 'Content-Type: application/json' \
+  "https://audit-ingestor:7182/api/audit/partition-plan/scale" \
+  -d '{
+    "pluginId": "hiveServer2",
+    "additionalPartitions": 2,
+    "expectedVersion": 2
+  }' | jq .
+```
+
+Server order: load plan vN → validate `expectedVersion` → allocate → grow `ranger_audits` if needed → re-read → write vN+1 → read-back verify.
+
+---
+
+## Handle HTTP 409 (version conflict)
+
+Two operators or automation jobs updated the plan concurrently. **Do not retry blindly with the same `expectedVersion`.**
+
+| Step | Action |
+|------|--------|
+| 1 | `GET /api/audit/partition-plan` (or use **409 response body** — contains current plan JSON) |
+| 2 | Note new `version` and partition lists |
+| 3 | Recompute your change against **current** plan (append-only rules still apply) |
+| 4 | Retry with updated `expectedVersion` |
+
+```bash
+# After 409, refresh version then retry promote
+VERSION=$(curl -s -u admin:password \
+  "https://audit-ingestor:7182/api/audit/partition-plan" | jq -r .version)
+
+curl -s -u admin:password -X POST \
+  -H 'Content-Type: application/json' \
+  "https://audit-ingestor:7182/api/audit/partition-plan/promote" \
+  -d "{\"pluginId\":\"trino\",\"partitionCount\":3,\"expectedVersion\":${VERSION}}" | jq .
+```
+
+---
+
+## Common operations
+
+### Onboard a new plugin without restart
+
+1. `GET` plan → note `version` and buffer size  
+2. `POST .../promote` with `pluginId`, `partitionCount`, `expectedVersion`  
+3. Wait ≤ `refresh.interval.ms` (default 30s) for all pods  
+4. Optional: `GET` on each pod to confirm same `version`  
+5. No dispatcher or plugin config change required
+
+### Give more partitions to an existing plugin
+
+1. `POST .../scale` with `additionalPartitions`  
+2. Handler grows `ranger_audits` **before** publishing plan  
+3. Dispatchers rebalance automatically on next consumer group rebalance
+
+### Verify routing after change
+
+- Ingestor log: `AuditPartitioner Configuration` block shows plan `version` and ranges at producer startup  
+- Kafka: `kafka-console-consumer` on `ranger_audit_partition_plan` (key = `ranger_audits`) — latest value per key  
+- Audits: compare event rate per partition in dispatcher metrics/logs
+
+---
+
+## Solr / HDFS dispatchers
+
+| Question | Answer |
+|----------|--------|
+| Reconfigure dispatchers when plan changes? | **No** |
+| What happens when `ranger_audits` grows? | Consumer groups rebalance; more parallelism up to partition count |
+| Plugin-based traffic shift? | Hot plugins mapped to more partitions → more load on corresponding dispatcher workers |
+| Tuning | See [README-KAFKA-DISPATCHERS.md](README-KAFKA-DISPATCHERS.md) (`CooperativeStickyAssignor`, `max.poll.interval.ms`, etc.) |
+
+---
+
+## Recovery / spool
+
+`AuditRecoveryManager` unchanged. Retries resend with same `agentId` key; partition may differ if plan changed since original send — acceptable for audit pipelines.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Action |
+|---------|--------------|--------|
+| Ingestor fails startup after enabling dynamic | Kafka down or ACL denied on plan topic | Fix connectivity/ACLs; check logs for `PartitionPlanWatcher` / `createPartitionPlanTopicIfNotExists` |
+| `GET` returns 503 feature disabled | `dynamic.enabled=false` or unset | Enable property + rolling restart |
+| Pods show different plan `version` | Watcher lag or Kafka read failure | Check watcher logs; compare `GET` across pods; verify plan topic with `kafka-console-consumer` |
+| `PUT`/`promote` returns 400 | Append-only violation or invalid plan | Compare proposed lists with current; no reshuffle of existing plugin IDs |
+| `promote` returns 503 grow topic | AdminClient cannot increase `ranger_audits` | Check ALTER ACL; broker limits |
+| XML edit had no effect | Dynamic mode on — XML is bootstrap-only | Use REST |
+| Dispatcher lag after scale | Rebalance in progress | Normal; tune poll interval / consumers if sustained |
+
+---
+
+## Disable dynamic mode (rollback)
+
+| Step | Action |
+|------|--------|
+| 1 | Set `kafka.partition.plan.dynamic.enabled=false` |
+| 2 | Rolling restart all ingestor pods |
+| 3 | Routing returns to **static XML** at startup (legacy behavior) |
+| 4 | Plan topic remains in Kafka (harmless); not read when disabled |
+
+For brownfield rollback on live traffic, follow [brownfield migration rollback](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md#rollback-to-static-mode) — ensure XML matches effective routing before disabling.
+
+---
+
+## Checklist before production enablement
+
+- [ ] XML bootstrap layout reviewed (`configured.plugins`, overrides, buffer)  
+- [ ] Kafka ACLs verified for plan topic + audit topic ALTER  
+- [ ] Ops trained on REST promote/scale and **409 retry**  
+- [ ] Runbook link shared with on-call  
+- [ ] Brownfield: [migration guide](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) completed if not greenfield  
+- [ ] Dispatcher capacity reviewed if scaling hot plugins  
diff --git a/audit-server/README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md b/audit-server/README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md
new file mode 100644
index 000000000..bc93ad279
--- /dev/null
+++ b/audit-server/README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md
@@ -0,0 +1,1476 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Kafka-backed partition plan registry + REST (detailed design)
+
+> **Consolidated design (start here for review):** [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) — architecture, flows, diagrams, brownfield migration, and Q&A in one document. This README is the deep dive on Kafka registry + REST semantics.
+
+This document describes the **recommended** approach for **dynamic plugin onboarding** and **dynamic partition scaling** in `audit-ingestor` without Postgres or ZooKeeper.
+
+**Related docs:**
+
+- **Consolidated design:** [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md)
+- Current static partitioning: `README-KAFKA-PLUGIN-PARTITIONING.md`
+- Design summary + checklist: `README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md`
+- **Phased implementation plan:** [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md)
+- Producer performance gaps: `README-KAFKA-PRODUCER-PERFORMANCE.md`
+- Solr/HDFS consumers: `README-KAFKA-DISPATCHERS.md`
+
+---
+
+## Problem we are solving
+
+Today (`README-KAFKA-PLUGIN-PARTITIONING.md`):
+
+- Plugin → partition mapping is computed once at ingestor startup from XML.
+- Changing `configured.plugins` or overrides requires restart.
+- Contiguous-range allocation **reshuffles** later plugins when an early plugin’s count changes.
+
+Goal:
+
+- **Onboard** plugins (e.g. trino) and **scale** hot plugins (e.g. hiveServer2) **without restart**.
+- **No new infra** (no Postgres/ZooKeeper).
+- **All ingestor replicas** use the same routing after a change.
+- **Survive pod crash/restart** without losing the plan.
+
+---
+
+## High-level architecture
+
+### In plain terms
+
+There are **two separate Kafka topics** and **two different jobs**:
+
+| Topic | What it stores | Who cares |
+|-------|----------------|-----------|
+| **`ranger_audit_partition_plan`** | Small JSON: which plugin uses which partition IDs | **Ingestor only** (config) |
+| **`ranger_audits`** | Actual audit events | **Ingestor produces**, **Solr/HDFS consume** |
+
+**Ingestor pods do three things:**
+
+1. **Serve audits** — plugins POST `/access` → pick partition from **in-memory plan** → write to `ranger_audits` (fast; no Kafka read per audit).
+2. **Watch the plan** — background thread reads `ranger_audit_partition_plan` and updates memory when the plan changes.
+3. **Admin REST** — ops call `GET/PUT /api/audit/partition-plan` → update plan topic (+ grow `ranger_audits` if needed).
+
+Solr and HDFS dispatchers **never read the plan**. They read **all** partitions of `ranger_audits`.
+
+---
+
+### Picture (control plane vs data plane)
+
+```mermaid
+flowchart TB
+  subgraph ops [Ops / automation]
+    Admin[Admin REST client]
+  end
+
+  subgraph ingestor [audit-ingestor pods A, B, C ...]
+    REST[AuditREST partition-plan API]
+    Svc[PartitionPlanService]
+    Watcher[PartitionPlanWatcher background thread]
+    Mem[(In-memory PartitionPlan)]
+    Part[AuditPartitioner]
+    Queue[AuditMessageQueue]
+
+    REST --> Svc
+    Svc --> PlanTopic
+    Watcher --> PlanTopic
+    Watcher --> Mem
+    Mem --> Part
+    Plugin[Plugin POST /access] --> Queue --> Part
+    Part --> AuditTopic
+  end
+
+  subgraph kafka [Kafka]
+    PlanTopic[(ranger_audit_partition_plan compacted)]
+    AuditTopic[(ranger_audits)]
+  end
+
+  subgraph consumers [Unchanged consumers]
+    Solr[Solr dispatcher]
+    HDFS[HDFS dispatcher]
+  end
+
+  Admin -->|any pod via LB| REST
+  Svc -->|createPartitions if needed| AuditTopic
+  AuditTopic --> Solr
+  AuditTopic --> HDFS
+```
+
+**Takeaway:** plan topic = **slow, rare config**; audit topic = **high volume data**. Only REST + watcher touch the plan topic.
+
+---
+
+### The three flows (step by step)
+
+---
+
+#### Flow 1 — Admin changes the plan
+
+**When:** You onboard a plugin (e.g. trino) or give a hot plugin more partitions (e.g. hiveServer2).  
+**How often:** Rare — ops or automation, not every audit.
+
+| Step | What happens |
+|------|----------------|
+| 1 | Admin sends REST to **any** ingestor pod (`GET` to read, `PUT` / `promote-plugin` / `scale-plugin` to change). |
+| 2 | That pod reads the current plan from **`ranger_audit_partition_plan`** (e.g. version 4). |
+| 3 | If more partitions are needed, pod grows **`ranger_audits`** via Kafka AdminClient. |
+| 4 | Pod writes the **new plan** (version 5) to the compacted topic. |
+| 5 | Pod returns **200 OK** to admin (or **409** if another pod updated first — retry with new version). |
+| 6 | **Every ingestor pod** — background watcher loads version 5 into memory (~30s or on Kafka message). |
+| 7 | **Solr / HDFS** — no config change; they rebalance only if `ranger_audits` got more partitions. |
+
+```mermaid
+flowchart TB
+  Admin[Admin / automation]
+
+  subgraph step1 [Ingestor pod handles REST]
+    REST[Ingestor REST]
+    PlanRW[(Plan topic<br/>read + write)]
+    Grow[(ranger_audits<br/>grow if needed)]
+    REST --> PlanRW
+    REST --> Grow
+  end
+
+  subgraph step2 [All ingestor pods sync]
+    Watcher[Watcher on each pod]
+    Mem[Memory updated]
+    Same[Same routing everywhere]
+    Watcher --> Mem --> Same
+  end
+
+  subgraph step3 [Dispatchers unchanged]
+    SolrHDFS[Solr / HDFS]
+    Consume[Keep consuming ranger_audits]
+    SolrHDFS --> Consume
+  end
+
+  Admin --> REST
+  PlanRW --> Watcher
+  Grow -.->|rebalance only if partitions grew| SolrHDFS
+```
+
+---
+
+#### Flow 2 — Plugin sends an audit
+
+**When:** Every time a Ranger plugin reports an access event.  
+**How often:** High volume — this is the hot path.
+
+| Step | What happens |
+|------|----------------|
+| 1 | Plugin sends **POST `/access`** to ingestor (any pod via load balancer). |
+| 2 | Ingestor reads the plan **already in memory** (not from Kafka). |
+| 3 | Ingestor finds partitions for this plugin id (`agentId`), e.g. hive → `[4,5,6,7,8,9]`. |
+| 4 | Ingestor picks one partition (round-robin within that list). |
+| 5 | Ingestor writes the audit event to **`ranger_audits`**. |
+
+**Important:** This path **never** reads `ranger_audit_partition_plan`. Fast and cheap.
+
+```mermaid
+flowchart LR
+  Plugin[Plugin] --> Access[POST /access]
+  Access --> Mem[(Memory<br/>plan)]
+  Mem --> Pick[Pick partition<br/>for agentId]
+  Pick --> Audit[(ranger_audits)]
+
+  Watcher[Watcher<br/>Flow 1 or Flow 3] -.->|fills memory| Mem
+```
+
+---
+
+#### Flow 3 — Pod startup (first pod vs others)
+
+**When:** Ingestor pod starts or restarts.  
+**Goal:** Every pod ends up with the **same plan in memory**.
+
+**Prerequisite for XML → Kafka bootstrap:** `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=true`. If `false` or absent, legacy XML-only mode applies and **`ranger_audit_partition_plan` is not populated**.
+
+| Situation | What the pod does |
+|-----------|-------------------|
+| **Pod 1** — plan topic is **empty** | Read XML → build plan **v1** → **write v1 to `ranger_audit_partition_plan`** → load into memory. |
+| **Pod 2, 3, …** — plan **already in Kafka** | **Read plan from Kafka only** → load into memory. **Do not** use XML for routing. |
+| **Any pod restarts** | Same as Pod 2+ — read from Kafka, not XML. |
+
+```mermaid
+flowchart TB
+  subgraph pod1 [First pod ever — plan topic empty]
+    direction LR
+    XML[XML config] --> Kafka1[(ranger_audit_partition_plan v1)]
+    Kafka1 --> Mem1[Memory]
+  end
+
+  subgraph podN [Later pods — plan already in Kafka]
+    direction LR
+    Kafka2[(ranger_audit_partition_plan)] --> Mem2[Memory]
+    XML2[XML ignored for routing]
+    XML2 -.->|not used| Mem2
+  end
+
+  subgraph podR [Pod crash or restart]
+    direction LR
+    Kafka3[(ranger_audit_partition_plan<br/>plan survives in Kafka)] --> Mem3[Memory]
+  end
+```
+
+**Rule of thumb:** After v1 exists in Kafka, **Kafka is the source of truth** — not XML on the pod.
+
+**Full bootstrap details** (XML properties, example v1 JSON, when bootstrap does *not* run): [Bootstrap and multi-pod startup → First pod: XML populates the plan topic](#first-pod-xml-populates-the-plan-topic).
+
+---
+
+### Who talks to what (quick reference)
+
+| Actor | Reads plan topic | Writes plan topic | Reads/writes ranger_audits |
+|-------|------------------|-------------------|----------------------------|
+| Plugin audit POST | No | No | Produce only |
+| PartitionPlanWatcher | Yes (background) | No | No |
+| REST GET/PUT | Yes | Yes (PUT) | AdminClient grow only |
+| Solr dispatcher | No | No | Consume all partitions |
+| HDFS dispatcher | No | No | Consume all partitions |
+
+---
+
+## Code map: design vs `audit-server` today
+
+The dynamic partition plan is **design + README only** — the classes below marked **Proposed** do not exist in the repo yet. This section maps the design to **current audit-ingestor code** so you can see what to extend.
+
+### Module layout
+
+| Module | Path | Role |
+|--------|------|------|
+| **audit-ingestor** | `audit-server/audit-ingestor/` | HTTP REST, Kafka producer, recovery |
+| **audit-common** | `audit-server/audit-common/` | Shared constants, `AuditMessageQueueUtils` (AdminClient) |
+| **audit-dispatcher** | `audit-server/audit-dispatcher/` | Solr/HDFS consumers (unchanged by partition plan) |
+
+### Design component → Java / config (exists today vs proposed)
+
+| Design component | Status | Location in repo |
+|------------------|--------|------------------|
+| **`PartitionPlan`** (JSON model) | **Proposed** | New class, e.g. `audit-ingestor/.../partition/PartitionPlan.java` |
+| **`PartitionPlanAllocator`** | **Proposed** | New — append-only tail allocation |
+| **`PartitionPlanRegistry`** | **Proposed** | New — Kafka compacted topic read/write |
+| **`PartitionPlanService`** | **Proposed** | New — REST handler logic |
+| **`PartitionPlanWatcher`** | **Proposed** | New — background thread per pod |
+| **`AuditPartitioner`** | **Exists** (static XML) | `audit-ingestor/.../kafka/AuditPartitioner.java` |
+| **`AuditREST`** `/access` | **Exists** | `audit-ingestor/.../rest/AuditREST.java` |
+| **`AuditREST`** `/partition-plan` | **Proposed** | Same file — new `@GET` / `@PUT` / `@POST` methods |
+| **`AuditMessageQueue`** | **Exists** | `audit-ingestor/.../kafka/AuditMessageQueue.java` |
+| **`AuditProducer`** | **Exists** | `audit-ingestor/.../kafka/AuditProducer.java` |
+| **Topic create + `createPartitions`** | **Exists** | `audit-common/.../AuditMessageQueueUtils.java` |
+| **XML partition config** | **Exists** | `audit-ingestor/.../conf/ranger-audit-ingestor-site.xml` |
+| **`partition.plan.dynamic.enabled`** etc. | **Proposed** | Not in `AuditServerConstants.java` or site XML yet |
+
+---
+
+### Flow 2 in code today (plugin POST → Kafka)
+
+**Description:** Every plugin audit hits the same Java call chain today. Partition key is `agentId` (plugin id). `AuditPartitioner` picks the Kafka partition from **static XML** at startup (not from plan topic yet).
+
+| Step | Class / file |
+|------|----------------|
+| 1 | `AuditREST.logAccessAudit()` — `audit-ingestor/.../rest/AuditREST.java` |
+| 2 | `AuditDestinationMgr.logBatch()` — `audit-ingestor/.../producer/AuditDestinationMgr.java` |
+| 3 | `AuditMessageQueue.log(batch)` — `audit-ingestor/.../kafka/AuditMessageQueue.java` |
+| 4 | `AuditProducer.sendBatch()` — `audit-ingestor/.../kafka/AuditProducer.java` |
+| 5 | `KafkaProducer` key=`agentId` → `AuditPartitioner.partition()` |
+| 6 | Topic **`ranger_audits`** |
+
+```mermaid
+flowchart LR
+  Plugin[Ranger plugin] -->|POST /audit/access| REST[AuditREST]
+  REST --> Mgr[AuditDestinationMgr]
+  Mgr --> Queue[AuditMessageQueue]
+  Queue -->|key = agentId| Prod[AuditProducer]
+  Prod --> Part[AuditPartitioner]
+  Part --> Topic[(ranger_audits)]
+```
+
+**Partition key** in `AuditMessageQueue.java` — `authzEvent.getAgentId()`.
+
+**Custom partitioner** wired in `AuditProducer.java` when `configured.plugins` is set → `AuditPartitioner`.
+
+---
+
+### Static partitioning today (`AuditPartitioner` = future bootstrap v1 logic)
+
+At startup, `configure()` reads the same XML properties the design uses for **first-pod bootstrap**. It builds **contiguous ranges** (not explicit JSON lists yet):
+
+```56:102:audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditPartitioner.java
+    public void configure(Map<String, ?> configs) {
+        String propPrefix = AuditServerConstants.PROP_PREFIX_AUDIT_SERVER;
+
+        String pluginsStr = getConfig(configs, propPrefix + AuditServerConstants.PROP_CONFIGURED_PLUGINS,  AuditServerConstants.DEFAULT_CONFIGURED_PLUGINS);
+        configuredPlugins = pluginsStr.split(",");
+        // ...
+        defaultPartitionsPerPlugin = getIntConfig(configs, propPrefix + AuditServerConstants.PROP_TOPIC_PARTITIONS_PER_CONFIGURED_PLUGIN, ...);
+        // ...
+        for (int i = 0; i < configuredPlugins.length; i++) {
+            String overrideKey = propPrefix + AuditServerConstants.PROP_PLUGIN_PARTITION_OVERRIDE_PREFIX + plugin;
+            int partitionCount = getIntConfig(configs, overrideKey, defaultPartitionsPerPlugin);
+            pluginPartitionCounts[i] = partitionCount;
+        }
+        // contiguous ranges → configuredPluginPartitionStart/End, bufferPartitionStart/Count
+```
+
+**Runtime routing** (round-robin for configured plugin, hash for buffer):
+
+```117:151:audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditPartitioner.java
+    public int partition(String topic, Object key, byte[] keyBytes, Object value, byte[] valueBytes, Cluster cluster) {
+        // ...
+        int pluginIndex = indexOfConfiguredPlugin(appId);
+        if (pluginIndex >= 0) {
+            // round-robin within plugin range
+            return start + subPartition;
+        } else {
+            // Unconfigured plugin - use buffer partitions
+            int p = Math.abs(appId.hashCode() % count) + start;
+            return Math.min(p, numPartitions - 1);
+        }
+    }
+```
+
+**Dynamic design change:** replace fixed `int[]` ranges with `AtomicReference<PartitionPlan>` and explicit `[0,1,2,...]` lists from Kafka.
+
+---
+
+### Topic size + `AdminClient.createPartitions` (reuse for REST PUT)
+
+Topic creation and partition **increase** already exist — the proposed `PartitionPlanService` should call the same patterns:
+
+```49:116:audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java
+    public static String createAuditsTopicIfNotExists(Properties props, String propPrefix) {
+        // ...
+        int    partitions           = getPartitions(props, propPrefix);
+        // AdminClient.createTopics or updateExistingTopicPartitions
+```
+
+```230:249:audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java
+            if (partitions > currentPartitions) {
+                // ...
+                newPartitionsMap.put(topicName, NewPartitions.increaseTo(partitions));
+                CreatePartitionsResult createPartitionsResult = admin.createPartitions(newPartitionsMap);
+                createPartitionsResult.all().get();
+```
+
+**Partition count from XML** (same inputs as bootstrap v1 JSON):
+
+```330:365:audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java
+    private static int getPartitions(Properties prop, String propPrefix) {
+        String configuredPlugins = MiscUtil.getStringProperty(prop, propPrefix + "." + AuditServerConstants.PROP_CONFIGURED_PLUGINS, ...);
+        if (configuredPlugins == null || configuredPlugins.trim().isEmpty()) {
+            totalPartitions = MiscUtil.getIntProperty(prop, propPrefix + "." + AuditServerConstants.PROP_TOPIC_PARTITIONS, ...);
+        } else {
+            for (String plugin : configuredPlugins.split(",")) {
+                int partitionCount = MiscUtil.getIntProperty(prop, overrideKey, defaultPartitionsPerPlugin);
+                totalPartitions += partitionCount;
+            }
+            totalPartitions += bufferPartitions;
+        }
+        return totalPartitions;
+    }
+```
+
+---
+
+### REST today vs proposed admin API
+
+**Exists** — plugin audit ingestion only:
+
+| Endpoint | File |
+|----------|------|
+| `GET /audit/health` | `AuditREST.java` |
+| `GET /audit/status` | `AuditREST.java` |
+| `POST /audit/access` | `AuditREST.java` — auth via `allowed.users` per service |
+
+**Proposed** — not in code yet:
+
+| Endpoint | Intended location |
+|----------|-------------------|
+| `GET /api/audit/partition-plan` | `AuditREST.java` or new resource class |
+| `PUT /api/audit/partition-plan` | `PartitionPlanService` |
+| `POST .../promote-plugin`, `.../scale-plugin` | `PartitionPlanService` |
+
+---
+
+### Configuration constants today (`AuditServerConstants`)
+
+Properties used for **legacy / bootstrap** partitioning (no `partition.plan.*` yet):
+
+```56:85:audit-server/audit-common/src/main/java/org/apache/ranger/audit/server/AuditServerConstants.java
+    public static final String PROP_TOPIC_PARTITIONS                         = "kafka.topic.partitions";
+    public static final String PROP_PARTITIONER_CLASS                        = "kafka.partitioner.class";
+    public static final String PROP_CONFIGURED_PLUGINS                       = "kafka.configured.plugins";
+    public static final String PROP_TOPIC_PARTITIONS_PER_CONFIGURED_PLUGIN   = "kafka.topic.partitions.per.configured.plugin";
+    public static final String PROP_PLUGIN_PARTITION_OVERRIDE_PREFIX         = "kafka.plugin.partition.overrides.";
+    public static final String PROP_BUFFER_PARTITIONS                        = "kafka.topic.partitions.buffer";
+    // ...
+    public static final int    DEFAULT_PARTITIONS_PER_CONFIGURED_PLUGIN      = 3;
+    public static final int    DEFAULT_BUFFER_PARTITIONS                     = 9;
+```
+
+**Sample XML** — `audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml`:
+
+- `ranger.audit.ingestor.kafka.configured.plugins`
+- `ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin`
+- `ranger.audit.ingestor.kafka.topic.partitions.buffer`
+- `ranger.audit.ingestor.kafka.plugin.partition.overrides.*`
+
+---
+
+### Where new code plugs in
+
+**Description:** Solid boxes = **exists today**. Dashed = **proposed**. Audit hot path unchanged; dynamic plan adds watcher + admin REST + plan topic.
+
+```mermaid
+flowchart TB
+  subgraph exists [Exists today]
+    Plugin[Plugin POST /access]
+    RESTA[AuditREST /access]
+    Queue[AuditMessageQueue]
+    Prod[AuditProducer]
+    Part[AuditPartitioner static XML]
+    Audits[(ranger_audits)]
+    Plugin --> RESTA --> Queue --> Prod --> Part --> Audits
+  end
+
+  subgraph proposed [Proposed]
+    RESTP[AuditREST /partition-plan]
+    Svc[PartitionPlanService]
+    Watcher[PartitionPlanWatcher]
+    Plan[(ranger_audit_partition_plan)]
+    Admin[Admin / automation]
+    Admin --> RESTP --> Svc
+    Svc --> Plan
+    Svc -->|createPartitions| Audits
+    Watcher -->|read| Plan
+    Watcher -->|update memory| Part
+  end
+```
+
+---
+
+## Core components (new code)
+
+| Component | Responsibility |
+|-----------|----------------|
+| **`PartitionPlan`** | Immutable snapshot: plugin → explicit partition ID list, buffer list, `version`, `topicPartitionCount`, `updatedAt` |
+| **`PartitionPlanAllocator`** | Append-only rules: assign new tail partitions; never remove/reassign existing plugin partitions |
+| **`PartitionPlanRegistry`** | Read/write plan to Kafka compacted topic |
+| **`PartitionPlanService`** | Orchestrates GET/PUT: validate, allocate, AdminClient, registry write |
+| **`PartitionPlanWatcher`** | Background thread on **every** ingestor pod; refreshes in-memory plan |
+| **`AuditPartitioner` (modified)** | Route by plan: configured plugin → round-robin within its list; unknown → buffer list |
+| **`AuditREST` (new endpoints)** | Admin API; AuthZ like `/access` |
+
+### Existing code to reuse (already in repo)
+
+**Description:** Build new partition-plan components on these classes — do not rewrite topic admin or produce plumbing.
+
+| Reuse | Path | Use for |
+|-------|------|---------|
+| `AuditMessageQueueUtils.createAuditsTopicIfNotExists()` | `audit-common/.../AuditMessageQueueUtils.java` | Pattern for `createPlanTopicIfNotExists()` |
+| `AuditMessageQueueUtils.updateExistingTopicPartitions()` | same | REST PUT → grow `ranger_audits` |
+| `AuditProducer` | `audit-ingestor/.../kafka/AuditProducer.java` | Existing Kafka producer; plan topic produce |
+| `AuditPartitioner` | `audit-ingestor/.../kafka/AuditPartitioner.java` | Add `AtomicReference<PartitionPlan>` |
+| `AuditREST` + `isAllowedServiceUser()` | `audit-ingestor/.../rest/AuditREST.java` | Admin AuthZ pattern for `/partition-plan` |
+
+```mermaid
+flowchart LR
+  subgraph new [Proposed new code]
+    PP[PartitionPlan]
+    Reg[PartitionPlanRegistry]
+    Svc[PartitionPlanService]
+    Watch[PartitionPlanWatcher]
+  end
+
+  subgraph reuse [Reuse from repo]
+    Utils[AuditMessageQueueUtils]
+    Part[AuditPartitioner]
+    REST[AuditREST]
+    Prod[AuditProducer]
+  end
+
+  Svc --> Utils
+  Svc --> Reg
+  Svc --> Prod
+  Watch --> Reg
+  Watch --> Part
+  REST --> Svc
+```
+
+---
+
+## Partition plan topic (`ranger_audit_partition_plan`)
+
+Why a **separate** topic from `ranger_audits`:
+
+- Audit topic carries high-volume events; plan is low-volume config.
+- Compacted config topic gives durable “latest value per key” semantics (like Kafka’s own `__consumer_offsets` pattern).
+
+Suggested topic config:
+
+```properties
+partitions=1
+cleanup.policy=compact
+min.compaction.lag.ms=0   # optional: faster visibility of new plan
+```
+
+**Key:** `ranger_audits` (audit topic name — allows multiple audit topics in future)  
+**Value:** JSON `PartitionPlan`
+
+When `dynamic.enabled=true`, each ingestor pod ensures this topic exists at startup via **`createPartitionPlanTopicIfNotExists()`** (implemented in `AuditMessageQueueUtils`; same AdminClient pattern as `createAuditsTopicIfNotExists()` for `ranger_audits`). If the topic is missing, the pod creates it with **1 partition** and **`cleanup.policy=compact`**.
+
+---
+
+## Compacted topic semantics: append, retention, and performance
+
+This section documents how plan **writes** and **reads** behave on `ranger_audit_partition_plan` — use it when reviewing or extending the design (Phase 2 registry, Phase 3 watcher).
+
+### Does `writePlan` update the same record?
+
+**No — Kafka does not update records in place.** Each `writePlan` (REST PUT, bootstrap publish, promote/scale) **appends a new record** to partition 0:
+
+```text
+offset 10: key=ranger_audits  value=plan v1
+offset 11: key=ranger_audits  value=plan v2
+offset 12: key=ranger_audits  value=plan v3
+```
+
+| Concept | Meaning |
+|---------|---------|
+| **Physical write** | Always **append** (new offset) |
+| **Logical update** | Same **key** (`ranger_audits`) + compaction → only **latest value per key** matters |
+| **`version` in JSON** | Application-level optimistic locking (REST `expectedVersion`); not a Kafka in-place edit |
+
+With `cleanup.policy=compact`, the log cleaner eventually **removes older records for the same key** and retains the **latest** value. After compaction, you typically have **~one record per audit topic key**, not an ever-growing history.
+
+### Phase 2 read strategy (`KafkaPartitionPlanRegistry.readPlan`)
+
+Current implementation (admin/bootstrap reads — **not** the audit hot path):
+
+1. Assign partition 0, `seekToBeginning`.
+2. Poll until empty; for each record with matching key, parse JSON into `latest`.
+3. Return **last matching record** (highest offset) — correct even if compaction has not run yet.
+
+This is intentionally simple for **rare** reads (startup, REST GET with force-read, compare-and-swap before PUT).
+
+### Will growing records hurt performance?
+
+**Not in normal Ranger use.** This topic is unlike `ranger_audits`:
+
+| Dimension | `ranger_audit_partition_plan` | `ranger_audits` |
+|-----------|-------------------------------|-----------------|
+| Write rate | Rare (ops: bootstrap, promote, scale) | Very high (every audit) |
+| Typical keys | **1** (`ranger_audits`) | N/A (data topic) |
+| Records retained (after compaction) | **~1 per key** | Full retention window |
+| Audit POST hot path | **Does not read** this topic | Produces every audit |
+
+**Cost of `readPlan` full scan** ≈ number of records still on disk for that key before compaction:
+
+```text
+~100 uncompacted versions × ~2 KB JSON ≈ 200 KB → usually well under 100 ms
+```
+
+Audit ingest throughput is **unaffected** — `AuditPartitioner` reads an in-memory plan only.
+
+### When record growth could matter (edge cases)
+
+| Situation | Risk | Mitigation |
+|-----------|------|------------|
+| Automation hammers PUT/promote/scale (many versions per minute) | Full scan reads more uncompacted records | Rate-limit ops; rely on compaction; Phase 3 watcher uses **incremental** consume |
+| Compaction lag / misconfigured topic | Old versions accumulate on disk | Monitor compaction; set `min.compaction.lag.ms` if needed; verify `cleanup.policy=compact` |
+| Many independent audit topic keys on one partition | More keys × versions before compact | Unusual today; one key per deployment is the default design |
+| Using full `seekToBeginning` on every watcher poll (anti-pattern) | Unnecessary IO every 30s | Phase 3: consume **new offsets only** after initial load |
+
+### Phase 3 watcher (planned — do not full-scan every refresh)
+
+| Phase | Read pattern | When |
+|-------|--------------|------|
+| **Phase 2** (`readPlan`) | Full compacted log scan | Rare: bootstrap, REST, admin debug |
+| **Phase 3** (`PartitionPlanWatcher`) | Initial load once; then **incremental** consumer poll | Every `refresh.interval.ms` (default 30s) |
+
+Watcher should **not** repeat `seekToBeginning` on every refresh. After startup, track consumer offset and apply only **new** plan records.
+
+### Ops guardrails (design assumptions)
+
+- Plan changes are **infrequent** (human or CI), not per-request.
+- Default deployment: **one** compacted key (`ranger_audits`) on **one** partition.
+- Runtime routing uses **memory**; Kafka is control plane only.
+- If plan update frequency ever approaches “every few seconds,” revisit watcher incremental consume and compaction tuning — not audit producer tuning.
+
+**Implementation reference:** `KafkaPartitionPlanRegistry` in `audit-ingestor/.../partition/` (Phase 2). See [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md) Phase 2–3.
+
+---
+
+## Partition plan JSON (canonical compacted-topic value)
+
+The compacted topic stores **one JSON document per audit topic key** — nothing else. This is the **only** durable source of truth when `dynamic.enabled=true`.
+
+**Key:** `ranger_audits` (audit topic name)  
+**Value:** JSON `PartitionPlan` (fields below — no extra metadata required):
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 5,
+  "topicPartitionCount": 28,
+  "updatedAt": "2026-06-02T12:00:00Z",
+  "updatedBy": "admin@example.com",
+  "plugins": {
+    "hdfs":        { "partitions": [0, 1, 2, 3] },
+    "hiveServer2": { "partitions": [4, 5, 6, 7, 8, 9] },
+    "trino":       { "partitions": [10, 11, 12, 13, 14, 15, 16, 17, 18] }
+  },
+  "buffer": {
+    "partitions": [19, 20, 21, 22, 23, 24, 25, 26, 27]
+  }
+}
+```
+
+| Field | Purpose |
+|-------|---------|
+| `topic` | Audit topic this plan applies to (matches compacted topic **key**) |
+| `version` | Monotonic integer; optimistic locking on REST PUT |
+| `topicPartitionCount` | Must match Kafka partition count for `topic` |
+| `updatedAt` / `updatedBy` | Audit trail (optional but recommended) |
+| `plugins` | Map plugin id (`agentId`) → explicit partition ID list |
+| `buffer` | Partition IDs for unknown / unconfigured plugins |
+
+**Create or update:** only via **REST** (`PUT` / `promote-plugin` / `scale-plugin`) or **one-time bootstrap publish** when the topic is empty (see below). Producers and audit POST handlers **never** write to this topic.
+
+**Routing rules in `AuditPartitioner`:**
+
+1. Lookup `agentId` in `plan.plugins`.
+2. If found → round-robin across that plugin’s partition list.
+3. If not found → hash into `plan.buffer.partitions`.
+4. Validate all partition IDs exist in `cluster.partitionsForTopic(topic)` before applying plan.
+
+---
+
+## Bootstrap and multi-pod startup
+
+When `dynamic.enabled=true`, **Kafka compacted topic wins** over XML whenever a plan message already exists.
+
+### First pod: XML populates the plan topic
+
+On the **first ingestor startup** with dynamic mode enabled, if `ranger_audit_partition_plan` has **no message** for key `ranger_audits`, the first pod **builds v1 from XML and publishes it** to the compacted topic. That is how the plan registry is initially filled.
+
+#### When bootstrap-from-XML runs
+
+| Condition | Bootstrap from XML → plan topic? |
+|-----------|----------------------------------|
+| `dynamic.enabled=true` **and** plan topic empty | **Yes** — first pod publishes v1 |
+| `dynamic.enabled=true` **and** plan already in Kafka | **No** — read Kafka only |
+| `dynamic.enabled=false` or property absent | **No** — legacy XML at startup; plan topic unused |
+
+#### XML properties used to build v1
+
+| XML property | Role in v1 plan |
+|--------------|-----------------|
+| `ranger.audit.ingestor.kafka.configured.plugins` | Plugin ids → keys in `plan.plugins` (order defines initial contiguous ranges) |
+| `ranger.audit.ingestor.kafka.plugin.partition.overrides.<plugin>` | Partition count for that plugin (length of its `partitions` list) |
+| `ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin` | Default count per plugin when no override (typically **3**) |
+| `ranger.audit.ingestor.kafka.topic.partitions.buffer` | Size of `plan.buffer.partitions` (typically **9**) |
+
+The bootstrap step **converts** today’s contiguous-range layout into **explicit partition ID lists** in JSON (same shape as REST-managed plans).
+
+#### Example: XML → v1 in `ranger_audit_partition_plan`
+
+**XML (simplified):** `configured.plugins=hdfs,hiveServer2`, default 3 partitions each, buffer 9.
+
+**Kafka compacted topic** — key `ranger_audits`, value:
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 1,
+  "topicPartitionCount": 15,
+  "updatedAt": "2026-06-02T10:00:00Z",
+  "updatedBy": "bootstrap",
+  "plugins": {
+    "hdfs":        { "partitions": [0, 1, 2] },
+    "hiveServer2": { "partitions": [3, 4, 5] }
+  },
+  "buffer": {
+    "partitions": [6, 7, 8, 9, 10, 11, 12, 13, 14]
+  }
+}
+```
+
+After this one-time publish, **all routing and later changes** use the plan in Kafka (REST or promote/scale), not XML edits.
+
+```mermaid
+flowchart LR
+  XML[ranger-audit-ingestor-site.xml] -->|first pod only| Build[Build v1]
+  Build --> Publish[Publish to ranger_audit_partition_plan]
+  Publish --> Mem[Load into memory]
+  Mem --> Audits[Serve audits]
+```
+
+---
+
+### Pod 1 (first ingestor, empty plan topic)
+
+**Description:** First pod with `dynamic.enabled=true` creates plan topic (if needed), seeds **v1 from XML** into Kafka, loads into memory. XML is used **once**.
+
+| Step | Action |
+|------|--------|
+| 1 | `PartitionPlanWatcher` starts |
+| 2 | `createPlanTopicIfNotExists()` — idempotent ([Race A](#race-a--multiple-pods-create-the-plan-topic-at-the-same-time)) |
+| 3 | Read plan topic → no message for key `ranger_audits` |
+| 4 | Build v1 from XML → explicit partition lists |
+| 5 | Publish v1 to `ranger_audit_partition_plan` ([Race B](#race-b--multiple-pods-publish-plan-v1-when-topic-exists-but-has-no-message)) |
+| 6 | Re-read compacted topic → install v1 in memory |
+| 7 | Serve audits (memory only on hot path) |
+
+```mermaid
+flowchart TD
+  Start[Pod 1 starts] --> Watcher[PartitionPlanWatcher]
+  Watcher --> Create[createPlanTopicIfNotExists]
+  Create --> Read{Plan message exists?}
+  Read -->|No| XML[Build v1 from XML]
+  XML --> Publish[Publish v1 to plan topic]
+  Publish --> Reread[Re-read compacted topic]
+  Reread --> Mem[Install in memory]
+  Mem --> Audits[Serve POST /access]
+```
+
+**Alternative:** wait for first admin REST PUT instead of auto-publish — possible, but auto-publish is recommended for pod 2+.
+
+### Pod 2+ (later ingestors, plan already in Kafka)
+
+**Description:** Plan already in Kafka — **read only**, never re-bootstrap from XML for routing.
+
+| Step | Action |
+|------|--------|
+| 1 | `PartitionPlanWatcher` starts |
+| 2 | `createPlanTopicIfNotExists()` — usually no-op (topic exists) |
+| 3 | Read plan version **N** from compacted topic |
+| 4 | Install into memory — **ignore XML** |
+| 5 | Serve audits |
+
+```mermaid
+flowchart TD
+  Start[Pod 2+ starts] --> Watcher[PartitionPlanWatcher]
+  Watcher --> Create[createPlanTopicIfNotExists no-op]
+  Create --> Read[Read plan vN from Kafka]
+  Read --> Mem[Install in memory]
+  Mem --> Audits[Serve POST /access]
+  XML[XML config] -.->|not used for routing| Mem
+```
+
+**Do not** bootstrap-from-XML again if a plan message exists — avoids ConfigMap drift across pods.
+
+---
+
+### Race A — multiple pods create the plan **topic** at the same time
+
+Several ingestor pods can start together when `ranger_audit_partition_plan` **does not exist yet**. Each pod may call `listTopics()`, see nothing, and call `createTopics()` — same class of race as `ranger_audits` creation in `AuditMessageQueueUtils.createAuditsTopicIfNotExists()`.
+
+**Required behavior (idempotent topic create):**
+
+**Description:** Multiple pods may call `createTopics()` at once. **Already exists = success.** Only fail on real errors (ACL, Kafka down).
+
+| Step | Action |
+|------|--------|
+| 1 | `listTopics()` — if topic exists → OK, continue |
+| 2 | `createTopics(1 partition, cleanup.policy=compact)` |
+| 3 | Success → `waitUntilTopicReady` → continue |
+| 4 | Failure **already exists** → treat as success, `describe` topic, continue |
+| 5 | Other failure → fail startup with clear error |
+
+```mermaid
+flowchart TD
+  Start[createPlanTopicIfNotExists] --> List{Topic exists?}
+  List -->|Yes| OK[Return OK]
+  List -->|No| Create[createTopics]
+  Create --> Success{Result?}
+  Success -->|OK| Wait[waitUntilTopicReady]
+  Wait --> OK
+  Success -->|Already exists| OK
+  Success -->|Other error| Fail[Fail startup]
+```
+
+| Outcome | Pod behavior |
+|---------|----------------|
+| This pod creates topic | Log info, proceed to read/publish plan |
+| Peer created topic first | Catch already-exists, describe topic, proceed |
+| Create fails for other reason | Fail startup (Kafka unreachable, ACL denied) |
+
+```mermaid
+sequenceDiagram
+  participant PodA as ingestor pod A
+  participant PodB as ingestor pod B
+  participant Kafka as Kafka Admin
+
+  PodA->>Kafka: listTopics — plan topic missing
+  PodB->>Kafka: listTopics — plan topic missing
+  PodA->>Kafka: createTopics(ranger_audit_partition_plan)
+  PodB->>Kafka: createTopics(ranger_audit_partition_plan)
+  Kafka-->>PodA: OK
+  Kafka-->>PodB: already exists
+  PodB->>PodB: treat as success, continue
+  Note over PodA,PodB: both proceed to plan read / bootstrap
+```
+
+**Implementation note:** reuse or factor shared logic from `audit-common/.../AuditMessageQueueUtils.java` (`createAuditsTopicIfNotExists`) and add explicit **already-exists** handling if not present today (concurrent `createTopics` on `ranger_audits` has the same gap).
+
+---
+
+### Race B — multiple pods publish plan **v1** when topic exists but has no message
+
+**Description:** Topic exists but no plan message yet. Both pods may build v1 — **re-read before/after produce**; mandatory read-back; adopt Kafka’s plan.
+
+| Step | Action |
+|------|--------|
+| 1 | Both pods: `ensurePlanTopicExists()` (Race A done) |
+| 2 | Read plan → null |
+| 3 | Build v1 from XML |
+| 4 | **Re-read** — if v1 appeared → install, skip publish |
+| 5 | Produce local v1 (first wins on offset) |
+| 6 | **Mandatory re-read** → install stored plan (not local object only) |
+
+```mermaid
+flowchart TD
+  Start[bootstrapPlanIfEmpty] --> Ensure[Race A: topic exists]
+  Ensure --> Read1[Read plan from Kafka]
+  Read1 -->|plan exists| Install1[Install and return]
+  Read1 -->|empty| Build[Build v1 from XML]
+  Build --> Read2[Re-read plan]
+  Read2 -->|peer published| Install2[Install peer plan return]
+  Read2 -->|still empty| Produce[Produce local v1]
+  Produce --> Read3[Mandatory read-back]
+  Read3 --> Install3[Install Kafka plan]
+```
+
+```mermaid
+sequenceDiagram
+  participant A as pod A
+  participant B as pod B
+  participant Plan as ranger_audit_partition_plan
+
+  A->>Plan: read → empty
+  B->>Plan: read → empty
+  A->>Plan: produce v1
+  B->>Plan: produce v1 or re-read sees v1
+  A->>Plan: read-back → install v1
+  B->>Plan: read-back → install same v1
+  Note over A,B: both pods same routing
+```
+
+This preserves backward compatibility with `ranger-audit-ingestor-site.xml` for greenfield installs.
+
+---
+
+## Kafka read load (REST + background thread only)
+
+The plan topic is **low volume** (config, not audit events). Avoid reading it on the hot audit path.
+
+| Code path | Reads plan topic? | Notes |
+|-----------|-------------------|--------|
+| Plugin audit POST → `AuditMessageQueue` → `AuditPartitioner.partition()` | **No** | Reads `AtomicReference<PartitionPlan>` in memory only |
+| `PartitionPlanWatcher` (background thread) | **Yes** | Poll / consume on interval or on compacted message |
+| REST `GET /api/audit/partition-plan` | **Yes** | Admin read; may return cached in-memory plan if fresh |
+| REST `PUT` / promote / scale | **Yes** | Read current version, then produce new version |
+| Audit produce to `ranger_audits` | **No** | Unrelated topic |
+
+**Design rule:** at most **one background consumer per ingestor pod** plus **occasional REST reads/writes**. No per-request Kafka access for partition routing.
+
+Recommended watcher behavior:
+
+- **Startup:** one read to load initial plan (from compacted topic, or bootstrap-then-read).
+- **Runtime:** consumer poll with long interval (`refresh.interval.ms`, default 30s) **or** event-driven on new compacted message — not tight spin loops.
+- **On failure:** keep **last known good** plan in memory; do not block audit POST.
+
+With a single-partition compacted topic and ~30s refresh, Kafka load from N ingestor pods is negligible compared to `ranger_audits` traffic.
+
+**Append vs update:** each plan write adds a record; compaction + “latest per key” semantics mean the effective store is one current plan. See [Compacted topic semantics: append, retention, and performance](#compacted-topic-semantics-append-retention-and-performance).
+
+---
+
+## REST API (control plane)
+
+### GET `/api/audit/partition-plan`
+
+Returns current plan from registry (or bootstrap-derived plan if topic empty).
+
+### PUT `/api/audit/partition-plan`
+
+Full plan replace with optimistic locking:
+
+```json
+{
+  "expectedVersion": 4,
+  "topicPartitionCount": 28,
+  "plugins": { ... },
+  "buffer": { "partitions": [ ... ] }
+}
+```
+
+Reject with `409 Conflict` if `expectedVersion` ≠ current (prevents lost updates).
+
+### POST `/api/audit/partition-plan/promote-plugin` (convenience)
+
+Move plugin from buffer → dedicated partitions (server-side allocation):
+
+```json
+{
+  "pluginId": "trino",
+  "partitionCount": 3,
+  "expectedVersion": 4
+}
+```
+
+Server:
+
+1. Finds unassigned tail partition IDs (or increases topic first).
+2. Adds `trino` to `plan.plugins` with new IDs.
+3. Shrinks buffer list accordingly.
+4. Writes plan v5.
+
+### POST `/api/audit/partition-plan/scale-plugin` (convenience)
+
+Add capacity to existing plugin (append-only):
+
+```json
+{
+  "pluginId": "hiveServer2",
+  "additionalPartitions": 2,
+  "expectedVersion": 5
+}
+```
+
+Server adds 2 new partition IDs from tail to hive’s list; increases audit topic if needed.
+
+**Auth:** Kerberos/JWT + admin role (not the same as plugin audit POST users).
+
+---
+
+## PUT handler flow (detailed)
+
+**Description:** Admin PUT on any ingestor pod. Grow `ranger_audits` **before** publishing plan that references new partition IDs. Server assigns `version = N+1`; client sends `expectedVersion` only.
+
+| Step | Action |
+|------|--------|
+| 1 | Authenticate + authorize admin |
+| 2 | Load plan from compacted topic (version **N**) |
+| 3 | If `expectedVersion != N` → **409** + current plan |
+| 4 | Validate + allocate (promote / scale) |
+| 5 | If needed → `AdminClient.createPartitions(ranger_audits)` |
+| 6 | **Re-read** plan — still **N**? else **409** |
+| 7 | Produce plan **N+1** to plan topic |
+| 8 | **Read-back** — matches intent? else **409** |
+| 9 | Return **200** + full plan |
+
+```mermaid
+flowchart TD
+  Admin[Admin PUT] --> Auth[Auth + authorize]
+  Auth --> Load[Load plan vN]
+  Load --> Check1{expectedVersion = N?}
+  Check1 -->|No| R409a[409 + current plan]
+  Check1 -->|Yes| Valid[Validate + allocate]
+  Valid --> Grow{Need more partitions?}
+  Grow -->|Yes| CP[createPartitions ranger_audits]
+  Grow -->|No| Reread[Re-read plan]
+  CP --> Reread
+  Reread --> Check2{Still vN?}
+  Check2 -->|No| R409b[409 peer won]
+  Check2 -->|Yes| Produce[Produce vN+1]
+  Produce --> Back[Read-back verify]
+  Back --> Check3{Matches intent?}
+  Check3 -->|No| R409c[409 lost race]
+  Check3 -->|Yes| OK[200 + plan]
+```
+
+**Order matters:** increase audit topic **before** plan references new IDs.
+
+**Version is server-assigned** — clients must not set the new version number.
+
+---
+
+## Concurrent updates from multiple ingestor pods
+
+REST is exposed on **every** ingestor pod behind a load balancer. Two admins (or automation jobs) can hit **different pods at the same time**. Writes must not double-allocate partition IDs or overwrite each other silently.
+
+### Recommended approach: optimistic concurrency + compare-and-swap
+
+This is the **default** implementation — no leader election required.
+
+| Mechanism | Role |
+|-----------|------|
+| **`expectedVersion` in request** | Client declares which plan it based its change on |
+| **Early reject** | If compacted topic already at version ≠ `expectedVersion` → **409 Conflict** before allocation |
+| **Re-read before produce** | After `createPartitions` (if any), re-read topic; if version changed → **409** without producing |
+| **Single-partition plan topic** | All plan writes are totally ordered by Kafka offset |
+| **Read-back after produce** | Confirm the compacted value is the plan this handler intended; else **409** |
+| **Client retry** | On 409: `GET` latest plan, re-apply intent with new `expectedVersion` |
+
+```mermaid
+sequenceDiagram
+  participant AdminA as Admin / job A
+  participant PodA as ingestor pod A
+  participant PodB as ingestor pod B
+  participant PlanTopic as ranger_audit_partition_plan
+
+  Note over PlanTopic: current version = 4
+
+  AdminA->>PodA: POST scale-plugin expectedVersion=4
+  AdminA->>PodB: POST promote-plugin expectedVersion=4
+
+  PodA->>PlanTopic: read plan → v4
+  PodB->>PlanTopic: read plan → v4
+
+  PodA->>PodA: allocate + createPartitions if needed
+  PodB->>PodB: allocate + createPartitions if needed
+
+  PodA->>PlanTopic: re-read → still v4
+  PodB->>PlanTopic: re-read → still v4
+
+  PodA->>PlanTopic: produce v5 (scale hive)
+  PlanTopic-->>PodB: compacted update visible
+
+  PodB->>PlanTopic: re-read → now v5
+  PodB-->>AdminA: 409 Conflict + current plan v5
+
+  Note over AdminA: retry with expectedVersion=5
+
+  AdminA->>PodB: POST promote-plugin expectedVersion=5
+  PodB->>PlanTopic: read v5 → allocate → produce v6
+  PodB-->>AdminA: 200 OK plan v6
+```
+
+### What each outcome means
+
+| HTTP | Meaning | Client action |
+|------|---------|---------------|
+| **200** | This handler’s plan v(N+1) is in the compacted topic | Done |
+| **409 Conflict** | Stale `expectedVersion` or lost compare-and-swap race | `GET` plan, merge intent, retry with new `expectedVersion` |
+| **503** | `createPartitions` failed or Kafka produce failed | Retry same request (idempotent if version unchanged) |
+
+**409 response body** should include the **current plan** (version, plugins, buffer) so callers can retry without a separate GET.
+
+### Why this is safe for partition allocation
+
+Two pods both scaling from v4 might temporarily compute overlapping tail IDs in memory — only one produce wins the compare-and-swap. The loser gets **409** and must **re-read v5** and allocate from the **new tail**, not reuse its stale allocation. Append-only validation on PUT rejects plans that steal IDs already assigned in the current version.
+
+### Residual race: both produce before either re-reads
+
+**Description:** Plan topic has **one partition** — Kafka orders writes by offset. Only one v5 survives in compaction; loser returns **409**, client retries on winning plan.
+
+| Step | What happens |
+|------|----------------|
+| 1 | Pod A and B both pass re-read at v4 |
+| 2 | Both produce v5 — higher **offset wins** in compacted topic |
+| 3 | Loser read-back ≠ intended plan → **409** to client (not 200) |
+| 4 | All watchers load **single** winning v5 |
+
+```mermaid
+sequenceDiagram
+  participant A as pod A handler
+  participant B as pod B handler
+  participant Plan as plan topic 1 partition
+
+  Note over Plan: both saw v4 at re-read
+  A->>Plan: produce v5 offset 100
+  B->>Plan: produce v5 offset 101
+  Note over Plan: compaction keeps offset 101
+  A->>Plan: read-back
+  A-->>A: content != intent → 409
+  B->>Plan: read-back
+  B-->>B: matches → 200
+  Note over Plan: watchers all load one v5
+```
+
+No silent split-brain — one plan version in registry; loser retries with `expectedVersion=5`.
+
+### Optional: stricter serialization (if you want zero client retry)
+
+| Approach | When to use |
+|----------|-------------|
+| **K8s Lease** (`partition-plan-writer`) | Only the lease holder executes PUT/promote/scale; other pods return **503 Retry on leader** or proxy internally |
+| **Single admin job / CI** | Human or pipeline serializes changes — sufficient for many ops teams |
+| **Dedicated single-replica “admin” ingestor** | Extreme isolation; usually unnecessary |
+
+Start with **optimistic concurrency + compare-and-swap + client retry**. Add leader lease only if automation cannot tolerate 409 retries.
+
+### What ingestor pods do *not* do
+
+- **No cross-pod locking** on the audit POST path.
+- **No per-pod plan writes** from the watcher (watchers are **read-only**).
+- **No merge of concurrent admin intent on the server** — conflicts are explicit 409; the client or operator merges.
+
+---
+
+## How every ingestor pod stays in sync
+
+**Description:** Each pod runs **`PartitionPlanWatcher`** (background only). `AuditPartitioner` reads memory — never plan topic on audit POST.
+
+| Option | Behavior |
+|--------|----------|
+| **A — Consumer (recommended)** | Group `ranger_audit_partition_plan_watcher`; on message → validate → `partitionPlanRef.set()` |
+| **B — Periodic poll** | Every `refresh.interval.ms` (default 30s) read latest compacted value |
+
+```mermaid
+flowchart TB
+  Plan[(ranger_audit_partition_plan)]
+
+  subgraph pod1 [Ingestor pod 1]
+    W1[PartitionPlanWatcher]
+    M1[(Memory plan)]
+    P1[AuditPartitioner]
+    W1 --> M1 --> P1
+  end
+
+  subgraph pod2 [Ingestor pod 2]
+    W2[PartitionPlanWatcher]
+    M2[(Memory plan)]
+    P2[AuditPartitioner]
+    W2 --> M2 --> P2
+  end
+
+  Plan --> W1
+  Plan --> W2
+
+  Plugin1[Plugin POST] --> P1
+  Plugin2[Plugin POST] --> P2
+```
+
+**Latency:** all pods converge within ~30s or on Kafka message. **No restart** when plan changes.
+
+---
+
+## Pod crash / restart
+
+**Description:** Same as **Pod 2+** — memory lost on crash; plan survives in Kafka compacted topic.
+
+| Step | Action |
+|------|--------|
+| 1 | Pod dies — in-memory plan lost |
+| 2 | New pod starts |
+| 3 | Watcher reads plan **vN** from Kafka |
+| 4 | Install memory — routing restored |
+
+```mermaid
+flowchart LR
+  Crash[Pod crash] --> Lost[Memory lost]
+  Lost --> New[New pod starts]
+  New --> Read[Read plan vN from Kafka]
+  Read --> Mem[Install memory]
+  Mem --> OK[Same routing as other pods]
+```
+
+Plan is **not** on pod disk — Kafka compacted topic is durable store.
+
+---
+
+## Worked example: hdfs + hiveServer2, then promote trino
+
+**Initial plan (v1)** — from bootstrap or first PUT:
+
+| Plugin | Partitions |
+|--------|------------|
+| hdfs | [0,1,2] |
+| hiveServer2 | [3,4,5] |
+| buffer | [6..14] (9 partitions) |
+
+Topic: **15** partitions.
+
+**Unknown plugin `trino` sends audits** → routes to buffer (hash among [6..14]).
+
+**Admin: POST promote-plugin trino, count=3**
+
+1. Allocator takes IDs [6,7,8] from buffer (or adds tail if buffer policy prefers grow-first).
+2. buffer becomes [9..14].
+3. Plan v2 published.
+4. All ingestors pick up v2 within refresh interval.
+5. **No ingestor restart.**
+
+**Later: POST scale-plugin hiveServer2, additionalPartitions=3**
+
+1. Increase topic 15 → 18 if needed.
+2. Append partition IDs [15,16,17] to hiveServer2 list (append-only — hdfs and trino lists unchanged).
+3. Plan v3 published.
+
+This fixes the “change hdfs override reshuffles everyone” problem from static contiguous allocation.
+
+---
+
+## Solr / HDFS dispatchers
+
+Dispatchers (`README-KAFKA-DISPATCHERS.md`) **ignore** the partition plan:
+
+- They subscribe to **all** partitions of `ranger_audits`.
+- When audit topic grows 15 → 18, both consumer groups rebalance and assign new partitions.
+- No dispatcher code or config change for plugin onboarding.
+
+You may need to scale dispatcher `thread.count` / replicas if partition count grows significantly.
+
+---
+
+## Failure modes and handling
+
+| Failure | Behavior |
+|---------|----------|
+| Plan topic unreadable | Keep **last known good** plan in memory; log error; `/status` shows degraded |
+| Invalid plan JSON | Reject write at REST; do not apply on read |
+| AdminClient partition increase fails | Do **not** publish new plan; return 503 to caller |
+| Partial write (partitions increased but plan not written) | Retry PUT idempotently; allocator sees higher topic count |
+| Two concurrent PUTs (different pods) | `expectedVersion` + re-read before produce + read-back → one **200**, one **409**; client retries on latest version |
+| Plugin sends audits during plan swap | `AtomicReference` swap is atomic; brief mix of old/new routing acceptable for audits |
+
+---
+
+## Feature flag: backward compatibility (old vs dynamic behavior)
+
+**Description:** Dynamic mode is **opt-in**. Property **missing** or **`false`** → legacy behavior (today). **`true`** → Kafka plan topic + watcher + REST.
+
+Dynamic mode is **disabled** when:
+
+- `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled` is **`false`**, or
+- the property is **missing / not set** (default = **false**)
+
+```mermaid
+flowchart TD
+  Flag{dynamic.enabled?}
+  Flag -->|false or absent| Legacy[Legacy mode]
+  Flag -->|true| Dynamic[Dynamic mode]
+
+  Legacy --> L1[AuditPartitioner from XML at startup]
+  Legacy --> L2[No plan topic / no watcher]
+  Legacy --> L3[XML change + restart]
+
+  Dynamic --> D1[Plan from Kafka compacted topic]
+  Dynamic --> D2[Watcher + REST enabled]
+  Dynamic --> D3[XML bootstrap once if empty]
+```
+
+### When dynamic mode is OFF (default — today’s behavior)
+
+| Area | Behavior |
+|------|----------|
+| Partition mapping | `AuditPartitioner.configure()` at startup from XML: `configured.plugins`, overrides, contiguous ranges + buffer |
+| Topic partitions | Created/updated via `AuditMessageQueueUtils.getPartitions()` from XML (sum + buffer) |
+| Changes | Update XML → restart audit-ingestor |
+| REST `/api/audit/partition-plan` | **Not registered** or returns `404` / `503 Feature disabled` |
+| `PartitionPlanWatcher` | **Not started** |
+| Plan topic `ranger_audit_partition_plan` | **Not used** (may be omitted from cluster) |
+
+This preserves **100% backward compatibility** for existing deployments with no config change.
+
+### When dynamic mode is ON (`dynamic.enabled=true`)
+
+| Area | Behavior |
+|------|----------|
+| Partition mapping | Runtime `PartitionPlan` from Kafka compacted topic (XML seeds bootstrap only if plan topic empty) |
+| Topic partitions | AdminClient increase driven by plan / REST |
+| Changes | REST → Kafka plan topic; all pods refresh via watcher — **no restart** |
+| REST partition-plan endpoints | **Enabled** (admin AuthZ) |
+| `PartitionPlanWatcher` | **Started** on every ingestor pod |
+
+### Recommended default in code and sample XML
+
+```xml
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled</name>
+  <value>false</value>
+  <description>
+    Enable Kafka-backed dynamic partition plan (registry topic + REST + watcher).
+    Default false: use legacy XML-based AuditPartitioner behavior at startup.
+    If property is absent, treat as false.
+  </description>
+</property>
+```
+
+Only set to `true` after `ranger_audit_partition_plan` topic exists and ops are ready to manage plans via REST.
+
+### Property defaults when `dynamic.enabled=true`
+
+If dynamic mode is on, missing optional properties use **built-in defaults** (do not fall back to legacy XML routing):
+
+| Property | If absent | Effective value |
+|----------|-----------|-----------------|
+| `partition.plan.topic` | Use default | **`ranger_audit_partition_plan`** |
+| `partition.plan.refresh.interval.ms` | Use default | **`30000`** (30 seconds) |
+
+**Startup behavior with defaults:**
+
+**Description:** When `dynamic.enabled=true`, optional properties default as below. Fail startup if Kafka/plan topic unavailable — do not silently fall back to legacy XML.
+
+| Step | Action |
+|------|--------|
+| 1 | Resolve plan topic → **`ranger_audit_partition_plan`** (unless overridden) |
+| 2 | **`createPlanTopicIfNotExists()`** — idempotent ([Race A](#race-a--multiple-pods-create-the-plan-topic-at-the-same-time)) |
+| 3 | Start **`PartitionPlanWatcher`** |
+| 4 | If no plan message → bootstrap v1 from XML ([Race B](#race-b--multiple-pods-publish-plan-v1-when-topic-exists-but-has-no-message)) |
+
+```mermaid
+flowchart TD
+  Start[Ingestor startup dynamic=true] --> Topic[Resolve plan topic name]
+  Topic --> Create[createPlanTopicIfNotExists Race A]
+  Create --> Watcher[Start PartitionPlanWatcher]
+  Watcher --> Empty{Plan message empty?}
+  Empty -->|Yes| Boot[Bootstrap v1 from XML Race B]
+  Empty -->|No| Load[Load plan from Kafka]
+  Boot --> Ready[Ready serve audits]
+  Load --> Ready
+```
+
+**You do not need** to set `partition.plan.topic` unless using a non-default name.
+
+**Misconfiguration:** If `dynamic.enabled=true` but Kafka unreachable → **fail startup** (avoid split routing across pods).
+
+---
+
+## What stays in XML (bootstrap only)
+
+| Property | Role after dynamic mode |
+|----------|-------------------------|
+| `configured.plugins` | Initial plan seed only (first pod bootstrap when plan topic empty) |
+| `plugin.partition.overrides.*` | Initial counts when seeding v1 |
+| `topic.partitions.buffer` | Initial buffer list size when seeding v1 |
+| `topic.partitions.per.configured.plugin` | Default per-plugin count when seeding v1 (if no override) |
+| `partitioner.class` | Still `AuditPartitioner` at JVM startup |
+| `partition.plan.topic` | Compacted registry topic name; **default `ranger_audit_partition_plan`** if unset |
+| `partition.plan.dynamic.enabled` | **`false` by default** — set `true` to enable dynamic mode |
+
+When `dynamic.enabled` is **false** or **unset**, XML properties above drive **legacy startup behavior** (not bootstrap-only).
+
+Runtime changes (when dynamic enabled) go through **REST → Kafka plan topic**, not XML edits.
+
+---
+
+## Bootstrap configuration (new properties)
+
+```xml
+<!-- partition.plan.topic optional when dynamic=true; default ranger_audit_partition_plan -->
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.topic</name>
+  <value>ranger_audit_partition_plan</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms</name>
+  <value>30000</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled</name>
+  <value>false</value>
+  <description>Default false. Set true to enable dynamic partition plan. If absent, use legacy XML behavior.</description>
+</property>
+```
+
+Existing `configured.plugins` / overrides remain **bootstrap** when the compacted topic has no plan yet.
+
+---
+
+## Implementation order (recommended)
+
+**Description:** Build bottom-up — model and registry first, then partitioner + watcher, then REST and ops.
+
+| Phase | Deliverable |
+|-------|-------------|
+| 1 | `PartitionPlan` model + allocator tests (append-only) |
+| 2 | Registry read/write + `createPlanTopicIfNotExists` (Race A) |
+| 3 | Plan-aware `AuditPartitioner` + watcher + bootstrap (Race B) |
+| 4 | REST GET (inspect plan) |
+| 5 | REST PUT / promote / scale + AdminClient |
+| 6 | AuthZ + `/status` (`plan.version`, watcher timestamp) |
+| 7 | Ops runbook — REST only when dynamic=true → [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) |
+| 8 | Migrate deployments — publish v1 from current XML |
+
+```mermaid
+flowchart LR
+  P1[1 Model + allocator] --> P2[2 Registry + topic create]
+  P2 --> P3[3 Partitioner + watcher]
+  P3 --> P4[4 REST GET]
+  P4 --> P5[5 REST PUT promote scale]
+  P5 --> P6[6 AuthZ + status]
+  P6 --> P7[7 Runbook]
+  P7 --> P8[8 Migration v1]
+```
+
+---
+
+## Design rationale and tradeoffs
+
+**Assessment:** This is a **sound approach** for Ranger audit-ingestor: Kafka is already required, partition-plan changes are infrequent (ops events, not per-request), and the design keeps the audit hot path off Kafka. It is not the only valid design, but the tradeoffs fit the problem well.
+
+### Why this design works
+
+| Principle | How this design delivers |
+|-----------|--------------------------|
+| **Established pattern** | Kafka compacted topic as config store (same idea as Connect/Streams config topics): one key → latest plan, durable across restarts |
+| **Hot path stays fast** | `AuditPartitioner.partition()` reads `AtomicReference` only; plan topic touched by watcher + REST, not every audit POST |
+| **Append-only explicit lists** | Avoids reshuffling later plugins when an early plugin scales (main limitation of static contiguous XML allocation) |
+| **Multi-pod consistency** | Pod 1 seeds Kafka from XML once; pod 2+ and restarts read Kafka; all replicas converge on the same JSON |
+| **Safe rollout** | `dynamic.enabled` defaults to `false` — existing deployments unchanged |
+| **Clean consumer boundary** | Solr/HDFS dispatchers consume all partitions; plan is producer-side only |
+
+### Acceptable tradeoffs
+
+| Concern | Severity | Mitigation in this design |
+|---------|----------|---------------------------|
+| Kafka required at startup when dynamic=true | Medium | Fail startup with clear error; do not silently fall back to legacy XML (would split routing across pods) |
+| Two pods bootstrap race on empty plan topic | Low | **Race A:** idempotent `createPlanTopicIfNotExists` + already-exists OK; **Race B:** re-read before/after v1 produce |
+| Watcher refresh lag (~30s default) | Low | Acceptable for plugin onboarding; tune `refresh.interval.ms` if needed |
+| Ops edit XML expecting live effect | Medium | When dynamic=true, runbook: change plan via REST, not XML (XML is bootstrap-only) |
+| `createPartitions` succeeds but plan write fails | Medium | Increase audit topic **before** publishing plan; retry PUT idempotently |
+| ConfigMap drift between pods | Low | Kafka is source of truth once v1 exists |
+
+These are normal distributed-config caveats, not fundamental flaws.
+
+### When this approach is a poor fit
+
+Avoid dynamic mode (or reconsider the registry) if:
+
+- Plan changes happen **very frequently** (seconds) — watcher lag and consumer rebalance churn add cost.
+- Kafka is **unavailable or not part of the stack** — use legacy XML or an external config store instead.
+- You operate **many independent audit topics** with separate plans — still workable (one compacted key per topic) but REST and ops complexity grow.
+- You require **strict per-plugin ordering across plan migrations** — append-only reduces reshuffle risk, but any partition reassignment still needs operational care.
+
+For typical Ranger deployments (infrequent plugin onboard/scale, Kafka already present), none of these apply strongly.
+
+### Alternatives considered
+
+| Option | Tradeoff vs this design |
+|--------|-------------------------|
+| **XML + restart only** (today) | Simplest; no dynamic onboarding without downtime |
+| **Postgres / ZooKeeper** | Stronger CRUD and consistency; extra infra this design deliberately avoids |
+| **K8s ConfigMap + watch** | K8s-centric; awkward for mixed environments, multi-cluster, or REST-driven automation |
+| **Leader pod writes local XML** | Breaks with multiple replicas — rejected |
+
+Given **no new infra**, **multi-replica ingestor**, **REST-driven ops**, and **survive pod restart**, Kafka compacted topic + REST + background watcher is a strong fit.
+
+### Implementation guardrails
+
+1. **Bootstrap:** `createPlanTopicIfNotExists()` must be idempotent (Race A); after plan publish, always re-read compacted topic (Race B).
+2. **GET `/partition-plan`:** prefer in-memory plan for normal reads; optional force-read from Kafka for debugging.
+3. **`/status`:** expose `plan.version` and watcher last-updated timestamp.
+4. **PUT validation:** optional strict mode — reject writes that shrink or reassign existing plugin partition IDs.
+5. **Runbook:** document that when `dynamic.enabled=true`, runtime changes go through REST, not XML edits.
+
+---
+
+## Summary
+
+| Question | Answer |
+|----------|--------|
+| Postgres/ZK needed? | **No** — use Kafka compacted topic + AdminClient |
+| Update XML in pod? | **No** for runtime — XML is bootstrap only |
+| REST endpoint? | **Yes** — writes plan to Kafka + increases partitions via AdminClient |
+| Pod crash/restart? | Re-read plan from Kafka compacted topic |
+| Other pods notified? | All pods watch same topic / poll same plan |
+| Dispatchers affected? | Rebalance only when partition count grows; no plan API needed |
diff --git a/audit-server/README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md b/audit-server/README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md
new file mode 100644
index 000000000..3c6ec029c
--- /dev/null
+++ b/audit-server/README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md
@@ -0,0 +1,497 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic plugin onboarding + dynamic partition scaling (design notes)
+
+> **Consolidated design (start here for review):** [DESIGN-KAFKA-DYNAMIC-PARTITIONING.md](DESIGN-KAFKA-DYNAMIC-PARTITIONING.md) — architecture, flows, diagrams, brownfield migration, and Q&A in one document. This README adds engineering checklist and implementation detail.
+
+**Plain-language overview (operators, architects, new readers):** [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md)
+
+This document proposes **code/engineering changes** to evolve `audit-ingestor` plugin-based Kafka partitioning from **static-at-startup** to **runtime dynamic**:
+
+- onboard new plugins without restart
+- increase hot-plugin capacity without reshuffling existing plugins
+- (optionally) auto-increase Kafka topic partitions
+
+Current behavior (static config-based mapping) is documented in:
+
+- `audit-server/README-KAFKA-PLUGIN-PARTITIONING.md`
+
+**Detailed design (Kafka registry + REST):** `audit-server/README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md`  
+**Phased implementation plan (code + tests by phase):** [README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md](README-KAFKA-PARTITION-PLAN-IMPLEMENTATION.md)  
+**Producer performance (separate topic):** `audit-server/README-KAFKA-PRODUCER-PERFORMANCE.md`
+
+---
+
+## Current limitation (why changes are needed)
+
+Today `AuditPartitioner` builds plugin → partition-range mapping once in `configure()`. There is:
+
+- no runtime reload of `configured.plugins` / overrides
+- no durable record of “which plugin owns which partitions”
+- no safe way to add a new plugin without changing ranges for other plugins (contiguous-range algorithm depends on ordering)
+
+So “dynamic” today requires: config update + topic partition update + **restart**.
+
+---
+
+## Goals and non-goals
+
+### Goals
+
+- **G1: Stable allocations**: onboarding/scaling a plugin should not move other plugins’ traffic unnecessarily.
+- **G2: Runtime updates**: update mapping without restarting `audit-ingestor`.
+- **G3: Append-only growth**: only allocate from newly added tail partitions (Kafka can increase partitions, not decrease).
+- **G4: Backward compatibility**: existing config (`configured.plugins`, overrides) can still be used as a bootstrap/default.
+
+### Non-goals
+
+- Decreasing topic partition counts (Kafka does not support shrinking partitions).
+- Perfect global ordering guarantees across plugins (already not guaranteed when plugins use multiple partitions).
+
+---
+
+## Recommended architecture (pragmatic)
+
+### 1) Introduce a Partition Registry (source of truth)
+
+Define a small interface (conceptually):
+
+- **Inputs**: topic name
+- **Outputs**:
+  - plugin → assigned partitions (range or explicit list)
+  - buffer partition set (for unconfigured/unonboarded plugins)
+  - topic partition count the plan was built for (for safety)
+
+Backend choices (pick one based on your environment):
+
+| Backend | New infra? | Multi-pod sync | Survives pod restart | Notes |
+|---------|------------|----------------|----------------------|-------|
+| **Kafka compacted config topic** (recommended) | No — uses existing Kafka | Yes — all ingestors consume same topic | Yes — plan lives in Kafka | Best fit when ingestor already depends on Kafka |
+| **File-based JSON** (ConfigMap + volume) | Minimal | Requires shared read + rollout or poll | Only if volume/ConfigMap is durable | Good for single replica or GitOps rollout |
+| **DB (Postgres)** | Yes | Yes | Yes | Auditable; **not** a current ingestor dependency |
+| **ZooKeeper** | Yes | Yes | Yes | Kafka-era pattern; **not** a current ingestor dependency |
+
+**Operational preference:** avoid Postgres/ZooKeeper for partition plan storage. Use **Kafka as the source of truth** plus **Kafka AdminClient** for partition increases — both are already required for audit-ingestor.
+
+See [Alternative: Kafka-backed registry + REST (no Postgres/ZK)](#alternative-kafka-backed-registry--rest-no-postgreszk) below.
+
+### 2) Make `AuditPartitioner` consume a Partition Plan
+
+Replace “compute ranges from configured.plugins at startup” with:
+
+- `AtomicReference<PartitionPlan>` inside partitioner
+- `partition()` consults the current plan
+
+Plan contents:
+
+- `Map<String, IntRange>` OR `Map<String, int[]>` (explicit partitions)
+- `int[] bufferPartitions` OR `(bufferStart, bufferCount)` if contiguous
+- metadata:
+  - `planVersion`
+  - `topicPartitionCount`
+  - timestamps
+
+### 3) Add runtime refresh (no restart)
+
+In `AuditPartitioner.configure()`:
+
+- build initial plan (from registry or fallback config)
+- start a lightweight scheduled refresh (every N seconds) that:
+  - reads registry
+  - validates it against current Kafka topic partitions (from `Cluster.partitionsForTopic`)
+  - atomically swaps the plan
+
+Refresh should be:
+
+- safe under concurrent calls to `partition()`
+- resilient to registry failures (keep last known good plan)
+
+### 4) Adopt an append-only allocation rule (critical)
+
+To avoid reshuffling existing plugins:
+
+- never recompute ranges based on `configured.plugins` ordering
+- when a plugin needs more capacity or a new plugin is promoted:
+  - **increase topic partitions** (if needed)
+  - allocate only from the **new tail partitions** (previously unassigned)
+
+This preserves:
+
+- existing plugin partition ownership
+- consumer-side locality and throughput behavior
+
+---
+
+## Optional: Auto-increase topic partitions (AdminClient)
+
+If you want `audit-ingestor` to scale partitions automatically:
+
+- add a component using Kafka `AdminClient` to:
+  - fetch current partition count
+  - increase partitions when requested by the control plane / policy
+
+Important considerations:
+
+- permissions: `CreatePartitions` / topic admin rights required
+- coordination: avoid multiple ingestors racing (use registry/DB lock or single leader)
+- safety: only increase; never attempt decrease
+
+---
+
+## Onboarding workflow (suggested)
+
+### Stage 0: Unknown plugin arrives
+
+- plugin id not in registry
+- route to **buffer partitions**
+- monitor per-plugin volume (metrics/logging)
+
+### Stage 1: Promote plugin
+
+- update registry to assign dedicated partitions (initial allocation)
+- plan refresh applies it without restart
+
+### Stage 2: Scale hot plugin
+
+When metrics indicate sustained load:
+
+- add more partitions to the topic (if needed)
+- allocate additional tail partitions to that plugin in the registry
+- refresh applies change
+
+---
+
+## Suggested registry data model (example JSON)
+
+This is an example shape (not a committed schema):
+
+```json
+{
+  "topic": "ranger_audits",
+  "version": 12,
+  "topicPartitionCount": 48,
+  "plugins": {
+    "hdfs":        { "partitions": [0,1,2,3,4,5] },
+    "hiveServer2": { "partitions": [6,7,8,9,10,11] },
+    "trino":       { "partitions": [12,13,14,15,16,17,18,19,20] }
+  },
+  "buffer": { "partitions": [21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47] }
+}
+```
+
+If you prefer ranges:
+
+- `{"range": {"start": 0, "end": 5}}` etc.
+
+---
+
+## Key trade-offs and decisions
+
+- **Explicit partition lists vs ranges**
+  - lists give maximum flexibility (non-contiguous tail allocations)
+  - ranges are simpler but can constrain append-only growth if you want to keep partitions contiguous
+
+- **Who writes the registry**
+  - manual ops (initially)
+  - future: automated controller (Kubernetes job / service) that watches metrics and updates registry
+
+- **Ordering guarantees**
+  - allocating multiple partitions per plugin increases throughput but reduces strict per-plugin ordering across partitions
+  - ensure consumers don’t rely on strict order across partitions for correctness
+
+---
+
+## Implementation checklist (code vs deployment)
+
+This section is a concrete “what to change” checklist to implement dynamic onboarding/scaling and to run multiple ingestor replicas safely.
+
+### Code changes (dynamic partitioning)
+
+- **Partition plan model**
+  - Add a `PartitionPlan` representation (plugin → partitions/ranges + buffer partitions + metadata: version, topic partition count).
+- **Partition registry**
+  - Add a `PartitionRegistry` interface; **required impl for dynamic mode:** Kafka compacted topic (`ranger_audit_partition_plan`).
+  - XML / `configured.plugins` seeds the **initial** plan only when the compacted topic is empty (first pod bootstrap); avoid Postgres/ZK unless already in your stack.
+- **`AuditPartitioner` runtime plan**
+  - Replace one-time contiguous-range calculation with `AtomicReference<PartitionPlan>`.
+  - `partition()` consults the current plan loaded from the registry (in memory on the hot path).
+  - Do not use a config-only plan without the registry for runtime updates or multi-pod consistency.
+- **Refresh loop (no restart)**
+  - Add a scheduled refresh (every N seconds) to reload the registry and atomically swap the plan.
+  - Validate the plan against `Cluster.partitionsForTopic(topic)` before applying.
+- **Append-only allocation rule**
+  - Add an allocation strategy/tooling so new plugins and “add capacity” operations allocate only from **new tail partitions** (no reshuffle of existing plugin allocations).
+- **Optional: Kafka AdminClient**
+  - Add an AdminClient helper to increase topic partitions when the control plane requests it (increase-only).
+- **Testing**
+  - Concurrency tests: plan swap while `partition()` is hot.
+  - Behavior tests: configured plugin routing vs buffer routing; promotion/scaling does not move existing allocations.
+
+### Code changes (audit recovery)
+
+- **No code changes required** for the current recovery flow (per-pod spool + per-pod retry).
+- Code changes are only needed if you want shared/centralized retry across replicas (leader election/locking or external queue), which is a separate design.
+
+### Deployment/config changes (dynamic mapping control plane)
+
+- **Kafka compacted plan topic**
+  - Create `ranger_audit_partition_plan` (1 partition, cleanup.policy=compact).
+  - Grant ingestor principal permission to produce to plan topic and `createPartitions` on audit topic.
+- **Bootstrap XML**
+  - Keep `configured.plugins` / overrides as defaults when plan topic is empty.
+  - First pod with `dynamic.enabled=true` publishes v1 from XML to `ranger_audit_partition_plan` (see [First pod bootstrap](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#first-pod-xml-populates-the-plan-topic)).
+- **Refresh interval**
+  - `ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms`
+- **REST admin auth**
+  - Restrict partition-plan endpoints to admin roles (same pattern as audit `/access` authorization).
+
+---
+
+See [Detailed elaboration: Kafka-backed registry + REST](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md) for the full end-to-end design (architecture, REST API, multi-pod sync, examples).
+
+### What not to do: edit XML inside the pod filesystem
+
+Properties like these are **bootstrap defaults**, not a good runtime store for a multi-replica deployment:
+
+- `ranger.audit.ingestor.kafka.configured.plugins`
+- `ranger.audit.ingestor.kafka.partitioner.class`
+- `ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin`
+- `ranger.audit.ingestor.kafka.plugin.partition.overrides.<plugin>`
+
+If a REST handler only writes `ranger-audit-ingestor-site.xml` on **one pod’s local disk**:
+
+- **Other pods never see the change** (each pod has its own filesystem).
+- **Restart/reschedule loses the change** (ephemeral container filesystem).
+- **Rolling update from Git/ConfigMap** can overwrite in-memory or local edits.
+
+**Runtime partition plan must live in durable shared storage** — recommended: a **Kafka compacted topic**, not pod-local XML.
+
+Keep XML/ConfigMap for **initial bootstrap** (first startup when no plan exists yet). See [First pod: XML populates the plan topic](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#first-pod-xml-populates-the-plan-topic).
+
+#### First pod bootstrap (XML → `ranger_audit_partition_plan`)
+
+Requires `ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled=true`.
+
+| Step | What happens |
+|------|----------------|
+| 1 | First ingestor pod starts; plan topic is empty |
+| 2 | Watcher reads XML: `configured.plugins`, overrides, buffer, default per-plugin count |
+| 3 | Builds plan **v1** (contiguous ranges → explicit partition lists) |
+| 4 | **Publishes v1** to `ranger_audit_partition_plan` (key `ranger_audits`) |
+| 5 | Loads v1 into memory; serves audits |
+
+Later pods and restarts **read Kafka only** — they do not re-seed from XML.
+
+| Condition | Plan topic populated from XML? |
+|-----------|-------------------------------|
+| `dynamic.enabled=true`, empty plan topic | **Yes** (first pod) |
+| `dynamic.enabled=true`, plan exists | **No** |
+| `dynamic.enabled=false` or absent | **No** (legacy mode; plan topic unused) |
+
+**Example v1** and full property list: [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md → First pod: XML populates the plan topic](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#first-pod-xml-populates-the-plan-topic).
+
+### Recommended design: Kafka compacted topic as partition registry
+
+Introduce a dedicated Kafka topic, e.g. `ranger_audit_partition_plan`:
+
+| Property | Suggested value |
+|----------|-----------------|
+| Partitions | 1 (single key = audit topic name) |
+| Cleanup policy | `compact` (keeps latest plan per key) |
+| Retention | compacted — survives broker retention if configured appropriately |
+
+**Message key:** audit topic name (e.g. `ranger_audits`)  
+**Message value:** JSON `PartitionPlan` (version, explicit partition lists per plugin, buffer list, `topicPartitionCount`)
+
+**Append vs update, compaction, and performance:** each plan change appends a new record (not an in-place edit); compaction retains the latest value per key. This does not affect audit ingest hot path. Details: [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md → Compacted topic semantics](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#compacted-topic-semantics-append-retention-and-performance).
+
+**Why this works without new dependencies:**
+
+- Ingestor already connects to Kafka (producer + existing `AdminClient` for topic create).
+- Plan is **durable in Kafka** → survives ingestor pod crash/restart.
+- All ingestor replicas **read the same plan** → consistent routing.
+
+### Kafka AdminClient: increase audit topic partitions
+
+When the plan needs more capacity (new plugin, scale hot plugin, grow buffer):
+
+1. Compute required `topicPartitionCount` (append-only: only add **tail** partitions).
+2. Call `AdminClient.createPartitions()` on `ranger_audits` (increase only).
+3. Publish updated `PartitionPlan` JSON to `ranger_audit_partition_plan`.
+
+Reuse/extend existing logic in `AuditMessageQueueUtils` (already increases partitions on startup for static config).
+
+**Permissions:** ingestor service principal needs `ALTER` / create-partitions on the audit topic.
+
+### New REST endpoint on `AuditREST` (control plane)
+
+Add an admin-only API (authenticated, not public like `/health`), e.g.:
+
+```text
+PUT /api/audit/partition-plan
+GET /api/audit/partition-plan
+POST /api/audit/partition-plan/promote-plugin   (optional convenience)
+POST /api/audit/partition-plan/scale-plugin     (optional convenience)
+```
+
+**Handler flow (single transactional intent):**
+
+1. Validate request (plugin id, desired partition count, append-only rules).
+2. Load current plan from Kafka compacted topic (or bootstrap from XML if empty).
+3. Allocate new partitions from **tail only** (do not reshuffle existing plugin lists).
+4. If `requiredPartitions > currentTopicPartitions` → `AdminClient.createPartitions`.
+5. Write new plan to `ranger_audit_partition_plan` (bump `version`).
+6. Return new plan + version.
+
+**Do not** rewrite `ranger-audit-ingestor-site.xml` on the pod for runtime updates.
+
+Optional: after successful Kafka write, ops may update Git/ConfigMap **as documentation** — not required for runtime.
+
+### How ingestor pods apply changes (no restart)
+
+Each ingestor pod runs a **`PartitionPlanWatcher`** background thread only:
+
+```text
+Startup (first pod, empty topic):
+  1. Build v1 from XML → publish to compacted topic → install in AtomicReference
+
+Startup (later pods or restart):
+  1. Read latest plan from compacted topic → install in AtomicReference
+  2. Do NOT re-bootstrap from XML if plan exists
+
+Runtime:
+  3. Watcher consumes/polls plan topic (interval refresh)
+  4. On new plan version → validate → atomic swap in AuditPartitioner
+
+Audit hot path:
+  5. AuditPartitioner.partition() → partitionPlanRef.get() only (no Kafka)
+```
+
+**Multi-pod:** pod 1 seeds Kafka from XML once; pod 2+ always use Kafka. REST and watcher are the **only** components that read/write the plan topic.
+
+**Crash / restart:** pod reconnects to Kafka, reads latest compacted plan → **same routing as before crash**. No dependency on pod-local files.
+
+**Other pods:** each pod’s watcher sees the same compacted message → **all ingestors route consistently** within seconds (bounded by poll interval).
+
+See `README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md` → **Bootstrap and multi-pod startup** and **Kafka read load**.
+
+### Multi-pod REST: who handles the PUT?
+
+Any ingestor pod can serve REST behind the load balancer. **Writes are coordinated** without a leader by default:
+
+| Approach | Complexity | Recommendation |
+|----------|------------|----------------|
+| **Optimistic concurrency + compare-and-swap** (`expectedVersion`, re-read before produce, read-back) | Low | **Default** — client retries on 409 |
+| **Single leader** (only one pod executes PUT) | Medium | Optional — K8s Lease if zero 409 retries is required |
+| **External operator** (CI job calls REST once) | Low | Good for manual onboarding |
+
+**Full flow, sequence diagram, and 409 retry pattern:** [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md → Concurrent updates from multiple ingestor pods](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#concurrent-updates-from-multiple-ingestor-pods)
+
+Avoid two concurrent PUTs allocating the same tail partitions — server always re-reads before produce; loser gets 409 and must allocate from the new tail on retry.
+
+### Mapping from today’s XML properties to the plan
+
+| Today (XML) | Dynamic model |
+|-------------|---------------|
+| `configured.plugins` | Keys in `plan.plugins` |
+| `plugin.partition.overrides.<plugin>` | Length of `plan.plugins[plugin].partitions` (explicit list, not contiguous ranges) |
+| `topic.partitions.per.configured.plugin` | Default count when **promoting** a new plugin |
+| `topic.partitions.buffer` | `plan.buffer.partitions` list (grow tail when buffer shrinks) |
+| `partitioner.class` | Still set once at bootstrap (`AuditPartitioner`); runtime behavior from plan |
+
+**Append-only example:** hdfs has `[0,1,2]`; scale hdfs to 4 → allocate partition `3` from new tail (after topic increase), new list `[0,1,2,3]` — hive/trino lists **unchanged**.
+
+This avoids the reshuffle problem documented in `README-KAFKA-PLUGIN-PARTITIONING.md` when changing early plugins in contiguous-range mode.
+
+### Impact on Solr/HDFS dispatchers
+
+**No change required** for dispatchers when the plan updates:
+
+- They consume **all** partitions of `ranger_audits` via their consumer groups (`README-KAFKA-DISPATCHERS.md`).
+- More partitions → rebalance → more consumer parallelism (up to partition count).
+- They do **not** read `configured.plugins` or partition overrides.
+
+Tune dispatchers separately (`CooperativeStickyAssignor`, `max.poll.interval.ms`, etc.) if hot plugins increase partition traffic.
+
+### Impact on recovery (`AuditRecoveryManager` / `AuditRecoveryWriter` / `AuditRecoveryRetry`)
+
+No code change required for recovery. Retries resend `(topic, key=agentId, value)`; partition may differ if plan changed since original send — acceptable for audit pipelines.
+
+### Phased implementation (Kafka-centric)
+
+Dynamic partitioning is **not** viable without a shared registry (Kafka compacted plan topic). Do not ship an in-memory-only or config-only intermediate — it is not durable or safe across pods/restarts.
+
+1. **`PartitionPlan` + append-only allocator** (unit tests).
+2. **Kafka registry**: compacted topic create + read/write helpers.
+3. **`AuditPartitioner`**: `AtomicReference` + plan-based routing (XML bootstrap only when plan topic is empty).
+4. **`PartitionPlanWatcher`**: background refresh on all ingestor pods.
+5. **`AuditREST` admin endpoints**: promote/scale plugin → AdminClient + registry write.
+6. **AuthZ** on admin endpoints (same pattern as `/access` allowed-users).
+7. **Metrics/logging**: expose current `plan.version` on `/status`.
+8. **Ops runbook**: [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md) — REST workflow, 409 retry, sample XML.
+9. **Brownfield migration**: [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md) — pre-seed plan v1, cutover checklist, rollback.
+
+### Configuration additions (bootstrap / feature flag)
+
+```xml
+<!-- Optional: only needed when enabling dynamic mode -->
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.topic</name>
+  <value>ranger_audit_partition_plan</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms</name>
+  <value>30000</value>
+</property>
+<property>
+  <name>ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled</name>
+  <value>false</value>
+  <description>
+    false or absent = legacy XML AuditPartitioner at startup (today's behavior).
+    true = Kafka registry + REST + PartitionPlanWatcher.
+  </description>
+</property>
+```
+
+When **`dynamic.enabled` is `false` or not set**: use existing `configured.plugins` / overrides / restart workflow (`README-KAFKA-PLUGIN-PARTITIONING.md`).
+
+When **`dynamic.enabled` is `true`**: `configured.plugins` / overrides seed the initial plan only if the compacted topic is empty. **`partition.plan.topic` is optional** — defaults to `ranger_audit_partition_plan`.
+
+See `README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md` → **Feature flag: backward compatibility** and **Property defaults when dynamic.enabled=true**.
+
+**Operators:** step-by-step enablement and REST examples → [README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md](README-KAFKA-PARTITION-PLAN-OPS-RUNBOOK.md). Live-cluster cutover → [README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md](README-KAFKA-PARTITION-PLAN-BROWNFIELD-MIGRATION.md).
+
+### Design assessment
+
+The recommended approach (Kafka compacted plan topic + REST + background watcher, in-memory partitioner on the audit hot path) is **appropriate for Ranger**: Kafka is already required, plan changes are rare, and multi-pod consistency does not depend on pod-local files. Tradeoffs (startup dependency on Kafka when dynamic=true, ~30s watcher convergence, bootstrap race handling) are acceptable for plugin onboarding workflows.
+
+**Full rationale, alternatives, and when *not* to use this pattern:** [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md → Design rationale and tradeoffs](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#design-rationale-and-tradeoffs)
+
+### Summary
+
+| Question | Answer |
+|----------|--------|
+| Postgres/ZK needed? | **No** — use Kafka compacted topic + AdminClient |
+| Update XML in pod? | **No** for runtime — XML is bootstrap only |
+| REST endpoint? | **Yes** — writes plan to Kafka + increases partitions via AdminClient |
+| Pod crash/restart? | Re-read plan from Kafka compacted topic |
+| Other pods notified? | All pods watch same topic / poll same plan |
+| Dispatchers affected? | Rebalance only when partition count grows; no plan API needed |
+
+**Full design:** [README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md)
+
diff --git a/audit-server/README-KAFKA-PLUGIN-PARTITIONING.md b/audit-server/README-KAFKA-PLUGIN-PARTITIONING.md
new file mode 100644
index 000000000..380980493
--- /dev/null
+++ b/audit-server/README-KAFKA-PLUGIN-PARTITIONING.md
@@ -0,0 +1,307 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Kafka producer partitioning: plugin-based allocation (audit-ingestor)
+
+**Design review summary:** [DESIGN-KAFKA-AUDIT-SERVER.md](DESIGN-KAFKA-AUDIT-SERVER.md) (short, non-duplicative).
+
+This document explains how **audit-ingestor** (Kafka producer) allocates Kafka partitions per Ranger plugin (appId/agentId), and how to plan onboarding and scaling as new plugins are added over time.
+
+Dynamic partitioning (plain-language guide): [README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md](README-KAFKA-DYNAMIC-PARTITIONING-GUIDE.md)  
+Engineering design notes: [README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md](README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md)  
+**Detailed Kafka registry + REST design:** `README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md`  
+**Producer throughput / tuning gaps:** `README-KAFKA-PRODUCER-PERFORMANCE.md`
+
+---
+
+## How partitions get allocated per plugin (current audit-ingestor code)
+
+### Key idea: Kafka record key = plugin id
+
+`audit-ingestor` publishes audit events to Kafka with:
+
+- **topic**: `ranger.audit.ingestor.kafka.topic.name` (default `ranger_audits`)
+- **key**: `AuthzAuditEvent.getAgentId()` (plugin id / agentId / appId)
+- **value**: serialized audit JSON
+
+This matters because Kafka partitioning is **key-based**.
+
+### Two producer modes
+
+`AuditProducer` chooses the partitioning strategy based on:
+
+- `ranger.audit.ingestor.kafka.configured.plugins`
+
+#### Mode A: Plugin-based partitioning (custom partitioner)
+
+If `ranger.audit.ingestor.kafka.configured.plugins` is **non-empty**, the producer uses a custom partitioner:
+
+- `ranger.audit.ingestor.kafka.partitioner.class` (default `org.apache.ranger.audit.producer.kafka.AuditPartitioner`)
+
+Allocation algorithm (`AuditPartitioner`):
+
+1. Parse `configured.plugins` list.
+2. For each configured plugin, assign a **contiguous range** of partitions.
+   - Default partitions per plugin:
+     - `ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin` (default `3`)
+   - Optional per-plugin override:
+     - `ranger.audit.ingestor.kafka.plugin.partition.overrides.<plugin>=<N>`
+3. The remaining partitions become the **buffer** range used for any plugin not listed in `configured.plugins`.
+
+Routing behavior:
+
+- **Configured plugin**: round-robin within its allocated range (load-balances that plugin across multiple partitions).
+- **Unconfigured plugin**: hash within the buffer range (shares buffer partitions with other unconfigured plugins).
+
+#### Mode B: Hash-based (Kafka default partitioner)
+
+If `configured.plugins` is **empty/not set**, the producer uses Kafka’s default hashing partitioner.
+
+- In this mode, the relevant partition count is:
+  - `ranger.audit.ingestor.kafka.topic.partitions`
+
+All plugins share all partitions based on hash(key).
+
+---
+
+## By default: how many Kafka partitions are created?
+
+### Plugin-based mode (`configured.plugins` is set)
+
+Topic creation (`AuditMessageQueueUtils.getPartitions`) **auto-calculates** partition count:
+
+```text
+topic partitions = Σ (partitions per plugin in configured.plugins) + buffer partitions
+```
+
+| Property | Default (shipped sample) | Role |
+|----------|--------------------------|------|
+| `ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin` | **3** | Per plugin unless overridden |
+| `ranger.audit.ingestor.kafka.topic.partitions.buffer` | **9** | Reserved for plugins **not** in the list |
+| `ranger.audit.ingestor.kafka.plugin.partition.overrides.<plugin>` | (none) | Optional per-plugin count |
+
+`ranger.audit.ingestor.kafka.topic.partitions` (default **10** in XML) is used for **hash-based mode only**. In plugin-based mode, topic create/update uses the sum formula above, not `10`.
+
+**Shipped sample XML** lists many plugins in `configured.plugins` (hdfs, yarn, knox, hiveServer2, …). With defaults that yields a **large** topic (e.g. 13 plugins × 3 + 9 buffer = **48**). For a minimal deployment, shorten `configured.plugins` to only plugins you actually use.
+
+### Hash-based mode (`configured.plugins` empty)
+
+Topic uses `ranger.audit.ingestor.kafka.topic.partitions` → default **10**.
+
+### Operational note (`topic.partitions` vs partitioner)
+
+`AuditPartitioner` also reads `topic.partitions` for buffer sizing at startup, while topic creation uses the calculated sum. For consistent layout, align `topic.partitions` with the calculated total or rely on Kafka cluster metadata at produce time (partitioner uses actual topic size when routing).
+
+---
+
+## Walkthrough: hdfs + hiveServer2, then trino, then hot-plugin overrides
+
+Examples use a **minimal** plugin list (not the full default list in sample XML):
+
+```properties
+ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin=3
+ranger.audit.ingestor.kafka.topic.partitions.buffer=9
+```
+
+### Phase 1: Start with HDFS + Hive only
+
+```properties
+ranger.audit.ingestor.kafka.configured.plugins=hdfs,hiveServer2
+```
+
+| Plugin | Partitions | Partition IDs |
+|--------|------------|---------------|
+| hdfs | 3 (default) | **0–2** |
+| hiveServer2 | 3 (default) | **3–5** |
+| buffer (unconfigured / future plugins) | 9 | **6–14** |
+
+**Topic created:** `3 + 3 + 9 = **15 partitions**` (0..14)
+
+Trino (or storm/knox/kms, etc.) before onboarding → **buffer** (6–14), hash-distributed within buffer.
+
+### Phase 2: Add Trino later
+
+1. Append `trino` to `configured.plugins` (do **not** reorder existing entries).
+2. Increase topic to **18** partitions (ingestor can increase existing topic on startup).
+3. **Restart audit-ingestor** (ranges computed at producer startup).
+
+```properties
+ranger.audit.ingestor.kafka.configured.plugins=hdfs,hiveServer2,trino
+```
+
+| Plugin | Partitions | Partition IDs |
+|--------|------------|---------------|
+| hdfs | 3 | **0–2** |
+| hiveServer2 | 3 | **3–5** |
+| trino | 3 | **6–8** |
+| buffer | 9 | **9–17** |
+
+**Topic:** `3 + 3 + 3 + 9 = **18 partitions**`
+
+### Phase 3: Hot plugins — more partitions (overrides)
+
+In plugin-based mode, a hot plugin can only use **its own** partition range. Increase throughput with overrides:
+
+```properties
+ranger.audit.ingestor.kafka.plugin.partition.overrides.hiveServer2=6
+ranger.audit.ingestor.kafka.plugin.partition.overrides.trino=9
+# hdfs stays default 3
+ranger.audit.ingestor.kafka.configured.plugins=hdfs,hiveServer2,trino
+ranger.audit.ingestor.kafka.topic.partitions.buffer=9
+```
+
+| Plugin | Partitions | Partition IDs |
+|--------|------------|---------------|
+| hdfs | 3 | **0–2** |
+| hiveServer2 | **6** | **3–8** |
+| trino | **9** | **9–17** |
+| buffer | 9 | **18–26** |
+
+**Topic:** `3 + 6 + 9 + 9 = **27 partitions**` (0..26)
+
+**Steps:**
+
+1. Set overrides in `ranger-audit-ingestor-site.xml`.
+2. Ensure Kafka topic has **≥ 27** partitions.
+3. Restart **audit-ingestor**.
+4. Scale **Solr/HDFS dispatchers** (consumer parallelism per group is capped by topic partition count).
+
+### Quick reference table
+
+| Stage | `configured.plugins` | Overrides | Topic partitions |
+|-------|----------------------|-----------|------------------|
+| Start | `hdfs,hiveServer2` | none | **15** |
+| + trino | `hdfs,hiveServer2,trino` | none | **18** |
+| Hot hive + trino | `hdfs,hiveServer2,trino` | hiveServer2=6, trino=9 (hdfs=3) | **27** |
+| Hot hive + trino + hdfs | same | hiveServer2=6, trino=9, **hdfs=4** | **28** |
+
+### Later change: add `plugin.partition.overrides.hdfs=4`
+
+If you already run Phase 3 (hdfs=3, hiveServer2=6, trino=9, topic **27** partitions) and later set:
+
+```properties
+ranger.audit.ingestor.kafka.plugin.partition.overrides.hdfs=4
+```
+
+Allocation is still **contiguous in list order** (`hdfs`, then `hiveServer2`, then `trino`). Only hdfs’s block grows; every later plugin’s partition **numbers shift**.
+
+| Plugin | Partitions | Before (hdfs=3) | After (hdfs=4) |
+|--------|------------|-----------------|----------------|
+| hdfs | **4** | 0–2 | **0–3** |
+| hiveServer2 | 6 | 3–8 | **4–9** (+1 shift) |
+| trino | 9 | 9–17 | **10–18** (+1 shift) |
+| buffer | 9 | 18–26 | **19–27** (+1 shift) |
+
+**Topic:** `4 + 6 + 9 + 9 = **28 partitions**` (0..27) — one more than the 27-partition layout.
+
+**Operational steps:**
+
+1. Add `ranger.audit.ingestor.kafka.plugin.partition.overrides.hdfs=4`.
+2. Increase Kafka topic partitions **27 → 28** (ingestor can increase on startup).
+3. Restart **audit-ingestor**.
+4. Solr/HDFS dispatchers will **rebalance**; hive/trino traffic moves to new partition IDs.
+
+**Important:** Changing an early plugin’s partition count reshuffles ranges for all plugins listed after it. To avoid that in production, prefer **append-only** growth (allocate new capacity from new tail partitions only) — see `README-KAFKA-PLUGIN-PARTITIONING-DYNAMIC-DESIGN.md`.
+
+### Phase 4: Add more plugins over months (storm/knox/kms, …)
+
+- New plugin can send audits immediately → lands in **buffer** (no config change).
+- To dedicate capacity: append to `configured.plugins`, add override if high volume, increase topic partitions, restart ingestor.
+
+---
+
+## How to scale plugin partitions dynamically (what’s possible today vs what needs changes)
+
+### What’s possible today (no code changes)
+
+You can scale with **configuration + operational actions**:
+
+1. **Increase Kafka topic partitions** (Kafka supports increase only).
+2. Adjust `configured.plugins` and per-plugin overrides.
+3. Restart audit-ingestor to apply a new partition layout.
+
+This is “dynamic” in the sense that you can evolve the system without code, but it is not runtime-reconfigurable.
+
+### What is not dynamic today (current limitations)
+
+With current code:
+
+- `AuditPartitioner` computes plugin → range mapping once during producer startup (`configure()`).
+- There is no built-in watcher to reload `configured.plugins` or overrides.
+- There is no control-plane that allocates new partition ranges for new plugins without restart.
+
+So you cannot:
+
+- automatically “promote” a plugin from buffer → dedicated partitions without a rollout/restart
+- automatically increase a specific plugin’s partition allocation at runtime based on observed load
+
+### What would need changes for true dynamic onboarding + scaling
+
+If you need runtime automation (no restart, self-scaling), you’d typically introduce:
+
+- **A persistent “partition registry”** (plugin → assigned partitions or weights), stored outside the process.
+- **Dynamic refresh**: audit-ingestor periodically pulls the registry and updates routing.
+- **Kafka Admin integration**: increase topic partitions when required (still increase-only).
+- **A safe growth rule**: avoid reshuffling existing plugins’ ranges; prefer allocating new plugin ranges from newly added tail partitions.
+
+These are product/code changes (not just configuration).
+
+---
+
+## Suggested changes to implement for your environment (practical plan)
+
+This section lists the changes you can do **today** vs changes that are **architectural**.
+
+### Recommended changes you can do today (config + ops)
+
+- **Use plugin-based mode** (set `ranger.audit.ingestor.kafka.configured.plugins`) if you want isolation and predictable per-plugin throughput.
+- **Reserve a real buffer** (enough partitions so new plugins don’t fight over 1–2 partitions).
+- **Append-only discipline**:
+  - never reorder `configured.plugins`
+  - always append new plugins at the end
+- **Per-plugin overrides for hot plugins**:
+  - allocate more partitions to high-volume plugins (Trino/Hive)
+- **Capacity planning**:
+  - increase Kafka topic partitions ahead of onboarding waves
+  - keep some slack so you aren’t resizing frequently
+- **Restart audit-ingestor after allocation changes**:
+  - required to apply new plugin partition ranges
+
+### Recommended changes that require engineering work (if you truly need “dynamic”)
+
+- **Dynamic mapping reload**: enable live reconfiguration of plugin allocations in `AuditPartitioner`.
+- **Registry/control-plane**: a single source of truth for allocations (and change audit trail).
+- **Auto partition expansion**: Kafka AdminClient to increase partitions when buffer is low.
+- **Explicit onboarding workflow**:
+  - “new plugin starts in buffer”
+  - “promote plugin to dedicated partitions” (allocates new tail partitions, does not reshuffle)
+
+**Proposed design (documented):** Kafka compacted topic `ranger_audit_partition_plan` + REST + background watcher. With `partition.plan.dynamic.enabled=true`, the **first ingestor pod** seeds that topic from the same XML properties above when the plan topic is empty; later pods read Kafka only. See `README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md` → [First pod: XML populates the plan topic](README-KAFKA-PARTITION-PLAN-REGISTRY-REST.md#first-pod-xml-populates-the-plan-topic).
+
+---
+
+## Key configuration reference (audit-ingestor)
+
+| Property | Purpose |
+|----------|---------|
+| `ranger.audit.ingestor.kafka.topic.name` | Kafka topic name |
+| `ranger.audit.ingestor.kafka.configured.plugins` | Enables plugin-based partitioning and lists onboarded plugins |
+| `ranger.audit.ingestor.kafka.topic.partitions.per.configured.plugin` | Default partitions per configured plugin (default **3**) |
+| `ranger.audit.ingestor.kafka.topic.partitions.buffer` | Buffer partitions for unlisted plugins (default **9**) |
+| `ranger.audit.ingestor.kafka.plugin.partition.overrides.<plugin>` | Per-plugin partition override |
+| `ranger.audit.ingestor.kafka.topic.partitions` | Topic size in **hash-based** mode (default **10**); also read by partitioner for buffer math in plugin-based mode |
+
diff --git a/audit-server/audit-common/src/main/java/org/apache/ranger/audit/server/AuditServerConstants.java b/audit-server/audit-common/src/main/java/org/apache/ranger/audit/server/AuditServerConstants.java
index 58b136b85..5cdaf8960 100644
--- a/audit-server/audit-common/src/main/java/org/apache/ranger/audit/server/AuditServerConstants.java
+++ b/audit-server/audit-common/src/main/java/org/apache/ranger/audit/server/AuditServerConstants.java
@@ -62,6 +62,17 @@ private AuditServerConstants() {}
     public static final String PROP_BUFFER_PARTITIONS                        = "kafka.topic.partitions.buffer";
     public static final String PROP_REPLICATION_FACTOR                       = "kafka.replication.factor";
 
+    // Dynamic partition plan (Kafka compacted registry topic)
+    public static final String PROP_PARTITION_PLAN_TOPIC                     = "kafka.partition.plan.topic";
+    public static final String PROP_PARTITION_PLAN_REFRESH_INTERVAL_MS       = "kafka.partition.plan.refresh.interval.ms";
+    public static final String PROP_PARTITION_PLAN_CONSUMER_POLL_TIMEOUT_MS  = "kafka.partition.plan.consumer.poll.timeout.ms";
+    public static final String PROP_PARTITION_PLAN_DYNAMIC_ENABLED           = "kafka.partition.plan.dynamic.enabled";
+    public static final String DEFAULT_PARTITION_PLAN_TOPIC                  = "ranger_audit_partition_plan";
+    public static final int    DEFAULT_PARTITION_PLAN_REFRESH_INTERVAL_MS    = 30000;
+    public static final int    DEFAULT_PARTITION_PLAN_CONSUMER_POLL_TIMEOUT_MS = 500;
+    public static final int    PARTITION_PLAN_TOPIC_PARTITION_COUNT          = 1;
+    public static final String KAFKA_TOPIC_CLEANUP_POLICY_COMPACT            = "compact";
+
     // Kafka producer tuning (ranger.audit.ingestor.kafka.producer.*)
     public static final String PROP_KAFKA_PRODUCER_PREFIX                    = "kafka.producer.";
     public static final String PROP_PRODUCER_BATCH_SIZE                        = "batch.size";
diff --git a/audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java b/audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java
index bfba27260..29770e9e2 100644
--- a/audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java
+++ b/audit-server/audit-common/src/main/java/org/apache/ranger/audit/utils/AuditMessageQueueUtils.java
@@ -27,6 +27,7 @@
 import org.apache.kafka.clients.admin.NewPartitions;
 import org.apache.kafka.clients.admin.NewTopic;
 import org.apache.kafka.clients.admin.TopicDescription;
+import org.apache.kafka.common.errors.TopicExistsException;
 import org.apache.ranger.audit.provider.MiscUtil;
 import org.apache.ranger.audit.server.AuditServerConstants;
 import org.slf4j.Logger;
@@ -39,6 +40,7 @@
 import java.util.Map;
 import java.util.Properties;
 import java.util.Set;
+import java.util.concurrent.ExecutionException;
 
 public class AuditMessageQueueUtils {
     private static final Logger LOG = LoggerFactory.getLogger(AuditMessageQueueUtils.class);
@@ -50,30 +52,13 @@ public static String createAuditsTopicIfNotExists(Properties props, String propP
         LOG.info("==> AuditMessageQueueUtils:createAuditsTopicIfNotExists(propPrefix={})", propPrefix);
 
         String ret                  = null;
-        String topicName            = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_TOPIC_NAME, AuditServerConstants.DEFAULT_TOPIC);
-        String bootstrapServers     = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_BOOTSTRAP_SERVERS);
-        String securityProtocol     = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_SECURITY_PROTOCOL, AuditServerConstants.DEFAULT_SECURITY_PROTOCOL);
-        String saslMechanism        = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_SASL_MECHANISM, AuditServerConstants.DEFAULT_SASL_MECHANISM);
-        int    connMaxIdleTimeoutMS = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_CONN_MAX_IDEAL_MS, 10000);
-        int    partitions           = getPartitions(props, propPrefix);
-        short  replicationFactor    = (short) MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REPLICATION_FACTOR, AuditServerConstants.DEFAULT_REPLICATION_FACTOR);
-        int    reqTimeoutMS         = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REQ_TIMEOUT_MS, 5000);
-        int    maxAttempts          = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_KAFKA_TOPIC_INIT_MAX_RETRIES, 10) + 1;
-        int    retryDelayMs         = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_KAFKA_TOPIC_INIT_RETRY_DELAY_MS, 3000);
+        String topicName         = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_TOPIC_NAME, AuditServerConstants.DEFAULT_TOPIC);
+        int    partitions        = getPartitions(props, propPrefix);
+        short  replicationFactor = (short) MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REPLICATION_FACTOR, AuditServerConstants.DEFAULT_REPLICATION_FACTOR);
+        int    maxAttempts       = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_KAFKA_TOPIC_INIT_MAX_RETRIES, 10) + 1;
+        int    retryDelayMs      = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_KAFKA_TOPIC_INIT_RETRY_DELAY_MS, 3000);
 
-        Map<String, Object> kafkaProp = new HashMap<>();
-
-        kafkaProp.put(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
-        kafkaProp.put("sasl.mechanism", saslMechanism);
-        kafkaProp.put(AdminClientConfig.SECURITY_PROTOCOL_CONFIG, securityProtocol);
-
-        if (securityProtocol != null && securityProtocol.toUpperCase().contains("SASL")) {
-            kafkaProp.put(AuditServerConstants.PROP_SASL_JAAS_CONFIG, getJAASConfig(props, propPrefix));
-            kafkaProp.put(AuditServerConstants.PROP_SASL_KERBEROS_SERVICE_NAME, AuditServerConstants.DEFAULT_SERVICE_NAME);
-        }
-
-        kafkaProp.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, reqTimeoutMS);
-        kafkaProp.put(AdminClientConfig.CONNECTIONS_MAX_IDLE_MS_CONFIG, connMaxIdleTimeoutMS);
+        Map<String, Object> kafkaProp = buildAdminClientConfig(props, propPrefix);
 
         for (int currentAttempt = 1; currentAttempt <= maxAttempts && ret == null; currentAttempt++) {
             try (AdminClient admin = AdminClient.create(kafkaProp)) {
@@ -92,7 +77,7 @@ public static String createAuditsTopicIfNotExists(Properties props, String propP
                         LOG.info("Topic '{}' configs: {}", topicName, topicConfigs);
                     }
 
-                    admin.createTopics(Collections.singletonList(topic)).all().get();
+                    createTopicIgnoringAlreadyExists(admin, topic);
 
                     ret = topic.name();
 
@@ -143,6 +128,97 @@ public static String createAuditsTopicIfNotExists(Properties props, String propP
         return ret;
     }
 
+    /**
+     * Create the compacted partition-plan registry topic if missing.
+     * Always exactly one partition ({@link AuditServerConstants#PARTITION_PLAN_TOPIC_PARTITION_COUNT});
+     * partition count is not configurable. A single partition is required so every plan version compacts
+     * under one key on one log end. Safe when multiple ingestor pods start together (concurrent topic creation).
+     */
+    public static String createPartitionPlanTopicIfNotExists(Properties props, String propPrefix) {
+        String planTopic         = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_PARTITION_PLAN_TOPIC, AuditServerConstants.DEFAULT_PARTITION_PLAN_TOPIC);
+        short  replicationFactor = (short) MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REPLICATION_FACTOR, AuditServerConstants.DEFAULT_REPLICATION_FACTOR);
+        int    planTopicPartitions = AuditServerConstants.PARTITION_PLAN_TOPIC_PARTITION_COUNT;
+        int    maxAttempts       = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_KAFKA_TOPIC_INIT_MAX_RETRIES, 10) + 1;
+        int    retryDelayMs      = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_KAFKA_TOPIC_INIT_RETRY_DELAY_MS, 3000);
+        Map<String, Object> adminConfig = buildAdminClientConfig(props, propPrefix);
+
+        for (int attempt = 1; attempt <= maxAttempts; attempt++) {
+            try (AdminClient admin = AdminClient.create(adminConfig)) {
+                Set<String> topicNames = admin.listTopics().names().get();
+                if (!topicNames.contains(planTopic)) {
+                    LOG.info("Creating partition plan topic '{}' with {} partition and replication factor {}", planTopic, planTopicPartitions, replicationFactor);
+                    NewTopic topic = new NewTopic(planTopic, planTopicPartitions, replicationFactor);
+                    topic.configs(Collections.singletonMap("cleanup.policy", AuditServerConstants.KAFKA_TOPIC_CLEANUP_POLICY_COMPACT));
+                    createTopicIgnoringAlreadyExists(admin, topic);
+                    AuditServerUtils.waitUntilTopicReady(admin, planTopic, Duration.ofSeconds(60));
+                    int partitionCount = describeTopicPartitionCount(admin, planTopic);
+                    LOG.info("Partition plan topic '{}' is ready with {} partition(s)", planTopic, partitionCount);
+                } else {
+                    int partitionCount = describeTopicPartitionCount(admin, planTopic);
+                    requirePlanTopicPartitionCount(planTopic, partitionCount, planTopicPartitions);
+                    LOG.info("Partition plan topic '{}' already exists with {} partition(s)", planTopic, partitionCount);
+                }
+                return planTopic;
+            } catch (Exception ex) {
+                if (attempt < maxAttempts) {
+                    LOG.warn("Failed to ensure partition plan topic on attempt {}/{}. Retrying in {} ms. Error: {}", attempt, maxAttempts, retryDelayMs, ex.getMessage());
+                    try {
+                        Thread.sleep(retryDelayMs);
+                    } catch (InterruptedException ie) {
+                        Thread.currentThread().interrupt();
+                        break;
+                    }
+                } else {
+                    LOG.error("Failed to create partition plan topic '{}' after {} attempts", planTopic, attempt, ex);
+                    throw new RuntimeException("Failed to create partition plan topic '" + planTopic + "' after " + attempt + " attempts", ex);
+                }
+            }
+        }
+        throw new RuntimeException("Failed to create partition plan topic '" + planTopic + "'");
+    }
+
+    public static Map<String, Object> buildAdminClientConfig(Properties props, String propPrefix) {
+        String bootstrapServers     = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_BOOTSTRAP_SERVERS);
+        String securityProtocol     = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_SECURITY_PROTOCOL, AuditServerConstants.DEFAULT_SECURITY_PROTOCOL);
+        String saslMechanism        = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_SASL_MECHANISM, AuditServerConstants.DEFAULT_SASL_MECHANISM);
+        int    connMaxIdleTimeoutMS = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_CONN_MAX_IDEAL_MS, 10000);
+        int    reqTimeoutMS         = MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REQ_TIMEOUT_MS, 5000);
+
+        Map<String, Object> kafkaProp = new HashMap<>();
+        kafkaProp.put(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
+        kafkaProp.put("sasl.mechanism", saslMechanism);
+        kafkaProp.put(AdminClientConfig.SECURITY_PROTOCOL_CONFIG, securityProtocol);
+        if (securityProtocol != null && securityProtocol.toUpperCase().contains("SASL")) {
+            kafkaProp.put(AuditServerConstants.PROP_SASL_JAAS_CONFIG, getJAASConfig(props, propPrefix));
+            kafkaProp.put(AuditServerConstants.PROP_SASL_KERBEROS_SERVICE_NAME, AuditServerConstants.DEFAULT_SERVICE_NAME);
+        }
+        kafkaProp.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, reqTimeoutMS);
+        kafkaProp.put(AdminClientConfig.CONNECTIONS_MAX_IDLE_MS_CONFIG, connMaxIdleTimeoutMS);
+        return kafkaProp;
+    }
+
+    private static int describeTopicPartitionCount(AdminClient admin, String topicName) throws Exception {
+        TopicDescription topicDescription = admin.describeTopics(Collections.singletonList(topicName)).values().get(topicName).get();
+        return topicDescription.partitions().size();
+    }
+
+    private static void requirePlanTopicPartitionCount(String planTopic, int actualPartitions, int expectedPartitions) {
+        if (actualPartitions != expectedPartitions) {
+            throw new RuntimeException("Partition plan topic '" + planTopic + "' must have exactly " + expectedPartitions + " partition(s) for compacted registry semantics, but has " + actualPartitions);
+        }
+    }
+
+    private static void createTopicIgnoringAlreadyExists(AdminClient admin, NewTopic topic) throws Exception {
+        try {
+            admin.createTopics(Collections.singletonList(topic)).all().get();
+        } catch (ExecutionException ex) {
+            if (!(ex.getCause() instanceof TopicExistsException)) {
+                throw ex;
+            }
+            LOG.info("Topic '{}' already exists", topic.name());
+        }
+    }
+
     public static String getJAASConfig(Properties props, String propPrefix) {
         // Use ranger service principal and keytab for Kafka authentication
         // This ensures consistent identity across all Ranger services and destination writes
@@ -215,6 +291,22 @@ public static String getJAASConfig(Properties props, String propPrefix) {
         return jaasConfig;
     }
 
+    /** Grows the audit topic partition count when the plan requires more partitions than exist today. */
+    public static void ensureTopicPartitionCount(Properties props, String propPrefix, String topicName, int requiredPartitions) {
+        LOG.info("Ensuring topic '{}' has at least {} partitions", topicName, requiredPartitions);
+        Map<String, Object> adminConfig = buildAdminClientConfig(props, propPrefix);
+        try (AdminClient admin = AdminClient.create(adminConfig)) {
+            updateExistingTopicPartitions(admin, topicName, requiredPartitions);
+            LOG.info("Topic '{}' partition count satisfied (required >= {})", topicName, requiredPartitions);
+        } catch (Exception e) {
+            LOG.error("Failed to ensure partition count for topic '{}' (required >= {})", topicName, requiredPartitions, e);
+            if (e instanceof RuntimeException) {
+                throw (RuntimeException) e;
+            }
+            throw new RuntimeException("Failed to ensure partition count for topic '" + topicName + "'", e);
+        }
+    }
+
     private static String updateExistingTopicPartitions(AdminClient admin, String topicName, int partitions) {
         LOG.info("==> AuditMessageQueueUtils:updateExistingTopicPartitions() topic: {}, desired partitions: {}", topicName, partitions);
 
diff --git a/audit-server/audit-common/src/test/java/org/apache/ranger/audit/utils/AuditMessageQueueUtilsTest.java b/audit-server/audit-common/src/test/java/org/apache/ranger/audit/utils/AuditMessageQueueUtilsTest.java
index e20a69647..950a7d477 100644
--- a/audit-server/audit-common/src/test/java/org/apache/ranger/audit/utils/AuditMessageQueueUtilsTest.java
+++ b/audit-server/audit-common/src/test/java/org/apache/ranger/audit/utils/AuditMessageQueueUtilsTest.java
@@ -17,6 +17,7 @@
 
 package org.apache.ranger.audit.utils;
 
+import org.apache.kafka.clients.admin.AdminClientConfig;
 import org.apache.ranger.audit.server.AuditServerConstants;
 import org.junit.jupiter.api.Test;
 
@@ -65,4 +66,16 @@ public void testBuildTopicConfigsMapsAllSetProperties() {
         assertEquals("lz4", configs.get("compression.type"));
         assertEquals("2", configs.get("min.insync.replicas"));
     }
+
+    @Test
+    public void testBuildAdminClientConfigUsesBootstrapServers() {
+        Properties props = new Properties();
+        props.setProperty(PROP_PREFIX + "." + AuditServerConstants.PROP_BOOTSTRAP_SERVERS, "kafka:9092");
+        props.setProperty(PROP_PREFIX + "." + AuditServerConstants.PROP_SECURITY_PROTOCOL, "PLAINTEXT");
+
+        Map<String, Object> adminConfig = AuditMessageQueueUtils.buildAdminClientConfig(props, PROP_PREFIX);
+
+        assertEquals("kafka:9092", adminConfig.get(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG));
+        assertEquals("PLAINTEXT", adminConfig.get(AdminClientConfig.SECURITY_PROTOCOL_CONFIG));
+    }
 }
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditMessageQueue.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditMessageQueue.java
index 216840989..800ebda4e 100644
--- a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditMessageQueue.java
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditMessageQueue.java
@@ -23,6 +23,8 @@
 import org.apache.ranger.audit.destination.AuditDestination;
 import org.apache.ranger.audit.model.AuditEventBase;
 import org.apache.ranger.audit.model.AuthzAuditEvent;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanKafkaConfig;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanWatcher;
 import org.apache.ranger.audit.provider.MiscUtil;
 import org.apache.ranger.audit.utils.AuditMessageQueueUtils;
 import org.slf4j.Logger;
@@ -48,6 +50,7 @@ public class AuditMessageQueue extends AuditDestination {
     private String                        topicName;
     private Thread                        producerThread;
     private AuditRecoveryManager          recoveryManager;
+    private PartitionPlanWatcher            partitionPlanWatcher;
 
     @Override
     public void init(Properties props, String propPrefix) {
@@ -56,6 +59,7 @@ public void init(Properties props, String propPrefix) {
         super.init(props, propPrefix);
 
         createAuditsTopic(props, PROP_INGESTOR_PREFIX);
+        startPartitionPlanWatcherIfEnabled(props);
         createKafkaProducer(props, PROP_INGESTOR_PREFIX);
         createRecoveryManager(props, PROP_INGESTOR_PREFIX);
 
@@ -75,6 +79,16 @@ public void start() {
     public void stop() {
         LOG.info("==> AuditMessageQueue.stop() [CORE AUDIT SERVER]");
 
+        if (partitionPlanWatcher != null) {
+            try {
+                partitionPlanWatcher.stop();
+            } catch (Exception e) {
+                LOG.error("Error stopping partition plan watcher", e);
+            } finally {
+                partitionPlanWatcher = null;
+            }
+        }
+
         // Shutdown recovery manager first to process any remaining messages
         if (recoveryManager != null) {
             try {
@@ -340,6 +354,22 @@ private void createAuditsTopic(final Properties props, final String propPrefix)
         }
     }
 
+    private void startPartitionPlanWatcherIfEnabled(final Properties props) {
+        if (!PartitionPlanKafkaConfig.isDynamicPartitionPlanEnabled(props, PROP_INGESTOR_PREFIX)) {
+            return;
+        }
+        if (topicName == null) {
+            throw new IllegalStateException("Audit topic must be created before starting partition plan watcher");
+        }
+        try {
+            partitionPlanWatcher = new PartitionPlanWatcher(props, PROP_INGESTOR_PREFIX, topicName, null);
+            partitionPlanWatcher.startBlocking();
+        } catch (Exception e) {
+            LOG.error("Failed to start partition plan watcher for audit topic '{}'", topicName, e);
+            throw new RuntimeException("Failed to start partition plan watcher for dynamic partitioning", e);
+        }
+    }
+
     private void createRecoveryManager(final Properties props, final String propPrefix) {
         // Create recovery manager even if kafkaProducer is null - it will handle null producer gracefully
         // This ensures audits are spooled when Kafka is unavailable during startup
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditPartitioner.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditPartitioner.java
index d0832bdaa..f6df42a3b 100644
--- a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditPartitioner.java
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/AuditPartitioner.java
@@ -22,6 +22,10 @@
 import org.apache.kafka.clients.producer.Partitioner;
 import org.apache.kafka.common.Cluster;
 import org.apache.kafka.common.PartitionInfo;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanHolder;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanKafkaConfig;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.producer.kafka.partition.model.PluginPartitionAssignment;
 import org.apache.ranger.audit.server.AuditServerConstants;
 import org.apache.ranger.audit.utils.AuditServerLogFormatter;
 import org.slf4j.Logger;
@@ -50,11 +54,19 @@ public class AuditPartitioner implements Partitioner {
     private int[]    configuredPluginPartitionEnd;
     private int      bufferPartitionStart;
     private int      bufferPartitionCount;
+    private boolean  dynamicPlanEnabled;
     private final    ConcurrentHashMap<String, AtomicInteger> appIdCounters = new ConcurrentHashMap<>();
 
     @Override
     public void configure(Map<String, ?> configs) {
         String propPrefix = AuditServerConstants.PROP_PREFIX_AUDIT_SERVER;
+        String ingestorPropPrefix = propPrefix.substring(0, propPrefix.length() - 1);
+        dynamicPlanEnabled = PartitionPlanKafkaConfig.isDynamicPartitionPlanEnabled(configs, ingestorPropPrefix);
+        if (dynamicPlanEnabled) {
+            LOG.info("Dynamic partition plan enabled — routing from in-memory plan (PartitionPlanHolder)");
+            logDynamicPlanConfiguration(configs, propPrefix);
+            return;
+        }
 
         String pluginsStr = getConfig(configs, propPrefix + AuditServerConstants.PROP_CONFIGURED_PLUGINS,  AuditServerConstants.DEFAULT_CONFIGURED_PLUGINS);
         configuredPlugins = pluginsStr.split(",");
@@ -116,13 +128,21 @@ public void configure(Map<String, ?> configs) {
 
     @Override
     public int partition(String topic, Object key, byte[] keyBytes, Object value, byte[] valueBytes, Cluster cluster) {
+        String appId = key != null ? key.toString() : null;
+        if (dynamicPlanEnabled) {
+            int numPartitions = resolveTopicPartitionCount(cluster, topic);
+            if (appId == null || appId.isEmpty()) {
+                return Math.abs(System.identityHashCode(key) % numPartitions);
+            }
+            return partitionFromPlan(appId, numPartitions);
+        }
+
         int numPartitions = totalPartitions;
         List<PartitionInfo> partitions = cluster.partitionsForTopic(topic);
         if (partitions != null && !partitions.isEmpty()) {
             numPartitions = partitions.size();
         }
 
-        String appId = key != null ? key.toString() : null;
         if (appId == null || appId.isEmpty()) {
             return Math.abs(System.identityHashCode(key) % numPartitions);
         }
@@ -135,10 +155,8 @@ public int partition(String topic, Object key, byte[] keyBytes, Object value, by
                 end = start;
             }
             int rangeSize = end - start + 1;
-            int subPartition = appIdCounters
-                    .computeIfAbsent(appId, k -> new AtomicInteger(0))
-                    .getAndIncrement() % rangeSize;
-            return start + subPartition;
+            int roundRobinIndex = nextRoundRobinIndex(appId, rangeSize);
+            return start + roundRobinIndex;
         } else {
             // Unconfigured plugin - use buffer partitions
             int start = Math.min(bufferPartitionStart, numPartitions - 1);
@@ -156,6 +174,111 @@ public void close() {
         appIdCounters.clear();
     }
 
+    /** Picks a partition from the in-memory plan: round-robin for known plugins, hash for buffer. */
+    private int partitionFromPlan(String appId, int numPartitions) {
+        PartitionPlan plan = PartitionPlanHolder.getInstance().getPlan();
+        if (plan == null) {
+            LOG.error("Dynamic partition plan is not loaded; falling back to hash routing for appId '{}'", appId);
+            return hashAppIdToPartitionIndex(appId, numPartitions);
+        }
+        PluginPartitionAssignment assignment = findPluginAssignment(plan, appId);
+        if (assignment != null && !assignment.getPartitions().isEmpty()) {
+            List<Integer> partitionIds = assignment.getPartitions();
+            int roundRobinIndex = nextRoundRobinIndex(appId, partitionIds.size());
+            return boundPartitionToTopic(partitionIds.get(roundRobinIndex), numPartitions);
+        }
+        List<Integer> bufferIds = plan.getBuffer().getPartitions();
+        if (bufferIds.isEmpty()) {
+            return hashAppIdToPartitionIndex(appId, numPartitions);
+        }
+        int bufferIndex = hashAppIdToPartitionIndex(appId, bufferIds.size());
+        return boundPartitionToTopic(bufferIds.get(bufferIndex), numPartitions);
+    }
+
+    /** Sticky hash: maps {@code appId} to an index in {@code [0, partitionCount)}. */
+    private static int hashAppIdToPartitionIndex(String appId, int partitionCount) {
+        return Math.abs(appId.hashCode() % partitionCount);
+    }
+
+    /**
+     * Picks the next slot for round-robin routing for one plugin.
+     * Each {@code appId} keeps its own counter (0, 1, 2, …); {@code % laneCount} cycles through lanes.
+     */
+    private int nextRoundRobinIndex(String appId, int laneCount) {
+        AtomicInteger messageCounter = appIdCounters.computeIfAbsent(appId, k -> new AtomicInteger(0));
+        return messageCounter.getAndIncrement() % laneCount;
+    }
+
+    /** Looks up a plugin assignment using case-insensitive plugin id matching. */
+    private static PluginPartitionAssignment findPluginAssignment(PartitionPlan plan, String appId) {
+        for (Map.Entry<String, PluginPartitionAssignment> entry : plan.getPlugins().entrySet()) {
+            if (entry.getKey().equalsIgnoreCase(appId)) {
+                return entry.getValue();
+            }
+        }
+        return null;
+    }
+
+    /** Returns the live partition count for the audit topic from the Kafka cluster metadata. */
+    private static int resolveTopicPartitionCount(Cluster cluster, String topic) {
+        List<PartitionInfo> partitions = cluster.partitionsForTopic(topic);
+        if (partitions != null && !partitions.isEmpty()) {
+            return partitions.size();
+        }
+        return 1;
+    }
+
+    /** Bounds a planned partition id to the topic's current live partition range. */
+    private static int boundPartitionToTopic(int plannedPartitionId, int topicPartitionCount) {
+        if (topicPartitionCount <= 0) {
+            return 0;
+        }
+        return Math.min(Math.max(0, plannedPartitionId), topicPartitionCount - 1);
+    }
+
+    /** Logs the dynamic plan snapshot installed in {@link PartitionPlanHolder} at startup. */
+    private void logDynamicPlanConfiguration(Map<String, ?> configs, String propPrefix) {
+        int defaultPerPlugin = getIntConfig(configs, propPrefix + AuditServerConstants.PROP_TOPIC_PARTITIONS_PER_CONFIGURED_PLUGIN, AuditServerConstants.DEFAULT_PARTITIONS_PER_CONFIGURED_PLUGIN);
+        if (defaultPerPlugin < 1) {
+            defaultPerPlugin = 1;
+        }
+
+        PartitionPlan plan = PartitionPlanHolder.getInstance().getPlan();
+        AuditServerLogFormatter.LogBuilder logBuilder = AuditServerLogFormatter.builder("****** AuditPartitioner Configuration ******");
+        if (plan == null) {
+            logBuilder.add("Mode: ", "dynamic (plan not loaded yet)");
+            logBuilder.logInfo(LOG);
+            return;
+        }
+
+        logBuilder.add("Mode: ", "dynamic (PartitionPlanHolder)");
+        logBuilder.add("Plan version: ", plan.getVersion());
+        logBuilder.add("Total partitions: ", plan.getTopicPartitionCount());
+        logBuilder.add("Configured plugins: ", plan.getPlugins().size());
+        logBuilder.add("Default partitions per plugin: ", defaultPerPlugin);
+        for (Map.Entry<String, PluginPartitionAssignment> entry : plan.getPlugins().entrySet()) {
+            List<Integer> partitionIds = entry.getValue().getPartitions();
+            String rangeInfo = formatPartitionRangeInfo(partitionIds);
+            logBuilder.add("Plugin '" + entry.getKey() + "'", rangeInfo);
+        }
+        logBuilder.add("Buffer partitions (unconfigured): ", formatBufferPartitionInfo(plan.getBuffer().getPartitions()));
+        logBuilder.logInfo(LOG);
+    }
+
+    private static String formatPartitionRangeInfo(List<Integer> partitionIds) {
+        if (partitionIds.isEmpty()) {
+            return "0 partitions (range: n/a): ";
+        }
+        return String.format("%d partitions (range: %d-%d): ", partitionIds.size(), partitionIds.get(0), partitionIds.get(partitionIds.size() - 1));
+    }
+
+    private static String formatBufferPartitionInfo(List<Integer> bufferPartitionIds) {
+        if (bufferPartitionIds.isEmpty()) {
+            return "0 partitions (range: n/a)";
+        }
+        return String.format("%d partitions (range: %d-%d)", bufferPartitionIds.size(), bufferPartitionIds.get(0), bufferPartitionIds.get(bufferPartitionIds.size() - 1));
+    }
+
     private int indexOfConfiguredPlugin(String appId) {
         for (int i = 0; i < configuredPlugins.length; i++) {
             if (configuredPlugins[i].equalsIgnoreCase(appId)) {
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/KafkaAuditTopicPartitionGrower.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/KafkaAuditTopicPartitionGrower.java
new file mode 100644
index 000000000..029acc813
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/KafkaAuditTopicPartitionGrower.java
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.utils.AuditMessageQueueUtils;
+
+import java.util.Properties;
+
+/** Grows the audit topic partition count before a plan references new tail IDs. */
+public class KafkaAuditTopicPartitionGrower {
+    /** Increases {@code ranger_audits} partition count when the plan needs more lanes. */
+    public void growAuditTopicToRequiredPartitionCount(Properties props, String propPrefix, String auditTopicName, int requiredPartitionCount) {
+        AuditMessageQueueUtils.ensureTopicPartitionCount(props, propPrefix, auditTopicName, requiredPartitionCount);
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/KafkaPartitionPlanRegistry.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/KafkaPartitionPlanRegistry.java
new file mode 100644
index 000000000..e0f5e3801
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/KafkaPartitionPlanRegistry.java
@@ -0,0 +1,129 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.kafka.clients.consumer.ConsumerRecord;
+import org.apache.kafka.clients.consumer.ConsumerRecords;
+import org.apache.kafka.clients.consumer.KafkaConsumer;
+import org.apache.kafka.clients.producer.KafkaProducer;
+import org.apache.kafka.clients.producer.ProducerRecord;
+import org.apache.kafka.common.TopicPartition;
+import org.apache.ranger.audit.producer.kafka.partition.constants.PartitionPlanConstants;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.utils.AuditMessageQueueUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Duration;
+import java.util.Collections;
+import java.util.Properties;
+
+/** Kafka compacted topic implementation of {@link PartitionPlanRegistry}. */
+public final class KafkaPartitionPlanRegistry implements PartitionPlanRegistry {
+    private static final Logger LOG = LoggerFactory.getLogger(KafkaPartitionPlanRegistry.class);
+
+    private final Properties props;
+    private final String propPrefix;
+    private final String planTopic;
+    private final int consumerPollTimeoutMs;
+    private final KafkaProducer<String, String> producer;
+
+    public KafkaPartitionPlanRegistry(Properties props, String propPrefix) throws Exception {
+        this.props                 = props;
+        this.propPrefix            = propPrefix;
+        this.planTopic             = PartitionPlanKafkaConfig.resolvePlanTopicName(props, propPrefix);
+        this.consumerPollTimeoutMs = PartitionPlanKafkaConfig.resolveConsumerPollTimeoutMs(props, propPrefix);
+        AuditMessageQueueUtils.createPartitionPlanTopicIfNotExists(props, propPrefix);
+        this.producer = new KafkaProducer<>(PartitionPlanKafkaConfig.producerConfig(props, propPrefix));
+        LOG.info("Kafka partition plan registry ready for topic '{}'", planTopic);
+    }
+
+    @Override
+    public String getPlanTopicName() {
+        return planTopic;
+    }
+
+    /** Reads the latest compacted value for the audit topic key from partition 0. */
+    @Override
+    public PartitionPlan readPlan(String auditTopicKey) {
+        requireAuditTopicKey(auditTopicKey);
+        try (KafkaConsumer<String, String> consumer = openConsumer()) {
+            return readLatestCompactedPlan(consumer, auditTopicKey);
+        } catch (PartitionPlanException e) {
+            throw e;
+        } catch (Exception e) {
+            LOG.error("Failed to read partition plan from Kafka topic '{}' for audit topic key '{}'", planTopic, auditTopicKey, e);
+            throw new PartitionPlanException("Failed to read partition plan from Kafka topic '" + planTopic + "'", e);
+        }
+    }
+
+    /** Publishes a new plan version to the compacted topic (key = audit topic name). */
+    @Override
+    public void writePlan(String auditTopicKey, PartitionPlan plan) {
+        requireAuditTopicKey(auditTopicKey);
+        if (plan == null) {
+            throw new PartitionPlanException("Partition plan is required");
+        }
+        PartitionPlanValidator.validate(plan);
+        try {
+            producer.send(new ProducerRecord<>(planTopic, auditTopicKey, plan.toJson())).get();
+            LOG.info("Wrote partition plan version {} for audit topic '{}' to '{}'", plan.getVersion(), auditTopicKey, planTopic);
+        } catch (Exception e) {
+            LOG.error("Failed to write partition plan version {} to Kafka topic '{}' for audit topic key '{}'", plan.getVersion(), planTopic, auditTopicKey, e);
+            throw new PartitionPlanException("Failed to write partition plan to Kafka topic '" + planTopic + "'", e);
+        }
+    }
+
+    @Override
+    public void close() {
+        producer.flush();
+        producer.close();
+    }
+
+    private KafkaConsumer<String, String> openConsumer() throws Exception {
+        return new KafkaConsumer<>(PartitionPlanKafkaConfig.consumerConfig(props, propPrefix, PartitionPlanConstants.PLAN_REGISTRY_CONSUMER_GROUP));
+    }
+
+    private PartitionPlan readLatestCompactedPlan(KafkaConsumer<String, String> consumer, String auditTopicKey) {
+        TopicPartition partition = new TopicPartition(planTopic, 0);
+        consumer.assign(Collections.singletonList(partition));
+        consumer.seekToBeginning(Collections.singletonList(partition));
+
+        PartitionPlan latest = null;
+        ConsumerRecords<String, String> records;
+        do {
+            records = consumer.poll(Duration.ofMillis(consumerPollTimeoutMs));
+            for (ConsumerRecord<String, String> record : records) {
+                if (auditTopicKey.equals(record.key())) {
+                    latest = PartitionPlan.fromJson(record.value());
+                }
+            }
+        } while (!records.isEmpty());
+        return latest;
+    }
+
+    private static void requireAuditTopicKey(String auditTopicKey) {
+        if (StringUtils.isBlank(auditTopicKey)) {
+            throw new PartitionPlanException("auditTopicKey is required");
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanAllocator.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanAllocator.java
new file mode 100644
index 000000000..37e870fde
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanAllocator.java
@@ -0,0 +1,129 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.producer.kafka.partition.model.PluginPartitionAssignment;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/** Append-only plan updates: promote unknown plugins and scale hot plugins without reshuffling. */
+public final class PartitionPlanAllocator {
+    private PartitionPlanAllocator() {
+    }
+
+    /**
+     * Give a plugin its own partitions. Uses buffer IDs first; adds new tail IDs when buffer is too small.
+     */
+    public static PartitionPlan promotePlugin(PartitionPlan current, String pluginId, int partitionCount, String updatedBy) {
+        requireMutationInputs(current, pluginId, partitionCount, updatedBy);
+        if (current.getPlugins().containsKey(pluginId)) {
+            throw new PartitionPlanException("Plugin '" + pluginId + "' already has dedicated partitions");
+        }
+
+        List<Integer> remainingBuffer = new ArrayList<>(current.getBuffer().getPartitions());
+        List<Integer> newPluginIds    = takeFromBuffer(remainingBuffer, partitionCount);
+        int topicPartitionCount       = appendTailPartitions(newPluginIds, current.getTopicPartitionCount(), partitionCount - newPluginIds.size());
+
+        return commitPlanUpdate(current, updatedBy, topicPartitionCount, addPluginAssignment(current, pluginId, newPluginIds), remainingBuffer);
+    }
+
+    /**
+     * Add more partitions to an existing plugin by appending new tail IDs only.
+     */
+    public static PartitionPlan scalePlugin(PartitionPlan current, String pluginId, int additionalPartitions, String updatedBy) {
+        requireMutationInputs(current, pluginId, additionalPartitions, updatedBy);
+        if (!current.getPlugins().containsKey(pluginId)) {
+            throw new PartitionPlanException("Plugin '" + pluginId + "' is not configured; promote it first");
+        }
+
+        List<Integer> pluginIds = new ArrayList<>(current.getPlugins().get(pluginId).getPartitions());
+        int topicPartitionCount = appendTailPartitions(pluginIds, current.getTopicPartitionCount(), additionalPartitions);
+
+        return commitPlanUpdate(current, updatedBy, topicPartitionCount, addPluginAssignment(current, pluginId, pluginIds), current.getBuffer().getPartitions());
+    }
+
+    /** Full plan replace (REST PUT) with append-only checks against the current plan. */
+    public static PartitionPlan replacePlan(PartitionPlan current, PartitionPlan proposed) {
+        if (current == null || proposed == null) {
+            throw new PartitionPlanException("Current and proposed plans are required");
+        }
+        if (!StringUtils.equals(current.getTopic(), proposed.getTopic())) {
+            throw new PartitionPlanException("Proposed topic must match current topic");
+        }
+        PartitionPlan next = proposed.toBuilder().version(current.getVersion() + 1).build();
+        PartitionPlanValidator.validate(next);
+        PartitionPlanValidator.validateAppendOnly(current, next);
+        return next;
+    }
+
+    /** Pull up to count partition IDs from the front of the buffer list. */
+    private static List<Integer> takeFromBuffer(List<Integer> bufferIds, int count) {
+        List<Integer> taken = new ArrayList<>(Math.min(count, bufferIds.size()));
+        while (taken.size() < count && !bufferIds.isEmpty()) {
+            taken.add(bufferIds.remove(0));
+        }
+        return taken;
+    }
+
+    /** Append new tail partition IDs and return the new topic partition count. */
+    private static int appendTailPartitions(List<Integer> target, int topicPartitionCount, int count) {
+        for (int i = 0; i < count; i++) {
+            target.add(topicPartitionCount++);
+        }
+        return topicPartitionCount;
+    }
+
+    private static Map<String, PluginPartitionAssignment> addPluginAssignment(PartitionPlan current, String pluginId, List<Integer> partitionIds) {
+        Map<String, PluginPartitionAssignment> plugins = new LinkedHashMap<>(current.getPlugins());
+        plugins.put(pluginId, new PluginPartitionAssignment(partitionIds));
+        return plugins;
+    }
+
+    private static PartitionPlan commitPlanUpdate(PartitionPlan current, String updatedBy, int topicPartitionCount, Map<String, PluginPartitionAssignment> plugins, List<Integer> bufferIds) {
+        PartitionPlan next = current.toBuilder()
+                .version(current.getVersion() + 1)
+                .topicPartitionCount(topicPartitionCount)
+                .plugins(plugins)
+                .buffer(new PluginPartitionAssignment(bufferIds))
+                .updatedAt(Instant.now().toString())
+                .updatedBy(updatedBy)
+                .build();
+        PartitionPlanValidator.validate(next);
+        PartitionPlanValidator.validateAppendOnly(current, next);
+        return next;
+    }
+
+    private static void requireMutationInputs(PartitionPlan current, String pluginId, int partitionCount, String updatedBy) {
+        if (current == null) {
+            throw new PartitionPlanException("Current plan is required");
+        }
+        PartitionPlanValidator.validate(current);
+        if (StringUtils.isBlank(pluginId) || partitionCount < 1 || StringUtils.isBlank(updatedBy)) {
+            throw new PartitionPlanException("pluginId, partitionCount, and updatedBy are required");
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrap.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrap.java
new file mode 100644
index 000000000..3850f6808
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrap.java
@@ -0,0 +1,105 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.ranger.audit.producer.kafka.partition.constants.PartitionPlanConstants;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.producer.kafka.partition.model.PluginPartitionAssignment;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** Builds the initial bootstrap plan from legacy XML and seeds the registry when the plan topic is empty. */
+public final class PartitionPlanBootstrap {
+    private static final Logger LOG = LoggerFactory.getLogger(PartitionPlanBootstrap.class);
+
+    private PartitionPlanBootstrap() {
+    }
+
+    /** Builds the initial bootstrap plan ({@link PartitionPlanConstants#INITIAL_PLAN_VERSION}) using the same contiguous layout as static {@code AuditPartitioner}. */
+    public static PartitionPlan createInitialPlan(PartitionPlanBootstrapConfig config) {
+        if (config == null || StringUtils.isBlank(config.getAuditTopic())) {
+            throw new PartitionPlanException("Audit topic and bootstrap config are required");
+        }
+
+        Map<String, PluginPartitionAssignment> plugins = new LinkedHashMap<>();
+        int nextPartition = 0;
+        for (String plugin : config.getConfiguredPlugins()) {
+            if (StringUtils.isBlank(plugin)) {
+                continue;
+            }
+            int count = config.getPartitionsForPlugin(plugin.trim());
+            plugins.put(plugin.trim(), PluginPartitionAssignment.ofRange(nextPartition, nextPartition + count - 1));
+            nextPartition += count;
+        }
+
+        int topicPartitionCount = nextPartition + Math.max(1, config.getBufferPartitionCount());
+        PartitionPlan plan = PartitionPlan.builder()
+                .topic(config.getAuditTopic())
+                .version(PartitionPlanConstants.INITIAL_PLAN_VERSION)
+                .topicPartitionCount(topicPartitionCount)
+                .updatedAt(Instant.now().toString())
+                .updatedBy(PartitionPlanConstants.BOOTSTRAP_UPDATED_BY)
+                .plugins(plugins)
+                .buffer(PluginPartitionAssignment.ofRange(nextPartition, topicPartitionCount - 1))
+                .build();
+
+        PartitionPlanValidator.validate(plan);
+        return plan;
+    }
+
+    /** Builds the first plan from legacy ingestor producer/XML configuration. */
+    public static PartitionPlan createInitialPlanFromProducerConfig(Map<String, ?> producerConfig, String auditTopic) {
+        return createInitialPlan(PartitionPlanBootstrapConfig.fromProducerConfigMap(producerConfig, auditTopic));
+    }
+
+    /**
+     * Empty-registry bootstrap: read registry, build the initial bootstrap plan from XML when no plan
+     * exists, re-read before publish (concurrent pods), write once, then mandatory read-back.
+     */
+    public static PartitionPlan bootstrapIfEmpty(PartitionPlanRegistry registry, String auditTopic, Map<String, ?> producerConfig) {
+        PartitionPlan plan = registry.readPlan(auditTopic);
+        if (plan != null) {
+            LOG.info("Partition plan version {} already present for audit topic '{}'", plan.getVersion(), auditTopic);
+            return plan;
+        }
+
+        PartitionPlan localPlan = createInitialPlanFromProducerConfig(producerConfig, auditTopic);
+        plan = registry.readPlan(auditTopic);
+        if (plan != null) {
+            LOG.info("Peer published partition plan version {} while bootstrapping audit topic '{}'", plan.getVersion(), auditTopic);
+            return plan;
+        }
+
+        registry.writePlan(auditTopic, localPlan);
+        plan = registry.readPlan(auditTopic);
+        if (plan == null) {
+            LOG.error("Mandatory read-back failed after publishing initial bootstrap plan for audit topic '{}'", auditTopic);
+            throw new PartitionPlanException("Mandatory read-back failed after publishing bootstrap plan for audit topic '" + auditTopic + "'");
+        }
+        LOG.info("Bootstrap partition plan version {} published and read back for audit topic '{}'", plan.getVersion(), auditTopic);
+        return plan;
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapConfig.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapConfig.java
new file mode 100644
index 000000000..5ff97b7ff
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapConfig.java
@@ -0,0 +1,120 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.server.AuditServerConstants;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** Inputs for building the first partition plan from legacy ingestor XML / producer config. */
+public final class PartitionPlanBootstrapConfig {
+    private final String auditTopic;
+    private final String[] configuredPlugins;
+    private final int defaultPartitionsPerPlugin;
+    private final int bufferPartitionCount;
+    private final Map<String, Integer> pluginPartitionOverrides;
+
+    public PartitionPlanBootstrapConfig(String auditTopic, String[] configuredPlugins, int defaultPartitionsPerPlugin, int bufferPartitionCount, Map<String, Integer> pluginPartitionOverrides) {
+        this.auditTopic                 = auditTopic;
+        this.configuredPlugins          = configuredPlugins != null ? configuredPlugins : new String[0];
+        this.defaultPartitionsPerPlugin = defaultPartitionsPerPlugin;
+        this.bufferPartitionCount       = bufferPartitionCount;
+        this.pluginPartitionOverrides   = pluginPartitionOverrides != null ? new LinkedHashMap<>(pluginPartitionOverrides) : Collections.emptyMap();
+    }
+
+    public static PartitionPlanBootstrapConfig create(String auditTopic, String[] configuredPlugins, int defaultPartitionsPerPlugin, int bufferPartitionCount) {
+        return new PartitionPlanBootstrapConfig(auditTopic, configuredPlugins, defaultPartitionsPerPlugin, bufferPartitionCount, Collections.emptyMap());
+    }
+
+    public PartitionPlanBootstrapConfig withPluginOverride(String pluginId, int partitionCount) {
+        Map<String, Integer> overrides = new LinkedHashMap<>(pluginPartitionOverrides);
+        overrides.put(pluginId, partitionCount);
+        return new PartitionPlanBootstrapConfig(auditTopic, configuredPlugins, defaultPartitionsPerPlugin, bufferPartitionCount, overrides);
+    }
+
+    public String getAuditTopic() {
+        return auditTopic;
+    }
+
+    public String[] getConfiguredPlugins() {
+        return configuredPlugins;
+    }
+
+    public int getDefaultPartitionsPerPlugin() {
+        return defaultPartitionsPerPlugin;
+    }
+
+    public int getBufferPartitionCount() {
+        return bufferPartitionCount;
+    }
+
+    public int getPartitionsForPlugin(String pluginId) {
+        Integer override = pluginPartitionOverrides.get(pluginId);
+        int count = override != null ? override : defaultPartitionsPerPlugin;
+        return Math.max(1, count);
+    }
+
+    public static PartitionPlanBootstrapConfig fromProducerConfigMap(Map<String, ?> configs, String auditTopic) {
+        String propPrefix = AuditServerConstants.PROP_PREFIX_AUDIT_SERVER;
+        String pluginsStr = getString(configs, propPrefix + AuditServerConstants.PROP_CONFIGURED_PLUGINS, AuditServerConstants.DEFAULT_CONFIGURED_PLUGINS);
+        String[] plugins = trimPlugins(pluginsStr.split(","));
+        int defaultPerPlugin = getInt(configs, propPrefix + AuditServerConstants.PROP_TOPIC_PARTITIONS_PER_CONFIGURED_PLUGIN, AuditServerConstants.DEFAULT_PARTITIONS_PER_CONFIGURED_PLUGIN);
+        int bufferCount = getInt(configs, propPrefix + AuditServerConstants.PROP_BUFFER_PARTITIONS, AuditServerConstants.DEFAULT_BUFFER_PARTITIONS);
+
+        PartitionPlanBootstrapConfig config = create(auditTopic, plugins, defaultPerPlugin, bufferCount);
+        for (String plugin : plugins) {
+            String overrideKey = propPrefix + AuditServerConstants.PROP_PLUGIN_PARTITION_OVERRIDE_PREFIX + plugin;
+            if (configs.containsKey(overrideKey)) {
+                config = config.withPluginOverride(plugin, getInt(configs, overrideKey, defaultPerPlugin));
+            }
+        }
+        return config;
+    }
+
+    private static String[] trimPlugins(String[] plugins) {
+        String[] trimmed = new String[plugins.length];
+        for (int i = 0; i < plugins.length; i++) {
+            trimmed[i] = plugins[i].trim();
+        }
+        return trimmed;
+    }
+
+    private static String getString(Map<String, ?> configs, String key, String defaultValue) {
+        Object val = configs.get(key);
+        return val != null ? val.toString() : defaultValue;
+    }
+
+    private static int getInt(Map<String, ?> configs, String key, int defaultValue) {
+        Object val = configs.get(key);
+        if (val == null) {
+            return defaultValue;
+        }
+        if (val instanceof Number) {
+            return ((Number) val).intValue();
+        }
+        try {
+            return Integer.parseInt(val.toString());
+        } catch (NumberFormatException e) {
+            return defaultValue;
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanHolder.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanHolder.java
new file mode 100644
index 000000000..8ce99689c
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanHolder.java
@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+
+import java.util.concurrent.atomic.AtomicReference;
+
+/** Hot-path in-memory plan for {@code AuditPartitioner} and the background watcher. */
+public final class PartitionPlanHolder {
+    private static final PartitionPlanHolder INSTANCE = new PartitionPlanHolder();
+
+    private final AtomicReference<PartitionPlan> planRef = new AtomicReference<>();
+    private volatile int lastInstalledVersion;
+
+    private PartitionPlanHolder() {
+    }
+
+    public static PartitionPlanHolder getInstance() {
+        return INSTANCE;
+    }
+
+    public PartitionPlan getPlan() {
+        return planRef.get();
+    }
+
+    public int getLastInstalledVersion() {
+        return lastInstalledVersion;
+    }
+
+    /** Validates and atomically installs the plan used by the Kafka partitioner. */
+    public void install(PartitionPlan plan, Integer kafkaPartitionCount) {
+        PartitionPlanValidator.validate(plan, kafkaPartitionCount);
+        planRef.set(plan);
+        lastInstalledVersion = plan.getVersion();
+    }
+
+    /** Clears holder state between unit tests. */
+    public void resetForTests() {
+        planRef.set(null);
+        lastInstalledVersion = 0;
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanKafkaConfig.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanKafkaConfig.java
new file mode 100644
index 000000000..fd1e6573c
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanKafkaConfig.java
@@ -0,0 +1,106 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.kafka.clients.admin.AdminClientConfig;
+import org.apache.kafka.clients.consumer.ConsumerConfig;
+import org.apache.kafka.clients.producer.ProducerConfig;
+import org.apache.ranger.audit.provider.MiscUtil;
+import org.apache.ranger.audit.server.AuditServerConstants;
+import org.apache.ranger.audit.utils.AuditMessageQueueUtils;
+
+import java.util.Map;
+import java.util.Properties;
+
+/** Kafka client settings for the partition-plan registry topic. */
+public final class PartitionPlanKafkaConfig {
+    private PartitionPlanKafkaConfig() {
+    }
+
+    /** Resolves the compacted Kafka topic that stores the partition plan registry. */
+    public static String resolvePlanTopicName(Properties props, String propPrefix) {
+        return MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_PARTITION_PLAN_TOPIC, AuditServerConstants.DEFAULT_PARTITION_PLAN_TOPIC);
+    }
+
+    /** Returns whether ingestor should load routing from the Kafka plan registry. */
+    public static boolean isDynamicPartitionPlanEnabled(Properties props, String propPrefix) {
+        return MiscUtil.getBooleanProperty(props, propPrefix + "." + AuditServerConstants.PROP_PARTITION_PLAN_DYNAMIC_ENABLED, false);
+    }
+
+    /** Returns whether the Kafka producer partitioner should use the in-memory dynamic plan. */
+    public static boolean isDynamicPartitionPlanEnabled(Map<String, ?> configs, String ingestorPropPrefix) {
+        String key = ingestorPropPrefix + "." + AuditServerConstants.PROP_PARTITION_PLAN_DYNAMIC_ENABLED;
+        Object val = configs.get(key);
+        if (val == null) {
+            return false;
+        }
+        if (val instanceof Boolean) {
+            return (Boolean) val;
+        }
+        return Boolean.parseBoolean(val.toString());
+    }
+
+    /** Resolves how often each ingestor pod reloads the plan from Kafka. */
+    public static int resolveRefreshIntervalMs(Properties props, String propPrefix) {
+        return MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_PARTITION_PLAN_REFRESH_INTERVAL_MS, AuditServerConstants.DEFAULT_PARTITION_PLAN_REFRESH_INTERVAL_MS);
+    }
+
+    /** Resolves the Kafka consumer poll timeout when draining the compacted plan topic. */
+    public static int resolveConsumerPollTimeoutMs(Properties props, String propPrefix) {
+        return MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_PARTITION_PLAN_CONSUMER_POLL_TIMEOUT_MS, AuditServerConstants.DEFAULT_PARTITION_PLAN_CONSUMER_POLL_TIMEOUT_MS);
+    }
+
+    /** Builds Kafka producer properties for writing to the plan registry topic. */
+    public static Properties producerConfig(Properties props, String propPrefix) throws Exception {
+        Properties producerProps = new Properties();
+        producerProps.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_BOOTSTRAP_SERVERS));
+        producerProps.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, "org.apache.kafka.common.serialization.StringSerializer");
+        producerProps.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, "org.apache.kafka.common.serialization.StringSerializer");
+        producerProps.put(ProducerConfig.ACKS_CONFIG, "all");
+        producerProps.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REQ_TIMEOUT_MS, AuditServerConstants.DEFAULT_PRODUCER_REQUEST_TIMEOUT_MS));
+        applySecurity(producerProps, props, propPrefix);
+        return producerProps;
+    }
+
+    /** Builds Kafka consumer properties for reading the plan registry topic. */
+    public static Properties consumerConfig(Properties props, String propPrefix, String groupId) throws Exception {
+        Properties consumerProps = new Properties();
+        consumerProps.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_BOOTSTRAP_SERVERS));
+        consumerProps.put(ConsumerConfig.GROUP_ID_CONFIG, groupId);
+        consumerProps.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, "org.apache.kafka.common.serialization.StringDeserializer");
+        consumerProps.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, "org.apache.kafka.common.serialization.StringDeserializer");
+        consumerProps.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "false");
+        consumerProps.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
+        consumerProps.put(ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG, MiscUtil.getIntProperty(props, propPrefix + "." + AuditServerConstants.PROP_REQ_TIMEOUT_MS, AuditServerConstants.DEFAULT_PRODUCER_REQUEST_TIMEOUT_MS));
+        applySecurity(consumerProps, props, propPrefix);
+        return consumerProps;
+    }
+
+    /** Applies Kerberos/SASL settings shared by plan-registry Kafka clients. */
+    private static void applySecurity(Properties clientProps, Properties props, String propPrefix) throws Exception {
+        String securityProtocol = MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_SECURITY_PROTOCOL, AuditServerConstants.DEFAULT_SECURITY_PROTOCOL);
+        clientProps.put(AdminClientConfig.SECURITY_PROTOCOL_CONFIG, securityProtocol);
+        clientProps.put(AuditServerConstants.PROP_SASL_MECHANISM, MiscUtil.getStringProperty(props, propPrefix + "." + AuditServerConstants.PROP_SASL_MECHANISM, AuditServerConstants.DEFAULT_SASL_MECHANISM));
+        clientProps.put(AuditServerConstants.PROP_SASL_KERBEROS_SERVICE_NAME, AuditServerConstants.DEFAULT_SERVICE_NAME);
+        if (securityProtocol.toUpperCase().contains(AuditServerConstants.PROP_SECURITY_PROTOCOL_VALUE)) {
+            clientProps.put(AuditServerConstants.PROP_SASL_JAAS_CONFIG, AuditMessageQueueUtils.getJAASConfig(props, propPrefix));
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanRegistry.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanRegistry.java
new file mode 100644
index 000000000..b639a3ba3
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanRegistry.java
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+
+/** Durable store for partition plans (Kafka compacted topic in dynamic mode). */
+public interface PartitionPlanRegistry extends AutoCloseable {
+    String getPlanTopicName();
+
+    PartitionPlan readPlan(String auditTopicKey);
+
+    void writePlan(String auditTopicKey, PartitionPlan plan);
+
+    @Override
+    void close();
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanRegistryFactory.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanRegistryFactory.java
new file mode 100644
index 000000000..2b07cdc3d
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanRegistryFactory.java
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import java.util.Properties;
+
+/** Opens a Kafka-backed {@link PartitionPlanRegistry} for REST mutations. */
+public class PartitionPlanRegistryFactory {
+    /** Creates a registry connected to the compacted plan topic. */
+    public PartitionPlanRegistry open(Properties props, String propPrefix) throws Exception {
+        return new KafkaPartitionPlanRegistry(props, propPrefix);
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanService.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanService.java
new file mode 100644
index 000000000..855e75121
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanService.java
@@ -0,0 +1,176 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanConflictException;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlanReplaceRequest;
+import org.apache.ranger.audit.producer.kafka.partition.model.PromotePluginRequest;
+import org.apache.ranger.audit.producer.kafka.partition.model.ScalePluginRequest;
+import org.apache.ranger.audit.provider.MiscUtil;
+import org.apache.ranger.audit.server.AuditServerConfig;
+import org.apache.ranger.audit.server.AuditServerConstants;
+import org.springframework.stereotype.Component;
+
+import java.util.Properties;
+
+/** REST mutations and reads for the dynamic Kafka partition plan. */
+@Component
+public class PartitionPlanService {
+    static final String INGESTOR_PROP_PREFIX = "ranger.audit.ingestor";
+
+    private final Properties configProps;
+    private final PartitionPlanHolder holder;
+    private final PartitionPlanRegistryFactory registryFactory;
+    private final KafkaAuditTopicPartitionGrower auditTopicPartitionGrower;
+
+    public PartitionPlanService() {
+        this(AuditServerConfig.getInstance().getProperties(), PartitionPlanHolder.getInstance(), new PartitionPlanRegistryFactory(), new KafkaAuditTopicPartitionGrower());
+    }
+
+    PartitionPlanService(Properties configProps, PartitionPlanHolder holder, PartitionPlanRegistryFactory registryFactory, KafkaAuditTopicPartitionGrower auditTopicPartitionGrower) {
+        this.configProps               = configProps;
+        this.holder                    = holder;
+        this.registryFactory           = registryFactory;
+        this.auditTopicPartitionGrower = auditTopicPartitionGrower;
+    }
+
+    /** Returns whether dynamic partition-plan mode is enabled in ingestor configuration. */
+    public boolean isDynamicPartitionPlanEnabled() {
+        return PartitionPlanKafkaConfig.isDynamicPartitionPlanEnabled(configProps, INGESTOR_PROP_PREFIX);
+    }
+
+    /** Returns the plan currently installed in memory on this ingestor pod. */
+    public PartitionPlan getPartitionPlan() {
+        PartitionPlan plan = holder.getPlan();
+        if (plan == null) {
+            throw new PartitionPlanException("Partition plan is not loaded in memory");
+        }
+        return plan;
+    }
+
+    /** Replaces the full plan via REST PUT with optimistic locking. */
+    public PartitionPlan replacePartitionPlan(PartitionPlanReplaceRequest request, String updatedBy) {
+        requireDynamicEnabled();
+        String auditTopic = resolveAuditTopicName();
+        try (PartitionPlanRegistry registry = registryFactory.open(configProps, INGESTOR_PROP_PREFIX)) {
+            PartitionPlan current = requirePlan(registry, auditTopic);
+            PartitionPlan next = PartitionPlanAllocator.replacePlan(current, request.toProposedPlan(current, updatedBy));
+            return publishMutation(registry, auditTopic, request.getExpectedVersion(), current, next);
+        } catch (PartitionPlanException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new PartitionPlanException("Failed to update partition plan for audit topic '" + auditTopic + "'", e);
+        }
+    }
+
+    /** Promotes a plugin from the buffer to dedicated partitions. */
+    public PartitionPlan promotePlugin(PromotePluginRequest request, String updatedBy) {
+        requireDynamicEnabled();
+        String auditTopic = resolveAuditTopicName();
+        try (PartitionPlanRegistry registry = registryFactory.open(configProps, INGESTOR_PROP_PREFIX)) {
+            PartitionPlan current = requirePlan(registry, auditTopic);
+            PartitionPlan next = PartitionPlanAllocator.promotePlugin(current, request.getPluginId(), request.getPartitionCount(), updatedBy);
+            return publishMutation(registry, auditTopic, request.getExpectedVersion(), current, next);
+        } catch (PartitionPlanException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new PartitionPlanException("Failed to update partition plan for audit topic '" + auditTopic + "'", e);
+        }
+    }
+
+    /** Appends tail partitions to a plugin already present in the plan. */
+    public PartitionPlan scalePlugin(ScalePluginRequest request, String updatedBy) {
+        requireDynamicEnabled();
+        String auditTopic = resolveAuditTopicName();
+        try (PartitionPlanRegistry registry = registryFactory.open(configProps, INGESTOR_PROP_PREFIX)) {
+            PartitionPlan current = requirePlan(registry, auditTopic);
+            PartitionPlan next = PartitionPlanAllocator.scalePlugin(current, request.getPluginId(), request.getAdditionalPartitions(), updatedBy);
+            return publishMutation(registry, auditTopic, request.getExpectedVersion(), current, next);
+        } catch (PartitionPlanException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new PartitionPlanException("Failed to update partition plan for audit topic '" + auditTopic + "'", e);
+        }
+    }
+
+    /** Validates version, grows the audit topic if needed, writes the plan, and reloads memory. */
+    private PartitionPlan publishMutation(PartitionPlanRegistry registry, String auditTopic, int expectedVersion, PartitionPlan current, PartitionPlan next) {
+        if (current.getVersion() != expectedVersion) {
+            throw new PartitionPlanConflictException(current);
+        }
+        growAuditTopicIfNeeded(next.getTopicPartitionCount());
+        verifyVersionUnchanged(registry, expectedVersion);
+        registry.writePlan(auditTopic, next);
+        verifyReadback(registry, auditTopic, next.getVersion());
+        return holder.getPlan();
+    }
+
+    /** Grows the audit topic before the plan references new partition IDs. */
+    private void growAuditTopicIfNeeded(int requiredPartitions) {
+        try {
+            auditTopicPartitionGrower.growAuditTopicToRequiredPartitionCount(configProps, INGESTOR_PROP_PREFIX, resolveAuditTopicName(), requiredPartitions);
+        } catch (RuntimeException e) {
+            throw new PartitionPlanException("Failed to grow audit topic partition count", e);
+        }
+    }
+
+    /** Confirms the registry still holds the expected version before writing. */
+    private void verifyVersionUnchanged(PartitionPlanRegistry registry, int expectedVersion) {
+        PartitionPlan latest = registry.readPlan(resolveAuditTopicName());
+        if (latest == null) {
+            throw new PartitionPlanException("Partition plan disappeared during update");
+        }
+        if (latest.getVersion() != expectedVersion) {
+            throw new PartitionPlanConflictException(latest);
+        }
+    }
+
+    /** Mandatory read-back after publish so every pod converges on the same plan version. */
+    private void verifyReadback(PartitionPlanRegistry registry, String auditTopic, int expectedVersion) {
+        PartitionPlan readback = registry.readPlan(auditTopic);
+        if (readback == null || readback.getVersion() != expectedVersion) {
+            throw new PartitionPlanConflictException(readback != null ? readback : holder.getPlan());
+        }
+        holder.install(readback, readback.getTopicPartitionCount());
+    }
+
+    /** Loads the current plan from Kafka or fails when the registry is empty. */
+    private static PartitionPlan requirePlan(PartitionPlanRegistry registry, String auditTopic) {
+        PartitionPlan plan = registry.readPlan(auditTopic);
+        if (plan == null) {
+            throw new PartitionPlanException("No partition plan found in Kafka for audit topic '" + auditTopic + "'");
+        }
+        return plan;
+    }
+
+    /** Rejects REST calls when dynamic mode is disabled. */
+    private void requireDynamicEnabled() {
+        if (!isDynamicPartitionPlanEnabled()) {
+            throw new PartitionPlanException("Dynamic partition plan is not enabled");
+        }
+    }
+
+    /** Resolves the audit data topic name from ingestor configuration. */
+    private String resolveAuditTopicName() {
+        return MiscUtil.getStringProperty(configProps, INGESTOR_PROP_PREFIX + "." + AuditServerConstants.PROP_TOPIC_NAME, AuditServerConstants.DEFAULT_TOPIC);
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanValidator.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanValidator.java
new file mode 100644
index 000000000..2b79d100c
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanValidator.java
@@ -0,0 +1,105 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.ranger.audit.producer.kafka.partition.constants.PartitionPlanConstants;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.producer.kafka.partition.model.PluginPartitionAssignment;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/** Checks partition plan shape and append-only updates. */
+public final class PartitionPlanValidator {
+    private PartitionPlanValidator() {
+    }
+
+    public static void validate(PartitionPlan plan) {
+        validate(plan, null);
+    }
+
+    /** When kafkaPartitionCount is set, it must match plan.topicPartitionCount. */
+    public static void validate(PartitionPlan plan, Integer kafkaPartitionCount) {
+        if (plan == null || StringUtils.isBlank(plan.getTopic()) || plan.getVersion() < PartitionPlanConstants.INITIAL_PLAN_VERSION || plan.getTopicPartitionCount() < 1) {
+            throw new PartitionPlanException("Invalid partition plan");
+        }
+        if (kafkaPartitionCount != null && !kafkaPartitionCount.equals(plan.getTopicPartitionCount())) {
+            throw new PartitionPlanException("topicPartitionCount does not match Kafka topic partition count");
+        }
+
+        Set<Integer> assigned = new HashSet<>();
+        registerPartitions(plan.getBuffer().getPartitions(), plan.getTopicPartitionCount(), assigned, true);
+        for (Map.Entry<String, PluginPartitionAssignment> entry : plan.getPlugins().entrySet()) {
+            if (StringUtils.isBlank(entry.getKey())) {
+                throw new PartitionPlanException("Plugin id is required");
+            }
+            registerPartitions(entry.getValue().getPartitions(), plan.getTopicPartitionCount(), assigned, false);
+        }
+        if (assigned.size() != plan.getTopicPartitionCount()) {
+            throw new PartitionPlanException("Partition plan must assign every topic partition exactly once");
+        }
+    }
+
+    /** New plan must only add tail partitions; existing plugin lists stay unchanged in order. */
+    public static void validateAppendOnly(PartitionPlan current, PartitionPlan proposed) {
+        if (current == null || proposed == null) {
+            throw new PartitionPlanException("Current and proposed plans are required");
+        }
+        if (proposed.getTopicPartitionCount() < current.getTopicPartitionCount() || proposed.getVersion() != current.getVersion() + 1) {
+            throw new PartitionPlanException("Plan must grow partition count and increment version by one");
+        }
+
+        for (Map.Entry<String, PluginPartitionAssignment> entry : current.getPlugins().entrySet()) {
+            String pluginId = entry.getKey();
+            List<Integer> before = entry.getValue().getPartitions();
+            PluginPartitionAssignment afterAssignment = proposed.getPlugins().get(pluginId);
+            if (afterAssignment == null) {
+                throw new PartitionPlanException("Append-only violation for plugin '" + pluginId + "'");
+            }
+            List<Integer> after = afterAssignment.getPartitions();
+            if (after.size() < before.size()) {
+                throw new PartitionPlanException("Append-only violation for plugin '" + pluginId + "'");
+            }
+            for (int i = 0; i < before.size(); i++) {
+                if (!before.get(i).equals(after.get(i))) {
+                    throw new PartitionPlanException("Append-only violation for plugin '" + pluginId + "' at index " + i);
+                }
+            }
+        }
+    }
+
+    private static void registerPartitions(List<Integer> partitionIds, int topicPartitionCount, Set<Integer> assigned, boolean allowEmpty) {
+        if (partitionIds.isEmpty()) {
+            if (allowEmpty) {
+                return;
+            }
+            throw new PartitionPlanException("Plugin partition list must not be empty");
+        }
+        for (int partitionId : partitionIds) {
+            if (partitionId < 0 || partitionId >= topicPartitionCount || !assigned.add(partitionId)) {
+                throw new PartitionPlanException("Invalid or duplicate partition id: " + partitionId);
+            }
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanWatcher.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanWatcher.java
new file mode 100644
index 000000000..d09101df6
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanWatcher.java
@@ -0,0 +1,189 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.kafka.clients.admin.AdminClient;
+import org.apache.kafka.clients.admin.DescribeTopicsResult;
+import org.apache.kafka.clients.admin.TopicDescription;
+import org.apache.kafka.clients.consumer.ConsumerRecord;
+import org.apache.kafka.clients.consumer.ConsumerRecords;
+import org.apache.kafka.clients.consumer.KafkaConsumer;
+import org.apache.kafka.common.TopicPartition;
+import org.apache.ranger.audit.producer.kafka.partition.constants.PartitionPlanConstants;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.utils.AuditMessageQueueUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Duration;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Properties;
+
+/** Background thread: load plan from Kafka (or XML-seeded initial bootstrap plan), then incrementally refresh in-memory plan. */
+public final class PartitionPlanWatcher implements Runnable {
+    private static final Logger LOG = LoggerFactory.getLogger(PartitionPlanWatcher.class);
+
+    private final Properties props;
+    private final String propPrefix;
+    private final String auditTopicKey;
+    private final PartitionPlanHolder partitionPlanHolder;
+    private final int refreshIntervalMs;
+    private final int consumerPollTimeoutMs;
+    private final String planTopic;
+
+    private PartitionPlanRegistry registry;
+    private KafkaConsumer<String, String> consumer;
+    private Thread watcherThread;
+    private volatile boolean running;
+
+    public PartitionPlanWatcher(Properties props, String propPrefix, String auditTopicKey, PartitionPlanHolder holder) {
+        this.props             = props;
+        this.propPrefix        = propPrefix;
+        this.auditTopicKey     = auditTopicKey;
+        this.partitionPlanHolder            = holder != null ? holder : PartitionPlanHolder.getInstance();
+        this.refreshIntervalMs     = PartitionPlanKafkaConfig.resolveRefreshIntervalMs(props, propPrefix);
+        this.consumerPollTimeoutMs = PartitionPlanKafkaConfig.resolveConsumerPollTimeoutMs(props, propPrefix);
+        this.planTopic             = PartitionPlanKafkaConfig.resolvePlanTopicName(props, propPrefix);
+    }
+
+    /** Blocking startup: empty-registry bootstrap, install plan, then start background refresh. */
+    public void startBlocking() throws Exception {
+        LOG.info("Starting partition plan watcher for audit topic '{}' (plan topic '{}', refresh {} ms, consumer poll {} ms)", auditTopicKey, planTopic, refreshIntervalMs, consumerPollTimeoutMs);
+        registry = new KafkaPartitionPlanRegistry(props, propPrefix);
+        Map<String, Object> producerConfig = buildProducerConfigMap();
+        PartitionPlan plan = PartitionPlanBootstrap.bootstrapIfEmpty(registry, auditTopicKey, producerConfig);
+        int kafkaPartitionCount = resolveAuditTopicPartitionCount();
+        partitionPlanHolder.install(plan, kafkaPartitionCount);
+        openConsumerAtLogEnd();
+        running       = true;
+        watcherThread = new Thread(this, "PartitionPlanWatcher");
+        watcherThread.setDaemon(true);
+        watcherThread.start();
+        LOG.info("Partition plan watcher ready: version={}, auditTopicPartitions={}", plan.getVersion(), kafkaPartitionCount);
+    }
+
+    /** Stops the background refresh thread and closes Kafka clients. */
+    public void stop() {
+        running = false;
+        if (watcherThread != null) {
+            watcherThread.interrupt();
+            try {
+                watcherThread.join(5000);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+            watcherThread = null;
+        }
+        closeConsumer();
+        if (registry != null) {
+            registry.close();
+            registry = null;
+        }
+        LOG.info("Partition plan watcher stopped");
+    }
+
+    @Override
+    public void run() {
+        while (running) {
+            try {
+                pollIncrementalUpdates();
+                Thread.sleep(refreshIntervalMs);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                break;
+            } catch (Exception e) {
+                LOG.error("Partition plan refresh failed; keeping last known good plan version {}", partitionPlanHolder.getLastInstalledVersion(), e);
+            }
+        }
+    }
+
+    /** Drains new compacted plan records and installs any newer version into memory. */
+    private void pollIncrementalUpdates() {
+        if (consumer == null) {
+            return;
+        }
+        ConsumerRecords<String, String> records;
+        do {
+            records = consumer.poll(Duration.ofMillis(consumerPollTimeoutMs));
+            for (ConsumerRecord<String, String> record : records) {
+                applyRecordIfNewer(record);
+            }
+        } while (!records.isEmpty());
+    }
+
+    /** Installs a plan record when its version is newer than the in-memory copy. */
+    private void applyRecordIfNewer(ConsumerRecord<String, String> record) {
+        if (!auditTopicKey.equals(record.key())) {
+            return;
+        }
+        try {
+            PartitionPlan plan = PartitionPlan.fromJson(record.value());
+            if (plan.getVersion() <= partitionPlanHolder.getLastInstalledVersion()) {
+                return;
+            }
+            int kafkaPartitionCount = resolveAuditTopicPartitionCount();
+            partitionPlanHolder.install(plan, kafkaPartitionCount);
+            LOG.info("Installed partition plan version {} from Kafka offset {}", plan.getVersion(), record.offset());
+        } catch (Exception e) {
+            LOG.error("Ignoring invalid partition plan at offset {} for audit topic '{}'", record.offset(), auditTopicKey, e);
+        }
+    }
+
+    private void openConsumerAtLogEnd() throws Exception {
+        consumer = new KafkaConsumer<>(PartitionPlanKafkaConfig.consumerConfig(props, propPrefix, PartitionPlanConstants.PLAN_WATCHER_CONSUMER_GROUP));
+        TopicPartition partition = new TopicPartition(planTopic, 0);
+        consumer.assign(Collections.singletonList(partition));
+        consumer.seekToEnd(Collections.singletonList(partition));
+    }
+
+    private void closeConsumer() {
+        if (consumer != null) {
+            consumer.close();
+            consumer = null;
+        }
+    }
+
+    private int resolveAuditTopicPartitionCount() throws Exception {
+        try {
+            Map<String, Object> adminConfig = AuditMessageQueueUtils.buildAdminClientConfig(props, propPrefix);
+            try (AdminClient admin = AdminClient.create(adminConfig)) {
+                DescribeTopicsResult describeTopicsResult = admin.describeTopics(Collections.singletonList(auditTopicKey));
+                TopicDescription topicDescription = describeTopicsResult.values().get(auditTopicKey).get();
+                return topicDescription.partitions().size();
+            }
+        } catch (Exception e) {
+            LOG.error("Failed to resolve partition count for audit topic '{}'", auditTopicKey, e);
+            throw e;
+        }
+    }
+
+    private Map<String, Object> buildProducerConfigMap() {
+        Map<String, Object> producerConfig = new LinkedHashMap<>();
+        String prefix = propPrefix + ".";
+        for (String key : props.stringPropertyNames()) {
+            if (key.startsWith(prefix)) {
+                producerConfig.put(key, props.getProperty(key));
+            }
+        }
+        return producerConfig;
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/constants/PartitionPlanConstants.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/constants/PartitionPlanConstants.java
new file mode 100644
index 000000000..6ef3f6dd4
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/constants/PartitionPlanConstants.java
@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.constants;
+
+/** Shared constants for the dynamic Kafka partition-plan registry. */
+public final class PartitionPlanConstants {
+    /** Version number of the first XML-seeded initial bootstrap plan in an empty registry. */
+    public static final int    INITIAL_PLAN_VERSION              = 1;
+    /** {@code updatedBy} value on plans published by {@code PartitionPlanBootstrap}. */
+    public static final String BOOTSTRAP_UPDATED_BY              = "bootstrap";
+    public static final String PLAN_REGISTRY_CONSUMER_GROUP      = "ranger_audit_partition_plan_registry";
+    public static final String PLAN_WATCHER_CONSUMER_GROUP       = "ranger_audit_partition_plan_watcher";
+
+    private PartitionPlanConstants() {
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/exception/PartitionPlanConflictException.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/exception/PartitionPlanConflictException.java
new file mode 100644
index 000000000..7d22de9f7
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/exception/PartitionPlanConflictException.java
@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.exception;
+
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+
+/** Optimistic-lock failure: another writer changed the plan version first (HTTP 409). */
+public final class PartitionPlanConflictException extends PartitionPlanException {
+    private static final long serialVersionUID = 1L;
+
+    private final PartitionPlan currentPlan;
+
+    public PartitionPlanConflictException(PartitionPlan currentPlan) {
+        super("Partition plan version conflict");
+        this.currentPlan = currentPlan;
+    }
+
+    public PartitionPlan getCurrentPlan() {
+        return currentPlan;
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/exception/PartitionPlanException.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/exception/PartitionPlanException.java
new file mode 100644
index 000000000..9080e4b23
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/exception/PartitionPlanException.java
@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.exception;
+
+/**
+ * Raised when a partition plan is invalid or an append-only allocation cannot be applied.
+ */
+public class PartitionPlanException extends RuntimeException {
+    private static final long serialVersionUID = 1L;
+
+    public PartitionPlanException(String message) {
+        super(message);
+    }
+
+    public PartitionPlanException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PartitionPlan.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PartitionPlan.java
new file mode 100644
index 000000000..d3dd3a37f
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PartitionPlan.java
@@ -0,0 +1,209 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.model;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanValidator;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.provider.MiscUtil;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/** Immutable partition routing plan stored in the Kafka compacted registry topic. */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public final class PartitionPlan {
+    private final String topic;
+    private final int version;
+    private final int topicPartitionCount;
+    private final String updatedAt;
+    private final String updatedBy;
+    private final Map<String, PluginPartitionAssignment> plugins;
+    private final PluginPartitionAssignment buffer;
+
+    @JsonCreator
+    public PartitionPlan(@JsonProperty("topic") String topic, @JsonProperty("version") int version, @JsonProperty("topicPartitionCount") int topicPartitionCount, @JsonProperty("updatedAt") String updatedAt, @JsonProperty("updatedBy") String updatedBy, @JsonProperty("plugins") Map<String, PluginPartitionAssignment> plugins, @JsonProperty("buffer") PluginPartitionAssignment buffer) {
+        this.topic               = topic;
+        this.version             = version;
+        this.topicPartitionCount = topicPartitionCount;
+        this.updatedAt           = updatedAt;
+        this.updatedBy           = updatedBy;
+        this.plugins             = copyPlugins(plugins);
+        this.buffer              = buffer != null ? buffer : PluginPartitionAssignment.empty();
+    }
+
+    private static Map<String, PluginPartitionAssignment> copyPlugins(Map<String, PluginPartitionAssignment> plugins) {
+        if (plugins == null || plugins.isEmpty()) {
+            return Collections.emptyMap();
+        }
+        return Collections.unmodifiableMap(new LinkedHashMap<>(plugins));
+    }
+
+    public String getTopic() {
+        return topic;
+    }
+
+    public int getVersion() {
+        return version;
+    }
+
+    public int getTopicPartitionCount() {
+        return topicPartitionCount;
+    }
+
+    public String getUpdatedAt() {
+        return updatedAt;
+    }
+
+    public String getUpdatedBy() {
+        return updatedBy;
+    }
+
+    public Map<String, PluginPartitionAssignment> getPlugins() {
+        return plugins;
+    }
+
+    public PluginPartitionAssignment getBuffer() {
+        return buffer;
+    }
+
+    public Builder toBuilder() {
+        return new Builder(this);
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /** Serializes this plan for the compacted Kafka registry topic. */
+    public String toJson() {
+        try {
+            return MiscUtil.getMapper().writeValueAsString(this);
+        } catch (Exception e) {
+            throw new PartitionPlanException("Failed to serialize partition plan", e);
+        }
+    }
+
+    /** Parses and validates a plan JSON payload from Kafka or REST. */
+    public static PartitionPlan fromJson(String json) {
+        try {
+            PartitionPlan plan = MiscUtil.getMapper().readValue(json, PartitionPlan.class);
+            PartitionPlanValidator.validate(plan);
+            return plan;
+        } catch (PartitionPlanException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new PartitionPlanException("Failed to deserialize partition plan", e);
+        }
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        PartitionPlan that = (PartitionPlan) o;
+        return version == that.version && topicPartitionCount == that.topicPartitionCount && Objects.equals(topic, that.topic) && Objects.equals(updatedAt, that.updatedAt) && Objects.equals(updatedBy, that.updatedBy) && Objects.equals(plugins, that.plugins) && Objects.equals(buffer, that.buffer);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(topic, version, topicPartitionCount, updatedAt, updatedBy, plugins, buffer);
+    }
+
+    @Override
+    public String toString() {
+        return "PartitionPlan{topic='" + topic + "', version=" + version + ", topicPartitionCount=" + topicPartitionCount + ", plugins=" + plugins.keySet() + ", bufferSize=" + buffer.size() + '}';
+    }
+
+    public static final class Builder {
+        private String topic;
+        private int version = 1;
+        private int topicPartitionCount;
+        private String updatedAt;
+        private String updatedBy;
+        private Map<String, PluginPartitionAssignment> plugins = new LinkedHashMap<>();
+        private PluginPartitionAssignment buffer = PluginPartitionAssignment.empty();
+
+        private Builder() {
+        }
+
+        private Builder(PartitionPlan plan) {
+            this.topic               = plan.topic;
+            this.version             = plan.version;
+            this.topicPartitionCount = plan.topicPartitionCount;
+            this.updatedAt           = plan.updatedAt;
+            this.updatedBy           = plan.updatedBy;
+            this.plugins             = new LinkedHashMap<>(plan.plugins);
+            this.buffer              = plan.buffer;
+        }
+
+        public Builder topic(String topic) {
+            this.topic = topic;
+            return this;
+        }
+
+        public Builder version(int version) {
+            this.version = version;
+            return this;
+        }
+
+        public Builder topicPartitionCount(int topicPartitionCount) {
+            this.topicPartitionCount = topicPartitionCount;
+            return this;
+        }
+
+        public Builder updatedAt(String updatedAt) {
+            this.updatedAt = updatedAt;
+            return this;
+        }
+
+        public Builder updatedBy(String updatedBy) {
+            this.updatedBy = updatedBy;
+            return this;
+        }
+
+        public Builder plugins(Map<String, PluginPartitionAssignment> plugins) {
+            this.plugins = plugins == null ? new LinkedHashMap<>() : new LinkedHashMap<>(plugins);
+            return this;
+        }
+
+        public Builder putPlugin(String pluginId, PluginPartitionAssignment assignment) {
+            this.plugins.put(pluginId, assignment);
+            return this;
+        }
+
+        public Builder buffer(PluginPartitionAssignment buffer) {
+            this.buffer = buffer != null ? buffer : PluginPartitionAssignment.empty();
+            return this;
+        }
+
+        public PartitionPlan build() {
+            return new PartitionPlan(topic, version, topicPartitionCount, updatedAt, updatedBy, plugins, buffer);
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PartitionPlanReplaceRequest.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PartitionPlanReplaceRequest.java
new file mode 100644
index 000000000..0ab8833dc
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PartitionPlanReplaceRequest.java
@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.model;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.time.Instant;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** PUT /api/audit/partition-plan body (server assigns version). */
+public final class PartitionPlanReplaceRequest {
+    private final int expectedVersion;
+    private final int topicPartitionCount;
+    private final Map<String, PluginPartitionAssignment> plugins;
+    private final PluginPartitionAssignment buffer;
+
+    @JsonCreator
+    public PartitionPlanReplaceRequest(@JsonProperty("expectedVersion") int expectedVersion, @JsonProperty("topicPartitionCount") int topicPartitionCount, @JsonProperty("plugins") Map<String, PluginPartitionAssignment> plugins, @JsonProperty("buffer") PluginPartitionAssignment buffer) {
+        this.expectedVersion     = expectedVersion;
+        this.topicPartitionCount = topicPartitionCount;
+        this.plugins             = copyPlugins(plugins);
+        this.buffer              = buffer != null ? buffer : PluginPartitionAssignment.empty();
+    }
+
+    private static Map<String, PluginPartitionAssignment> copyPlugins(Map<String, PluginPartitionAssignment> plugins) {
+        if (plugins == null || plugins.isEmpty()) {
+            return Collections.emptyMap();
+        }
+        return Collections.unmodifiableMap(new LinkedHashMap<>(plugins));
+    }
+
+    public int getExpectedVersion() {
+        return expectedVersion;
+    }
+
+    public int getTopicPartitionCount() {
+        return topicPartitionCount;
+    }
+
+    public Map<String, PluginPartitionAssignment> getPlugins() {
+        return plugins;
+    }
+
+    public PluginPartitionAssignment getBuffer() {
+        return buffer;
+    }
+
+    /** Converts the REST PUT body into a proposed plan for append-only validation. */
+    public PartitionPlan toProposedPlan(PartitionPlan current, String updatedBy) {
+        return PartitionPlan.builder()
+                .topic(current.getTopic())
+                .topicPartitionCount(topicPartitionCount)
+                .plugins(plugins)
+                .buffer(buffer)
+                .updatedAt(Instant.now().toString())
+                .updatedBy(updatedBy)
+                .build();
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PluginPartitionAssignment.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PluginPartitionAssignment.java
new file mode 100644
index 000000000..be48e6742
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PluginPartitionAssignment.java
@@ -0,0 +1,93 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.model;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/** Partition ID list for one plugin or the shared buffer. */
+public final class PluginPartitionAssignment {
+    private final List<Integer> partitions;
+
+    @JsonCreator
+    public PluginPartitionAssignment(@JsonProperty("partitions") List<Integer> partitions) {
+        if (partitions == null || partitions.isEmpty()) {
+            this.partitions = Collections.emptyList();
+        } else {
+            this.partitions = Collections.unmodifiableList(new ArrayList<>(partitions));
+        }
+    }
+
+    /** Returns an assignment with no partition IDs (empty buffer). */
+    public static PluginPartitionAssignment empty() {
+        return new PluginPartitionAssignment(Collections.emptyList());
+    }
+
+    /** Builds an assignment from explicit partition IDs. */
+    public static PluginPartitionAssignment of(int... partitionIds) {
+        List<Integer> ids = new ArrayList<>(partitionIds.length);
+        for (int id : partitionIds) {
+            ids.add(id);
+        }
+        return new PluginPartitionAssignment(ids);
+    }
+
+    /** Builds a contiguous inclusive partition ID range. */
+    public static PluginPartitionAssignment ofRange(int startInclusive, int endInclusive) {
+        if (endInclusive < startInclusive) {
+            throw new IllegalArgumentException("Invalid partition range: " + startInclusive + "-" + endInclusive);
+        }
+        List<Integer> ids = new ArrayList<>(endInclusive - startInclusive + 1);
+        for (int i = startInclusive; i <= endInclusive; i++) {
+            ids.add(i);
+        }
+        return new PluginPartitionAssignment(ids);
+    }
+
+    public List<Integer> getPartitions() {
+        return partitions;
+    }
+
+    public int size() {
+        return partitions.size();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        PluginPartitionAssignment that = (PluginPartitionAssignment) o;
+        return Objects.equals(partitions, that.partitions);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(partitions);
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PromotePluginRequest.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PromotePluginRequest.java
new file mode 100644
index 000000000..bc706c2f8
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/PromotePluginRequest.java
@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.model;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/** POST /api/audit/partition-plan/promote body. */
+public final class PromotePluginRequest {
+    private final String pluginId;
+    private final int partitionCount;
+    private final int expectedVersion;
+
+    @JsonCreator
+    public PromotePluginRequest(@JsonProperty("pluginId") String pluginId, @JsonProperty("partitionCount") int partitionCount, @JsonProperty("expectedVersion") int expectedVersion) {
+        this.pluginId         = pluginId;
+        this.partitionCount   = partitionCount;
+        this.expectedVersion  = expectedVersion;
+    }
+
+    public String getPluginId() {
+        return pluginId;
+    }
+
+    public int getPartitionCount() {
+        return partitionCount;
+    }
+
+    public int getExpectedVersion() {
+        return expectedVersion;
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/ScalePluginRequest.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/ScalePluginRequest.java
new file mode 100644
index 000000000..ab71267bf
--- /dev/null
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/producer/kafka/partition/model/ScalePluginRequest.java
@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition.model;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/** POST /api/audit/partition-plan/scale body. */
+public final class ScalePluginRequest {
+    private final String pluginId;
+    private final int additionalPartitions;
+    private final int expectedVersion;
+
+    @JsonCreator
+    public ScalePluginRequest(@JsonProperty("pluginId") String pluginId, @JsonProperty("additionalPartitions") int additionalPartitions, @JsonProperty("expectedVersion") int expectedVersion) {
+        this.pluginId              = pluginId;
+        this.additionalPartitions  = additionalPartitions;
+        this.expectedVersion       = expectedVersion;
+    }
+
+    public String getPluginId() {
+        return pluginId;
+    }
+
+    public int getAdditionalPartitions() {
+        return additionalPartitions;
+    }
+
+    public int getExpectedVersion() {
+        return expectedVersion;
+    }
+}
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/rest/AuditREST.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/rest/AuditREST.java
index 2ae7d14e0..1410730d5 100644
--- a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/rest/AuditREST.java
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/rest/AuditREST.java
@@ -23,6 +23,13 @@
 import org.apache.hadoop.security.authentication.util.KerberosName;
 import org.apache.ranger.audit.model.AuthzAuditEvent;
 import org.apache.ranger.audit.producer.AuditDestinationMgr;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanService;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanConflictException;
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlanReplaceRequest;
+import org.apache.ranger.audit.producer.kafka.partition.model.PromotePluginRequest;
+import org.apache.ranger.audit.producer.kafka.partition.model.ScalePluginRequest;
 import org.apache.ranger.audit.provider.MiscUtil;
 import org.apache.ranger.audit.server.AuditServerConfig;
 import org.apache.ranger.audit.server.AuditServerConstants;
@@ -36,6 +43,7 @@
 import javax.ws.rs.Consumes;
 import javax.ws.rs.GET;
 import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
 import javax.ws.rs.Path;
 import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
@@ -68,6 +76,9 @@ public class AuditREST {
     @Autowired
     AuditDestinationMgr auditDestinationMgr;
 
+    @Autowired
+    PartitionPlanService partitionPlanService;
+
     /**
      * Health check endpoint
      */
@@ -147,7 +158,7 @@ public Response getStatus() {
     }
 
     /**
-     *  Access Audits producer endpoint.
+     * Access Audits producer endpoint.
      *  @param serviceName Required query parameter to identify the source service (hdfs, hive, kafka, solr, etc.)
      *  @param appId Optional query parameter for batch processing - identifies the application instance
      *  @param accessAudits List of audit events to process
@@ -240,6 +251,155 @@ public Response logAccessAudit(@QueryParam("serviceName") String serviceName, @Q
         return ret;
     }
 
+    /** Returns the in-memory partition plan when dynamic mode is enabled. */
+    @GET
+    @Path("/partition-plan")
+    @Produces("application/json")
+    public Response getPartitionPlan() {
+        LOG.debug("==> AuditREST.getPartitionPlan()");
+        Response ret;
+        if (!partitionPlanService.isDynamicPartitionPlanEnabled()) {
+            ret = partitionPlanDisabled("GET /partition-plan");
+        } else {
+            try {
+                ret = Response.ok(partitionPlanService.getPartitionPlan().toJson()).build();
+            } catch (PartitionPlanException e) {
+                LOG.error("Partition plan GET failed", e);
+                ret = Response.status(Response.Status.SERVICE_UNAVAILABLE).entity(buildErrorResponse(e.getMessage())).build();
+            }
+        }
+        LOG.debug("<== AuditREST.getPartitionPlan(): status={}", ret.getStatus());
+        return ret;
+    }
+
+    /** Replaces the full plan (optimistic lock via expectedVersion). */
+    @PUT
+    @Path("/partition-plan")
+    @Consumes("application/json")
+    @Produces("application/json")
+    public Response putPartitionPlan(PartitionPlanReplaceRequest request, @Context HttpServletRequest httpRequest) {
+        LOG.debug("==> AuditREST.putPartitionPlan()");
+        Response ret;
+        if (!partitionPlanService.isDynamicPartitionPlanEnabled()) {
+            ret = partitionPlanDisabled("PUT /partition-plan");
+        } else {
+            try {
+                ret = toSuccessfulPartitionPlanResponse(partitionPlanService.replacePartitionPlan(request, resolveUpdatedBy(httpRequest)));
+            } catch (PartitionPlanConflictException e) {
+                ret = toPartitionPlanConflictResponse("PUT /partition-plan", e);
+            } catch (PartitionPlanException e) {
+                ret = toPartitionPlanErrorResponse("PUT /partition-plan", e);
+            } catch (Exception e) {
+                LOG.error("Unexpected error replacing partition plan", e);
+                ret = Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(buildErrorResponse("Failed to replace partition plan")).build();
+            }
+        }
+        LOG.debug("<== AuditREST.putPartitionPlan(): status={}", ret.getStatus());
+        return ret;
+    }
+
+    /** Moves a plugin from the buffer to dedicated partitions. */
+    @POST
+    @Path("/partition-plan/promote")
+    @Consumes("application/json")
+    @Produces("application/json")
+    public Response promotePlugin(PromotePluginRequest request, @Context HttpServletRequest httpRequest) {
+        LOG.debug("==> AuditREST.promotePlugin(pluginId={})", request != null ? request.getPluginId() : null);
+        Response ret;
+        if (!partitionPlanService.isDynamicPartitionPlanEnabled()) {
+            ret = partitionPlanDisabled("POST /partition-plan/promote");
+        } else {
+            try {
+                ret = toSuccessfulPartitionPlanResponse(partitionPlanService.promotePlugin(request, resolveUpdatedBy(httpRequest)));
+            } catch (PartitionPlanConflictException e) {
+                ret = toPartitionPlanConflictResponse("POST /partition-plan/promote", e);
+            } catch (PartitionPlanException e) {
+                ret = toPartitionPlanErrorResponse("POST /partition-plan/promote", e);
+            } catch (Exception e) {
+                LOG.error("Unexpected error promoting plugin in partition plan", e);
+                ret = Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(buildErrorResponse("Failed to promote plugin in partition plan")).build();
+            }
+        }
+        LOG.debug("<== AuditREST.promotePlugin(): status={}", ret.getStatus());
+        return ret;
+    }
+
+    /** Appends tail partitions to an existing plugin. */
+    @POST
+    @Path("/partition-plan/scale")
+    @Consumes("application/json")
+    @Produces("application/json")
+    public Response scalePlugin(ScalePluginRequest request, @Context HttpServletRequest httpRequest) {
+        LOG.debug("==> AuditREST.scalePlugin(pluginId={})", request != null ? request.getPluginId() : null);
+        Response ret;
+        if (!partitionPlanService.isDynamicPartitionPlanEnabled()) {
+            ret = partitionPlanDisabled("POST /partition-plan/scale");
+        } else {
+            try {
+                ret = toSuccessfulPartitionPlanResponse(partitionPlanService.scalePlugin(request, resolveUpdatedBy(httpRequest)));
+            } catch (PartitionPlanConflictException e) {
+                ret = toPartitionPlanConflictResponse("POST /partition-plan/scale", e);
+            } catch (PartitionPlanException e) {
+                ret = toPartitionPlanErrorResponse("POST /partition-plan/scale", e);
+            } catch (Exception e) {
+                LOG.error("Unexpected error scaling plugin in partition plan", e);
+                ret = Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(buildErrorResponse("Failed to scale plugin in partition plan")).build();
+            }
+        }
+        LOG.debug("<== AuditREST.scalePlugin(): status={}", ret.getStatus());
+        return ret;
+    }
+
+    /** Returns HTTP 200 with the updated plan JSON body. */
+    private Response toSuccessfulPartitionPlanResponse(PartitionPlan updatedPlan) {
+        return Response.ok(updatedPlan.toJson()).build();
+    }
+
+    /** Returns HTTP 409 with the current plan when optimistic locking fails. */
+    private Response toPartitionPlanConflictResponse(String operation, PartitionPlanConflictException conflict) {
+        PartitionPlan currentPlan = conflict.getCurrentPlan();
+        if (currentPlan == null) {
+            LOG.error("{} rejected: partition plan version conflict (current plan unavailable)", operation, conflict);
+            return Response.status(Response.Status.CONFLICT).entity(buildErrorResponse("Partition plan version conflict")).build();
+        }
+        LOG.error("{} rejected: partition plan version conflict; current version is {}", operation, currentPlan.getVersion(), conflict);
+        return Response.status(Response.Status.CONFLICT).entity(currentPlan.toJson()).build();
+    }
+
+    /** Returns HTTP 400 or 503 for validation and Kafka admin failures. */
+    private Response toPartitionPlanErrorResponse(String operation, PartitionPlanException error) {
+        Response.Status status = resolvePartitionPlanErrorStatus(error);
+        LOG.error("{} failed: {}", operation, error.getMessage(), error);
+        return Response.status(status).entity(buildErrorResponse(error.getMessage())).build();
+    }
+
+    /** Returns HTTP 503 when dynamic partition-plan mode is disabled. */
+    private Response partitionPlanDisabled(String operation) {
+        LOG.error("{} rejected: dynamic partition plan is not enabled", operation);
+        return Response.status(Response.Status.SERVICE_UNAVAILABLE).entity(buildErrorResponse("Dynamic partition plan is not enabled")).build();
+    }
+
+    /** Maps service/infrastructure failures to 503; client validation mistakes to 400. */
+    private static Response.Status resolvePartitionPlanErrorStatus(PartitionPlanException error) {
+        if (error.getCause() != null) {
+            return Response.Status.SERVICE_UNAVAILABLE;
+        }
+        String message = error.getMessage();
+        if (message != null && (message.contains("Partition plan is not loaded in memory")
+                || message.contains("Partition plan disappeared during update")
+                || message.contains("No partition plan found in Kafka")
+                || message.contains("Mandatory read-back failed"))) {
+            return Response.Status.SERVICE_UNAVAILABLE;
+        }
+        return Response.Status.BAD_REQUEST;
+    }
+
+    /** Records the authenticated admin user on plan mutations. */
+    private String resolveUpdatedBy(HttpServletRequest request) {
+        String user = getAuthenticatedUser(request);
+        return StringUtils.isNotBlank(user) ? user : "rest-api";
+    }
+
     private String buildResponse(Map<String, Object> respMap) {
         try {
             return MiscUtil.getMapper().writeValueAsString(respMap);
diff --git a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/server/AuditServerConfig.java b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/server/AuditServerConfig.java
index 185ca1000..ba25d9341 100644
--- a/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/server/AuditServerConfig.java
+++ b/audit-server/audit-ingestor/src/main/java/org/apache/ranger/audit/server/AuditServerConfig.java
@@ -29,7 +29,8 @@
 public class AuditServerConfig extends AuditConfig {
     private static final Logger LOG = LoggerFactory.getLogger(AuditServerConfig.class);
 
-    private static final String CONFIG_FILE_PATH = "conf/ranger-audit-ingestor-site.xml";
+    private static final String CONFIG_FILE_PATH     = "conf/ranger-audit-ingestor-site.xml";
+    private static final String AUDIT_CONFIG_PROPERTY = "audit.config";
 
     private static volatile AuditServerConfig sInstance;
 
@@ -60,9 +61,10 @@ private boolean addAuditServerResources() {
 
         boolean ret = true;
 
-        // Load ranger-audit-ingestor-site.xml
-        if (!addAuditResource(CONFIG_FILE_PATH, true)) {
-            LOG.error("Could not load required configuration: {}", CONFIG_FILE_PATH);
+        // Prefer -Daudit.config (external conf dir) over classpath WEB-INF copy
+        String configPath = System.getProperty(AUDIT_CONFIG_PROPERTY, CONFIG_FILE_PATH);
+        if (!addAuditResource(configPath, true)) {
+            LOG.error("Could not load required configuration: {}", configPath);
             ret = false;
         }
 
diff --git a/audit-server/audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml b/audit-server/audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml
index 1688b4dc4..943f57147 100644
--- a/audit-server/audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml
+++ b/audit-server/audit-ingestor/src/main/resources/conf/ranger-audit-ingestor-site.xml
@@ -240,6 +240,7 @@
         <name>ranger.audit.ingestor.service.dev_solr.allowed.users</name>
         <value>solr</value>
         <description>Allowed users for dev_solr (Solr plugin)</description>
+
     </property>
 
     <!-- AUTH_TO_LOCAL RULES FOR KERBEROS PRINCIPAL MAPPING -->
@@ -249,6 +250,21 @@
                RULE:[2:$1/$2@$0]([ndj]n/.*@.*|hdfs/.*@.*)s/.*/hdfs/
                RULE:[2:$1/$2@$0]([rn]m/.*@.*|yarn/.*@.*)s/.*/yarn/
                RULE:[2:$1/$2@$0](jhs/.*@.*)s/.*/mapred/
+               RULE:[2:$1/$2@$0](hive/.*@.*)s/.*/hive/
+               RULE:[2:$1/$2@$0](hbase/.*@.*)s/.*/hbase/
+               RULE:[2:$1/$2@$0](kafka/.*@.*)s/.*/kafka/
+               RULE:[2:$1/$2@$0](knox/.*@.*)s/.*/knox/
+               RULE:[2:$1/$2@$0](rangerkms/.*@.*)s/.*/rangerkms/
+               RULE:[2:$1/$2@$0](trino/.*@.*)s/.*/trino/
+               RULE:[2:$1/$2@$0](ozone/.*@.*)s/.*/ozone/
+               RULE:[2:$1/$2@$0](om/.*@.*)s/.*/om/
+               RULE:[2:$1/$2@$0](scm/.*@.*)s/.*/scm/
+               RULE:[2:$1/$2@$0](dn/.*@.*)s/.*/dn/
+               RULE:[2:$1/$2@$0](solr/.*@.*)s/.*/solr/
+               RULE:[2:$1/$2@$0](rangertagsync/.*@.*)s/.*/rangertagsync/
+               RULE:[2:$1/$2@$0](atlas/.*@.*)s/.*/atlas/
+               RULE:[2:$1/$2@$0](kudu/.*@.*)s/.*/kudu/
+               RULE:[2:$1/$2@$0](nifi/.*@.*)s/.*/nifi/
                RULE:[1:$1@$0](.*@.*)s/@.*//
                DEFAULT
         </value>
@@ -265,6 +281,21 @@
             - RULE:[2:$1/$2@$0]([ndj]n/.*@.*|hdfs/.*@.*)s/.*/hdfs/     # nn,dn,jn,hdfs/* -> hdfs (dev_hdfs)
             - RULE:[2:$1/$2@$0]([rn]m/.*@.*|yarn/.*@.*)s/.*/yarn/      # rm,nm,yarn/* -> yarn (dev_yarn)
             - RULE:[2:$1/$2@$0](jhs/.*@.*)s/.*/mapred/                 # jhs/* -> mapred
+            - RULE:[2:$1/$2@$0](hive/.*@.*)s/.*/hive/                  # hive/* -> hive (dev_hive)
+            - RULE:[2:$1/$2@$0](hbase/.*@.*)s/.*/hbase/                # hbase/* -> hbase (dev_hbase)
+            - RULE:[2:$1/$2@$0](kafka/.*@.*)s/.*/kafka/                # kafka/* -> kafka (dev_kafka)
+            - RULE:[2:$1/$2@$0](knox/.*@.*)s/.*/knox/                  # knox/* -> knox (dev_knox)
+            - RULE:[2:$1/$2@$0](rangerkms/.*@.*)s/.*/rangerkms/        # rangerkms/* -> rangerkms (dev_kms)
+            - RULE:[2:$1/$2@$0](trino/.*@.*)s/.*/trino/                # trino/* -> trino (dev_trino)
+            - RULE:[2:$1/$2@$0](ozone/.*@.*)s/.*/ozone/                # ozone/* -> ozone (dev_ozone)
+            - RULE:[2:$1/$2@$0](om/.*@.*)s/.*/om/                      # om/* -> om (dev_ozone)
+            - RULE:[2:$1/$2@$0](scm/.*@.*)s/.*/scm/                    # scm/* -> scm (dev_ozone)
+            - RULE:[2:$1/$2@$0](dn/.*@.*)s/.*/dn/                      # dn/* -> dn (dev_ozone)
+            - RULE:[2:$1/$2@$0](solr/.*@.*)s/.*/solr/                  # solr/* -> solr (dev_solr)
+            - RULE:[2:$1/$2@$0](rangertagsync/.*@.*)s/.*/rangertagsync/  # rangertagsync/* -> rangertagsync (dev_tag)
+            - RULE:[2:$1/$2@$0](atlas/.*@.*)s/.*/atlas/                # atlas/* -> atlas (dev_atlas)
+            - RULE:[2:$1/$2@$0](kudu/.*@.*)s/.*/kudu/                  # kudu/* -> kudu (dev_kudu)
+            - RULE:[2:$1/$2@$0](nifi/.*@.*)s/.*/nifi/                  # nifi/* -> nifi (dev_nifi)
             - RULE:[1:$1@$0](.*@.*)s/@.*//                             # user@REALM -> user
             - DEFAULT
         ]]></description>
@@ -401,6 +432,36 @@
         </description>
     </property>
 
+    <!--
+      Dynamic partition plan (Kafka compacted registry). Shipped disabled — legacy XML routing is the default.
+      When dynamic.enabled=true: runtime routing changes via REST only (not XML edits).
+    -->
+    <property>
+        <name>ranger.audit.ingestor.kafka.partition.plan.dynamic.enabled</name>
+        <value>false</value>
+        <description>
+            false or absent = legacy XML AuditPartitioner at startup (today's behavior).
+            true = Kafka registry + REST + PartitionPlanWatcher.
+        </description>
+    </property>
+    <!-- Optional when dynamic.enabled=true (defaults: topic=ranger_audit_partition_plan, refresh=30000 ms, consumer poll=500 ms):
+    <property>
+        <name>ranger.audit.ingestor.kafka.partition.plan.topic</name>
+        <value>ranger_audit_partition_plan</value>
+        <description>Compacted topic storing PartitionPlan JSON. Default ranger_audit_partition_plan if unset.</description>
+    </property>
+    <property>
+        <name>ranger.audit.ingestor.kafka.partition.plan.refresh.interval.ms</name>
+        <value>30000</value>
+        <description>Background watcher sleep between plan refresh cycles (milliseconds).</description>
+    </property>
+    <property>
+        <name>ranger.audit.ingestor.kafka.partition.plan.consumer.poll.timeout.ms</name>
+        <value>500</value>
+        <description>Kafka consumer poll timeout when draining the compacted plan topic (milliseconds). Default 500.</description>
+    </property>
+    -->
+
     <property>
         <name>ranger.audit.ingestor.kafka.security.protocol</name>
         <value>SASL_PLAINTEXT</value>
diff --git a/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/AuditPartitionerDynamicTest.java b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/AuditPartitionerDynamicTest.java
new file mode 100644
index 000000000..75431b395
--- /dev/null
+++ b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/AuditPartitionerDynamicTest.java
@@ -0,0 +1,159 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka;
+
+import org.apache.kafka.common.Cluster;
+import org.apache.kafka.common.Node;
+import org.apache.kafka.common.PartitionInfo;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanBootstrap;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanBootstrapConfig;
+import org.apache.ranger.audit.producer.kafka.partition.PartitionPlanHolder;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.server.AuditServerConstants;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertIterableEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class AuditPartitionerDynamicTest {
+    private static final String TOPIC = "ranger_audits";
+    private static final Node BROKER  = new Node(0, "localhost", 9092);
+
+    @AfterEach
+    public void tearDown() {
+        PartitionPlanHolder.getInstance().resetForTests();
+    }
+
+    @Test
+    public void testStaticModeUnchangedWhenDynamicDisabled() {
+        AuditPartitioner partitioner = new AuditPartitioner();
+        partitioner.configure(staticProducerConfig());
+
+        assertEquals(0, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertEquals(1, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertEquals(2, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertEquals(0, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertTrue(partitioner.partition(TOPIC, "unknownPlugin", null, null, null, cluster(15)) >= 6);
+    }
+
+    @Test
+    public void testDynamicModeRoutesConfiguredPluginRoundRobin() {
+        PartitionPlan plan = PartitionPlanBootstrap.createInitialPlan(PartitionPlanBootstrapConfig.create(TOPIC, new String[] {"hdfs", "hiveServer2"}, 3, 9));
+        PartitionPlanHolder.getInstance().install(plan, 15);
+
+        AuditPartitioner partitioner = new AuditPartitioner();
+        partitioner.configure(dynamicProducerConfig());
+
+        assertEquals(0, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertEquals(1, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertEquals(2, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertEquals(0, partitioner.partition(TOPIC, "hdfs", null, null, null, cluster(15)));
+        assertIterableEquals(List.of(3, 4, 5), List.of(
+                partitioner.partition(TOPIC, "hiveServer2", null, null, null, cluster(15)),
+                partitioner.partition(TOPIC, "hiveServer2", null, null, null, cluster(15)),
+                partitioner.partition(TOPIC, "hiveServer2", null, null, null, cluster(15))));
+    }
+
+    @Test
+    public void testDynamicModeRoutesUnknownPluginToBuffer() {
+        PartitionPlan plan = PartitionPlanBootstrap.createInitialPlan(PartitionPlanBootstrapConfig.create(TOPIC, new String[] {"hdfs"}, 3, 3));
+        PartitionPlanHolder.getInstance().install(plan, 6);
+
+        AuditPartitioner partitioner = new AuditPartitioner();
+        partitioner.configure(dynamicProducerConfig());
+
+        int partition = partitioner.partition(TOPIC, "trino", null, null, null, cluster(6));
+        assertTrue(partition >= 3 && partition <= 5);
+    }
+
+    @Test
+    public void testConcurrentPartitionWhilePlanSwaps() throws Exception {
+        PartitionPlan planV1 = PartitionPlanBootstrap.createInitialPlan(PartitionPlanBootstrapConfig.create(TOPIC, new String[] {"hdfs"}, 2, 2));
+        PartitionPlanHolder.getInstance().install(planV1, 4);
+
+        AuditPartitioner partitioner = new AuditPartitioner();
+        partitioner.configure(dynamicProducerConfig());
+        Cluster cluster = cluster(4);
+
+        PartitionPlan planV2 = planV1.toBuilder().version(2).updatedBy("test").build();
+
+        ExecutorService executor = Executors.newFixedThreadPool(8);
+        CountDownLatch startLatch = new CountDownLatch(1);
+        AtomicInteger errors = new AtomicInteger();
+        Set<Integer> seen = Collections.synchronizedSet(new HashSet<>());
+
+        for (int i = 0; i < 8; i++) {
+            executor.submit(() -> {
+                try {
+                    startLatch.await();
+                    for (int j = 0; j < 200; j++) {
+                        int p = partitioner.partition(TOPIC, "hdfs", null, null, null, cluster);
+                        seen.add(p);
+                    }
+                } catch (Exception e) {
+                    errors.incrementAndGet();
+                }
+            });
+        }
+
+        startLatch.countDown();
+        PartitionPlanHolder.getInstance().install(planV2, 4);
+        executor.shutdown();
+        assertTrue(executor.awaitTermination(10, TimeUnit.SECONDS));
+        assertEquals(0, errors.get());
+        assertTrue(seen.stream().allMatch(p -> p >= 0 && p < 4));
+    }
+
+    private static Map<String, Object> staticProducerConfig() {
+        String propPrefix = AuditServerConstants.PROP_PREFIX_AUDIT_SERVER;
+        Map<String, Object> config = new HashMap<>();
+        config.put(propPrefix + AuditServerConstants.PROP_CONFIGURED_PLUGINS, "hdfs,hiveServer2");
+        config.put(propPrefix + AuditServerConstants.PROP_TOPIC_PARTITIONS_PER_CONFIGURED_PLUGIN, 3);
+        config.put(propPrefix + AuditServerConstants.PROP_TOPIC_PARTITIONS, 15);
+        config.put(propPrefix + AuditServerConstants.PROP_BUFFER_PARTITIONS, 9);
+        return config;
+    }
+
+    private static Map<String, Object> dynamicProducerConfig() {
+        Map<String, Object> config = staticProducerConfig();
+        config.put(AuditServerConstants.PROP_PREFIX_AUDIT_SERVER.substring(0, AuditServerConstants.PROP_PREFIX_AUDIT_SERVER.length() - 1) + "." + AuditServerConstants.PROP_PARTITION_PLAN_DYNAMIC_ENABLED, "true");
+        return config;
+    }
+
+    private static Cluster cluster(int partitionCount) {
+        PartitionInfo[] partitionInfos = new PartitionInfo[partitionCount];
+        for (int i = 0; i < partitionCount; i++) {
+            partitionInfos[i] = new PartitionInfo(TOPIC, i, BROKER, new Node[] {BROKER}, new Node[] {BROKER});
+        }
+        return new Cluster("cluster", Collections.singletonList(BROKER), List.of(partitionInfos), Collections.emptySet(), Collections.emptySet());
+    }
+}
diff --git a/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanAllocatorTest.java b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanAllocatorTest.java
new file mode 100644
index 000000000..3be35b507
--- /dev/null
+++ b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanAllocatorTest.java
@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.producer.kafka.partition.exception.PartitionPlanException;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertIterableEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+public class PartitionPlanAllocatorTest {
+    private PartitionPlan initialPlan;
+
+    @BeforeEach
+    public void setUp() {
+        initialPlan = PartitionPlanBootstrap.createInitialPlan(PartitionPlanBootstrapConfig.create("ranger_audits", new String[] {"hdfs", "hiveServer2"}, 3, 9));
+    }
+
+    @Test
+    public void testPromotePluginFromBuffer() {
+        PartitionPlan next = PartitionPlanAllocator.promotePlugin(initialPlan, "trino", 3, "ops");
+
+        assertEquals(2, next.getVersion());
+        assertEquals(15, next.getTopicPartitionCount());
+        assertIterableEquals(List.of(6, 7, 8), next.getPlugins().get("trino").getPartitions());
+        assertIterableEquals(List.of(9, 10, 11, 12, 13, 14), next.getBuffer().getPartitions());
+        assertIterableEquals(List.of(0, 1, 2), next.getPlugins().get("hdfs").getPartitions());
+        assertIterableEquals(List.of(3, 4, 5), next.getPlugins().get("hiveServer2").getPartitions());
+    }
+
+    @Test
+    public void testPromotePluginGrowsTopicWhenBufferInsufficient() {
+        PartitionPlan next = PartitionPlanAllocator.promotePlugin(initialPlan, "trino", 12, "ops");
+
+        assertEquals(18, next.getTopicPartitionCount());
+        assertIterableEquals(List.of(6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17), next.getPlugins().get("trino").getPartitions());
+        assertEquals(0, next.getBuffer().size());
+    }
+
+    @Test
+    public void testScalePluginAppendsTailOnly() {
+        PartitionPlan promoted = PartitionPlanAllocator.promotePlugin(initialPlan, "trino", 3, "ops");
+        PartitionPlan scaled   = PartitionPlanAllocator.scalePlugin(promoted, "hiveServer2", 3, "ops");
+
+        assertEquals(3, scaled.getVersion());
+        assertEquals(18, scaled.getTopicPartitionCount());
+        assertIterableEquals(List.of(3, 4, 5, 15, 16, 17), scaled.getPlugins().get("hiveServer2").getPartitions());
+        assertIterableEquals(List.of(0, 1, 2), scaled.getPlugins().get("hdfs").getPartitions());
+        assertIterableEquals(List.of(6, 7, 8), scaled.getPlugins().get("trino").getPartitions());
+    }
+
+    @Test
+    public void testPromoteAlreadyConfiguredPluginFails() {
+        assertThrows(PartitionPlanException.class, () -> PartitionPlanAllocator.promotePlugin(initialPlan, "hdfs", 1, "ops"));
+    }
+
+    @Test
+    public void testScaleUnknownPluginFails() {
+        assertThrows(PartitionPlanException.class, () -> PartitionPlanAllocator.scalePlugin(initialPlan, "trino", 2, "ops"));
+    }
+}
diff --git a/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapSupportTest.java b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapSupportTest.java
new file mode 100644
index 000000000..9cb075232
--- /dev/null
+++ b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapSupportTest.java
@@ -0,0 +1,152 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.server.AuditServerConstants;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertIterableEquals;
+
+public class PartitionPlanBootstrapSupportTest {
+    private static final String TOPIC = "ranger_audits";
+
+    @Test
+    public void testBootstrapReturnsExistingPlan() {
+        PartitionPlan existing = samplePlan();
+        InMemoryPartitionPlanRegistry registry = new InMemoryPartitionPlanRegistry(existing);
+        Map<String, Object> config = producerConfig();
+
+        PartitionPlan plan = PartitionPlanBootstrap.bootstrapIfEmpty(registry, TOPIC, config);
+
+        assertEquals(existing, plan);
+        assertEquals(0, registry.getWriteCount());
+    }
+
+    @Test
+    public void testBootstrapPublishesV1WhenEmpty() {
+        InMemoryPartitionPlanRegistry registry = new InMemoryPartitionPlanRegistry(null);
+        Map<String, Object> config = producerConfig();
+
+        PartitionPlan plan = PartitionPlanBootstrap.bootstrapIfEmpty(registry, TOPIC, config);
+
+        assertEquals(1, plan.getVersion());
+        assertEquals(15, plan.getTopicPartitionCount());
+        assertIterableEquals(plan.getPlugins().get("hdfs").getPartitions(), registry.readPlan(TOPIC).getPlugins().get("hdfs").getPartitions());
+        assertEquals(1, registry.getWriteCount());
+    }
+
+    @Test
+    public void testBootstrapAdoptsPeerPlanBeforePublish() {
+        PartitionPlan peerPlan = samplePlan().toBuilder().updatedBy("peer").build();
+        PeerPublishesOnSecondReadRegistry registry = new PeerPublishesOnSecondReadRegistry(peerPlan);
+
+        PartitionPlan plan = PartitionPlanBootstrap.bootstrapIfEmpty(registry, TOPIC, producerConfig());
+
+        assertEquals(peerPlan, plan);
+        assertEquals(0, registry.getWriteCount());
+    }
+
+    private static Map<String, Object> producerConfig() {
+        String propPrefix = AuditServerConstants.PROP_PREFIX_AUDIT_SERVER;
+        Map<String, Object> config = new HashMap<>();
+        config.put(propPrefix + AuditServerConstants.PROP_CONFIGURED_PLUGINS, "hdfs,hiveServer2");
+        config.put(propPrefix + AuditServerConstants.PROP_TOPIC_PARTITIONS_PER_CONFIGURED_PLUGIN, 3);
+        config.put(propPrefix + AuditServerConstants.PROP_BUFFER_PARTITIONS, 9);
+        return config;
+    }
+
+    private static PartitionPlan samplePlan() {
+        return PartitionPlanBootstrap.createInitialPlan(PartitionPlanBootstrapConfig.create(TOPIC, new String[] {"hdfs", "hiveServer2"}, 3, 9));
+    }
+
+    private static final class PeerPublishesOnSecondReadRegistry implements PartitionPlanRegistry {
+        private final PartitionPlan peerPlan;
+        private int readCount;
+        private int writeCount;
+
+        private PeerPublishesOnSecondReadRegistry(PartitionPlan peerPlan) {
+            this.peerPlan = peerPlan;
+        }
+
+        @Override
+        public String getPlanTopicName() {
+            return "ranger_audit_partition_plan";
+        }
+
+        @Override
+        public PartitionPlan readPlan(String auditTopicKey) {
+            readCount++;
+            if (readCount >= 2) {
+                return peerPlan;
+            }
+            return null;
+        }
+
+        @Override
+        public void writePlan(String auditTopicKey, PartitionPlan plan) {
+            writeCount++;
+        }
+
+        @Override
+        public void close() {
+        }
+
+        private int getWriteCount() {
+            return writeCount;
+        }
+    }
+
+    private static class InMemoryPartitionPlanRegistry implements PartitionPlanRegistry {
+        private final AtomicReference<PartitionPlan> planRef;
+        private int writeCount;
+
+        private InMemoryPartitionPlanRegistry(PartitionPlan initialPlan) {
+            this.planRef = new AtomicReference<>(initialPlan);
+        }
+
+        @Override
+        public String getPlanTopicName() {
+            return "ranger_audit_partition_plan";
+        }
+
+        @Override
+        public PartitionPlan readPlan(String auditTopicKey) {
+            return planRef.get();
+        }
+
+        @Override
+        public void writePlan(String auditTopicKey, PartitionPlan plan) {
+            planRef.set(plan);
+            writeCount++;
+        }
+
+        @Override
+        public void close() {
+        }
+
+        private int getWriteCount() {
+            return writeCount;
+        }
+    }
+}
diff --git a/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapTest.java b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapTest.java
new file mode 100644
index 000000000..4ecd6adc5
--- /dev/null
+++ b/audit-server/audit-ingestor/src/test/java/org/apache/ranger/audit/producer/kafka/partition/PartitionPlanBootstrapTest.java
@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.ranger.audit.producer.kafka.partition;
+
+import org.apache.ranger.audit.producer.kafka.partition.constants.PartitionPlanConstants;
+import org.apache.ranger.audit.producer.kafka.partition.model.PartitionPlan;
+import org.apache.ranger.audit.server.AuditServerConstants;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertIterableEquals;
+
... 2450 lines suppressed ...