Update the cdc technical overview for new changefeed work distribution (

#18745)

src/current/_includes/releases/v24.1/v24.1.0-alpha.5.md

@@ -6,7 +6,7 @@ Release Date: April 1, 2024
 
 <h3 id="v24-1-0-alpha-5-{{-site.data.products.enterprise-}}-edition-changes">{{ site.data.products.enterprise }} edition changes</h3>
 
-- [Changefeeds]({% link v24.1/change-data-capture-overview.md %}) now default to evenly distributing their work across all replicas, including followers, regardless of leaseholder placement. To disable this behavior, set the [cluster setting]({% link v24.1/cluster-settings.md %}) `changefeed.random_replica_selection.enabled ` to `false`. If disabled, changefeed planning reverts to its previous behavior for distributing work. [#120077][#120077]
+- [Changefeeds]({% link v24.1/change-data-capture-overview.md %}) now default to evenly distributing their work across all replicas, including followers, regardless of leaseholder placement. On upgrade to v24.1, running changefeed jobs will be restarted automatically as part of the upgrade process and will default to distributing work across replicas. To disable this behavior, set the [cluster setting]({% link v24.1/cluster-settings.md %}) `changefeed.random_replica_selection.enabled ` to `false`. If disabled, changefeed planning reverts to its previous behavior for distributing work. [#120077][#120077]
 - When [physical cluster replication]({% link v24.1/physical-cluster-replication-overview.md %}) is enabled, the output of the `SHOW VIRTUAL CLUSTER ... WITH REPLICATION STATUS` command now displays replication lag. [#120782][#120782]
 - When [physical cluster replication]({% link v24.1/physical-cluster-replication-overview.md %}) is enabled, the output of the `SHOW VIRTUAL CLUSTER WITH REPLICATION STATUS to 1` command has changed:
     - The output no longer displays `replication_job_id` or `service_mode` return fields.

src/current/_includes/v23.1/cdc/work-distribution-setting.md

@@ -0,0 +1 @@
+{% include_cached new-in.html version="v23.1.23" %} You can enable the `changefeed.random_replica_selection.enabled` cluster setting to change the way in which a changefeed distributes work across the cluster. With `changefeed.random_replica_selection.enabled` set to `true`, the job will evenly distribute changefeed work across the cluster by assigning it to any [replica]({% link {{ page.version.version }}/architecture/replication-layer.md %}) for a particular range. For `changefeed.random_replica_selection.enabled` to take effect on changefeed jobs, ensure you enable the cluster setting and then [pause]({% link {{ page.version.version }}/pause-job.md %}) and [resume]({% link {{ page.version.version }}/resume-job.md %}) existing changefeeds.

src/current/_includes/v23.2/cdc/work-distribution-setting.md

@@ -0,0 +1 @@
+{% include_cached new-in.html version="v23.2.7" %} You can enable the `changefeed.random_replica_selection.enabled` cluster setting to change the way in which a changefeed distributes work across the cluster. With `changefeed.random_replica_selection.enabled` set to `true`, the job will evenly distribute changefeed work across the cluster by assigning it to any [replica]({% link {{ page.version.version }}/architecture/replication-layer.md %}) for a particular range. For `changefeed.random_replica_selection.enabled` to take effect on changefeed jobs, ensure you enable the cluster setting and then [pause]({% link {{ page.version.version }}/pause-job.md %}) and [resume]({% link {{ page.version.version }}/resume-job.md %}) existing changefeeds.

src/current/v23.1/changefeeds-in-multi-region-deployments.md

@@ -53,6 +53,10 @@ Once the coordinating node is determined, nodes that match the locality requirem
 - If the [leaseholder]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-leaseholder) for the change data matches the filter, it will emit the changefeed messages.
 - If the leaseholder does not match the locality filter, a node will be selected matching the locality filter with a preference for nodes with localities that are more similar to the leaseholder.
 
+{{site.data.alerts.callout_info}}
+{% include {{ page.version.version }}/cdc/work-distribution-setting.md %}
+{{site.data.alerts.end}}
+
 When a node matching the locality filter takes part in the changefeed job, that node will read from the closest [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica). If the node is the leaseholder, or is itself a replica, it can read from itself. In the scenario where no replicas are available in the region of the assigned node, it may then read from a replica in a different region. As a result, you may want to consider [placing replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}), including potentially [non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) that will have less impact on read latency, in the locality or region that you plan on pinning for changefeed job execution.
 
 For an overview of how a changefeed job works, see the [How does an Enterprise changefeed work?]({% link {{ page.version.version }}/how-does-an-enterprise-changefeed-work.md %}) section.

src/current/v23.1/how-does-an-enterprise-changefeed-work.md

@@ -7,6 +7,10 @@ docs_area: stream_data
 
 When an {{ site.data.products.enterprise }} changefeed is started on a node, that node becomes the _coordinator_ for the changefeed job (**Node 2** in the diagram). The coordinator node acts as an administrator: keeping track of all other nodes during job execution and the changefeed work as it completes. The changefeed job will run across all nodes in the cluster to access changed data in the watched table. Typically, the [leaseholder]({% link {{ page.version.version }}/architecture/replication-layer.md %}#leases) for a particular range (or the range’s replica) determines which node emits the changefeed data.
 
+{{site.data.alerts.callout_info}}
+{% include {{ page.version.version }}/cdc/work-distribution-setting.md %}
+{{site.data.alerts.end}}
+
 Each node uses its aggregator processors to send back checkpoint progress to the coordinator, which gathers this information to update the high-water mark timestamp. The high-water mark acts as a checkpoint for the changefeed’s job progress, and guarantees that all changes before (or at) the timestamp have been emitted. In the unlikely event that the changefeed’s coordinating node were to fail during the job, that role will move to a different node and the changefeed will restart from the last checkpoint. If restarted, the changefeed may [re-emit messages]({% link {{ page.version.version }}/changefeed-messages.md %}#duplicate-messages) starting at the high-water mark time to the current time. Refer to [Ordering Guarantees]({% link {{ page.version.version }}/changefeed-messages.md %}#ordering-and-delivery-guarantees) for detail on CockroachDB's at-least-once-delivery-guarantee and how per-key message ordering is applied.
 
 <img src="{{ 'images/v23.1/changefeed-structure.png' | relative_url }}" alt="Changefeed process in a 3-node cluster" style="border:0px solid #eee;max-width:100%" />

src/current/v23.2/changefeeds-in-multi-region-deployments.md

@@ -53,6 +53,10 @@ Once the coordinating node is determined, nodes that match the locality requirem
 - If the [leaseholder]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-leaseholder) for the change data matches the filter, it will emit the changefeed messages.
 - If the leaseholder does not match the locality filter, a node will be selected matching the locality filter with a preference for nodes with localities that are more similar to the leaseholder.
 
+{{site.data.alerts.callout_info}}
+{% include {{ page.version.version }}/cdc/work-distribution-setting.md %}
+{{site.data.alerts.end}}
+
 When a node matching the locality filter takes part in the changefeed job, that node will read from the closest [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica). If the node is the leaseholder, or is itself a replica, it can read from itself. In the scenario where no replicas are available in the region of the assigned node, it may then read from a replica in a different region. As a result, you may want to consider [placing replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}), including potentially [non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) that will have less impact on read latency, in the locality or region that you plan on pinning for changefeed job execution.
 
 For an overview of how a changefeed job works, see the [How does an Enterprise changefeed work?]({% link {{ page.version.version }}/how-does-an-enterprise-changefeed-work.md %}) section.

src/current/v23.2/how-does-an-enterprise-changefeed-work.md

@@ -7,6 +7,10 @@ docs_area: stream_data
 
 When an {{ site.data.products.enterprise }} changefeed is started on a node, that node becomes the _coordinator_ for the changefeed job (**Node 2** in the diagram). The coordinator node acts as an administrator: keeping track of all other nodes during job execution and the changefeed work as it completes. The changefeed job will run across all nodes in the cluster to access changed data in the watched table. Typically, the [leaseholder]({% link {{ page.version.version }}/architecture/replication-layer.md %}#leases) for a particular range (or the range’s replica) determines which node emits the changefeed data.
 
+{{site.data.alerts.callout_info}}
+{% include {{ page.version.version }}/cdc/work-distribution-setting.md %}
+{{site.data.alerts.end}}
+
 Each node uses its aggregator processors to send back checkpoint progress to the coordinator, which gathers this information to update the high-water mark timestamp. The high-water mark acts as a checkpoint for the changefeed’s job progress, and guarantees that all changes before (or at) the timestamp have been emitted. In the unlikely event that the changefeed’s coordinating node were to fail during the job, that role will move to a different node and the changefeed will restart from the last checkpoint. If restarted, the changefeed may [re-emit messages]({% link {{ page.version.version }}/changefeed-messages.md %}#duplicate-messages) starting at the high-water mark time to the current time. Refer to [Ordering Guarantees]({% link {{ page.version.version }}/changefeed-messages.md %}#ordering-and-delivery-guarantees) for detail on CockroachDB's at-least-once-delivery-guarantee and how per-key message ordering is applied.
 
 <img src="{{ 'images/v23.2/changefeed-structure.png' | relative_url }}" alt="Changefeed process in a 3-node cluster" style="border:0px solid #eee;max-width:100%" />

src/current/v24.1/changefeeds-in-multi-region-deployments.md

@@ -46,12 +46,12 @@ When you start or [resume]({% link {{ page.version.version }}/resume-job.md %})
 
 Once the coordinating node is determined, nodes that match the locality requirements will take part in emitting changefeed messages to the sink. The following will happen in different cases:
 
-- If the [leaseholder]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-leaseholder) for the change data matches the filter, it will emit the changefeed messages.
-- If the leaseholder does not match the locality filter, a node will be selected matching the locality filter with a preference for nodes with localities that are more similar to the leaseholder.
+- If a [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica) for the change data matches the filter, it will emit the changefeed messages.
+- If a replica does not match the locality filter, a node will be selected matching the locality filter with a preference for nodes with localities that are more similar to a replica.
 
-When a node matching the locality filter takes part in the changefeed job, that node will read from the closest [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica). If the node is the leaseholder, or is itself a replica, it can read from itself. In the scenario where no replicas are available in the region of the assigned node, it may then read from a replica in a different region. As a result, you may want to consider [placing replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}), including potentially [non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) that will have less impact on read latency, in the locality or region that you plan on pinning for changefeed job execution.
+When a node matching the locality filter takes part in the changefeed job, that node will read from the closest [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica). If the node is a replica, it can read from itself. In the scenario where no replicas are available in the region of the assigned node, it may then read from a replica in a different region. As a result, you may want to consider [placing replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}), including potentially [non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) that will have less impact on read latency, in the locality or region that you plan on pinning for changefeed job execution.
 
-For an overview of how a changefeed job works, see the [How does an Enterprise changefeed work?]({% link {{ page.version.version }}/how-does-an-enterprise-changefeed-work.md %}) section.
+For an overview of how a changefeed job works, refer to the [How does an Enterprise changefeed work?]({% link {{ page.version.version }}/how-does-an-enterprise-changefeed-work.md %}) page.
 
 ## Run changefeeds on regional by row tables
 

src/current/v24.1/how-does-an-enterprise-changefeed-work.md

@@ -5,7 +5,7 @@ toc: true
 docs_area: stream_data
 ---
 
-When an {{ site.data.products.enterprise }} changefeed is started on a node, that node becomes the _coordinator_ for the changefeed job (**Node 2** in the diagram). The coordinator node acts as an administrator: keeping track of all other nodes during job execution and the changefeed work as it completes. The changefeed job will run across all nodes in the cluster to access changed data in the watched table. Typically, the [leaseholder]({% link {{ page.version.version }}/architecture/replication-layer.md %}#leases) for a particular range (or the range’s replica) determines which node emits the changefeed data.
+When an {{ site.data.products.enterprise }} changefeed is started on a node, that node becomes the _coordinator_ for the changefeed job (**Node 2** in the diagram). The coordinator node acts as an administrator: keeping track of all other nodes during job execution and the changefeed work as it completes. The changefeed job will run across nodes in the cluster to access changed data in the watched table. The job will evenly distribute changefeed work across the cluster by assigning it to any [replica]({% link {{ page.version.version }}/architecture/replication-layer.md %}) for a particular range, which determines the node that will emit the changefeed data. If a [locality filter]({% link {{ page.version.version }}/changefeeds-in-multi-region-deployments.md %}#run-a-changefeed-job-by-locality) is specified, work is distributed to a node from those that match the locality filter and has the most locality tiers in common with a node that has a replica.
 
 Each node uses its aggregator processors to send back checkpoint progress to the coordinator, which gathers this information to update the high-water mark timestamp. The high-water mark acts as a checkpoint for the changefeed’s job progress, and guarantees that all changes before (or at) the timestamp have been emitted. In the unlikely event that the changefeed’s coordinating node were to fail during the job, that role will move to a different node and the changefeed will restart from the last checkpoint. If restarted, the changefeed may [re-emit messages]({% link {{ page.version.version }}/changefeed-messages.md %}#duplicate-messages) starting at the high-water mark time to the current time. Refer to [Ordering Guarantees]({% link {{ page.version.version }}/changefeed-messages.md %}#ordering-and-delivery-guarantees) for detail on CockroachDB's at-least-once-delivery-guarantee and how per-key message ordering is applied.
 

src/current/v24.2/changefeeds-in-multi-region-deployments.md

@@ -46,12 +46,12 @@ When you start or [resume]({% link {{ page.version.version }}/resume-job.md %})
 
 Once the coordinating node is determined, nodes that match the locality requirements will take part in emitting changefeed messages to the sink. The following will happen in different cases:
 
-- If the [leaseholder]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-leaseholder) for the change data matches the filter, it will emit the changefeed messages.
-- If the leaseholder does not match the locality filter, a node will be selected matching the locality filter with a preference for nodes with localities that are more similar to the leaseholder.
+- If a [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica) for the change data matches the filter, it will emit the changefeed messages.
+- If a replica does not match the locality filter, a node will be selected matching the locality filter with a preference for nodes with localities that are more similar to a replica.
 
-When a node matching the locality filter takes part in the changefeed job, that node will read from the closest [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica). If the node is the leaseholder, or is itself a replica, it can read from itself. In the scenario where no replicas are available in the region of the assigned node, it may then read from a replica in a different region. As a result, you may want to consider [placing replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}), including potentially [non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) that will have less impact on read latency, in the locality or region that you plan on pinning for changefeed job execution.
+When a node matching the locality filter takes part in the changefeed job, that node will read from the closest [replica]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}#architecture-replica). If the node is a replica, it can read from itself. In the scenario where no replicas are available in the region of the assigned node, it may then read from a replica in a different region. As a result, you may want to consider [placing replicas]({% link {{ page.version.version }}/configure-replication-zones.md %}), including potentially [non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) that will have less impact on read latency, in the locality or region that you plan on pinning for changefeed job execution.
 
-For an overview of how a changefeed job works, see the [How does an Enterprise changefeed work?]({% link {{ page.version.version }}/how-does-an-enterprise-changefeed-work.md %}) section.
+For an overview of how a changefeed job works, refer to the [How does an Enterprise changefeed work?]({% link {{ page.version.version }}/how-does-an-enterprise-changefeed-work.md %}) page.
 
 ## Run changefeeds on regional by row tables