X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/61791108dea923e7f2e722b21fba3b23d93ddcf9..e4c03256a608b64421258ea50f60d6fa032ef0a4:/doc/iallocator.rst diff --git a/doc/iallocator.rst b/doc/iallocator.rst index dfdcd69..c6b150b 100644 --- a/doc/iallocator.rst +++ b/doc/iallocator.rst @@ -1,7 +1,7 @@ Ganeti automatic instance allocation ==================================== -Documents Ganeti version 2.1 +Documents Ganeti version 2.5 .. contents:: @@ -111,7 +111,7 @@ instances 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) @@ -189,13 +189,22 @@ follows. In all cases, it includes: type - 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 request type; this can be either ``allocate``, ``relocate``, + ``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 + 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 `. For both allocate and relocate mode, the following extra keys are needed in the ``request`` dictionary: @@ -203,19 +212,24 @@ in the ``request`` dictionary: 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 + is the FQDN of the new instance; type *string* required_nodes how many nodes should the algorithm return; while this information can be deduced from the instace's disk template, it's better if this computation is left to Ganeti as then allocator scripts are - less sensitive to changes to the disk templates + less sensitive to changes to the disk templates; type *integer* disk_space_total the total disk space that will be used by this instance on the (new) nodes; again, this information can be computed from the list of instance disks and its template type, but Ganeti is better - suited to compute it + suited to compute it; type *integer* + +.. pyassert:: + + constants.DISK_ACCESS_SET == set([constants.DISK_RDONLY, + constants.DISK_RDWR]) Allocation needs, in addition: @@ -224,7 +238,8 @@ Allocation needs, in addition: instance (in the order they are exported to the hypervisor): mode - either ``r`` or ``w`` denoting if the disk is read-only or + either :pyeval:`constants.DISK_RDONLY` or + :pyeval:`constants.DISK_RDWR` denoting if the disk is read-only or writable size @@ -266,13 +281,27 @@ 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) + current secondary of the instance); type *list of strings* + +As for ``node-evacuate``, it needs the following request arguments: + + instances + a list of instance names to evacuate; type *list of strings* -In the case of multi-evacuate, there's one single request argument (in -addition to ``type``): + evac_mode + specify which instances to evacuate; one of ``primary-only``, + ``secondary-only``, ``all``, type *string* - evac_nodes - the names of the nodes to be evacuated +``change-group`` needs the following request arguments: + + instances + a list of instance names whose group to change; type + *list of strings* + + target_groups + must either be the empty list, or contain a list of group UUIDs that + should be considered for relocating instances to; type + *list of strings* Response message ~~~~~~~~~~~~~~~~ @@ -296,8 +325,10 @@ result 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 + for the ``node-evacuate`` and ``change-group`` modes, this is a + dictionary containing, among other information, a list of lists of + serialized opcodes; see the :ref:`design document + ` for a detailed description .. note:: Current Ganeti version accepts either ``result`` or ``nodes`` as a backwards-compatibility measure (older versions only supported @@ -466,19 +497,6 @@ Input message, reallocation:: } } -Input message, node evacuation:: - - { - "version": 2, - ... - "request": { - "type": "multi-evacuate", - "evac_nodes": [ - "node2" - ], - } - } - Response messages ~~~~~~~~~~~~~~~~~ @@ -539,10 +557,9 @@ Command line messages Reference implementation ~~~~~~~~~~~~~~~~~~~~~~~~ -Ganeti's default iallocator is "hail" which is part of the separate -ganeti-htools project. In order to see its source code please clone -``git://git.ganeti.org/htools.git``. Note that htools is implemented -using the Haskell programming language. +Ganeti's default iallocator is "hail" which is available when "htools" +components have been enabled at build time (see :doc:`install-quick` for +more details). .. vim: set textwidth=72 : .. Local Variables: