From 009bee75ab4bc4878a14e915c99be6ae937a0855 Mon Sep 17 00:00:00 2001
From: Calvin Liu <83986057+CalvinConfluent@users.noreply.github.com>
Date: Mon, 24 Feb 2025 15:19:18 -0800
Subject: [PATCH] KIP-966 part 1 release doc (#18898)

Add notes to explain how ELR and how to manage ELR.

Reviewers: Colin P. McCabe <cmccabe@apache.org>
---
 docs/ops.html     | 26 ++++++++++++++++++++++++++
 docs/upgrade.html |  7 +++++++
 2 files changed, 33 insertions(+)

diff --git a/docs/ops.html b/docs/ops.html
index ffaca8bf3b863..3177b49d48722 100644
--- a/docs/ops.html
+++ b/docs/ops.html
@@ -4281,6 +4281,32 @@ <h4 class="anchor-heading"><a id="transaction_protocol_performance" class="ancho
   <li><code>add.partitions.to.txn.retry.backoff.max.ms</code></li>
 </ul>
 
+  <h3 class="anchor-heading"><a id="eligible_leader_replicas" class="anchor-link"></a><a href="#eligible_leader_replicas">6.12 Eligible Leader Replicas</a></h3>
+
+  <h4 class="anchor-heading"><a id="eligible_leader_replicas_overview" class="anchor-link"></a><a href="#eligible_leader_replicas_overview">Overview</a></h4>
+
+  <p>Starting from Apache Kafka 4.0, Eligible Leader Replicas (<a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-966%3A+Eligible+Leader+Replicas">KIP-966 Part 1</a>)
+    is available for the users to an improvement to Kafka replication. As the "strict min ISR" rule has been generally applied, which means the high watermark for the data partition can't advance
+    if the size of the ISR is smaller than the min ISR(<code>min.insync.replicas</code>), it makes some replicas that are not in the ISR safe to become the leader. The KRaft controller
+    stores such replicas in the PartitionRecord field called <code>Eligible Leader Replicas</code>. During the leader election, the controller will select the leaders
+    with the following order:</p>
+  <ul>
+    <li>If ISR is not empty, select one of them.</li>
+    <li>If ELR is not empty, select one that is not fenced.</li>
+    <li>Select the last known leader if it is unfenced. This is a similar behavior prior to the 4.0 when all the replicas are offline.</li>
+  </ul>
+
+  <h4 class="anchor-heading"><a id="eligible_leader_replicas_upgrade" class="anchor-link"></a><a href="#eligible_leader_replicas_upgrade">Upgrade & Downgrade</a></h4>
+
+  <p>The ELR is not enabled by default for 4.0. To enable the new protocol on the server, set <code>eligible.leader.replicas.version=1</code>. After that the upgrade, the KRaft
+    controller will start tracking the ELR. </p>
+  <p>Downgrades are safe to perform by setting <code>eligible.leader.replicas.version=0</code>.</p>
+
+  <h4 class="anchor-heading"><a id="eligible_leader_replicas_tool" class="anchor-link"></a><a href="#eligible_leader_replicas_tool">Tool</a></h4>
+  <p>The ELR fields can be checked through the API DescribeTopicPartitions. The admin client can fetch the ELR info by describing the topics.
+    Also note that, if <code>min.insync.replicas</code> is updated for a topic, the ELR field will be cleaned. If cluster default min ISR is updated,
+    all the ELR fields will be cleaned.</p>
+
 </script>
 
 <div class="p-ops"></div>
diff --git a/docs/upgrade.html b/docs/upgrade.html
index 4ea791f3a7faa..48b829759e9f7 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -81,6 +81,13 @@ <h5><a id="upgrade_400_notable" href="#upgrade_400_notable">Notable changes in 4
             When using 4.0 producer clients, the producer epoch is bumped on every transaction to ensure every transaction includes the intended messages and duplicates are not
             written as part of the next transaction. Downgrading the protocol is safe. For more information check <a href="/{{version}}/documentation.html#transaction_protocol">here</a>
         </li>
+        <li>
+            Eligible Leader Replicas (<a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-966%3A+Eligible+Leader+Replicas">KIP-966 Part 1</a>)
+            enhances the replication protocol for the Apache Kafka 4.0. Now the KRaft controller keeps track of the data partition replicas that are
+            not included in ISR but are safe to be elected as leader without data loss. Such replicas are stored in the partition metadata as
+            the <code>Eligible Leader Replicas</code>(ELR).
+            For more information check <a href="/{{version}}/documentation.html#eligible_leader_replicas">here</a>
+        </li>
         <li>
             Since Apache Kafka 4.0.0, we have added a system property ("org.apache.kafka.sasl.oauthbearer.allowed.urls") to
             set the allowed URLs as SASL OAUTHBEARER token or jwks endpoints. By default, the value is an empty list.