X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/de40437a5698133fb7242fda6525f14480b87f3d..3008f56cbb58ef3d70db6006d89eb279b2deb165:/doc/rapi.rst

diff --git a/doc/rapi.rst b/doc/rapi.rst
index e1ee709..9f8b1b9 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
@@ -166,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).
 
+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
 --------------
 
@@ -239,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``
 ++++++
 
-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 +366,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``
 +++++++++++++++
@@ -330,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:
 
-``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``
@@ -352,6 +415,10 @@ Body parameters:
 
 .. opcode_params:: OP_CLUSTER_SET_PARAMS
 
+Job result:
+
+.. opcode_result:: OP_CLUSTER_SET_PARAMS
+
 
 ``/2/groups``
 +++++++++++++
@@ -382,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.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
+
 Example::
 
     [
@@ -421,6 +490,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]``
 ++++++++++++++++++++++++++
@@ -435,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.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
+
 ``DELETE``
 ~~~~~~~~~~
 
@@ -442,6 +517,10 @@ Deletes a node group.
 
 It supports the ``dry-run`` argument.
 
+Job result:
+
+.. opcode_result:: OP_GROUP_REMOVE
+
 
 ``/2/groups/[group_name]/modify``
 +++++++++++++++++++++++++++++++++
@@ -460,6 +539,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``
 +++++++++++++++++++++++++++++++++
@@ -478,6 +561,10 @@ Body parameters:
 .. opcode_params:: OP_GROUP_RENAME
    :exclude: group_name
 
+Job result:
+
+.. opcode_result:: OP_GROUP_RENAME
+
 
 ``/2/groups/[group_name]/assign-nodes``
 +++++++++++++++++++++++++++++++++++++++
@@ -496,6 +583,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``
 +++++++++++++++++++++++++++++++
@@ -537,6 +628,25 @@ to URI like::
 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``
 ++++++++++++++++
 
@@ -566,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.
 
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
+
 Example::
 
     [
@@ -621,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.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_CREATE
+
 
 ``/2/instances/[instance_name]``
 ++++++++++++++++++++++++++++++++
@@ -635,6 +751,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``
 ~~~~~~~~~~
 
@@ -642,6 +760,10 @@ Deletes an instance.
 
 It supports the ``dry-run`` argument.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_REMOVE
+
 
 ``/2/instances/[instance_name]/info``
 +++++++++++++++++++++++++++++++++++++++
@@ -656,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.
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_QUERY_DATA
+
 
 ``/2/instances/[instance_name]/reboot``
 +++++++++++++++++++++++++++++++++++++++
@@ -684,6 +810,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``
 +++++++++++++++++++++++++++++++++++++++++
@@ -702,6 +832,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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -720,6 +854,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``
 ++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -756,16 +895,19 @@ It supports the following commands: ``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``
@@ -781,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).
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
+
 
 ``/2/instances/[instance_name]/deactivate-disks``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -794,6 +940,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -812,6 +983,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -825,6 +1000,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -844,6 +1023,10 @@ Body parameters:
    :exclude: instance_name
    :alias: target_node=destination
 
+Job result:
+
+.. opcode_result:: OP_BACKUP_EXPORT
+
 
 ``/2/instances/[instance_name]/migrate``
 ++++++++++++++++++++++++++++++++++++++++
@@ -862,6 +1045,32 @@ Body parameters:
 .. 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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -880,6 +1089,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_RENAME
    :exclude: instance_name
 
+Job result:
+
+.. opcode_result:: OP_INSTANCE_RENAME
+
 
 ``/2/instances/[instance_name]/modify``
 ++++++++++++++++++++++++++++++++++++++++
@@ -898,6 +1111,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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -912,22 +1129,35 @@ 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,
+     constants.CONS_SPICE,
+     ])
+
 ``instance``
-  Instance name.
+  Instance name
 ``kind``
-  Console type, one of ``ssh``, ``vnc`` or ``msg``.
+  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 (``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`,
+  :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
 ``port``
-  TCP port to connect to (``vnc`` only).
+  TCP port to connect to (:pyeval:`constants.CONS_VNC` or
+  :pyeval:`constants.CONS_SPICE` 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``
@@ -984,6 +1214,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]``
 ++++++++++++++++++++
 
@@ -995,9 +1233,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:
 
@@ -1091,14 +1328,14 @@ Waits for changes on a job. Takes the following body parameters in a
 dict:
 
 ``fields``
-  The job fields on which to watch for changes.
+  The job fields on which to watch for changes
 
 ``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
-  available.
+  available
 
 Returns None if no changes have been detected and a dict with two keys,
 ``job_info`` and ``log_entries`` otherwise.
@@ -1129,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::
 
@@ -1158,6 +1397,23 @@ Returns information about a node.
 
 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``
 +++++++++++++++++++++++++++++++++
 
@@ -1180,6 +1436,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``
 +++++++++++++++++++++++++++++++++
@@ -1192,13 +1452,18 @@ It supports the following commands: ``POST``.
 ~~~~~~~~
 
 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
 
-``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.
+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``
@@ -1211,11 +1476,14 @@ It supports the following commands: ``GET``, ``PUT``.
 The role is always one of the following:
 
   - drained
-  - master
   - 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``
 ~~~~~~~
 
@@ -1235,6 +1503,32 @@ be a job id.
 
 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``
 ++++++++++++++++++++++++++++++++
 
@@ -1270,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.
 
+Job result:
+
+.. opcode_result:: OP_NODE_MODIFY_STORAGE
+
+
 ``/2/nodes/[node_name]/storage/repair``
 +++++++++++++++++++++++++++++++++++++++
 
@@ -1289,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.
 
+Job result:
+
+.. opcode_result:: OP_REPAIR_NODE_STORAGE
+
+
 ``/2/nodes/[node_name]/tags``
 +++++++++++++++++++++++++++++