X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/9626f028aac9075403417d62cc380c57cfaa25ad..9f604ab8127becefe3161887286c72b984278f56:/doc/iallocator.rst

diff --git a/doc/iallocator.rst b/doc/iallocator.rst
index 3fe1487..a81e981 100644
--- a/doc/iallocator.rst
+++ b/doc/iallocator.rst
@@ -1,7 +1,7 @@
 Ganeti automatic instance allocation
 ====================================
 
-Documents Ganeti version 2.1
+Documents Ganeti version 2.5
 
 .. contents::
 
@@ -190,14 +190,20 @@ In all cases, it includes:
 
   type
     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.
+    ``change-group``, ``node-evacuate`` 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.
+
+    The ``multi-evacuate`` protocol used to request that the script
+    computes the optimal relocate solution for all secondary instances
+    of the given nodes. It is now deprecated and should no longer be
+    used.
+
+    The ``change-group`` request is used to relocate multiple instances
+    across multiple node groups. ``node-evacuate`` evacuates instances
+    off their node(s). These are described in a separate :ref:`design
+    document <multi-reloc-detailed-design>`.
 
 For both allocate and relocate mode, the following extra keys are needed
 in the ``request`` dictionary:
@@ -205,19 +211,24 @@ in the ``request`` dictionary:
   name
     the name of the instance; if the request is a realocation, then this
     name will be found in the list of instances (see below), otherwise
-    is the FQDN of the new instance
+    is the FQDN of the new instance; type *string*
 
   required_nodes
     how many nodes should the algorithm return; while this information
     can be deduced from the instace's disk template, it's better if
     this computation is left to Ganeti as then allocator scripts are
-    less sensitive to changes to the disk templates
+    less sensitive to changes to the disk templates; type *integer*
 
   disk_space_total
     the total disk space that will be used by this instance on the
     (new) nodes; again, this information can be computed from the list
     of instance disks and its template type, but Ganeti is better
-    suited to compute it
+    suited to compute it; type *integer*
+
+.. pyassert::
+
+   constants.DISK_ACCESS_SET == set([constants.DISK_RDONLY,
+     constants.DISK_RDWR])
 
 Allocation needs, in addition:
 
@@ -226,7 +237,8 @@ Allocation needs, in addition:
     instance (in the order they are exported to the hypervisor):
 
     mode
-      either ``r`` or ``w`` denoting if the disk is read-only or
+      either :pyeval:`constants.DISK_RDONLY` or
+      :pyeval:`constants.DISK_RDWR` denoting if the disk is read-only or
       writable
 
     size
@@ -268,31 +280,33 @@ Relocation:
   relocate_from
      a list of nodes to move the instance away from (note that with
      Ganeti 2.0, this list will always contain a single node, the
-     current secondary of the instance)
+     current secondary of the instance); type *list of strings*
 
-As for ``multi-relocate``, it needs the three following request
-arguments:
+As for ``node-evacuate``, it needs the following request arguments:
 
   instances
-    a list of instance names to relocate
+    a list of instance names to evacuate; type *list of strings*
 
-  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 document <multi-reloc-detailed-design>`
+  evac_mode
+    specify which instances to evacuate; one of ``primary-only``,
+    ``secondary-only``, ``all``, type *string*
+
+``change-group`` needs the following request arguments:
+
+  instances
+    a list of instance names whose group to change; type
+    *list of strings*
 
   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
+    must either be the empty list, or contain a list of group UUIDs that
+    should be considered for relocating instances to; type
+    *list of strings*
 
 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
+    the names of the nodes to be evacuated; type *list of strings*
 
 Response message
 ~~~~~~~~~~~~~~~~
@@ -316,9 +330,10 @@ result
   entry in the input message, otherwise Ganeti will consider the result
   as failed
 
-  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 the ``node-evacuate`` and ``change-group`` modes, this is a
+  dictionary containing, among other information, a list of lists of
+  serialized opcodes; see the :ref:`design document
+  <multi-reloc-result>` for a detailed description
 
   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