iallocator: add ht-checking for the request

[ganeti-local] / doc / rapi.rst

diff --git a/doc/rapi.rst b/doc/rapi.rst
index 1a45c8c..fbc9970 100644 (file)
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -70,6 +70,10 @@ HTTP Basic authentication as per :rfc:`2617` is supported.
 .. _JSON: http://www.json.org/
 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
 
 .. _JSON: http://www.json.org/
 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
 

+HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
+header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
+(HTTP/1.1), section 7.2.1).
+

 
 A note on JSON as used by RAPI
 ++++++++++++++++++++++++++++++
 
 A note on JSON as used by RAPI
 ++++++++++++++++++++++++++++++

@@ -346,53 +350,7 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``vg_name`` (string)
-  Volume group name.
-``enabled_hypervisors`` (list)
-  List of enabled hypervisors.
-``hvparams`` (dict)
-  Cluster-wide hypervisor parameter defaults, hypervisor-dependent.
-``beparams`` (dict)
-  Cluster-wide backend parameter defaults.
-``os_hvp`` (dict)
-  Cluster-wide per-OS hypervisor parameter defaults.
-``osparams`` (dict)
-  Dictionary with OS parameters.
-``candidate_pool_size`` (int)
-  Master candidate pool size.
-``uid_pool`` (list)
-  Set UID pool. Must be list of lists describing UID ranges (two items,
-  start and end inclusive).
-``add_uids``
-  Extend UID pool. Must be list of lists describing UID ranges (two
-  items, start and end inclusive) to be added.
-``remove_uids``
-  Shrink UID pool. Must be list of lists describing UID ranges (two
-  items, start and end inclusive) to be removed.
-``maintain_node_health`` (bool)
-  Whether to automatically maintain node health.
-``prealloc_wipe_disks`` (bool)
-  Whether to wipe disks before allocating them to instances.
-``nicparams`` (dict)
-  Cluster-wide NIC parameter defaults.
-``ndparams`` (dict)
-  Cluster-wide node parameter defaults.
-``drbd_helper`` (string)
-  DRBD helper program.
-``default_iallocator`` (string)
-  Default iallocator for cluster.
-``master_netdev`` (string)
-  Master network device.
-``reserved_lvs`` (list)
-  List of reserved LVs (strings).
-``hidden_os`` (list)
-  List of modifications as lists. Each modification must have two items,
-  the operation and the OS name. The operation can be ``add`` or
-  ``remove``.
-``blacklisted_os`` (list)
-  List of modifications as lists. Each modification must have two items,
-  the operation and the OS name. The operation can be ``add`` or
-  ``remove``.
+.. opcode_params:: OP_CLUSTER_SET_PARAMS

 
 
 ``/2/groups``
 
 
 ``/2/groups``

@@ -458,8 +416,10 @@ Returns: a job ID that can be used later for polling.
 
 Body parameters:
 
 
 Body parameters:
 

-``name`` (string, required)
-  Node group name.
+.. opcode_params:: OP_GROUP_ADD
+
+Earlier versions used a parameter named ``name`` which, while still
+supported, has been renamed to ``group_name``.

 
 
 ``/2/groups/[group_name]``
 
 
 ``/2/groups/[group_name]``

@@ -497,8 +457,8 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``alloc_policy`` (string)
-  If present, the new allocation policy for the node group.
+.. opcode_params:: OP_GROUP_SET_PARAMS
+   :exclude: group_name

 
 
 ``/2/groups/[group_name]/rename``
 
 
 ``/2/groups/[group_name]/rename``

@@ -515,8 +475,8 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``new_name`` (string, required)
-  New node group name.
+.. opcode_params:: OP_GROUP_RENAME
+   :exclude: group_name

 
 
 ``/2/groups/[group_name]/assign-nodes``
 
 
 ``/2/groups/[group_name]/assign-nodes``

@@ -533,8 +493,48 @@ Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
 
 Body parameters:
 
 
 Body parameters:
 

