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]>

Author: showuon

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

@@ -181,7 +181,8 @@ public class TopicConfig {
         "When used together, <code>min.insync.replicas</code> and <code>acks</code> allow you to enforce greater durability guarantees. " +
         "A typical scenario would be to create a topic with a replication factor of 3, " +
         "set <code>min.insync.replicas</code> to 2, and produce with <code>acks</code> of \"all\". " +
-        "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.";
+        "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." +
+        "<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>";
 
     public static final String COMPRESSION_TYPE_CONFIG = "compression.type";
     public static final String COMPRESSION_TYPE_DOC = "Specify the final compression type for a given topic. " +

docs/ops.html

@@ -4499,9 +4499,16 @@ <h4 class="anchor-heading"><a id="eligible_leader_replicas_upgrade" class="ancho
   <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>
+  <p>The ELR fields can be checked through the API DescribeTopicPartitions. The admin client can fetch the ELR info by describing the topics.</p>
+  <p>Note that when the ELR feature is enabled:</p>
+  <ul>
+    <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>
+    <li>The removal of <code>min.insync.replicas</code> config at the cluster-level is not allowed.</li>
+    <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>
+    <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>
+    <li>The alteration of <code>min.insync.replicas</code> config at the broker-level is not allowed.</li>
+    <li>If <code>min.insync.replicas</code> is updated for a topic, the ELR state will be cleaned.</li>
+  </ul>
 
 </script>
 

docs/upgrade.html

@@ -48,6 +48,8 @@ <h6><a id="upgrade_410_notable" href="#upgrade_410_notable">Notable changes in 4
                     </li>
                     <li>
                         The KIP-966 part 1: Eligible Leader Replicas(ELR) will be enabled by default on the new clusters.
+                        After the ELR feature enabled, 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.
                         For further details, please refer to <a href="/{{version}}/documentation.html#eligible_leader_replicas">here</a>.
                     </li>
                 </ul>

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

@@ -613,7 +613,7 @@ int getStaticallyConfiguredMinInsyncReplicas() {
 
     /**
      * Generate any configuration records that are needed to make it safe to enable ELR.
-     * Specifically, we need to remove all cluster-level configurations for min.insync.replicas,
+     * Specifically, we need to remove all broker-level configurations for min.insync.replicas,
      * and create a cluster-level configuration for min.insync.replicas. It is always safe to call
      * this function if ELR is already enabled; it will simply do nothing if the necessary
      * configurations already exist.