+In all cases, it includes:
+
+ type
+ 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 <multi-reloc-detailed-design>`.
+
+ The ``multi-allocate`` request is used to allocate multiple
+ instances on the cluster. The request is beside of that very
+ similiar to the ``allocate`` one. For more details look at
+ :doc:`Ganeti bulk create <design-bulk-create>`.
+
+For both allocate and relocate mode, the following extra keys are needed
+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; 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; 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; type *integer*
+
+.. pyassert::
+
+ constants.DISK_ACCESS_SET == set([constants.DISK_RDONLY,
+ constants.DISK_RDWR])
+
+Allocation needs, in addition:
+
+ disks
+ list of dictionaries holding the disk definitions for this
+ instance (in the order they are exported to the hypervisor):
+
+ mode
+ either :pyeval:`constants.DISK_RDONLY` or
+ :pyeval:`constants.DISK_RDWR` denoting if the disk is read-only or
+ writable
+
+ size
+ the size of this disk in mebibytes
+
+ nics
+ a list of dictionaries holding the network interfaces for this
+ instance, containing:
+
+ ip
+ the IP address that Ganeti know for this instance, or null
+
+ mac
+ the MAC address for this interface
+
+ bridge
+ the bridge to which this interface will be connected
+
+ vcpus
+ the number of VCPUs for the instance
+
+ disk_template
+ the disk template for the instance
+
+ memory
+ the memory size for the instance
+
+ os
+ the OS type for the instance
+
+ tags
+ the list of the instance's tags
+
+ hypervisor
+ the hypervisor of this instance
+
+Relocation:
+
+ relocate_from
+ a list of nodes to move the instance away from; for DRBD-based
+ instances, this will contain a single node, the current secondary
+ of the instance, whereas for shared-storage instance, this will
+ contain also a single node, the current primary 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*
+
+ evac_mode
+ specify which instances to evacuate; one of ``primary-only``,
+ ``secondary-only``, ``all``, type *string*
+
+``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*
+
+``multi-allocate`` needs the following request arguments:
+
+ instances
+ a list of request dicts
+
+Response message
+~~~~~~~~~~~~~~~~