projects / ganeti-local / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Add job result descriptions to RAPI documentation
[ganeti-local] / doc / rapi.rst
diff --git a/doc/rapi.rst b/doc/rapi.rst
index 238b849..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).
 
 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
 --------------
 
 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``
 ++++++
 
 
 ``/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``
 +++++++++++
@@ -320,6 +361,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``
 +++++++++++++++
@@ -365,6 +410,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``
 +++++++++++++
@@ -436,6 +485,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]``
 ++++++++++++++++++++++++++
@@ -459,6 +512,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``
 +++++++++++++++++++++++++++++++++
@@ -521,6 +578,10 @@ 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``
 +++++++++++++++++++++++++++++++
 
 ``/2/groups/[group_name]/tags``
 +++++++++++++++++++++++++++++++
@@ -675,6 +736,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``
 +++++++++++++++++++++++++++++++++++++++
@@ -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.
 
 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``
 +++++++++++++++++++++++++++++++++++++++
@@ -717,6 +786,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``
 +++++++++++++++++++++++++++++++++++++++++
@@ -735,6 +808,10 @@ It supports the ``dry-run`` argument.
 .. opcode_params:: OP_INSTANCE_SHUTDOWN
    :exclude: instance_name, dry_run
 
 .. 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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -753,6 +830,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``
 ++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -789,16 +871,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:
+
+.. opcode_params:: OP_INSTANCE_REPLACE_DISKS
+   :exclude: instance_name
+
+Ganeti 2.4 and below used query parameters. Those are deprecated and
+should no longer be used.
 
 
-Either ``remote_node`` or ``iallocator`` needs to be defined when using
-``mode=replace_new_secondary``.
+Job result:
 
 
-``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
-the broken disk(s) on its own and replacing it.
+.. opcode_result:: OP_INSTANCE_REPLACE_DISKS
 
 
 ``/2/instances/[instance_name]/activate-disks``
 
 
 ``/2/instances/[instance_name]/activate-disks``
@@ -814,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).
 
 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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -827,6 +916,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -845,6 +959,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -858,6 +976,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -877,6 +999,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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -895,6 +1021,10 @@ 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``
 +++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/failover``
 +++++++++++++++++++++++++++++++++++++++++
@@ -913,6 +1043,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_FAILOVER
    :exclude: instance_name
 
 .. 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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -1241,6 +1375,21 @@ It supports the following commands: ``GET``.
 
 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
 
 
 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``
 +++++++++++++++++++++++++++++++++
 
@@ -1288,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.
 
 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``
 +++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/role``
 +++++++++++++++++++++++++++++
@@ -1326,15 +1479,19 @@ 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``
 
 ``/2/nodes/[node_name]/modify``
-+++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++
 
 Modifies the parameters of a node. Supports the following commands:
 ``POST``.
 
 ``POST``
 
 Modifies the parameters of a node. Supports the following commands:
 ``POST``.
 
 ``POST``
-~~~~~~~
+~~~~~~~~
 
 Returns a job ID.
 
 
 Returns a job ID.
 
@@ -1383,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.
 
 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``
 +++++++++++++++++++++++++++++++++++++++
 
@@ -1402,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.
 
 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``
 +++++++++++++++++++++++++++++
 
Unnamed repository; edit this file 'description' to name the repository.