(kafka) branch trunk updated: KIP-966 part 1 release doc (#18898)

[cm...@apache.org]

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

cmccabe pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 009bee75ab4 KIP-966 part 1 release doc (#18898)
009bee75ab4 is described below

commit 009bee75ab4bc4878a14e915c99be6ae937a0855
Author: Calvin Liu <83...@users.noreply.github.com>
AuthorDate: Mon Feb 24 15:19:18 2025 -0800

    KIP-966 part 1 release doc (#18898)
    
    Add notes to explain how ELR and how to manage ELR.
    
    Reviewers: Colin P. McCabe <cm...@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 ffaca8bf3b8..3177b49d487 100644
--- a/docs/ops.html
+++ b/docs/ops.html
@@ -4281,6 +4281,32 @@ $ bin/kafka-topics.sh --create --topic tieredTopic --bootstrap-server localhost:
   <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 4ea791f3a7f..48b829759e9 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -81,6 +81,13 @@
             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.