Use reserved documentation IPs and domains

[ganeti-local] / doc / iallocator.rst

diff --git a/doc/iallocator.rst b/doc/iallocator.rst
index 58719a0..de2759c 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.0
+Documents Ganeti version 2.1

 
 .. contents::
 
 
 .. contents::
 

@@ -87,15 +87,20 @@ request
   a dictionary containing the request data:
 
   type
   a dictionary containing the request data:
 
   type

-    the request type; this can be either ``allocate`` or ``relocate``;
-    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 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 following keys are needed in allocate/relocate mode:

 
   name
 
   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
+    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

 
   required_nodes
     how many nodes should the algorithm return; while this information
 
   required_nodes
     how many nodes should the algorithm return; while this information

@@ -161,6 +166,11 @@ request
   2.0, this list will always contain a single node, the current
   secondary of the instance.
 
   2.0, this list will always contain a single node, the current
   secondary of the instance.
 

+  The multi-evacuate mode has instead a single request argument:
+
+  nodes
+    the names of the nodes to be evacuated
+

 instances
   a dictionary with the data for the current existing instance on the
   cluster, indexed by instance name; the contents are similar to the
 instances
   a dictionary with the data for the current existing instance on the
   cluster, indexed by instance name; the contents are similar to the

@@ -176,7 +186,7 @@ instances
 
 nodes
   dictionary with the data for the nodes in the cluster, indexed by
 
 nodes
   dictionary with the data for the nodes in the cluster, indexed by

-  the node name; the dict contains:
+  the node name; the dict contains [*]_ :

 
   total_disk
     the total disk size of this node (mebibytes)
 
   total_disk
     the total disk size of this node (mebibytes)

@@ -225,26 +235,40 @@ nodes
   or ``offline`` flags set. More details about these of node status
   flags is available in the manpage :manpage:`ganeti(7)`.
 
   or ``offline`` flags set. More details about these of node status
   flags is available in the manpage :manpage:`ganeti(7)`.
 

+.. [*] Note that no run-time data is present for offline or drained
+   nodes; this means the tags total_memory, reserved_memory,
+   free_memory, total_disk, free_disk, total_cpus, i_pri_memory and
+   i_pri_up memory will be absent
+

 
 

-Respone message
-~~~~~~~~~~~~~~~
+Response message
+~~~~~~~~~~~~~~~~

 
 The response message is much more simple than the input one. It is
 also a dict having three keys:
 
 success
 
 The response message is much more simple than the input one. It is
 also a dict having three keys:
 
 success

-  a boolean value denoting if the allocation was successfull or not
+  a boolean value denoting if the allocation was successful or not

 
 info
   a string with information from the scripts; if the allocation fails,
   this will be shown to the user
 
 
 info
   a string with information from the scripts; if the allocation fails,
   this will be shown to the user
 

-nodes
-  the list of nodes computed by the algorithm; even if the algorithm
-  failed (i.e. success is false), this must be returned as an empty
-  list; also note that the length of this list must equal the
-  ``requested_nodes`` entry in the input message, otherwise Ganeti
-  will consider the result as failed
+result
+  the output of the algorithm; even if the algorithm failed
+  (i.e. success is false), this must be returned as an empty list
+
+  for allocate/relocate, this is the list of node(s) for the instance;
+  note that the length of this list must equal the ``requested_nodes``
+  entry in the input message, otherwise Ganeti will consider the result
+  as failed
+
+  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
+
+.. note:: Current Ganeti version accepts either ``result`` or ``nodes``
+   as a backwards-compatibility measure (older versions only supported
+   ``nodes``)

 
 Examples
 --------
 
 Examples
 --------

@@ -351,8 +375,8 @@ Input message, new instance allocation::
     "nodes": {
       "node1.example.com": {
         "total_disk": 858276,
     "nodes": {
       "node1.example.com": {
         "total_disk": 858276,

-        "primary_ip": "192.168.1.1",
-        "secondary_ip": "192.168.2.1",
+        "primary_ip": "198.51.100.1",
+        "secondary_ip": "192.0.2.1",

         "tags": [],
         "free_memory": 3505,
         "free_disk": 856740,
         "tags": [],
         "free_memory": 3505,
         "free_disk": 856740,

@@ -360,8 +384,8 @@ Input message, new instance allocation::
       },
       "node2.example.com": {
         "total_disk": 858240,
       },
       "node2.example.com": {
         "total_disk": 858240,

-        "primary_ip": "192.168.1.3",
-        "secondary_ip": "192.168.2.3",
+        "primary_ip": "198.51.100.2",
+        "secondary_ip": "192.0.2.2",

         "tags": ["test"],
         "free_memory": 3505,
         "free_disk": 848320,
         "tags": ["test"],
         "free_memory": 3505,
         "free_disk": 848320,

@@ -369,8 +393,8 @@ Input message, new instance allocation::
       },
       "node3.example.com.com": {
         "total_disk": 572184,
       },
       "node3.example.com.com": {
         "total_disk": 572184,

-        "primary_ip": "192.168.1.3",
-        "secondary_ip": "192.168.2.3",
+        "primary_ip": "198.51.100.3",
+        "secondary_ip": "192.0.2.3",

         "tags": [],
         "free_memory": 3505,
         "free_disk": 570648,
         "tags": [],
         "free_memory": 3505,
         "free_disk": 570648,

@@ -393,13 +417,23 @@ message is changed, we show only this changed entry::
   },
 
 
   },
 
 

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

 Response messages
 ~~~~~~~~~~~~~~~~~
 Successful response message::
 
   {
     "info": "Allocation successful",
 Response messages
 ~~~~~~~~~~~~~~~~~
 Successful response message::
 
   {
     "info": "Allocation successful",

-    "nodes": [
+    "result": [

       "node2.example.com",
       "node1.example.com"
     ],
       "node2.example.com",
       "node1.example.com"
     ],

@@ -410,10 +444,28 @@ Failed response message::
 
   {
     "info": "Can't find a suitable node for position 2 (already selected: node2.example.com)",
 
   {
     "info": "Can't find a suitable node for position 2 (already selected: node2.example.com)",

-    "nodes": [],
+    "result": [],

     "success": false
   }
 
     "success": false
   }
 

+Successful node evacuation message::
+
+  {
+    "info": "Request successful",
+    "result": [
+      [
+        "instance1",
+        "node3"
+      ],
+      [
+        "instance2",
+        "node1"
+      ]
+    ],
+    "success": true
+  }
+
+

 Command line messages
 ~~~~~~~~~~~~~~~~~~~~~
 ::
 Command line messages
 ~~~~~~~~~~~~~~~~~~~~~
 ::

@@ -430,3 +482,9 @@ Command line messages
   # gnt-instance add -t drbd -m 1400m --os-size 1g --swap-size 512m --iallocator dumb-allocator -o etch-image instance5
   Failure: prerequisites not met for this operation:
   Can't compute nodes using iallocator 'dumb-allocator': Can't find a suitable node for position 2 (already selected: node1.example.com)
   # gnt-instance add -t drbd -m 1400m --os-size 1g --swap-size 512m --iallocator dumb-allocator -o etch-image instance5
   Failure: prerequisites not met for this operation:
   Can't compute nodes using iallocator 'dumb-allocator': Can't find a suitable node for position 2 (already selected: node1.example.com)

+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End: