Add job result descriptions to RAPI documentation

[ganeti-local] / doc / rapi.rst

diff --git a/doc/rapi.rst b/doc/rapi.rst
index 6dea27c..baed7fe 100644 (file)
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -166,6 +166,64 @@ 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).
 
+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]))
+
+.. |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.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
 --------------
 
@@ -239,30 +297,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``
 ++++++
 
-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``
 +++++++++++
@@ -320,6 +361,10 @@ It supports the following commands: ``PUT``.
 
 Redistribute configuration to all nodes. The result will be a job id.
 
+Job result:
+
+.. opcode_result:: OP_CLUSTER_REDIST_CONF
+
 
 ``/2/features``
 +++++++++++++++
@@ -365,6 +410,10 @@ Body parameters:
 
 .. opcode_params:: OP_CLUSTER_SET_PARAMS
 
+Job result:
+
+.. opcode_result:: OP_CLUSTER_SET_PARAMS
+
 
 ``/2/groups``
 +++++++++++++
@@ -436,6 +485,10 @@ Body parameters:
 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]``
 ++++++++++++++++++++++++++
@@ -459,6 +512,10 @@ Deletes a node group.
 
 It supports the ``dry-run`` argument.
 
+Job result:
+
+.. opcode_result:: OP_GROUP_REMOVE
+
 
 ``/2/groups/[group_name]/modify``
 +++++++++++++++++++++++++++++++++
@@ -521,6 +578,10 @@ Body parameters:
 .. 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``
 +++++++++++++++++++++++++++++++
@@ -675,6 +736,10 @@ Deletes an instance.
 
 It supports the ``dry-run`` argument.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_REMOVE
+
 
 ``/2/instances/[instance_name]/info``
 +++++++++++++++++++++++++++++++++++++++
@@ -689,6 +754,10 @@ Requests detailed information about the instance. An optional parameter,
 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``
 +++++++++++++++++++++++++++++++++++++++
@@ -717,6 +786,10 @@ instance even if secondary disks are failing.
 
 It supports the ``dry-run`` argument.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_REBOOT
+
 
 ``/2/instances/[instance_name]/shutdown``
 +++++++++++++++++++++++++++++++++++++++++
@@ -735,6 +808,10 @@ 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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -753,6 +830,11 @@ instance even if secondary disks are failing.
 
 It supports the ``dry-run`` argument.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_STARTUP
+
+
 ``/2/instances/[instance_name]/reinstall``
 ++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -799,6 +881,10 @@ Body parameters:
 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``
 +++++++++++++++++++++++++++++++++++++++++++++++
@@ -813,6 +899,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).
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
+
 
 ``/2/instances/[instance_name]/deactivate-disks``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -826,6 +916,31 @@ It supports the following commands: ``PUT``.
 
 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``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -844,6 +959,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_GROW_DISK
    :exclude: instance_name, disk
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_GROW_DISK
+
 
 ``/2/instances/[instance_name]/prepare-export``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -857,6 +976,10 @@ It supports the following commands: ``PUT``.
 
 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 
+Job result:
+
+.. opcode_result:: OP_BACKUP_PREPARE
+
 
 ``/2/instances/[instance_name]/export``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -876,6 +999,10 @@ Body parameters:
    :exclude: instance_name
    :alias: target_node=destination
 
+Job result:
+
+.. opcode_result:: OP_BACKUP_EXPORT
+
 
 ``/2/instances/[instance_name]/migrate``
 ++++++++++++++++++++++++++++++++++++++++
@@ -894,6 +1021,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_MIGRATE
    :exclude: instance_name, live
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_MIGRATE
+
 
 ``/2/instances/[instance_name]/failover``
 +++++++++++++++++++++++++++++++++++++++++
@@ -912,6 +1043,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_FAILOVER
    :exclude: instance_name
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_FAILOVER
+
 
 ``/2/instances/[instance_name]/rename``
 ++++++++++++++++++++++++++++++++++++++++
@@ -1240,6 +1375,21 @@ 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``
 +++++++++++++++++++++++++++++++++
 
@@ -1287,6 +1437,10 @@ 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.
 
+Job result:
+
+.. opcode_result:: OP_NODE_MIGRATE
+
 
 ``/2/nodes/[node_name]/role``
 +++++++++++++++++++++++++++++
@@ -1325,6 +1479,10 @@ be a job id.
 
 It supports the bool ``force`` argument.
 
+Job result:
+
+.. opcode_result:: OP_NODE_SET_PARAMS
+
 
 ``/2/nodes/[node_name]/modify``
 +++++++++++++++++++++++++++++++
@@ -1382,6 +1540,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.
 
+Job result:
+
+.. opcode_result:: OP_NODE_MODIFY_STORAGE
+
+
 ``/2/nodes/[node_name]/storage/repair``
 +++++++++++++++++++++++++++++++++++++++
 
@@ -1401,6 +1564,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.
 
+Job result:
+
+.. opcode_result:: OP_REPAIR_NODE_STORAGE
+
+
 ``/2/nodes/[node_name]/tags``
 +++++++++++++++++++++++++++++