projects / ganeti-local / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Merge branch 'devel-2.6'
[ganeti-local] / doc / rapi.rst
diff --git a/doc/rapi.rst b/doc/rapi.rst
index c80a309..9f8b1b9 100644 (file)
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -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).
 
 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
 --------------
 
@@ -303,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``
 +++++++++++++++
@@ -321,12 +388,12 @@ features:
                              rlib2._NODE_EVAC_RES1])
 
 :pyeval:`rlib2._INST_CREATE_REQV1`
                              rlib2._NODE_EVAC_RES1])
 
 :pyeval:`rlib2._INST_CREATE_REQV1`
-  Instance creation request data version 1 supported.
+  Instance creation request data version 1 supported
 :pyeval:`rlib2._INST_REINSTALL_REQV1`
 :pyeval:`rlib2._INST_REINSTALL_REQV1`
-  Instance reinstall supports body parameters.
+  Instance reinstall supports body parameters
 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
   Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
   Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
-  request body parameters.
+  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)
 :pyeval:`rlib2._NODE_EVAC_RES1`
   Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
   a new-style result (see resource description)
@@ -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,7 +449,7 @@ 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))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
 
 Example::
 
 
 Example::
 
@@ -419,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]``
 ++++++++++++++++++++++++++
@@ -433,7 +508,7 @@ 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))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
 
 ``DELETE``
 ~~~~~~~~~~
 
 ``DELETE``
 ~~~~~~~~~~
@@ -442,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``
 +++++++++++++++++++++++++++++++++
@@ -504,6 +583,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``
 +++++++++++++++++++++++++++++++
@@ -545,6 +628,25 @@ to URI like::
 It supports the ``dry-run`` argument.
 
 
 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``
 ++++++++++++++++
 
@@ -574,7 +676,7 @@ 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))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
 
 Example::
 
 
 Example::
 
@@ -649,7 +751,7 @@ 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))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
 
 ``DELETE``
 ~~~~~~~~~~
 
 ``DELETE``
 ~~~~~~~~~~
@@ -658,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``
 +++++++++++++++++++++++++++++++++++++++
@@ -672,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``
 +++++++++++++++++++++++++++++++++++++++
@@ -700,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``
 +++++++++++++++++++++++++++++++++++++++++
@@ -718,6 +832,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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -736,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``
 ++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -782,6 +905,10 @@ Body parameters:
 Ganeti 2.4 and below used query parameters. Those are deprecated and
 should no longer be used.
 
 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``
 +++++++++++++++++++++++++++++++++++++++++++++++
@@ -796,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -809,6 +940,10 @@ 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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/recreate-disks``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -826,6 +961,10 @@ Body parameters:
 .. opcode_params:: OP_INSTANCE_RECREATE_DISKS
    :exclude: instance_name
 
 .. 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``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -844,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -857,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``
 +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -876,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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -894,6 +1045,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``
 +++++++++++++++++++++++++++++++++++++++++
@@ -912,6 +1067,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``
 ++++++++++++++++++++++++++++++++++++++++
@@ -980,25 +1139,25 @@ console. Contained keys:
      ])
 
 ``instance``
      ])
 
 ``instance``
-  Instance name.
+  Instance name
 ``kind``
   Console type, one of :pyeval:`constants.CONS_SSH`,
   :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
 ``kind``
   Console type, one of :pyeval:`constants.CONS_SSH`,
   :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
-  or :pyeval:`constants.CONS_MESSAGE`.
+  or :pyeval:`constants.CONS_MESSAGE`
 ``message``
 ``message``
-  Message to display (:pyeval:`constants.CONS_MESSAGE` type only).
+  Message to display (:pyeval:`constants.CONS_MESSAGE` type only)
 ``host``
   Host to connect to (:pyeval:`constants.CONS_SSH`,
 ``host``
   Host to connect to (:pyeval:`constants.CONS_SSH`,
-  :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only).
+  :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
 ``port``
   TCP port to connect to (:pyeval:`constants.CONS_VNC` or
 ``port``
   TCP port to connect to (:pyeval:`constants.CONS_VNC` or
-  :pyeval:`constants.CONS_SPICE` only).
+  :pyeval:`constants.CONS_SPICE` only)
 ``user``
 ``user``
-  Username to use (:pyeval:`constants.CONS_SSH` only).
+  Username to use (:pyeval:`constants.CONS_SSH` only)
 ``command``
   Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
 ``display``
 ``command``
   Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
 ``display``
-  VNC display number (:pyeval:`constants.CONS_VNC` only).
+  VNC display number (:pyeval:`constants.CONS_VNC` only)
 
 
 ``/2/instances/[instance_name]/tags``
 
 
 ``/2/instances/[instance_name]/tags``
@@ -1061,7 +1220,7 @@ as a list.
 
 Returned fields for bulk requests (unlike other bulk requests, these
 fields are not the same as for per-job requests):
 
 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))`
+:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`.
 
 ``/2/jobs/[job_id]``
 ++++++++++++++++++++
 
 ``/2/jobs/[job_id]``
 ++++++++++++++++++++
@@ -1169,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.
@@ -1211,7 +1370,7 @@ 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.
 
 (i.e ``?bulk=1``), the output contains detailed information about nodes
 as a list.
 
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
 
 Example::
 
 
 Example::
 
@@ -1238,7 +1397,7 @@ 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))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
 
 ``/2/nodes/[node_name]/powercycle``
 +++++++++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/powercycle``
 +++++++++++++++++++++++++++++++++++
@@ -1250,6 +1409,10 @@ Powercycles a node. Supports the following commands: ``POST``.
 
 Returns a job ID.
 
 
 Returns a job ID.
 
+Job result:
+
+.. opcode_result:: OP_NODE_POWERCYCLE
+
 
 ``/2/nodes/[node_name]/evacuate``
 +++++++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/evacuate``
 +++++++++++++++++++++++++++++++++
@@ -1340,6 +1503,10 @@ 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``
 +++++++++++++++++++++++++++++++
@@ -1397,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``
 +++++++++++++++++++++++++++++++++++++++
 
@@ -1416,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``
 +++++++++++++++++++++++++++++
 
Unnamed repository; edit this file 'description' to name the repository.