.. [#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
.. _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
++++++++++++++++++++++++++++++
Returns a list of features supported by the RAPI server. Available
features:
-``instance-create-reqv1``
+.. 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.
-``instance-reinstall-reqv1``
+: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``
(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::
[
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``
~~~~~~~~~~
.. opcode_params:: OP_GROUP_SET_PARAMS
:exclude: group_name
+Job result:
+
+.. opcode_result:: OP_GROUP_SET_PARAMS
+
``/2/groups/[group_name]/rename``
+++++++++++++++++++++++++++++++++
.. opcode_params:: OP_GROUP_RENAME
:exclude: group_name
+Job result:
+
+.. opcode_result:: OP_GROUP_RENAME
+
``/2/groups/[group_name]/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``
++++++++++++++++
(i.e ``?bulk=1``), the output contains detailed information about
instances as a list.
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
+
Example::
[
``__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 and should no longer be used).
+ instance creation requests, version ``0``, but that format is no
+ longer supported)
.. opcode_params:: OP_INSTANCE_CREATE
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]``
++++++++++++++++++++++++++++++++
Returns information about an instance, similar to the bulk output from
the instance list.
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
+
``DELETE``
~~~~~~~~~~
It supports the ``dry-run`` argument.
+.. opcode_params:: OP_INSTANCE_SHUTDOWN
+ :exclude: instance_name, dry_run
+
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
:exclude: instance_name, live
+``/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
+
+
``/2/instances/[instance_name]/rename``
++++++++++++++++++++++++++++++++++++++++
.. opcode_params:: OP_INSTANCE_RENAME
:exclude: instance_name
+Job result:
+
+.. opcode_result:: OP_INSTANCE_RENAME
+
``/2/instances/[instance_name]/modify``
++++++++++++++++++++++++++++++++++++++++
.. opcode_params:: OP_INSTANCE_SET_PARAMS
:exclude: instance_name
+Job result:
+
+.. opcode_result:: OP_INSTANCE_SET_PARAMS
+
``/2/instances/[instance_name]/console``
++++++++++++++++++++++++++++++++++++++++
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,
+ ])
+
``instance``
Instance name.
``kind``
- Console type, one of ``ssh``, ``vnc`` or ``msg``.
+ Console type, one of :pyeval:`constants.CONS_SSH`,
+ :pyeval:`constants.CONS_VNC` 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` and
+ :pyeval:`constants.CONS_VNC` only).
``port``
- TCP port to connect to (``vnc`` only).
+ TCP port to connect to (:pyeval:`constants.CONS_VNC` 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``
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]``
++++++++++++++++++++
``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:
}
]
-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::
It supports the following commands: ``GET``.
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
+
``/2/nodes/[node_name]/evacuate``
+++++++++++++++++++++++++++++++++
-Evacuates all secondary instances off a node.
+Evacuates instances off a node.
It supports the following commands: ``POST``.
``POST``
~~~~~~~~
-To evacuate a node, either one of the ``iallocator`` or ``remote_node``
-parameters must be passed::
+Returns a job ID. The result of the job will contain the IDs of the
+individual jobs submitted to evacuate the node.
+
+Body parameters:
- evacuate?iallocator=[iallocator]
- evacuate?remote_node=[nodeX.example.com]
+.. opcode_params:: OP_NODE_EVACUATE
+ :exclude: nodes
-The result value will be a list, each element being a triple of the job
-id (for this specific evacuation), the instance which is being evacuated
-by this job, and the node to which it is being relocated. In case the
-node is already empty, the result will be an empty list (without any
-jobs being submitted).
+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.
-And additional parameter ``early_release`` signifies whether to try to
-parallelize the evacuations, at the risk of increasing I/O contention
-and increasing the chances of data loss, if the primary node of any of
-the instances being evacuated is not fully healthy.
+Job result:
-If the dry-run parameter was specified, then the evacuation jobs were
-not actually submitted, and the job IDs will be null.
+.. opcode_result:: OP_NODE_EVACUATE
``/2/nodes/[node_name]/migrate``
~~~~~~~~
If no mode is explicitly specified, each instances' hypervisor default
-migration mode will be used. Query parameters:
+migration mode will be used. Body parameters:
-``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.
+.. opcode_params:: OP_NODE_MIGRATE
+ :exclude: node_name
+
+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.
``/2/nodes/[node_name]/role``
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``
~~~~~~~
projects / ganeti-local / blobdiff