Merge pull request #191746 from vladelekic/dev/vladeleki/moveCostDocumentation

Report Move Cost on behalf of other partition

Author: denrea

articles/service-fabric/service-fabric-cluster-resource-manager-movement-cost.md

@@ -54,14 +54,60 @@ await fabricClient.ServiceManager.UpdateServiceAsync(new Uri("fabric:/AppName/Se
 
 ## Dynamically specifying move cost on a per-replica basis
 
-The preceding snippets are all for specifying MoveCost for a whole service at once from outside the service itself. However, move cost is most useful is when the move cost of a specific service object changes over its lifespan. Since the services themselves probably have the best idea of how costly they are to move a given time, there's an API for services to report their own individual move cost during runtime. 
+The preceding snippets are all for specifying MoveCost for a whole service at once from outside the service itself. However, move cost is most useful when the move cost of a specific service object changes over its lifespan. Since the services themselves probably have the best idea of how costly they are to move a given time, there's an API for services to report their own individual move cost during runtime. 
 
 C#:
 
 ```csharp
 this.Partition.ReportMoveCost(MoveCost.Medium);
 ```
 
+## Reporting move cost for a partition
+
+The previous section describes how service replicas or instances report MoveCost themselves. We provided Service Fabric API for reporting MoveCost values on behalf of other partitions. Sometimes service replica or instance can't determine the best MoveCost value by itself, and must rely on other services logic. Reporting MoveCost on behalf of other partitions, alongside [reporting load on behalf of other partitions](service-fabric-cluster-resource-manager-metrics.md#reporting-load-for-a-partition), allows you to completely manage partitions from outside. These APIs eliminate needs for [the Sidecar pattern](https://docs.microsoft.com/azure/architecture/patterns/sidecar), from the perspective of the Cluster Resource Manager.
+
+You can report MoveCost updates for a different partition with the same API call. You need to specify PartitionMoveCostDescription object for each partition that you want to update with new values of MoveCost. The API allows multiple ways to update MoveCost:
+
+  - A stateful service partition can update its primary replica MoveCost.
+  - Both stateless and stateful services can update the MoveCost of all its secondary replicas or instances.
+  - Both stateless and stateful services can update the MoveCost of a specific replica or instance on a node.
+
+Each MoveCost update for partition should contain at least one valid value that will be changed. For example, you could skip primary replica update with assigning _null_ to primary replica entry, other entries will be used during MoveCost update and we will skip MoveCost update for primary replica. Since updating of MoveCost for multiple partitions with single API call is possible, API provides a list of return codes for corresponding partition. If we successfully accept and process a request for MoveCost update, return code will be Success. Otherwise, API provides error code: 
+
+  - PartitionNotFound - Specified partition ID doesn't exist.
+  - ReconfigurationPending - Partition is currently reconfiguring.
+  - InvalidForStatelessServices - An attempt was made to change the MoveCost of a primary replica for a partition belonging to a stateless service.
+  - ReplicaDoesNotExist - Secondary replica or instance does not exist on a specified node.
+  - InvalidOperation - Updating MoveCost for a partition that belongs to the System application.
+
+C#:
+
+```csharp
+Guid partitionId = Guid.Parse("53df3d7f-5471-403b-b736-bde6ad584f42");
+string nodeName0 = "NodeName0";
+
+OperationResult<UpdatePartitionMoveCostResultList> updatePartitionMoveCostResults =
+    await this.FabricClient.UpdatePartitionMoveCostAsync(
+        new UpdatePartitionMoveCostQueryDescription
+        {
+            new List<PartitionMoveCostDescription>()
+            {
+                new PartitionMoveCostDescription(
+                    partitionId,
+                    MoveCost.VeryHigh,
+                    MoveCost.Zero,
+                    new List<ReplicaMoveCostDescription>()
+                    {
+                        new ReplicaMoveCostDescription(nodeName0, MoveCost.Medium)
+                    })
+            }
+        },
+        this.Timeout,
+        cancellationToken);
+```
+
+With this example, you will perform an update of the last reported move cost for a partition _53df3d7f-5471-403b-b736-bde6ad584f42_. Primary replica move cost will be _VeryHigh_. All secondary replicas move cost will be _Zero_, except move cost for a specific secondary replica located at the node _NodeName0_. Move cost for a specific replica will be _Medium_. If you want to skip updating move cost for primary replica or all secondary replicas, you could leave corresponding entry as _null_.
+
 ## Impact of move cost
 MoveCost has five levels: Zero, Low, Medium, High and VeryHigh. The following rules apply: