Document shard level migrations feature

content/en/docs/15.0/reference/programs/vtctldclient/_index.md

@@ -20,6 +20,7 @@ Executes a cluster management command on the remote vtctld server.
 * [vtctldclient AddCellsAlias](./vtctldclient_addcellsalias/)	 - Defines a group of cells that can be referenced by a single name (the alias).
 * [vtctldclient ApplyRoutingRules](./vtctldclient_applyroutingrules/)	 - Applies the VSchema routing rules.
 * [vtctldclient ApplySchema](./vtctldclient_applyschema/)	 - Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication.
+* [vtctldclient ApplyShardRoutingRules](./vtctldclient_applyshardroutingrules/)	 - Applies the provided shard routing rules.
 * [vtctldclient ApplyVSchema](./vtctldclient_applyvschema/)	 - Applies the VTGate routing schema to the provided keyspace. Shows the result after application.
 * [vtctldclient Backup](./vtctldclient_backup/)	 - Uses the BackupStorage service on the given tablet to create and store a new backup.
 * [vtctldclient BackupShard](./vtctldclient_backupshard/)	 - Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard and uses the BackupStorage service on that tablet to create and store a new backup.
@@ -47,6 +48,7 @@ Executes a cluster management command on the remote vtctld server.
 * [vtctldclient GetRoutingRules](./vtctldclient_getroutingrules/)	 - Displays the VSchema routing rules.
 * [vtctldclient GetSchema](./vtctldclient_getschema/)	 - Displays the full schema for a tablet, optionally restricted to the specified tables/views.
 * [vtctldclient GetShard](./vtctldclient_getshard/)	 - Returns information about a shard in the topology.
+* [vtctldclient GetShardRoutingRules](./vtctldclient_getshardroutingrules/)	 - Returns the current shard routing rules as a JSON document.
 * [vtctldclient GetSrvKeyspaceNames](./vtctldclient_getsrvkeyspacenames/)	 - Outputs a JSON mapping of cell=>keyspace names served in that cell. Omit to query all cells.
 * [vtctldclient GetSrvKeyspaces](./vtctldclient_getsrvkeyspaces/)	 - Returns the SrvKeyspaces for the given keyspace in one or more cells.
 * [vtctldclient GetSrvVSchema](./vtctldclient_getsrvvschema/)	 - Returns the SrvVSchema for the given cell.

content/en/docs/15.0/reference/programs/vtctldclient/vtctldclient_ApplyShardRoutingRules.md

@@ -0,0 +1,33 @@
+---
+title: ApplyShardRoutingRules
+series: vtctldclient
+---
+## vtctldclient ApplyShardRoutingRules
+
+Applies the provided shard routing rules. See the documentation on [shard level migrations](../../../vreplication/shardlevelmigrations/) for more information.
+
+```
+vtctldclient ApplyShardRoutingRules {--rules RULES | --rules-file RULES_FILE} [--skip-rebuild] [--dry-run]
+```
+
+### Options
+
+```
+  -h, --help               help for ApplyShardRoutingRules
+      --rules RULES        JSON string of the shard routing rules to apply
+      --rules-file         Path to a file containing the shard routing rules to apply as a JSON document
+      --skip-rebuild       Don't rebuild the SrvVSchema after applying the rules (if you want to delay enforcement of the new rules)
+      --dry-run            Don't actually apply the rules, just print informtion about the work that would be done
+```
+
+### Options inherited from parent commands
+
+```
+      --action_timeout duration   timeout for the total command (default 1h0m0s)
+      --server string             server to use for connection (required)
+```
+
+### SEE ALSO
+
+* [vtctldclient](../)	 - Executes a cluster management command on the remote vtctld server.
+

content/en/docs/15.0/reference/programs/vtctldclient/vtctldclient_GetShardRoutingRules.md

@@ -0,0 +1,29 @@
+---
+title: GetShardRoutingRules
+series: vtctldclient
+---
+## vtctldclient GetShardRoutingRules
+
+Returns the currently active shard routing rules as a JSON document. See the documentation on [shard level migrations](../../../vreplication/shardlevelmigrations/) for more information.
+
+```
+vtctldclient GetShardRoutingRules
+```
+
+### Options
+
+```
+  -h, --help               help for GetShardRoutingRules
+```
+
+### Options inherited from parent commands
+
+```
+      --action_timeout duration   timeout for the total command (default 1h0m0s)
+      --server string             server to use for connection (required)
+```
+
+### SEE ALSO
+
+* [vtctldclient](../)	 - Executes a cluster management command on the remote vtctld server.
+

content/en/docs/15.0/reference/programs/vtgate.md

