iallocator: Specify result of “multi-relocate” request

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

doc/design-multi-reloc.rst

@@ -56,19 +56,53 @@ The mode of operation will be one of:
 
 In all modes, the groups' ``alloc_policy`` attribute will be honored.
 
+.. _multi-reloc-result:
+
 Result
 ------
 
 In all storage models, an inter-group move can be modeled as a sequence
-of **replace secondary** and **failover** operations (when shared
-storage is used, they will all be failover operations within the
-corresponding mobility domain). This will be represented as a list of
-``(instance, [operations])`` pairs.
-
-For replace secondary operations, a new secondary node must be
-specified. For failover operations, a node *may* be specified when
-necessary, e.g. when shared storage is in use and there's no designated
-secondary for the instance.
+of **replace secondary**, **migration** and **failover** operations
+(when shared storage is used, they will all be failover or migration
+operations within the corresponding mobility domain).
+
+The result is expected to be a list of jobsets. Each jobset contains
+lists of serialized opcodes. Example::
+
+  [
+    [
+      { "OP_ID": "OP_INSTANCE_MIGRATE",
+        "instance_name": "inst1.example.com",
+      },
+      { "OP_ID": "OP_INSTANCE_MIGRATE",
+        "instance_name": "inst2.example.com",
+      },
+    ],
+    [
+      { "OP_ID": "OP_INSTANCE_REPLACE_DISKS",
+        "instance_name": "inst2.example.com",
+        "mode": "replace_new_secondary",
+        "remote_node": "node4.example.com"
+      },
+    ],
+    [
+      { "OP_ID": "OP_INSTANCE_FAILOVER",
+        "instance_name": "inst8.example.com",
+      },
+    ]
+  ]
+
+Accepted opcodes:
+
+- ``OP_INSTANCE_FAILOVER``
+- ``OP_INSTANCE_MIGRATE``
+- ``OP_INSTANCE_REPLACE_DISKS``
+
+Starting with the first set, Ganeti will submit all jobs of a set at the
+same time, enabling execution in parallel. Upon completion of all jobs
+in a set, the process is repeated for the next one. Ganeti is at liberty
+to abort the execution of the relocation after any jobset. In such a
+case the user is notified and can restart the relocation.
 
 .. vim: set textwidth=72 :
 .. Local Variables:

doc/iallocator.rst

@@ -280,7 +280,7 @@ arguments:
     a string indicating the relocation mode; there are three possible
     values for this string: *keep_group*, *change_group*, and
     *any_group*, the semantics or which are explained in :ref:`the
-    design doc <multi-reloc-detailed-design>`
+    design document <multi-reloc-detailed-design>`
 
   target_groups
     this argument is only accepted when ``reloc_mode``, as explained
@@ -316,9 +316,9 @@ result
   entry in the input message, otherwise Ganeti will consider the result
   as failed
 
-  for multi-relocate mode, this is a list of 2-tuples in which the first
-  element of the tuple will be an instance name, and the second element
-  a list of operations to perform in order to relocate the instance
+  for multi-relocate mode, this is a list of lists of serialized
+  opcodes. See the :ref:`design document <multi-reloc-result>` for a
+  detailed dscription.
 
   for multi-evacuation mode, this is a list of lists; each element of
   the list is a list of instance name and the new secondary node