Fix pylint breakage due to unused var in gnt_cluster

[ganeti-local] / doc / rapi.rst

diff --git a/doc/rapi.rst b/doc/rapi.rst
index a72fc3f..9f8b1b9 100644 (file)
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -53,8 +53,8 @@ Example::
 
 
 .. [#pwhash] Using the MD5 hash of username, realm and password is
 
 
 .. [#pwhash] Using the MD5 hash of username, realm and password is

-   described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 and
-   3.3. The reason for using it over another algorithm is forward
+   described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
+   and 3.3. The reason for using it over another algorithm is forward

    compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
    authentication in the future, the same hash could be used.
    In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
    compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
    authentication in the future, the same hash could be used.
    In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote

@@ -70,6 +70,10 @@ HTTP Basic authentication as per :rfc:`2617` is supported.
 .. _JSON: http://www.json.org/
 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
 
 .. _JSON: http://www.json.org/
 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
 

+HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
+header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
+(HTTP/1.1), section 7.2.1).
+

 
 A note on JSON as used by RAPI
 ++++++++++++++++++++++++++++++
 
 A note on JSON as used by RAPI
 ++++++++++++++++++++++++++++++

@@ -162,6 +166,69 @@ likely to succeed or at least start executing.
 Force operation to continue even if it will cause the cluster to become
 inconsistent (e.g. because there are not enough master candidates).
 
 Force operation to continue even if it will cause the cluster to become
 inconsistent (e.g. because there are not enough master candidates).
 

+Parameter details
+-----------------
+
+Some parameters are not straight forward, so we describe them in details
+here.
+
+.. _rapi-ipolicy:
+
+``ipolicy``
++++++++++++
+
+The instance policy specification is a dict with the following fields:
+
+.. pyassert::
+
+  constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN,
+                                     constants.ISPECS_MAX,
+                                     constants.ISPECS_STD,
+                                     constants.IPOLICY_DTS,
+                                     constants.IPOLICY_VCPU_RATIO,
+                                     constants.IPOLICY_SPINDLE_RATIO])
+
+
+.. pyassert::
+
+  (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
+   set([constants.ISPEC_MEM_SIZE,
+        constants.ISPEC_DISK_SIZE,
+        constants.ISPEC_DISK_COUNT,
+        constants.ISPEC_CPU_COUNT,
+        constants.ISPEC_NIC_COUNT,
+        constants.ISPEC_SPINDLE_USE]))
+
+.. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
+.. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
+.. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
+
+
+|ispec-min|, |ispec-max|, |ispec-std|
+  A sub- `dict` with the following fields, which sets the limit and standard
+  values of the instances:
+
+  :pyeval:`constants.ISPEC_MEM_SIZE`
+    The size in MiB of the memory used
+  :pyeval:`constants.ISPEC_DISK_SIZE`
+    The size in MiB of the disk used
+  :pyeval:`constants.ISPEC_DISK_COUNT`
+    The numbers of disks used
+  :pyeval:`constants.ISPEC_CPU_COUNT`
+    The numbers of cpus used
+  :pyeval:`constants.ISPEC_NIC_COUNT`
+    The numbers of nics used
+  :pyeval:`constants.ISPEC_SPINDLE_USE`
+    The numbers of virtual disk spindles used by this instance. They are
+    not real in the sense of actual HDD spindles, but useful for
+    accounting the spindle usage on the residing node
+:pyeval:`constants.IPOLICY_DTS`
+  A `list` of disk templates allowed for instances using this policy
+:pyeval:`constants.IPOLICY_VCPU_RATIO`
+  Maximum ratio of virtual to physical CPUs (`float`)
+:pyeval:`constants.IPOLICY_SPINDLE_RATIO`
+  Maximum ratio of instances to their node's ``spindle_count`` (`float`)
+

 Usage examples
 --------------
 
 Usage examples
 --------------
 

@@ -235,30 +302,13 @@ Resources
 ``/``
 +++++
 
 ``/``
 +++++
 

