X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/876860a3cf6f39450b0bf749a5979cd48f49bdba..926feaf11d13f8451f286c0096202bab331cca6b:/doc/iallocator.rst diff --git a/doc/iallocator.rst b/doc/iallocator.rst index ac9831e..de2759c 100644 --- a/doc/iallocator.rst +++ b/doc/iallocator.rst @@ -1,7 +1,7 @@ Ganeti automatic instance allocation ==================================== -Documents Ganeti version 2.0 +Documents Ganeti version 2.1 .. contents:: @@ -72,7 +72,7 @@ the following: version the version of the protocol; this document - specifies version 1 + specifies version 2 cluster_name the cluster name @@ -80,19 +80,27 @@ 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 @@ -148,6 +156,9 @@ request 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 @@ -155,12 +166,17 @@ request 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) @@ -170,7 +186,7 @@ instances 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) @@ -200,25 +216,59 @@ nodes 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 -------- @@ -325,8 +375,8 @@ Input message, new instance allocation:: "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, @@ -334,8 +384,8 @@ Input message, new instance allocation:: }, "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, @@ -343,8 +393,8 @@ Input message, new instance allocation:: }, "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, @@ -367,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", - "nodes": [ + "result": [ "node2.example.com", "node1.example.com" ], @@ -384,10 +444,28 @@ Failed response message:: { "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 ~~~~~~~~~~~~~~~~~~~~~ :: @@ -404,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) + +.. vim: set textwidth=72 : +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: