Update iallocator.rst for multi-reloc mode

Signed-off-by: Adeodato Simo <dato@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

doc/design-multi-reloc.rst

@@ -28,6 +28,8 @@ that will be able to compute inter-group instance moves, taking into
 account mobility domains as appropriate. The interface proposed below
 should be enough to cover the use cases mentioned above.
 
+.. _multi-reloc-detailed-design:
+
 Detailed design
 ===============
 

doc/iallocator.rst

@@ -189,13 +189,15 @@ follows.
 In all cases, it includes:
 
   type
-    the request type; this can be either ``allocate``, ``relocate`` or
-    ``multi-evacuate``; the ``allocate`` request is used when a new
-    instance needs to be placed on the cluster, while the ``relocate``
-    request is used when an existing instance needs to be moved within
-    the cluster; the ``multi-evacuate`` protocol requests that the
-    script computes the optimal relocate solution for all secondary
-    instances of the given nodes
+    the request type; this can be either ``allocate``, ``relocate``,
+    ``multi-relocate`` or ``multi-evacuate``. The ``allocate`` request
+    is used when a new instance needs to be placed on the cluster. The
+    ``relocate`` request is used when an existing instance needs to be
+    moved within its node group, while the ``multi-relocate`` one is
+    able to relocate multiple instances across multiple node groups. The
+    ``multi-evacuate`` protocol requests that the script computes the
+    optimal relocate solution for all secondary instances of the given
+    nodes.
 
 For both allocate and relocate mode, the following extra keys are needed
 in the ``request`` dictionary:
@@ -268,8 +270,26 @@ Relocation:
      Ganeti 2.0, this list will always contain a single node, the
      current secondary of the instance)
 
-In the case of multi-evacuate, there's one single request argument (in
-addition to ``type``):
+As for ``multi-relocate``, it needs the three following request
+arguments:
+
+  instances
+    a list of instance names to relocate
+
+  reloc_mode
+    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>`
+
+  target_groups
+    this argument is only accepted when ``reloc_mode``, as explained
+    above, is *change_group*; if present, it must either be the empty
+    list, or contain a list of group UUIDs that should be considered for
+    relocating instances to
+
+Finally, in the case of multi-evacuate, there's one single request
+argument (in addition to ``type``):
 
   evac_nodes
     the names of the nodes to be evacuated
@@ -296,6 +316,10 @@ 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-evacuation mode, this is a list of lists; each element of
   the list is a list of instance name and the new secondary node