docs(review): minor updates to mm2 config (#12273)

Signed-off-by: prmellor <pmellor@redhat.com>

Author: PaulRMellor

documentation/modules/configuring/con-config-kafka-connect-multiple-instances.adoc

@@ -28,7 +28,7 @@ spec:
 <3> Kafka topic that stores connector offsets.
 <4> Kafka topic that stores connector and task status updates.
 
-NOTE: Values for the three topics must be the same for all instances with the same `group.id`.
+This requirement applies across all Kafka Connect–based deployments, including Kafka Connect and  MirrorMaker 2 instances that target the same Kafka cluster.
 
 Unless you use different settings for each instance, all instances form a cluster and use the same internal topics.
 Multiple instances attempting to use the same internal topics will cause unexpected errors, so you must change the values of these properties for each instance.

documentation/modules/configuring/con-config-mirrormaker2-connect-workers.adoc

@@ -8,7 +8,11 @@
 = Tuning Kafka Connect worker settings
 
 [role="_abstract"]
-Adjust Kafka Connect worker behavior for MirrorMaker 2 by adding configuration to your target cluster's `config` section.
+Adjust Kafka Connect worker runtime behavior for MirrorMaker 2 by configuring worker properties on the Kafka Connect cluster that runs the MirrorMaker 2 connectors.
+
+Kafka Connect workers running MirrorMaker 2 connectors are configured to store their internal state in a single target Kafka cluster.
+The worker configuration specifies Kafka Connect runtime settings, such as task rebalance behavior, shutdown handling, and how frequently offsets are written to internal topics.
+To preserve records without modification, configure byte array converters for record keys and values.
 
 .Example Kafka Connect configuration
 [source,yaml,subs="+quotes,attributes"]
@@ -28,12 +32,19 @@ spec:
     offsetStorageTopic: my-mirror-maker2-offset
     statusStorageTopic: my-mirror-maker2-status
     config: # <2>
+      # Key and value converters
+      key.converter: org.apache.kafka.connect.converters.ByteArrayConverter
+      value.converter: org.apache.kafka.connect.converters.ByteArrayConverter
+      # Worker shutdown and rebalance behavior
       task.shutdown.graceful.timeout.ms: 30000
       scheduled.rebalance.max.delay.ms: 300000
+      # Offset flush interval
       offset.flush.interval.ms: 10000
-      config.storage.replication.factor: 1
-      offset.storage.replication.factor: 1
-      status.storage.replication.factor: 1
+      # Kafka Connect internal topic replication
+      config.storage.replication.factor: -1
+      offset.storage.replication.factor: -1
+      status.storage.replication.factor: -1
 ----
 <1> The target cluster configuration. The target cluster is always used to store Kafka Connect's internal topics.
-<2> These properties configure the Kafka Connect workers in this cluster.
+<2> These properties configure the Kafka Connect workers created by this `KafkaMirrorMaker2` resource.
+The settings apply to all MirrorMaker 2 connectors managed by the resource.

documentation/modules/configuring/con-config-mirrormaker2-connectors.adoc

@@ -8,7 +8,7 @@
 = Configuring MirrorMaker 2 connectors
 
 [role="_abstract"]
-MirrorMaker 2 uses internal connectors to synchronize data between Kafka clusters. 
+MirrorMaker 2 comprises a set of connectors to synchronize data between Kafka clusters. 
 You configure these connectors in the `KafkaMirrorMaker2` custom resource.
 
 MirrorMaker 2 consists of the following connectors:
@@ -20,11 +20,14 @@ MirrorMaker 2 consists of the following connectors:
 `MirrorSourceConnector` and `MirrorCheckpointConnector` are configured in the
 `spec.mirrors` section of the `KafkaMirrorMaker2` custom resource using the `sourceConnector` and `checkpointConnector` properties.
 
+These connectors run in the Kafka Connect cluster associated with the target Kafka cluster.
+
 `MirrorHeartbeatConnector` is not configurable through the `KafkaMirrorMaker2` custom resource.
 To run a `MirrorHeartbeatConnector`, use a separate `KafkaConnect` and `KafkaConnector` custom resource.
+Because it produces heartbeat records to the source Kafka cluster, the `MirrorHeartbeatConnector` typically runs in a Kafka Connect cluster that stores its state in the source cluster.
 
 For a full list of supported MirrorMaker 2 connector properties, including common configuration and connector-specific options, see the {kafkaDoc}.
 
-WARNING: Configure the following properties with the *same values in both the source and checkpoint connectors*:
+WARNING: Configure the following properties with the same values in both the `MirrorSourceConnector` and `MirrorCheckpointConnector`:
 `replication.policy.class`, `replication.policy.separator`, `offset-syncs.topic.location`, and `topic.filter.class`.
 If these properties do not match, replication or offset synchronization can fail.

documentation/modules/configuring/con-config-mirrormaker2-producers-consumers.adoc

@@ -9,50 +9,57 @@
 
 [role="_abstract"]
 MirrorMaker 2 connectors use internal producers and consumers.
-If needed, you can configure these producers and consumers to override the default settings. 
+If required, you can configure these producers and consumers to override the default settings. 
 
 For example, you can increase the `batch.size` for the source producer that sends topics to the target Kafka cluster to better accommodate large volumes of messages.
 
 IMPORTANT: Producer and consumer configuration options depend on the MirrorMaker 2 implementation, and may be subject to change.  
 
 The following tables describe the producers and consumers for each of the connectors and where you can add configuration. 
 
+Configuration can be applied as follows:
+
+* Overriding the configuration used by the internal producer or consumer by using the `producer.override.` or `consumer.override.` properties.
+* Configuring the internal producer or consumer directly in the connector by using the `producer.` or `consumer.` properties.
+
 .Source connector producers and consumers
-[cols="1,1a,3m",options="header"]
+[cols="1,2a,2m",options="header"]
 |===
 
 |Type
 |Description
 |Configuration
 
 |Producer
-|Sends topic messages to the target Kafka cluster. Consider tuning the configuration of this producer when it is handling large volumes of data. 
-|mirrors.sourceConnector.config: producer.override.*
+|Sends replicated topic messages to the target Kafka cluster.
+Tune this producer when handling large volumes of data.
+|`producer.override.*`
 
 |Producer
-|Writes to the `offset-syncs` topic, which maps the source and target offsets for replicated topic partitions. 
-|mirrors.sourceConnector.config: producer.*
+|Writes to the `offset-syncs` topic, which maps source and target offsets.
+|`producer.*`
 
 |Consumer
-|Retrieves topic messages from the source Kafka cluster.
-|mirrors.sourceConnector.config: consumer.* 
+|Consumes topic messages from the source Kafka cluster.
+|`consumer.*`
+
 |===
 
 .Checkpoint connector producers and consumers
-[cols="1,1a,3m",options="header"]
+[cols="1,2a,2m",options="header"]
 |===
 
 |Type
 |Description
 |Configuration
 
 |Producer
-|Emits consumer offset checkpoints.
-|mirrors.checkpointConnector.config: producer.override.* 
+|Emits consumer group offset checkpoints.
+|`producer.override.*`
 
 |Consumer
-|Loads the `offset-syncs` topic.
-|mirrors.checkpointConnector.config: consumer.*
+|Consumes data from the `offset-syncs` topic.
+|`consumer.*`
 
 |===
 

documentation/modules/configuring/con-config-mirrormaker2-sync-acls.adoc

@@ -11,15 +11,20 @@
 MirrorMaker 2 can synchronize topic ACL rules from source to target clusters. 
 Enable this feature by configuring the `MirrorSourceConnector`.
 
-With `simple` authorization:
+When using simple ACL-based authorization:
 
-* ACL rules apply to both source and target topics
-* Users with source topic access automatically get equivalent target topic access
+* Topic ACL rules can be synchronized between source and target topics
+* MirrorMaker 2 copies topic-related ACL rules from the source cluster to the target cluster
+* The `ALLOW ALL` topic ACL is not copied
 
-IMPORTANT: This feature is not compatible with the User Operator, so disable by setting `sync.topic.acls.enabled` to `false`.
+Copying ACL rules does not guarantee equivalent access for all operations on the target cluster.
+Additional ACL rules may still be required to allow producers or consumers to operate as expected on the target cluster, for example, ACLs for other resource types such as consumer groups or transactional IDs.
+
+IMPORTANT: This feature is not compatible with the User Operator. 
+If you use the User Operator, set `sync.topic.acls.enabled` to `false`.
 When using OAuth 2.0 authorization, the setting has no effect.
 
-.Example configuration to enable offset synchronization
+.Example configuration to enable ACL synchronization
 [source,yaml,subs="+quotes,attributes"]
 ----
 apiVersion: {KafkaMirrorMaker2ApiVersion}
@@ -34,4 +39,4 @@ metadata:
         config:
           sync.topic.acls.enabled: "true" # <1>
 ----
-<1> Replicates all source topic ACLs to the target cluster.
+<1> Copies topic-related ACL rules from the source cluster to the target cluster.

documentation/modules/configuring/con-config-mirrormaker2-sync.adoc

@@ -24,15 +24,17 @@ Configuring the `MirrorCheckpointConnector` to emit periodic offset checkpoints
 * Failover recovery as consumers switch to the target cluster at the correct position
 
 Offset synchronization occurs at regular intervals.
-The `MirrorCheckpointConnector` emits checkpoints for all consumer groups.
+The `MirrorCheckpointConnector` emits checkpoints for all consumer groups enabled by the group configuration.
 However, applying those checkpoints in the target cluster requires the target group to be inactive.
-If consumers switch to the target cluster between checkpoints, they might reprocess some messages because the last synchronized offset lags behind the source.
+If consumers switch to the target cluster between checkpoints, they might reprocess some messages because offset synchronization is asynchronous and the last synchronized offset lags behind the source.
 This duplication is expected.
 
 NOTE: The connector continues to emit checkpoints to the checkpoints topic even if the target consumer group is active. 
-However, the offsets cannot be committed while the group has active members. 
+However, the offsets cannot be committed while the consumer group has active members. 
 In this case, the connector logs a warning and the offsets are not synchronized.
 
+Each connector is configured separately.
+
 .Example configuration to enable offset synchronization
 [source,yaml,subs="+quotes,attributes"]
 ----
@@ -67,15 +69,15 @@ A value of -1 uses the broker’s default replication factor, which is typically
 <7> Replication factor for the internal checkpoints topic that stores the last committed offsets for each consumer group. 
 A value of -1 uses the broker’s default replication factor, which is typically set to provide resilience (for example, 3).
 
-TIP: If you have an application written in Java, you can use the `RemoteClusterUtils.java` utility to fetch offsets through the application. 
-The utility fetches remote offsets for a consumer group from the `checkpoints` topic.
+TIP: Java applications can use the `RemoteClusterUtils` utility to fetch remote offsets for a consumer group from the checkpoints topic.
+
+== Changing the location of the offset synchronization topic
 
-== Changing the location of the consumer group offsets topic
+By default, the `offset-syncs` topic used by the `MirrorSourceConnector` is created in the source cluster.
+You can change this behavior by setting the `offset-syncs.topic.location` connector configuration to `target`.
 
-The location of the `offset-syncs` topic is the `source` cluster by default.
-You can use the `offset-syncs.topic.location` connector configuration to change this to the `target` cluster.
-You need read/write access to the cluster that contains the topic.
-Using the target cluster as the location of the `offset-syncs` topic allows you to use MirrorMaker 2 even if you have only read access to the source cluster.
+Placing the `offset-syncs` topic on the target cluster allows the `MirrorSourceConnector` to run when it has read-only access to the source cluster.
+The connector must still have read and write access to the `offset-syncs` topic on the cluster where the topic is located.
 
 == Listing the offsets of connectors
 
@@ -170,5 +172,5 @@ data:
 To provide a custom owner reference, create the `ConfigMap` in advance and set the owner reference.
 <2> The `.json` property uses the connector name. Since `&#45;&#62;` characters are not allowed in `ConfigMap` keys, `&#45;&#62;` is changed to `--` in the connector name.
 
-NOTE: It is possible to use configuration to xref:proc-altering-connector-offsets-{context}[alter] or xref:proc-resetting-connector-offsets-{context}[reset] connector offsets, though this is rarely necessary.
-
+NOTE: It is possible to use configuration to xref:proc-altering-connector-offsets-{context}[alter] or xref:proc-resetting-connector-offsets-{context}[reset] connector offsets. 
+This should be done with caution.

documentation/modules/configuring/con-config-mm2-multiple-instances.adoc

@@ -8,8 +8,25 @@
 = Configuring MirrorMaker 2 using a shared target Kafka cluster
 
 [role="_abstract"]
-The group ID and names of the internal topics used by the Kafka Connect framework that MirrorMaker 2 runs on are configured in the `.spec.target` section. 
-When running multiple instances of MirrorMaker 2, and they share the same target cluster, you must use unique values to make sure the MirrorMaker 2 clusters operate independently.
+MirrorMaker 2 runs on the Kafka Connect framework and uses internal Kafka topics to store configuration, offsets, and status information.
+
+You can run multiple MirrorMaker 2 connectors in a single Kafka Connect cluster, for example to replicate data from multiple source Kafka clusters to the same target Kafka cluster.
+
+When running multiple Kafka Connect clusters that replicate data to the same target Kafka cluster, you must configure unique Kafka Connect worker settings so that each cluster operates independently.
+
+This requirement applies across all Kafka Connect–based deployments, including Kafka Connect and  MirrorMaker 2 instances that target the same Kafka cluster.
+
+Kafka Connect identifies a worker cluster by its group ID and by the names of the internal topics it uses.
+If multiple Kafka Connect clusters use the same values, they form a single Kafka Connect cluster and share internal state.
+
+When deploying multiple Kafka Connect clusters against the same target Kafka cluster, configure unique values for the following Kafka Connect worker properties in each deployment:
+
+* `group.id`
+* `config.storage.topic`
+* `offset.storage.topic`
+* `status.storage.topic`
+
+These settings are configured in the `.spec.target` section. 
 
 [source,yaml,subs="attributes+"]
 ----
@@ -33,13 +50,11 @@ spec:
 <3> Kafka topic that stores connector and task status configurations.
 <4> Kafka topic that stores connector and task status updates.
 
-NOTE: Values for the three topics must be the same for all instances with the same `group.id`.
-
-The `target` cluster specifies the target Kafka cluster used by Kafka Connect for its internal topics. 
-As a result, modifications to the `target`, group ID, and internal topic naming configuration are specific to the target Kafka cluster. 
-You don't need to make changes if two MirrorMaker 2 instances are using the same source Kafka cluster or in an active-active mode where each MirrorMaker 2 instance has a different target cluster.
+If multiple Kafka Connect clusters are deployed with the same worker group ID and internal topic names, they form a single Kafka Connect cluster and share internal state.
+This can result in unexpected behavior and replication errors.
 
-However, if multiple MirrorMaker 2 instances share the same `target`, each instance connecting to the same target Kafka cluster is deployed with the same values. 
-In practice, this means all instances form a cluster and use the same internal topics.
+You do not need to change these settings when:
 
-Multiple instances attempting to use the same internal topics will cause unexpected errors, so you must change the values of these properties for each instance.
+* Running multiple MirrorMaker 2 connectors in a single Kafka Connect cluster
+* Replicating data from the same source Kafka cluster to different target Kafka clusters by using separate Kafka Connect clusters
+* Deploying active-active replication, where each Kafka Connect cluster targets a different Kafka cluster

documentation/modules/configuring/con-mm2-recovery.adoc

@@ -13,7 +13,7 @@ To support this, the Kafka cluster should also be monitored for health and perfo
 
 If failover occurs, which can be automated, operations switch from the active cluster to the passive cluster when the active cluster becomes unavailable.
 The original active cluster is typically considered permanently lost.
-The passive cluster is promoted to active status, taking over as the source for all application traffic.
+The passive cluster is promoted to active status, taking over as the source and target for all application traffic.
 In this state, MirrorMaker 2 no longer replicates data from the original active cluster while it remains unavailable.
 
 Failback, or restoring operations to the original active cluster, requires careful planning.
@@ -25,20 +25,20 @@ For a simpler and more reliable failback process, rebuild the original active cl
 
 Follow these best practices for disaster recovery in the event of failure of the active cluster in an active/passive configuration:
 
-. Promote the passive recovery cluster to an active role. +
+. Promote the passive recovery cluster to an active role. 
 Designate the passive cluster as the active cluster for all client connections.
 This minimizes downtime and ensures operations can continue.
-. Redirect applications to the new active recovery cluster. +
+. Redirect applications to the new active recovery cluster. 
 MirrorMaker 2 synchronizes committed offsets to passive clusters, allowing consumer applications to resume from the last transferred offset when switching to the recovery cluster.
 However, because of the time lag in offset synchronization, switching consumers may result in some message duplication.
 To minimize duplication, switch all members of a consumer group together as soon as possible. 
 Keeping the group intact minimizes the chance of a consumer processing duplicate messages.
-. Remove the MirrorMaker 2 configuration for replication from the original active cluster to the passive cluster. +
+. Remove the MirrorMaker 2 configuration for replication from the original active cluster to the passive cluster. 
 After failover, the original configuration is no longer needed and should be removed to avoid conflicts.
 . Re-create the failed cluster in a clean state, adhering to the original configuration.
-. Deploy a new MirrorMaker 2 instance to replicate data from the active recovery cluster to the rebuilt cluster. +
+. Deploy a new MirrorMaker 2 instance to replicate data from the active recovery cluster to the rebuilt cluster. 
 Treat the rebuilt cluster as the passive cluster during this replication process.
-To prevent automatic renaming of topics, configure MirrorMaker 2 to use the `IdentityReplicationPolicy` by setting the `replication.policy.class` property in the MirrorMaker 2 configuration.
+To prevent automatic renaming of topics, configure MirrorMaker 2 to use the `IdentityReplicationPolicy` by setting the `replication.policy.class` property in the connector configuration.
 With this configuration applied, topics retain their original names in the target cluster.
 . Ensure the rebuilt cluster mirrors all data from the now-active recovery cluster.
 . (Optional) Promote the rebuilt cluster back to active status by redirecting applications to the rebuilt cluster, after ensuring it is fully synchronized with the active cluster.