Skip to content

Commit 657b496

Browse files
authored
MINOR: improve the min.insync.replicas doc (#20237)
Along with the change: #17952 ([KIP-966](https://cwiki.apache.org/confluence/display/KAFKA/KIP-966%3A+Eligible+Leader+Replicas)), the semantics of `min.insync.replicas` config has small change, and add some constraints. We should document them clearly. Reviewers: Jun Rao <[email protected]>, Calvin Liu <[email protected]>, Mickael Maison <[email protected]>, Paolo Patierno <[email protected]>, Federico Valeri <[email protected]>, Chia-Ping Tsai <[email protected]>
1 parent 904ee87 commit 657b496

File tree

4 files changed

+15
-5
lines changed

4 files changed

+15
-5
lines changed

clients/src/main/java/org/apache/kafka/common/config/TopicConfig.java

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,8 @@ public class TopicConfig {
181181
"When used together, <code>min.insync.replicas</code> and <code>acks</code> allow you to enforce greater durability guarantees. " +
182182
"A typical scenario would be to create a topic with a replication factor of 3, " +
183183
"set <code>min.insync.replicas</code> to 2, and produce with <code>acks</code> of \"all\". " +
184-
"This will ensure that a majority of replicas must persist a write before it's considered successful by the producer and it's visible to consumers.";
184+
"This ensures that a majority of replicas must persist a write before it's considered successful by the producer and it's visible to consumers." +
185+
"<p>Note that when the Eligible Leader Replicas feature is enabled, the semantics of this config changes. Please refer to <a href=\"#eligible_leader_replicas\">the ELR section</a> for more info.</p>";
185186

186187
public static final String COMPRESSION_TYPE_CONFIG = "compression.type";
187188
public static final String COMPRESSION_TYPE_DOC = "Specify the final compression type for a given topic. " +

docs/ops.html

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4501,9 +4501,16 @@ <h4 class="anchor-heading"><a id="eligible_leader_replicas_upgrade" class="ancho
45014501
<p>Downgrades are safe to perform by setting <code>eligible.leader.replicas.version=0</code>.</p>
45024502

45034503
<h4 class="anchor-heading"><a id="eligible_leader_replicas_tool" class="anchor-link"></a><a href="#eligible_leader_replicas_tool">Tool</a></h4>
4504-
<p>The ELR fields can be checked through the API DescribeTopicPartitions. The admin client can fetch the ELR info by describing the topics.
4505-
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,
4506-
all the ELR fields will be cleaned.</p>
4504+
<p>The ELR fields can be checked through the API DescribeTopicPartitions. The admin client can fetch the ELR info by describing the topics.</p>
4505+
<p>Note that when the ELR feature is enabled:</p>
4506+
<ul>
4507+
<li>The cluster-level <code>min.insync.replicas</code> config will be added if there is not any. The value is the same as the static config in the active controller.</li>
4508+
<li>The removal of <code>min.insync.replicas</code> config at the cluster-level is not allowed.</li>
4509+
<li>If the cluster-level <code>min.insync.replicas</code> is updated, even if the value is unchanged, all the ELR state will be cleaned.</li>
4510+
<li>The previously set <code>min.insync.replicas</code> value at the broker-level config will be removed. Please set at the cluster-level if necessary.</li>
4511+
<li>The alteration of <code>min.insync.replicas</code> config at the broker-level is not allowed.</li>
4512+
<li>If <code>min.insync.replicas</code> is updated for a topic, the ELR state will be cleaned.</li>
4513+
</ul>
45074514

45084515
</script>
45094516

docs/upgrade.html

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ <h5><a id="upgrade_410_notable" href="#upgrade_410_notable">Notable changes in 4
6868
</li>
6969
<li>
7070
The KIP-966 part 1: Eligible Leader Replicas(ELR) will be enabled by default on the new clusters.
71+
After the ELR feature enabled, the previously set <code>min.insync.replicas</code> value at the broker-level config will be removed.
72+
Please set at the cluster-level if necessary.
7173
For further details, please refer to <a href="/{{version}}/documentation.html#eligible_leader_replicas">here</a>.
7274
</li>
7375
</ul>

metadata/src/main/java/org/apache/kafka/controller/ConfigurationControlManager.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -611,7 +611,7 @@ int getStaticallyConfiguredMinInsyncReplicas() {
611611

612612
/**
613613
* Generate any configuration records that are needed to make it safe to enable ELR.
614-
* Specifically, we need to remove all cluster-level configurations for min.insync.replicas,
614+
* Specifically, we need to remove all broker-level configurations for min.insync.replicas,
615615
* and create a cluster-level configuration for min.insync.replicas. It is always safe to call
616616
* this function if ELR is already enabled; it will simply do nothing if the necessary
617617
* configurations already exist.

0 commit comments

Comments
 (0)