@@ -54,6 +54,7 @@ The following global options apply to `vtgate`:
 | --emit_stats | boolean | true iff we should emit stats to push-based monitoring/stats backends |
 | --enable_buffer | boolean | Enable buffering (stalling) of primary traffic during failovers. |
 | --enable_buffer_dry_run | boolean | Detect and log failover events, but do not actually buffer requests. |
+| --enable_partial_keyspace_migration | boolean | (Experimental) Follow shard routing rules: enable only while migrating a keyspace shard by shard. See the documentation on [shard level migrations](../../vreplication/shardlevelmigrations/) for more information. (default false) |
 | --enable_system_settings | boolean | Enables the system settings to be changed per session at the database connection level. Override with @@enable_system_settings session variable. |
 | --enable_set_var | boolean | This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections. |
 | --gate_query_cache_size | int | gate server query cache size, maximum number of queries to be cached. vtgate analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 10000) |

content/en/docs/15.0/reference/vreplication/shardlevelmigrations.md

@@ -0,0 +1,88 @@
+---
+title: Shard Level Migrations
+description: Migrate large keyspaces without downtime
+weight: 120
+aliases: ['/docs/reference/vreplication/v2/shardlevelmigrations/']
+---
+
+{{< warning >}}
+This feature is an **experimental** variant of the `MoveTables` command that 
+allows you to migrate individual shards from one keyspace to another. Please be 
+sure to understand the limitations and requirements below.
+{{< /warning >}}
+
+The full set of options for the `MoveTables` command [can be found here](../movetables/). 
+The options and other aspects specific to shard level migrations will be covered here.
+
+## Use Case
+
+The [`Mount`](../mount/) and [`Migrate`](../migrate/) commands are the default 
+method provided for moving keyspaces from one Vitess cluster to another. This 
+method, however, only provides a one-time one-way cutover without the ability 
+to revert in the way that [`MoveTables`](../movetables/) does. 
+
+This feature introduces the concept of partial keyspaces where some shards are
+served from a different keyspace during migration. This is useful for a specific
+but critical use-case where a large production Vitess setup (100s of shards) is
+being migrated to a new data center or provider. Migrating the entire cluster in
+one go using MoveTables could cause an unacceptable downtime due to the large
+number of primaries that need to be synced when writes are switched.
+
+Supporting shard level migrations allows you to move very large keyspaces from one Vitess cluster 
+to another in an incremental way, cutting over traffic and reverting as needed 
+on a per-shard basis. When using this method, there is also a 
+new [`vtgate`](../../programs/vtgate/) `--enable_partial_keyspace_migration` 
+flag that enables support for shard level query routing so that individual 
+shards can be routed to one side of the migration or the other during the 
+migration period — *including when shard targeting is used*.
+
+## Command
+
+```
+MoveTables --source_shards=<source_shards> <options> <action> <workflow identifier>
+```
+
+## Parameters
+
+#### --source_shards
+**mandatory** (for shard level migrations)
+<div class="cmd">
+
+A list of one or more shards that you want to migrate from the source keyspace 
+to the target keyspace.
+
+</div>
+
+## Limitations and Requirements
+
+  - The source and target keyspaces must have the exact same shard definitions
+  - Query routing is all or nothing per shard, so you must *move all tables in the workflow 
+that you wish to migrate* and you would use [`SwitchTraffic --tablet_types=RDONLY,REPLICA,PRIMARY`](../switchtraffic/) 
+to switch *read and write traffic* all at once for the shard(s)
+  - When the entire migration is complete, you cannot use the standard 
+[`Complete`](../complete/) workflow action and the final cleanup step requires manual work:
+    - The _reverse workflows should be [`Cancel`](../cancel/)ed. This will clean up 
+    the both the global routing rules and the shard routing rules associated with the migration
+      - Note: [`Workflow delete`](../workflow/) does not clean up the shard routing rules
+    - You would need to perform any and all source side cleanup manually
+
+## Related Vitess Flags
+
+In order to support the shard level query routing during the migration, 
+the `--enable_partial_keyspace_migration` flag must be set for all of the 
+[`vtgate`](../../programs/vtgate/) instances in the target Vitess cluster.
+
+{{< warning >}}
+This routing support has a performance impact for all traffic and thus you 
+should only use this flag during the migration period and remove it once the 
+migration is complete.
+{{< /warning >}}
+
+## Related Commands
+
+You can view the current shard level routing rules in place using 
+the [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) 
+[`vtctldclient`](../../programs/vtctldclient/) command and you can save updated
+routing rules using the 
+[`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyshardroutingrules/) 
+command.

content/en/docs/16.0/reference/programs/vtctldclient/_index.md

@@ -20,6 +20,7 @@ Executes a cluster management command on the remote vtctld server.
 * [vtctldclient AddCellsAlias](./vtctldclient_addcellsalias/)	 - Defines a group of cells that can be referenced by a single name (the alias).
 * [vtctldclient ApplyRoutingRules](./vtctldclient_applyroutingrules/)	 - Applies the VSchema routing rules.
 * [vtctldclient ApplySchema](./vtctldclient_applyschema/)	 - Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication.
+* [vtctldclient ApplyShardRoutingRules](./vtctldclient_applyshardroutingrules/)	 - Applies the provided shard routing rules.
 * [vtctldclient ApplyVSchema](./vtctldclient_applyvschema/)	 - Applies the VTGate routing schema to the provided keyspace. Shows the result after application.
 * [vtctldclient Backup](./vtctldclient_backup/)	 - Uses the BackupStorage service on the given tablet to create and store a new backup.
 * [vtctldclient BackupShard](./vtctldclient_backupshard/)	 - Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard and uses the BackupStorage service on that tablet to create and store a new backup.
@@ -47,6 +48,7 @@ Executes a cluster management command on the remote vtctld server.
 * [vtctldclient GetRoutingRules](./vtctldclient_getroutingrules/)	 - Displays the VSchema routing rules.
 * [vtctldclient GetSchema](./vtctldclient_getschema/)	 - Displays the full schema for a tablet, optionally restricted to the specified tables/views.
 * [vtctldclient GetShard](./vtctldclient_getshard/)	 - Returns information about a shard in the topology.
+* [vtctldclient GetShardRoutingRules](./vtctldclient_getshardroutingrules/)	 - Returns the current shard routing rules as a JSON document.
 * [vtctldclient GetSrvKeyspaceNames](./vtctldclient_getsrvkeyspacenames/)	 - Outputs a JSON mapping of cell=>keyspace names served in that cell. Omit to query all cells.
 * [vtctldclient GetSrvKeyspaces](./vtctldclient_getsrvkeyspaces/)	 - Returns the SrvKeyspaces for the given keyspace in one or more cells.
 * [vtctldclient GetSrvVSchema](./vtctldclient_getsrvvschema/)	 - Returns the SrvVSchema for the given cell.

content/en/docs/16.0/reference/programs/vtctldclient/vtctldclient_ApplyShardRoutingRules.md

@@ -0,0 +1,33 @@
+---
+title: ApplyShardRoutingRules
+series: vtctldclient
+---
+## vtctldclient ApplyShardRoutingRules
+
+Applies the provided shard routing rules. See the documentation on [shard level migrations](../../../vreplication/shardlevelmigrations/) for more information.
+
+```
+vtctldclient ApplyShardRoutingRules {--rules RULES | --rules-file RULES_FILE} [--skip-rebuild] [--dry-run]
+```
+
+### Options
+
+```
+  -h, --help               help for ApplyShardRoutingRules
+      --rules RULES        JSON string of the shard routing rules to apply
+      --rules-file         Path to a file containing the shard routing rules to apply as a JSON document
+      --skip-rebuild       Don't rebuild the SrvVSchema after applying the rules (if you want to delay enforcement of the new rules)
+      --dry-run            Don't actually apply the rules, just print informtion about the work that would be done
+```
+
+### Options inherited from parent commands
+
+```
+      --action_timeout duration   timeout for the total command (default 1h0m0s)
+      --server string             server to use for connection (required)
+```
+
+### SEE ALSO
+
+* [vtctldclient](../)	 - Executes a cluster management command on the remote vtctld server.
+

content/en/docs/16.0/reference/programs/vtctldclient/vtctldclient_GetShardRoutingRules.md

@@ -0,0 +1,29 @@
+---
+title: GetShardRoutingRules
+series: vtctldclient
+---
+## vtctldclient GetShardRoutingRules
+
+Returns the currently active shard routing rules as a JSON document. See the documentation on [shard level migrations](../../../vreplication/shardlevelmigrations/) for more information.
+
+```
+vtctldclient GetShardRoutingRules
+```
+
+### Options
+
+```
+  -h, --help               help for GetShardRoutingRules
+```
+
+### Options inherited from parent commands
+
+```
+      --action_timeout duration   timeout for the total command (default 1h0m0s)
+      --server string             server to use for connection (required)
+```
+
+### SEE ALSO
+
+* [vtctldclient](../)	 - Executes a cluster management command on the remote vtctld server.
+

content/en/docs/16.0/reference/programs/vtgate.md

@@ -54,6 +54,7 @@ The following global options apply to `vtgate`:
 | --emit_stats | boolean | true iff we should emit stats to push-based monitoring/stats backends |
 | --enable_buffer | boolean | Enable buffering (stalling) of primary traffic during failovers. |
 | --enable_buffer_dry_run | boolean | Detect and log failover events, but do not actually buffer requests. |
+| --enable_partial_keyspace_migration | boolean | (Experimental) Follow shard routing rules: enable only while migrating a keyspace shard by shard. See the documentation on [shard level migrations](../../vreplication/shardlevelmigrations/) for more information. (default false) |
 | --enable_system_settings | boolean | Enables the system settings to be changed per session at the database connection level. Override with @@enable_system_settings session variable. |
 | --enable_set_var | boolean | This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections. |
 | --gate_query_cache_size | int | gate server query cache size, maximum number of queries to be cached. vtgate analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 10000) |

content/en/docs/16.0/reference/vreplication/shardlevelmigrations.md

@@ -0,0 +1,88 @@
+---
+title: Shard Level Migrations
+description: Migrate large keyspaces without downtime
+weight: 120
+aliases: ['/docs/reference/vreplication/v2/shardlevelmigrations/']
+---
+
+{{< warning >}}
+This feature is an **experimental** variant of the `MoveTables` command that 
+allows you to migrate individual shards from one keyspace to another. Please be 
+sure to understand the limitations and requirements below.
+{{< /warning >}}
+
+The full set of options for the `MoveTables` command [can be found here](../movetables/). 
+The options and other aspects specific to shard level migrations will be covered here.
+
+## Use Case
+
+The [`Mount`](../mount/) and [`Migrate`](../migrate/) commands are the default 
+method provided for moving keyspaces from one Vitess cluster to another. This 
+method, however, only provides a one-time one-way cutover without the ability 
+to revert in the way that [`MoveTables`](../movetables/) does. 
+
+This feature introduces the concept of partial keyspaces where some shards are
+served from a different keyspace during migration. This is useful for a specific
+but critical use-case where a large production Vitess setup (100s of shards) is
+being migrated to a new data center or provider. Migrating the entire cluster in
+one go using MoveTables could cause an unacceptable downtime due to the large
+number of primaries that need to be synced when writes are switched.
+
+Supporting shard level migrations allows you to move very large keyspaces from one Vitess cluster 
+to another in an incremental way, cutting over traffic and reverting as needed 
+on a per-shard basis. When using this method, there is also a 
+new [`vtgate`](../../programs/vtgate/) `--enable_partial_keyspace_migration` 
+flag that enables support for shard level query routing so that individual 
+shards can be routed to one side of the migration or the other during the 
+migration period — *including when shard targeting is used*.
+
+## Command
+
+```
+MoveTables --source_shards=<source_shards> <options> <action> <workflow identifier>
+```
+
+## Parameters
+
+#### --source_shards
+**mandatory** (for shard level migrations)
+<div class="cmd">
+
+A list of one or more shards that you want to migrate from the source keyspace 
+to the target keyspace.
+
+</div>
+
+## Limitations and Requirements
+
+  - The source and target keyspaces must have the exact same shard definitions
+  - Query routing is all or nothing per shard, so you must *move all tables in the workflow 
+that you wish to migrate* and you would use [`SwitchTraffic --tablet_types=RDONLY,REPLICA,PRIMARY`](../switchtraffic/) 
+to switch *read and write traffic* all at once for the shard(s)
+  - When the entire migration is complete, you cannot use the standard 
+[`Complete`](../complete/) workflow action and the final cleanup step requires manual work:
+    - The _reverse workflows should be [`Cancel`](../cancel/)ed. This will clean up 
+    the both the global routing rules and the shard routing rules associated with the migration
+      - Note: [`Workflow delete`](../workflow/) does not clean up the shard routing rules
+    - You would need to perform any and all source side cleanup manually
+
+## Related Vitess Flags
+
+In order to support the shard level query routing during the migration, 
+the `--enable_partial_keyspace_migration` flag must be set for all of the 
+[`vtgate`](../../programs/vtgate/) instances in the target Vitess cluster.
+
+{{< warning >}}
+This routing support has a performance impact for all traffic and thus you 
+should only use this flag during the migration period and remove it once the 
+migration is complete.
+{{< /warning >}}
+
+## Related Commands
+
+You can view the current shard level routing rules in place using 
+the [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) 
+[`vtctldclient`](../../programs/vtctldclient/) command and you can save updated
+routing rules using the 
+[`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyshardroutingrules/) 
+command.