-``nodes`` (list, required)
-  One or more nodes to assign to the group.
+.. opcode_params:: OP_GROUP_ASSIGN_NODES
+   :exclude: group_name, force, dry_run
+
+
+``/2/groups/[group_name]/tags``
++++++++++++++++++++++++++++++++
+
+Manages per-nodegroup tags.
+
+Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns a list of tags.
+
+Example::
+
+    ["tag1", "tag2", "tag3"]
+
+``PUT``
+~~~~~~~
+
+Add a set of tags.
+
+The request as a list of strings should be ``PUT`` to this URI. The
+result will be a job id.
+
+It supports the ``dry-run`` argument.
+
+
+``DELETE``
+~~~~~~~~~~
+
+Delete a tag.
+
+In order to delete a set of tags, the DELETE request should be addressed
+to URI like::
+
+    /tags?tag=[tag]&tag=[tag]
+
+It supports the ``dry-run`` argument.

 
 
 ``/2/instances``
 
 
 ``/2/instances``

@@ -612,64 +612,14 @@ Body parameters:
 
 ``__version__`` (int, required)
   Must be ``1`` (older Ganeti versions used a different format for
 
 ``__version__`` (int, required)
   Must be ``1`` (older Ganeti versions used a different format for

-  instance creation requests, version ``0``, but that format is not
-  documented).
-``mode`` (string, required)
-  Instance creation mode.
-``name`` (string, required)
-  Instance name.
-``disk_template`` (string, required)
-  Disk template for instance.
-``disks`` (list, required)
-  List of disk definitions. Example: ``[{"size": 100}, {"size": 5}]``.
-  Each disk definition must contain a ``size`` value and can contain an
-  optional ``mode`` value denoting the disk access mode (``ro`` or
-  ``rw``).
-``nics`` (list, required)
-  List of NIC (network interface) definitions. Example: ``[{}, {},
-  {"ip": "198.51.100.4"}]``. Each NIC definition can contain the
-  optional values ``ip``, ``mode``, ``link`` and ``bridge``.
-``os`` (string, required)
-  Instance operating system.
-``osparams`` (dictionary)
-  Dictionary with OS parameters. If not valid for the given OS, the job
-  will fail.
-``force_variant`` (bool)
-  Whether to force an unknown variant.
-``no_install`` (bool)
-  Do not install the OS (will enable no-start)
-``pnode`` (string)
-  Primary node.
-``snode`` (string)
-  Secondary node.
-``src_node`` (string)
-  Source node for import.
-``src_path`` (string)
-  Source directory for import.
-``start`` (bool)
-  Whether to start instance after creation.
-``ip_check`` (bool)
-  Whether to ensure instance's IP address is inactive.
-``name_check`` (bool)
-  Whether to ensure instance's name is resolvable.
-``file_storage_dir`` (string)
-  File storage directory.
-``file_driver`` (string)
-  File storage driver.
-``iallocator`` (string)
-  Instance allocator name.
-``source_handshake`` (list)
-  Signed handshake from source (remote import only).
-``source_x509_ca`` (string)
-  Source X509 CA in PEM format (remote import only).
-``source_instance_name`` (string)
-  Source instance name (remote import only).
-``hypervisor`` (string)
-  Hypervisor name.
-``hvparams`` (dict)
-  Hypervisor parameters, hypervisor-dependent.
-``beparams`` (dict)
-  Backend parameters.
+  instance creation requests, version ``0``, but that format is no
+  longer supported)
+
+.. opcode_params:: OP_INSTANCE_CREATE
+
+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.

 
 
 ``/2/instances/[instance_name]``
 
 
 ``/2/instances/[instance_name]``

@@ -749,6 +699,9 @@ Shutdowns an instance.
 
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 

+.. opcode_params:: OP_INSTANCE_SHUTDOWN
+   :exclude: instance_name, dry_run
+

 
 ``/2/instances/[instance_name]/startup``
 ++++++++++++++++++++++++++++++++++++++++
 
 ``/2/instances/[instance_name]/startup``
 ++++++++++++++++++++++++++++++++++++++++

@@ -856,10 +809,8 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``amount`` (int, required)
-  Amount of disk space to add.
-``wait_for_sync`` (bool)
-  Whether to wait for the disk to synchronize.
+.. opcode_params:: OP_INSTANCE_GROW_DISK
+   :exclude: instance_name, disk

 
 
 ``/2/instances/[instance_name]/prepare-export``
 
 
 ``/2/instances/[instance_name]/prepare-export``

@@ -889,18 +840,9 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``mode`` (string)
-  Export mode.
-``destination`` (required)
-  Destination information, depends on export mode.
-``shutdown`` (bool, required)
-  Whether to shutdown instance before export.
-``remove_instance`` (bool)
-  Whether to remove instance after export.
-``x509_key_name``
-  Name of X509 key (remote export only).
-``destination_x509_ca``
-  Destination X509 CA (remote export only).
+.. opcode_params:: OP_BACKUP_EXPORT
+   :exclude: instance_name
+   :alias: target_node=destination

 
 
 ``/2/instances/[instance_name]/migrate``
 
 
 ``/2/instances/[instance_name]/migrate``

@@ -917,10 +859,8 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``mode`` (string)
-  Migration mode.
-``cleanup`` (bool)
-  Whether a previously failed migration should be cleaned up.
+.. opcode_params:: OP_INSTANCE_MIGRATE
+   :exclude: instance_name, live

 
 
 ``/2/instances/[instance_name]/rename``
 
 
 ``/2/instances/[instance_name]/rename``

@@ -937,12 +877,8 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``new_name`` (string, required)
-  New instance name.
-``ip_check`` (bool)
-  Whether to ensure instance's IP address is inactive.
-``name_check`` (bool)
-  Whether to ensure instance's name is resolvable.
+.. opcode_params:: OP_INSTANCE_RENAME
+   :exclude: instance_name

 
 
 ``/2/instances/[instance_name]/modify``
 
 
 ``/2/instances/[instance_name]/modify``

@@ -959,29 +895,8 @@ Returns a job ID.
 
 Body parameters:
 
 
 Body parameters:
 

-``osparams`` (dict)
-  Dictionary with OS parameters.
-``hvparams`` (dict)
-  Hypervisor parameters, hypervisor-dependent.
-``beparams`` (dict)
-  Backend parameters.
-``force`` (bool)
-  Whether to force the operation.
-``nics`` (list)
-  List of NIC changes. Each item is of the form ``(op, settings)``.
-  ``op`` can be ``add`` to add a new NIC with the specified settings,
-  ``remove`` to remove the last NIC or a number to modify the settings
-  of the NIC with that index.
-``disks`` (list)
-  List of disk changes. See ``nics``.
-``disk_template`` (string)
-  Disk template for instance.
-``remote_node`` (string)
-  Secondary node (used when changing disk template).
-``os_name`` (string)
-  Change instance's OS name. Does not reinstall the instance.
-``force_variant`` (bool)
-  Whether to force an unknown variant.
+.. opcode_params:: OP_INSTANCE_SET_PARAMS
+   :exclude: instance_name

 
 
 ``/2/instances/[instance_name]/console``
 
 
 ``/2/instances/[instance_name]/console``

@@ -1110,42 +1025,49 @@ executing, so it's possible to retry the OpCode without side
 effects. But whether it make sense to retry depends on the error
 classification:
 
 effects. But whether it make sense to retry depends on the error
 classification:
 

-``resolver_error``
+.. pyassert::
+
+   errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
+     errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
+     errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
+     errors.ECODE_ENVIRON])
+
+:pyeval:`errors.ECODE_RESOLVER`

   Resolver errors. This usually means that a name doesn't exist in DNS,
   so if it's a case of slow DNS propagation the operation can be retried
   later.
 
   Resolver errors. This usually means that a name doesn't exist in DNS,
   so if it's a case of slow DNS propagation the operation can be retried
   later.
 

-``insufficient_resources``
+:pyeval:`errors.ECODE_NORES`

   Not enough resources (iallocator failure, disk space, memory,
   etc.). If the resources on the cluster increase, the operation might
   succeed.
 
   Not enough resources (iallocator failure, disk space, memory,
   etc.). If the resources on the cluster increase, the operation might
   succeed.
 

-``wrong_input``
+:pyeval:`errors.ECODE_INVAL`

   Wrong arguments (at syntax level). The operation will not ever be
   accepted unless the arguments change.
 
   Wrong arguments (at syntax level). The operation will not ever be
   accepted unless the arguments change.
 

-``wrong_state``
+:pyeval:`errors.ECODE_STATE`

   Wrong entity state. For example, live migration has been requested for
   a down instance, or instance creation on an offline node. The
   operation can be retried once the resource has changed state.
 
   Wrong entity state. For example, live migration has been requested for
   a down instance, or instance creation on an offline node. The
   operation can be retried once the resource has changed state.
 

-``unknown_entity``
+:pyeval:`errors.ECODE_NOENT`

   Entity not found. For example, information has been requested for an
   unknown instance.
 
   Entity not found. For example, information has been requested for an
   unknown instance.
 

-``already_exists``
+:pyeval:`errors.ECODE_EXISTS`

   Entity already exists. For example, instance creation has been
   requested for an already-existing instance.
 
   Entity already exists. For example, instance creation has been
   requested for an already-existing instance.
 

