PCSM-203 Implement copy of chunk distribution from source

docs/limitations.md

@@ -28,13 +28,15 @@
 
 The following limitations apply specifically to sharded cluster replication:
 
-* {{pcsm.short}} replicates the data and doesn't replicate metadata. This means that the following information is not preserved from the source cluster:
+- {{pcsm.short}} replicates the data and doesn't continuously replicate metadata. For ranged shard keys, the initial chunk boundaries are copied and ownership is initialized on the target during the initial sync, but subsequent sharding metadata changes are not replicated. The following information is therefore not preserved from the source cluster:
 
-   * The primary shard name for a collection. The target cluster may have a different primary shard name.
-   * The chunk distribution information. The target cluster manages chunk distribution according to its own sharding configuration. See [Sharding support](sharding.md#limitations) for more information.
-   * The configuration of [zones for sharded data :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/zone-sharding/).
+    * The primary shard name for a collection. The target cluster may have a different primary shard name.
 
-* During data replication, the following commands are not supported: `movePrimary`, `reshardCollecton`, `unshardCollection`, `refineCollectionShardKey`. Running them results in failed replication and you must start it anew, from the initial data sync stage.
+    * Ongoing chunk distribution information. The target cluster manages chunk distribution according to its own sharding configuration. See [Chunk distribution](sharding.md#chunk-distribution) for more information.
+
+    * The configuration of [zones for sharded data :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/zone-sharding/).
+
+    * During data replication, the following commands are not supported: `movePrimary`, `reshardCollecton`, `unshardCollection`, `refineCollectionShardKey`. Running them results in failed replication and you must start it anew, from the initial data sync stage.
 
 ## Data types
 

docs/sharding.md

@@ -12,7 +12,7 @@
 
 Since {{pcsm.short}} connects through `mongos`, the cluster topology doesn't matter. This means the source and target clusters can have different numbers of shards.
 
-Also, {{pcsm.short}} replicates data and not metadata. This means chunk distribution as well as the primary shard name for a collection may differ on source and target clusters.
+{{pcsm.short}} does not continuously replicate sharding metadata from the source to the target. For collections with a ranged shard key, it copies the initial chunk boundaries to the target before the clone starts. Any sharding metadata changes made after that are not replicated. The primary shard name for a collection may also differ between the source and target clusters. See [Chunk distribution](#chunk-distribution).
 
 ## Prerequisites
 
@@ -36,17 +36,76 @@
 
 ### Initial sync preparation
 
-Before starting the initial sync, {{pcsm.short}} checks which collections are sharded on the source cluster and creates corresponding sharded collections on the destination cluster. The only sharding configuration preserved from the source cluster is the sharding key; all other sharding details are handled internally by the destination cluster.
+Before starting the initial sync, {{pcsm.short}} checks which collections are sharded on the source cluster and creates corresponding sharded collections on the destination cluster. The sharding key is preserved from the source cluster. For ranged shard keys, {{pcsm.short}} also copies the initial chunk boundaries and ownership to the target; it does not replicate sharding metadata afterwards.
+
+For a ranged shard key, {{pcsm.short}} then pre-splits the collection using the source chunk boundaries, immediately after it shards the collection on the target and before it copies any documents. Collections with a hashed shard key keep the layout that `shardCollection` creates. See [Chunk distribution](#chunk-distribution).
 
 ### Balancer operation
 
 {{pcsm.full_name}} connects to source and target clusters via a `mongos` instance. Therefore, you do not need to disable the balancer on either the source or target cluster before starting replication. The target cluster's balancer continues to operate normally and manages chunk distribution according to its own sharding configuration and balancer settings.
 
-### Chunk distribution
+For ranged shard keys, the target also starts from the source chunk boundaries, which leaves the target balancer less data to move once the clone begins. Chunk migrations on either cluster are not replicated to the other, so both clusters keep managing their own layout throughout. See [Manage sharded cluster balancer :octicons-link-external-16:](https://www.mongodb.com/docs/manual/tutorial/manage-sharded-cluster-balancer/){:target="_blank"} in the MongoDB documentation.
+
+## Chunk distribution
+
+!!! admonition "Version added: 0.10.0"
+
+When MongoDB shards an empty collection on a ranged shard key, it creates a single chunk covering the entire range of shard key values. See [Data partitioning with chunks :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/sharding-data-partitioning/){:target="_blank"} in the MongoDB documentation. A clone into that collection would therefore write to a single shard, and the target balancer would move the data afterwards.
+
+{{pcsm.short}} therefore recreates the source chunk boundaries on the target before copying any documents. Clone writes follow the source layout instead of concentrating on one shard, which reduces how much the target balancer has to move afterwards.
+
+This runs automatically for every collection with a ranged shard key, immediately after {{pcsm.short}} shards it on the target. There is no flag and nothing to configure. Collections with a hashed shard key are not pre-split.
+
+| **Source collection** | **Target shards** | **Result on the target** |
+|-----------------------|-------------------|--------------------------|
+| Hashed shard key | Any number | The layout that `shardCollection` creates, unchanged. |
+| Ranged shard key | Same number as the source | The same chunk boundaries and the same ownership pattern as the source. |
+| Ranged shard key | Different number from the source | The same chunk boundaries, with chunks placed to even out the estimated data volume per shard.|
+
+!!! note
+    {{pcsm.short}} reads the source boundaries once, before the clone, and does not replicate sharding metadata afterwards. Later migrations, splits, merges, and resharding on the source have no effect on the target, so the two layouts drift apart as the balancers work. That is expected and does not indicate a replication problem.
+
+### Hashed shard keys
+
+{{pcsm.short}} does not pre-split hashed collections, and does not need to. MongoDB already spreads the initial chunks evenly across the shards for a hashed shard key, so {{pcsm.short}} keeps that layout. See [Hashed sharding :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/hashed-sharding/){:target="_blank"} in the MongoDB documentation.
+
+### Ranged shard keys
 
-{{pcsm.short}} does not preserve chunk distribution information from the source cluster. The target cluster manages chunk distribution internally through its balancer. This means that after replication, chunks may be distributed differently on the target cluster compared to the source cluster, which is expected behavior.
+With the same number of shards on both sides, the target gets the source boundaries and the same ownership pattern. Shards are paired in sorted order, so a range does not necessarily land on the target shard whose name resembles its source shard.
+
+With different shard counts, the boundaries still come from the source, but the largest chunks are placed first, each on whichever target shard holds the least data at that point. Every shard ends up owning chunks and holding roughly the same volume. The estimate carries across collections, so the large chunks of several collections do not all collect on one shard.
+
+??? example "How the two cases look"
+
+    ```{.text .no-copy}
+    Same number of shards
+    ---------------------
+    Source: [MinKey, 100) -> src-a    Target: [MinKey, 100) -> tgt-a
+            [100, MaxKey) -> src-b            [100, MaxKey) -> tgt-b
+
+    Different number of shards
+    --------------------------
+    Target shards: tgt-a, tgt-b
+    Source chunk sizes: 100 MB, 60 MB, 40 MB
+
+    100 MB -> tgt-a        Estimated result:
+     60 MB -> tgt-b        tgt-a: 100 MB
+     40 MB -> tgt-b        tgt-b: 100 MB
+    ```
+
+### If the pre-split fails
+
+A failed pre-split fails the clone for that instance, and there is no fallback to loading into an unsplit collection. Check the log for the reported failure, resolve it on the target cluster, then restart replication with `pcsm resume --from-failure`. See [Resume the replication](install/usage.md#resume-the-replication), [Logging in {{pcsm.full_name}}](logging.md), and the [Troubleshooting guide](troubleshooting.md).
+
+### Check the layout on the target
+
+Connect to the target `mongos` and look at how a replicated collection is spread:
+
+```javascript
+db.getSiblingDB('<database>').getCollection('<collection>').getShardDistribution()
+```
 
-Since the target cluster already has information about which collections are sharded, it handles sharding internally. {{pcsm.short}} does not interfere with the target cluster's sharding configuration or chunk distribution.
+Look for data on every shard rather than an exact match with the source, since counts differ even immediately after the clone and keep changing as the balancer works. For chunk counts per shard across the cluster, use [sh.status() :octicons-link-external-16:](https://www.mongodb.com/docs/manual/reference/method/sh.status/){:target="_blank"}.
 
 ## Usage