-The root resource.
-
-It supports the following commands: ``GET``.
-
-``GET``
-~~~~~~~
-
-Shows the list of mapped resources.
-
-Returns: a dictionary with 'name' and 'uri' keys for each of them.
+The root resource. Has no function, but for legacy reasons the ``GET``
+method is supported.

 
 ``/2``
 ++++++
 
 
 ``/2``
 ++++++
 

-The ``/2`` resource, the root of the version 2 API.
-
-It supports the following commands: ``GET``.
-
-``GET``
-~~~~~~~
-
-Show the list of mapped resources.
-
-Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
+Has no function, but for legacy reasons the ``GET`` method is supported.

 
 ``/2/info``
 +++++++++++
 
 ``/2/info``
 +++++++++++

@@ -316,6 +366,10 @@ It supports the following commands: ``PUT``.
 
 Redistribute configuration to all nodes. The result will be a job id.
 
 
 Redistribute configuration to all nodes. The result will be a job id.
 

+Job result:
+
+.. opcode_result:: OP_CLUSTER_REDIST_CONF
+

 
 ``/2/features``
 +++++++++++++++
 
 ``/2/features``
 +++++++++++++++

@@ -326,10 +380,23 @@ Redistribute configuration to all nodes. The result will be a job id.
 Returns a list of features supported by the RAPI server. Available
 features:
 
 Returns a list of features supported by the RAPI server. Available
 features:
 

-``instance-create-reqv1``
-  Instance creation request data version 1 supported.
-``instance-reinstall-reqv1``
-  Instance reinstall supports body parameters.
+.. pyassert::
+
+  rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
+                             rlib2._INST_REINSTALL_REQV1,
+                             rlib2._NODE_MIGRATE_REQV1,
+                             rlib2._NODE_EVAC_RES1])
+
+:pyeval:`rlib2._INST_CREATE_REQV1`
+  Instance creation request data version 1 supported
+:pyeval:`rlib2._INST_REINSTALL_REQV1`
+  Instance reinstall supports body parameters
+:pyeval:`rlib2._NODE_MIGRATE_REQV1`
+  Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
+  request body parameters
+:pyeval:`rlib2._NODE_EVAC_RES1`
+  Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
+  a new-style result (see resource description)

 
 
 ``/2/modify``
 
 
 ``/2/modify``

@@ -348,6 +415,10 @@ Body parameters:
 
 .. opcode_params:: OP_CLUSTER_SET_PARAMS
 
 
 .. opcode_params:: OP_CLUSTER_SET_PARAMS
 

+Job result:
+
+.. opcode_result:: OP_CLUSTER_SET_PARAMS
+

 
 ``/2/groups``
 +++++++++++++
 
 ``/2/groups``
 +++++++++++++

@@ -378,6 +449,8 @@ If the optional bool *bulk* argument is provided and set to a true value
 (i.e ``?bulk=1``), the output contains detailed information about node
 groups as a list.
 
 (i.e ``?bulk=1``), the output contains detailed information about node
 groups as a list.
 

