X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/b795a7752528819af3a5007f8cb99fbc1067dbba..0c009cc5622fe33caeb2a0dc7dd36ecb480f5e21:/doc/rapi.rst

diff --git a/doc/rapi.rst b/doc/rapi.rst
index 49e8234..7ed29a8 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -53,8 +53,8 @@ Example::
 
 
 .. [#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
@@ -395,6 +395,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.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`
+
 Example::
 
     [
@@ -448,6 +450,8 @@ It supports the following commands: ``GET``, ``DELETE``.
 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``
 ~~~~~~~~~~
 
@@ -473,6 +477,10 @@ Body parameters:
 .. opcode_params:: OP_GROUP_SET_PARAMS
    :exclude: group_name
 
+Job result:
+
+.. opcode_result:: OP_GROUP_SET_PARAMS
+
 
 ``/2/groups/[group_name]/rename``
 +++++++++++++++++++++++++++++++++
@@ -491,6 +499,10 @@ Body parameters:
 .. opcode_params:: OP_GROUP_RENAME
    :exclude: group_name
 
+Job result:
+
+.. opcode_result:: OP_GROUP_RENAME
+
 
 ``/2/groups/[group_name]/assign-nodes``
 +++++++++++++++++++++++++++++++++++++++
@@ -579,6 +591,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.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
+
 Example::
 
     [
@@ -634,6 +648,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.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_CREATE
+
 
 ``/2/instances/[instance_name]``
 ++++++++++++++++++++++++++++++++
@@ -648,6 +666,8 @@ It supports the following commands: ``GET``, ``DELETE``.
 Returns information about an instance, similar to the bulk output from
 the instance list.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
+
 ``DELETE``
 ~~~~~~~~~~
 
@@ -876,6 +896,24 @@ Body parameters:
    :exclude: instance_name, live
 
 
+``/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
+
+
 ``/2/instances/[instance_name]/rename``
 ++++++++++++++++++++++++++++++++++++++++
 
@@ -893,6 +931,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_RENAME
    :exclude: instance_name
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_RENAME
+
 
 ``/2/instances/[instance_name]/modify``
 ++++++++++++++++++++++++++++++++++++++++
@@ -911,6 +953,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_SET_PARAMS
    :exclude: instance_name
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_SET_PARAMS
+
 
 ``/2/instances/[instance_name]/console``
 ++++++++++++++++++++++++++++++++++++++++
@@ -925,22 +971,32 @@ Supports the following commands: ``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,
+     ])
+
 ``instance``
   Instance name.
 ``kind``
-  Console type, one of ``ssh``, ``vnc`` or ``msg``.
+  Console type, one of :pyeval:`constants.CONS_SSH`,
+  :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_MESSAGE`.
 ``message``
-  Message to display (``msg`` type only).
+  Message to display (:pyeval:`constants.CONS_MESSAGE` type only).
 ``host``
-  Host to connect to (``ssh`` and ``vnc`` only).
+  Host to connect to (:pyeval:`constants.CONS_SSH` and
+  :pyeval:`constants.CONS_VNC` only).
 ``port``
-  TCP port to connect to (``vnc`` only).
+  TCP port to connect to (:pyeval:`constants.CONS_VNC` only).
 ``user``
-  Username to use (``ssh`` only).
+  Username to use (:pyeval:`constants.CONS_SSH` only).
 ``command``
-  Command to execute on machine (``ssh`` only)
+  Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
 ``display``
-  VNC display number (``vnc`` only).
+  VNC display number (:pyeval:`constants.CONS_VNC` only).
 
 
 ``/2/instances/[instance_name]/tags``
@@ -997,6 +1053,14 @@ Returns a dictionary of jobs.
 
 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]``
 ++++++++++++++++++++
 
@@ -1008,9 +1072,8 @@ It supports the following commands: ``GET``, ``DELETE``.
 ``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:
 
@@ -1142,9 +1205,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::
 
@@ -1171,6 +1236,8 @@ Returns information about a node.
 
 It supports the following commands: ``GET``.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
+
 ``/2/nodes/[node_name]/evacuate``
 +++++++++++++++++++++++++++++++++
 
@@ -1193,6 +1260,10 @@ 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.
 
+Job result:
+
+.. opcode_result:: OP_NODE_EVACUATE
+
 
 ``/2/nodes/[node_name]/migrate``
 +++++++++++++++++++++++++++++++++