Ganeti automatic instance allocation
====================================
-Documents Ganeti version 2.0
+Documents Ganeti version 2.1
.. contents::
version
the version of the protocol; this document
- specifies version 1
+ specifies version 2
cluster_name
the cluster name
cluster_tags
the list of cluster tags
+enabled_hypervisors
+ the list of enabled hypervisors
+
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
- 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
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
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
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)
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)
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
+
+ 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
- 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
-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
--------
"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,
},
"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,
},
"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,
},
+Input message, node evacuation::
+
+ "request": {
+ "evac_nodes": [
+ "node2"
+ ],
+ "type": "multi-evacuate"
+ },
+
+
Response messages
~~~~~~~~~~~~~~~~~
Successful response message::
{
"info": "Allocation successful",
- "nodes": [
+ "result": [
"node2.example.com",
"node1.example.com"
],
{
"info": "Can't find a suitable node for position 2 (already selected: node2.example.com)",
- "nodes": [],
+ "result": [],
"success": false
}
+Successful node evacuation message::
+
+ {
+ "info": "Request successful",
+ "result": [
+ [
+ "instance1",
+ "node3"
+ ],
+ [
+ "instance2",
+ "node1"
+ ]
+ ],
+ "success": true
+ }
+
+
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)
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End: