projects / ganeti-local / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Export a node's group information in iallocator
[ganeti-local] / doc / iallocator.rst
diff --git a/doc/iallocator.rst b/doc/iallocator.rst
index ac9831e..6b90e86 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::
 
@@ -72,7 +72,7 @@ the following:
 
 version
   the version of the protocol; this document
 
 version
   the version of the protocol; this document
-  specifies version 1
+  specifies version 2
 
 cluster_name
   the cluster name
 
 cluster_name
   the cluster name
@@ -80,19 +80,27 @@ cluster_name
 cluster_tags
   the list of cluster tags
 
 cluster_tags
   the list of cluster tags
 
+enabled_hypervisors
+  the list of enabled hypervisors
+
 request
   a dictionary containing the request data:
 
   type
 request
   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
@@ -148,6 +156,9 @@ request
   tags
     the list of the instance's tags
 
   tags
     the list of the instance's tags
 
+  hypervisor
+    the hypervisor of this instance
+
 
   If the request is of type relocate, then there is one more entry in
   the request dictionary, named ``relocate_from``, and it contains a
 
   If the request is of type relocate, then there is one more entry in
   the request dictionary, named ``relocate_from``, and it contains a
@@ -155,12 +166,25 @@ 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
+
+nodegroups
+  a dictionary with the data for the cluster's node groups; it is keyed
+  on the group UUID, and the values are a dictionary with the following
+  keys:
+
+  name
+    the node group name
+
 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:
 
-  should_run
+  admin_up
     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)
 
@@ -170,7 +194,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)
@@ -200,25 +224,62 @@ nodes
   tags
     list with the tags of the node
 
   tags
     list with the tags of the node
 
-Respone message
-~~~~~~~~~~~~~~~
+  master_candidate:
+    a boolean flag denoting whether this node is a master candidate
+
+  drained:
+    a boolean flag denoting whether this node is being drained
+
+  offline:
+    a boolean flag denoting whether this node is offline
+
+  i_pri_memory:
+    total memory required by primary instances
+
+  i_pri_up_memory:
+    total memory required by running primary instances
+
+  group:
+    the node group that this node belongs to
+
+  No allocations should be made on nodes having either the ``drained``
+  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
+
+
+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
 --------
@@ -325,8 +386,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,
@@ -334,8 +395,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,
@@ -343,8 +404,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,
@@ -367,13 +428,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"
     ],
@@ -384,10 +455,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
 ~~~~~~~~~~~~~~~~~~~~~
 ::
@@ -404,3 +493,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:
Unnamed repository; edit this file 'description' to name the repository.