Merge branch 'stable-2.7' into stable-2.8

[ganeti-local] / doc / iallocator.rst

diff --git a/doc/iallocator.rst b/doc/iallocator.rst
index a81e981..957c2bb 100644 (file)
--- a/doc/iallocator.rst
+++ b/doc/iallocator.rst
@@ -1,7 +1,7 @@
 Ganeti automatic instance allocation
 ====================================
 
 Ganeti automatic instance allocation
 ====================================
 

-Documents Ganeti version 2.5
+Documents Ganeti version 2.7

 
 .. contents::
 
 
 .. contents::
 

@@ -41,7 +41,7 @@ using the first one whose filename matches the one given by the user.
 Command line interface changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Command line interface changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-The node selection options in instanece add and instance replace disks
+The node selection options in instance add and instance replace disks

 can be replace by the new ``--iallocator=NAME`` option (shortened to
 ``-I``), which will cause the auto-assignement of nodes with the
 passed iallocator. The selected node(s) will be show as part of the
 can be replace by the new ``--iallocator=NAME`` option (shortened to
 ``-I``), which will cause the auto-assignement of nodes with the
 passed iallocator. The selected node(s) will be show as part of the

@@ -90,6 +90,10 @@ cluster_tags
 enabled_hypervisors
   the list of enabled hypervisors
 
 enabled_hypervisors
   the list of enabled hypervisors
 

+ipolicy
+  the cluster-wide instance policy (for information; the per-node group
+  values take precedence and should be used instead)
+

 request
   a dictionary containing the details of the request; the keys vary
   depending on the type of operation that's being requested, as
 request
   a dictionary containing the details of the request; the keys vary
   depending on the type of operation that's being requested, as

@@ -105,13 +109,15 @@ nodegroups
   alloc_policy
     the allocation policy of the node group (consult the semantics of
     this attribute in the :manpage:`gnt-group(8)` manpage)
   alloc_policy
     the allocation policy of the node group (consult the semantics of
     this attribute in the :manpage:`gnt-group(8)` manpage)

+  ipolicy
+    the instance policy of the node group

 
 instances
   a dictionary with the data for the current existing instance on the
   cluster, indexed by instance name; the contents are similar to the
   instance definitions for the allocate mode, with the addition of:
 
 
 instances
   a dictionary with the data for the current existing instance on the
   cluster, indexed by instance name; the contents are similar to the
   instance definitions for the allocate mode, with the addition of:
 

-  admin_up
+  admin_state

     if this instance is set to run (but not the actual status of the
     instance)
 
     if this instance is set to run (but not the actual status of the
     instance)
 

@@ -190,21 +196,27 @@ In all cases, it includes:
 
   type
     the request type; this can be either ``allocate``, ``relocate``,
 
   type
     the request type; this can be either ``allocate``, ``relocate``,

-    ``change-group``, ``node-evacuate`` or ``multi-evacuate``. The
+    ``change-group`` or ``node-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
     ``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.
+    of the given nodes. It is now deprecated and needs only be
+    implemented if backwards compatibility with Ganeti 2.4 and lower is
+    needed.

 
     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>`.
 
 
     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>`.
 

+    The ``multi-allocate`` request is used to allocate multiple
+    instances on the cluster. The request is beside of that very
+    similiar to the ``allocate`` one. For more details look at
+    :doc:`Ganeti bulk create <design-bulk-create>`.
+

 For both allocate and relocate mode, the following extra keys are needed
 in the ``request`` dictionary:
 
 For both allocate and relocate mode, the following extra keys are needed
 in the ``request`` dictionary:
 

@@ -278,9 +290,11 @@ Allocation needs, in addition:
 Relocation:
 
   relocate_from
 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); type *list of strings*
+     a list of nodes to move the instance away from; for DRBD-based
+     instances, this will contain a single node, the current secondary
+     of the instance, whereas for shared-storage instance, this will
+     contain also a single node, the current primary of the instance;
+     type *list of strings*

 
 As for ``node-evacuate``, it needs the following request arguments:
 
 
 As for ``node-evacuate``, it needs the following request arguments:
 

@@ -302,11 +316,10 @@ As for ``node-evacuate``, it needs the following request arguments:
     should be considered for relocating instances to; type
     *list of strings*
 
     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``):
+``multi-allocate`` needs the following request arguments:

 
 

-  evac_nodes
-    the names of the nodes to be evacuated; type *list of strings*
+  instances
+    a list of request dicts

 
 Response message
 ~~~~~~~~~~~~~~~~
 
 Response message
 ~~~~~~~~~~~~~~~~

@@ -335,8 +348,11 @@ result
   serialized opcodes; see the :ref:`design document
   <multi-reloc-result>` for a detailed description
 
   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
+  for the ``multi-allocate`` mode this is a tuple of 2 lists, the first
+  being element of the tuple is a list of succeeded allocation, with the
+  instance name as first element of each entry and the node placement in
+  the second. The second element of the tuple is the instance list of
+  failed allocations.

 
 .. note:: Current Ganeti version accepts either ``result`` or ``nodes``
    as a backwards-compatibility measure (older versions only supported
 
 .. note:: Current Ganeti version accepts either ``result`` or ``nodes``
    as a backwards-compatibility measure (older versions only supported

@@ -505,19 +521,6 @@ Input message, reallocation::
     }
   }
 
     }
   }
 

-Input message, node evacuation::
-
-  {
-    "version": 2,
-    ...
-    "request": {
-      "type": "multi-evacuate",
-      "evac_nodes": [
-        "node2"
-      ],
-    }
-  }
-

 
 Response messages
 ~~~~~~~~~~~~~~~~~
 
 Response messages
 ~~~~~~~~~~~~~~~~~