-``resource_not_unique``
+:pyeval:`errors.ECODE_NOTUNIQUE`

   Resource not unique (e.g. MAC or IP duplication).
 
   Resource not unique (e.g. MAC or IP duplication).
 

-``internal_error``
+:pyeval:`errors.ECODE_FAULT`

   Internal cluster error. For example, a node is unreachable but not set
   offline, or the ganeti node daemons are not working, etc. A
   ``gnt-cluster verify`` should be run.
 
   Internal cluster error. For example, a node is unreachable but not set
   offline, or the ganeti node daemons are not working, etc. A
   ``gnt-cluster verify`` should be run.
 

-``environment_error``
+:pyeval:`errors.ECODE_ENVIRON`

   Environment error (e.g. node disk error). A ``gnt-cluster verify``
   should be run.
 
   Environment error (e.g. node disk error). A ``gnt-cluster verify``
   should be run.
 

@@ -1329,8 +1251,15 @@ Manages storage units on the node.
 ``GET``
 ~~~~~~~
 
 ``GET``
 ~~~~~~~
 

+.. pyassert::
+
+   constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
+                                         constants.ST_LVM_PV,
+                                         constants.ST_LVM_VG])
+

 Requests a list of storage units on a node. Requires the parameters
 Requests a list of storage units on a node. Requires the parameters

-``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
+``storage_type`` (one of :pyeval:`constants.ST_FILE`,
+:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and

 ``output_fields``. The result will be a job id, using which the result
 can be retrieved.
 
 ``output_fields``. The result will be a job id, using which the result
 can be retrieved.
 

@@ -1343,10 +1272,11 @@ Modifies storage units on the node.
 ~~~~~~~
 
 Modifies parameters of storage units on the node. Requires the
 ~~~~~~~
 
 Modifies parameters of storage units on the node. Requires the

-parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
+parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
+:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)

 and ``name`` (name of the storage unit).  Parameters can be passed
 and ``name`` (name of the storage unit).  Parameters can be passed

-additionally. Currently only ``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.

 
 ``/2/nodes/[node_name]/storage/repair``
 +++++++++++++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/storage/repair``
 +++++++++++++++++++++++++++++++++++++++

@@ -1356,9 +1286,16 @@ Repairs a storage unit on the node.
 ``PUT``
 ~~~~~~~
 
 ``PUT``
 ~~~~~~~
 

+.. pyassert::
+
+   constants.VALID_STORAGE_OPERATIONS == {
+    constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
+    }
+

 Repairs a storage unit on the node. Requires the parameters
 Repairs a storage unit on the node. Requires the parameters

-``storage_type`` (currently only ``lvm-vg`` can be repaired) and
-``name`` (name of the storage unit). The result will be a job id.
+``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
+repaired) and ``name`` (name of the storage unit). The result will be a
+job id.

 
 ``/2/nodes/[node_name]/tags``
 +++++++++++++++++++++++++++++
 
 ``/2/nodes/[node_name]/tags``
 +++++++++++++++++++++++++++++

@@ -1399,6 +1336,50 @@ to URI like::
 It supports the ``dry-run`` argument.
 
 
 It supports the ``dry-run`` argument.
 
 

+``/2/query/[resource]``
++++++++++++++++++++++++
+
+Requests resource information. Available fields can be found in man
+pages and using ``/2/query/[resource]/fields``. The resource is one of
+:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
+design document <design-query2>` for more details.
+
+Supports the following commands: ``GET``, ``PUT``.
+
+``GET``
+~~~~~~~
+
+Returns list of included fields and actual data. Takes a query parameter
+named "fields", containing a comma-separated list of field names. Does
+not support filtering.
+
+``PUT``
+~~~~~~~
+
+Returns list of included fields and actual data. The list of requested
+fields can either be given as the query parameter "fields" or as a body
+parameter with the same name. The optional body parameter "filter" can
+be given and must be either ``null`` or a list containing filter
+operators.
+
+
+``/2/query/[resource]/fields``
+++++++++++++++++++++++++++++++
+
+Request list of available fields for a resource. The resource is one of
+:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
+:doc:`query2 design document <design-query2>` for more details.
+
+Supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns a list of field descriptions for available fields. Takes an
+optional query parameter named "fields", containing a comma-separated
+list of field names.
+
+

 ``/2/os``
 +++++++++
 
 ``/2/os``
 +++++++++