+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
+

 Example::
 
     [
 Example::
 
     [

@@ -417,6 +490,10 @@ Body parameters:
 Earlier versions used a parameter named ``name`` which, while still
 supported, has been renamed to ``group_name``.
 
 Earlier versions used a parameter named ``name`` which, while still
 supported, has been renamed to ``group_name``.
 

+Job result:
+
+.. opcode_result:: OP_GROUP_ADD
+

 
 ``/2/groups/[group_name]``
 ++++++++++++++++++++++++++
 
 ``/2/groups/[group_name]``
 ++++++++++++++++++++++++++

@@ -431,6 +508,8 @@ It supports the following commands: ``GET``, ``DELETE``.
 Returns information about a node group, similar to the bulk output from
 the node group list.
 
 Returns information about a node group, similar to the bulk output from
 the node group list.
 

+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
+

 ``DELETE``
 ~~~~~~~~~~
 
 ``DELETE``
 ~~~~~~~~~~
 

@@ -438,6 +517,10 @@ Deletes a node group.
 
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 

+Job result:
+
+.. opcode_result:: OP_GROUP_REMOVE
+

 
 ``/2/groups/[group_name]/modify``
 +++++++++++++++++++++++++++++++++
 
 ``/2/groups/[group_name]/modify``
 +++++++++++++++++++++++++++++++++

@@ -456,6 +539,10 @@ Body parameters:
 .. opcode_params:: OP_GROUP_SET_PARAMS
    :exclude: group_name
 
 .. opcode_params:: OP_GROUP_SET_PARAMS
    :exclude: group_name
 

+Job result:
+
+.. opcode_result:: OP_GROUP_SET_PARAMS
+

 
 ``/2/groups/[group_name]/rename``
 +++++++++++++++++++++++++++++++++
 
 ``/2/groups/[group_name]/rename``
 +++++++++++++++++++++++++++++++++

@@ -474,6 +561,10 @@ Body parameters:
 .. opcode_params:: OP_GROUP_RENAME
    :exclude: group_name
 
 .. opcode_params:: OP_GROUP_RENAME
    :exclude: group_name
 

+Job result:
+
+.. opcode_result:: OP_GROUP_RENAME
+

 
 ``/2/groups/[group_name]/assign-nodes``
 +++++++++++++++++++++++++++++++++++++++
 
 ``/2/groups/[group_name]/assign-nodes``
 +++++++++++++++++++++++++++++++++++++++

@@ -492,6 +583,69 @@ Body parameters:
 .. opcode_params:: OP_GROUP_ASSIGN_NODES
    :exclude: group_name, force, dry_run
 
 .. opcode_params:: OP_GROUP_ASSIGN_NODES
    :exclude: group_name, force, dry_run
 

+Job result:
+
+.. opcode_result:: OP_GROUP_ASSIGN_NODES
+
+
+``/2/groups/[group_name]/tags``
++++++++++++++++++++++++++++++++
+
+Manages per-nodegroup tags.
+
+Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns a list of tags.
+
+Example::
+
+    ["tag1", "tag2", "tag3"]
+
+``PUT``
+~~~~~~~
+
+Add a set of tags.
+
+The request as a list of strings should be ``PUT`` to this URI. The
+result will be a job id.
+
+It supports the ``dry-run`` argument.
+
+
+``DELETE``
+~~~~~~~~~~
+
+Delete a tag.
+
+In order to delete a set of tags, the DELETE request should be addressed
+to URI like::
+
+    /tags?tag=[tag]&tag=[tag]
+
+It supports the ``dry-run`` argument.
+
+
+``/2/instances-multi-alloc``
+++++++++++++++++++++++++++++
+
+Tries to allocate multiple instances.
+
+It supports the following commands: ``POST``
+
+``POST``
+~~~~~~~~
+
+The parameters:
+
+.. opcode_params:: OP_INSTANCE_MULTI_ALLOC
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_MULTI_ALLOC
+

 
 ``/2/instances``
 ++++++++++++++++
 
 ``/2/instances``
 ++++++++++++++++

@@ -522,6 +676,8 @@ If the optional bool *bulk* argument is provided and set to a true value
 (i.e ``?bulk=1``), the output contains detailed information about
 instances as a list.
 
 (i.e ``?bulk=1``), the output contains detailed information about
 instances as a list.
 

+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
+

 Example::
 
     [
 Example::
 
     [

@@ -568,8 +724,8 @@ Body parameters:
 
 ``__version__`` (int, required)
   Must be ``1`` (older Ganeti versions used a different format for
 
 ``__version__`` (int, required)
   Must be ``1`` (older Ganeti versions used a different format for

-  instance creation requests, version ``0``, but that format is not
-  documented and should no longer be used).
+  instance creation requests, version ``0``, but that format is no
+  longer supported)

 
 .. opcode_params:: OP_INSTANCE_CREATE
 
 
 .. opcode_params:: OP_INSTANCE_CREATE
 

@@ -577,6 +733,10 @@ Earlier versions used parameters named ``name`` and ``os``. These have
 been replaced by ``instance_name`` and ``os_type`` to match the
 underlying opcode. The old names can still be used.
 
 been replaced by ``instance_name`` and ``os_type`` to match the
 underlying opcode. The old names can still be used.
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_CREATE
+

 
 ``/2/instances/[instance_name]``
 ++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]``
 ++++++++++++++++++++++++++++++++

@@ -591,6 +751,8 @@ It supports the following commands: ``GET``, ``DELETE``.
 Returns information about an instance, similar to the bulk output from
 the instance list.
 
 Returns information about an instance, similar to the bulk output from
 the instance list.
 

+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
+

 ``DELETE``
 ~~~~~~~~~~
 
 ``DELETE``
 ~~~~~~~~~~
 

@@ -598,6 +760,10 @@ Deletes an instance.
 
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_REMOVE
+

 
 ``/2/instances/[instance_name]/info``
 +++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/info``
 +++++++++++++++++++++++++++++++++++++++

@@ -612,6 +778,10 @@ Requests detailed information about the instance. An optional parameter,
 configuration without querying the instance's nodes. The result will be
 a job id.
 
 configuration without querying the instance's nodes. The result will be
 a job id.
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_QUERY_DATA
+

 
 ``/2/instances/[instance_name]/reboot``
 +++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/reboot``
 +++++++++++++++++++++++++++++++++++++++

@@ -640,6 +810,10 @@ instance even if secondary disks are failing.
 
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_REBOOT
+

 
 ``/2/instances/[instance_name]/shutdown``
 +++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/shutdown``
 +++++++++++++++++++++++++++++++++++++++++

@@ -655,6 +829,13 @@ Shutdowns an instance.
 
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 

+.. opcode_params:: OP_INSTANCE_SHUTDOWN
+   :exclude: instance_name, dry_run
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_SHUTDOWN
+

 
 ``/2/instances/[instance_name]/startup``
 ++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/startup``
 ++++++++++++++++++++++++++++++++++++++++

@@ -673,6 +854,11 @@ instance even if secondary disks are failing.
 
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_STARTUP
+
+

 ``/2/instances/[instance_name]/reinstall``
 ++++++++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/reinstall``
 ++++++++++++++++++++++++++++++++++++++++++++++
 

@@ -709,16 +895,19 @@ It supports the following commands: ``POST``.
 ``POST``
 ~~~~~~~~
 
 ``POST``
 ~~~~~~~~
 

-Takes the parameters ``mode`` (one of ``replace_on_primary``,
-``replace_on_secondary``, ``replace_new_secondary`` or
-``replace_auto``), ``disks`` (comma separated list of disk indexes),
-``remote_node`` and ``iallocator``.
+Returns a job ID.
+
+Body parameters:

 
 

-Either ``remote_node`` or ``iallocator`` needs to be defined when using
-``mode=replace_new_secondary``.
+.. opcode_params:: OP_INSTANCE_REPLACE_DISKS
+   :exclude: instance_name

 
 

-``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
-the broken disk(s) on its own and replacing it.
+Ganeti 2.4 and below used query parameters. Those are deprecated and
+should no longer be used.
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_REPLACE_DISKS

 
 
 ``/2/instances/[instance_name]/activate-disks``
 
 
 ``/2/instances/[instance_name]/activate-disks``

@@ -734,6 +923,10 @@ It supports the following commands: ``PUT``.
 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 size (useful for forcing activation when recorded size is wrong).
 
 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 size (useful for forcing activation when recorded size is wrong).
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
+

 
 ``/2/instances/[instance_name]/deactivate-disks``
 +++++++++++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/deactivate-disks``
 +++++++++++++++++++++++++++++++++++++++++++++++++

@@ -747,6 +940,31 @@ It supports the following commands: ``PUT``.
 
 Takes no parameters.
 
 
 Takes no parameters.
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS
+
+
+``/2/instances/[instance_name]/recreate-disks``
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Recreate disks of an instance. Supports the following commands:
+``POST``.
+
+``POST``
+~~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_INSTANCE_RECREATE_DISKS
+   :exclude: instance_name
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_RECREATE_DISKS
+

 
 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++

@@ -765,6 +983,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_GROW_DISK
    :exclude: instance_name, disk
 
 .. opcode_params:: OP_INSTANCE_GROW_DISK
    :exclude: instance_name, disk
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_GROW_DISK
+

 
 ``/2/instances/[instance_name]/prepare-export``
 +++++++++++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/prepare-export``
 +++++++++++++++++++++++++++++++++++++++++++++++++

@@ -778,6 +1000,10 @@ It supports the following commands: ``PUT``.
 
 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 
 
 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 

+Job result:
+
+.. opcode_result:: OP_BACKUP_PREPARE
+

 
 ``/2/instances/[instance_name]/export``
 +++++++++++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/export``
 +++++++++++++++++++++++++++++++++++++++++++++++++

@@ -797,6 +1023,10 @@ Body parameters:
    :exclude: instance_name
    :alias: target_node=destination
 
    :exclude: instance_name
    :alias: target_node=destination
 

+Job result:
+
+.. opcode_result:: OP_BACKUP_EXPORT
+

 
 ``/2/instances/[instance_name]/migrate``
 ++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/migrate``
 ++++++++++++++++++++++++++++++++++++++++

@@ -815,6 +1045,32 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_MIGRATE
    :exclude: instance_name, live
 
 .. opcode_params:: OP_INSTANCE_MIGRATE
    :exclude: instance_name, live
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_MIGRATE
+
+
+``/2/instances/[instance_name]/failover``
++++++++++++++++++++++++++++++++++++++++++
+
+Does a failover of an instance.
+
+Supports the following commands: ``PUT``.
+
+``PUT``
+~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_INSTANCE_FAILOVER
+   :exclude: instance_name
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_FAILOVER
+

 
 ``/2/instances/[instance_name]/rename``
 ++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/rename``
 ++++++++++++++++++++++++++++++++++++++++

@@ -833,6 +1089,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_RENAME
    :exclude: instance_name
 
 .. opcode_params:: OP_INSTANCE_RENAME
    :exclude: instance_name
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_RENAME
+

 
 ``/2/instances/[instance_name]/modify``
 ++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/modify``
 ++++++++++++++++++++++++++++++++++++++++

@@ -851,6 +1111,54 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_SET_PARAMS
    :exclude: instance_name
 
 .. opcode_params:: OP_INSTANCE_SET_PARAMS
    :exclude: instance_name
 

+Job result:
+
+.. opcode_result:: OP_INSTANCE_SET_PARAMS
+
+
+``/2/instances/[instance_name]/console``
+++++++++++++++++++++++++++++++++++++++++
+
+Request information for connecting to instance's console.
+
+Supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns a dictionary containing information about the instance's
+console. Contained keys:
+
+.. pyassert::
+
+   constants.CONS_ALL == frozenset([
+     constants.CONS_MESSAGE,
+     constants.CONS_SSH,
+     constants.CONS_VNC,
+     constants.CONS_SPICE,
+     ])
+
+``instance``
+  Instance name
+``kind``
+  Console type, one of :pyeval:`constants.CONS_SSH`,
+  :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
+  or :pyeval:`constants.CONS_MESSAGE`
+``message``
+  Message to display (:pyeval:`constants.CONS_MESSAGE` type only)
+``host``
+  Host to connect to (:pyeval:`constants.CONS_SSH`,
+  :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
+``port``
+  TCP port to connect to (:pyeval:`constants.CONS_VNC` or
+  :pyeval:`constants.CONS_SPICE` only)
+``user``
+  Username to use (:pyeval:`constants.CONS_SSH` only)
+``command``
+  Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
+``display``
+  VNC display number (:pyeval:`constants.CONS_VNC` only)
+

 
 ``/2/instances/[instance_name]/tags``
 +++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/tags``
 +++++++++++++++++++++++++++++++++++++

@@ -906,6 +1214,14 @@ Returns a dictionary of jobs.
 
 Returns: a dictionary with jobs id and uri.
 
 
 Returns: a dictionary with jobs id and uri.
 

+If the optional bool *bulk* argument is provided and set to a true value
+(i.e. ``?bulk=1``), the output contains detailed information about jobs
+as a list.
+
+Returned fields for bulk requests (unlike other bulk requests, these
+fields are not the same as for per-job requests):
+:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`.
+

 ``/2/jobs/[job_id]``
 ++++++++++++++++++++
 
 ``/2/jobs/[job_id]``
 ++++++++++++++++++++
 

@@ -917,9 +1233,8 @@ It supports the following commands: ``GET``, ``DELETE``.
 ``GET``
 ~~~~~~~
 
 ``GET``
 ~~~~~~~
 

-Returns a job status.
-
-Returns: a dictionary with job parameters.
+Returns a dictionary with job parameters, containing the fields
+:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.

 
 The result includes:
 
 
 The result includes:
 

@@ -1013,14 +1328,14 @@ Waits for changes on a job. Takes the following body parameters in a
 dict:
 
 ``fields``
 dict:
 
 ``fields``

-  The job fields on which to watch for changes.
+  The job fields on which to watch for changes

 
 ``previous_job_info``
 
 ``previous_job_info``

-  Previously received field values or None if not yet available.
+  Previously received field values or None if not yet available

 
 ``previous_log_serial``
   Highest log serial number received so far or None if not yet
 
 ``previous_log_serial``
   Highest log serial number received so far or None if not yet

-  available.
+  available

 
 Returns None if no changes have been detected and a dict with two keys,
 ``job_info`` and ``log_entries`` otherwise.
 
 Returns None if no changes have been detected and a dict with two keys,
 ``job_info`` and ``log_entries`` otherwise.

@@ -1051,9 +1366,11 @@ Example::
       }
     ]
 
       }
     ]
 

-If the optional 'bulk' argument is provided and set to 'true' value (i.e
-'?bulk=1'), the output contains detailed information about nodes as a
-list.
+If the optional bool *bulk* argument is provided and set to a true value
+(i.e ``?bulk=1``), the output contains detailed information about nodes
+as a list.
+
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.

 
 Example::
 
 
 Example::
 

@@ -1080,35 +1397,48 @@ Returns information about a node.
 
 It supports the following commands: ``GET``.
 
 
 It supports the following commands: ``GET``.
 

+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
+
+``/2/nodes/[node_name]/powercycle``
++++++++++++++++++++++++++++++++++++
+
+Powercycles a node. Supports the following commands: ``POST``.
+
+``POST``
+~~~~~~~~
+
+Returns a job ID.
+
+Job result:
+
+.. opcode_result:: OP_NODE_POWERCYCLE
+
+

 ``/2/nodes/[node_name]/evacuate``
 +++++++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/evacuate``
 +++++++++++++++++++++++++++++++++
 

-Evacuates all secondary instances off a node.
+Evacuates instances off a node.

 
 It supports the following commands: ``POST``.
 
 ``POST``
 ~~~~~~~~
 
 
 It supports the following commands: ``POST``.
 
 ``POST``
 ~~~~~~~~
 

-To evacuate a node, either one of the ``iallocator`` or ``remote_node``
-parameters must be passed::
+Returns a job ID. The result of the job will contain the IDs of the
+individual jobs submitted to evacuate the node.

 
 

-    evacuate?iallocator=[iallocator]
-    evacuate?remote_node=[nodeX.example.com]
+Body parameters:

 
 

-The result value will be a list, each element being a triple of the job
-id (for this specific evacuation), the instance which is being evacuated
-by this job, and the node to which it is being relocated. In case the
-node is already empty, the result will be an empty list (without any
-jobs being submitted).
+.. opcode_params:: OP_NODE_EVACUATE
+   :exclude: nodes

 
 

-And additional parameter ``early_release`` signifies whether to try to
-parallelize the evacuations, at the risk of increasing I/O contention
-and increasing the chances of data loss, if the primary node of any of
-the instances being evacuated is not fully healthy.
+Up to and including Ganeti 2.4 query arguments were used. Those are no
+longer supported. The new request can be detected by the presence of the
+:pyeval:`rlib2._NODE_EVAC_RES1` feature string.

 
 

-If the dry-run parameter was specified, then the evacuation jobs were
-not actually submitted, and the job IDs will be null.
+Job result:
+
+.. opcode_result:: OP_NODE_EVACUATE

 
 
 ``/2/nodes/[node_name]/migrate``
 
 
 ``/2/nodes/[node_name]/migrate``

@@ -1122,13 +1452,18 @@ It supports the following commands: ``POST``.
 ~~~~~~~~
 
 If no mode is explicitly specified, each instances' hypervisor default
 ~~~~~~~~
 
 If no mode is explicitly specified, each instances' hypervisor default

-migration mode will be used. Query parameters:
+migration mode will be used. Body parameters:
+
+.. opcode_params:: OP_NODE_MIGRATE
+   :exclude: node_name
+
+The query arguments used up to and including Ganeti 2.4 are deprecated
+and should no longer be used. The new request format can be detected by
+the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.

 
 

-``live`` (bool)
-  If set, use live migration if available.
-``mode`` (string)
-  Sets migration mode, ``live`` for live migration and ``non-live`` for
-  non-live migration. Supported by Ganeti 2.2 and above.
+Job result:
+
+.. opcode_result:: OP_NODE_MIGRATE

 
 
 ``/2/nodes/[node_name]/role``
 
 
 ``/2/nodes/[node_name]/role``

@@ -1141,11 +1476,14 @@ It supports the following commands: ``GET``, ``PUT``.
 The role is always one of the following:
 
   - drained
 The role is always one of the following:
 
   - drained

-  - master

   - master-candidate
   - offline
   - regular
 
   - master-candidate
   - offline
   - regular
 

+Note that the 'master' role is a special, and currently it can't be
+modified via RAPI, only via the command line (``gnt-cluster
+master-failover``).
+

 ``GET``
 ~~~~~~~
 
 ``GET``
 ~~~~~~~
 

@@ -1165,6 +1503,32 @@ be a job id.
 
 It supports the bool ``force`` argument.
 
 
 It supports the bool ``force`` argument.
 

+Job result:
+
+.. opcode_result:: OP_NODE_SET_PARAMS
+
+
+``/2/nodes/[node_name]/modify``
++++++++++++++++++++++++++++++++
+
+Modifies the parameters of a node. Supports the following commands:
+``POST``.
+
+``POST``
+~~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_NODE_SET_PARAMS
+   :exclude: node_name
+
+Job result:
+
+.. opcode_result:: OP_NODE_SET_PARAMS
+
+

 ``/2/nodes/[node_name]/storage``
 ++++++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/storage``
 ++++++++++++++++++++++++++++++++
 

@@ -1200,6 +1564,11 @@ and ``name`` (name of the storage unit).  Parameters can be passed
 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
 is supported. The result will be a job id.
 
 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
 is supported. The result will be a job id.
 

+Job result:
+
+.. opcode_result:: OP_NODE_MODIFY_STORAGE
+
+

 ``/2/nodes/[node_name]/storage/repair``
 +++++++++++++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/storage/repair``
 +++++++++++++++++++++++++++++++++++++++
 

@@ -1219,6 +1588,11 @@ Repairs a storage unit on the node. Requires the parameters
 repaired) and ``name`` (name of the storage unit). The result will be a
 job id.
 
 repaired) and ``name`` (name of the storage unit). The result will be a
 job id.
 

+Job result:
+
+.. opcode_result:: OP_REPAIR_NODE_STORAGE
+
+

 ``/2/nodes/[node_name]/tags``
 +++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/tags``
 +++++++++++++++++++++++++++++
 

@@ -1258,6 +1632,50 @@ to URI like::
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 
 

+``/2/query/[resource]``
++++++++++++++++++++++++
+
+Requests resource information. Available fields can be found in man
+pages and using ``/2/query/[resource]/fields``. The resource is one of
+:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
+design document <design-query2>` for more details.
+
+Supports the following commands: ``GET``, ``PUT``.
+
+``GET``
+~~~~~~~
+
+Returns list of included fields and actual data. Takes a query parameter
+named "fields", containing a comma-separated list of field names. Does
+not support filtering.
+
+``PUT``
+~~~~~~~
+
+Returns list of included fields and actual data. The list of requested
+fields can either be given as the query parameter "fields" or as a body
+parameter with the same name. The optional body parameter "filter" can
+be given and must be either ``null`` or a list containing filter
+operators.
+
+
+``/2/query/[resource]/fields``
+++++++++++++++++++++++++++++++
+
+Request list of available fields for a resource. The resource is one of
+:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
+:doc:`query2 design document <design-query2>` for more details.
+
+Supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns a list of field descriptions for available fields. Takes an
+optional query parameter named "fields", containing a comma-separated
+list of field names.
+
+

 ``/2/os``
 +++++++++
 
 ``/2/os``
 +++++++++