Commit 2cad4b91 authored by Iustin Pop's avatar Iustin Pop
Browse files

Update RAPI docs for the dry-run mode


Signed-off-by: default avatarIustin Pop <iustin@google.com>
Reviewed-by: default avatarGuido Trotter <ultrotter@google.com>
parent 6f59b964
......@@ -25,6 +25,31 @@ principle.
.. _JSON: http://www.json.org/
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
Generic parameters
------------------
A few parameter mean the same thing across all resources which implement it.
``bulk``
++++++++
Bulk-mode means that for the resources which usually return just a
list of child resources (e.g. ``/2/instances`` which returns just
instance names), the output will instead contain detailed data for all
these subresources. This is more efficient than query-ing the
sub-resources themselves.
``dry-run``
+++++++++++
The optional *dry-run* argument, if provided and set to a positive
integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
should not be executed, only the pre-execution checks will be done.
This is useful in trying to determine (without guarantees though, as
in the meantime the cluster state could have changed) if the operation
is likely to succeed or at least start executing.
Usage examples
--------------
......@@ -58,10 +83,10 @@ Python
JavaScript
++++++++++
.. warning:: While it's possible to use JavaScript, it poses several potential
problems, including browser blocking request due to
non-standard ports or different domain names. Fetching the data
on the webserver is easier.
.. warning:: While it's possible to use JavaScript, it poses several
potential problems, including browser blocking request due to
non-standard ports or different domain names. Fetching the data on
the webserver is easier.
.. highlight:: javascript
......@@ -171,7 +196,6 @@ It supports the following commands: ``GET``, ``POST``.
Returns a list of all available instances.
Example::
[
......@@ -224,6 +248,12 @@ Example::
Creates an instance.
If the optional *dry-run* argument is provided and set to a positive
integer valu (e.g. ``?dry-run=1``), the job will not be actually
executed, only the pre-execution checks will be done. Query-ing the
job result will return, in both dry-run and normal case, the list of
nodes selected for the instance.
Returns: a job ID that can be used later for polling.
``/2/instances/[instance_name]``
......@@ -244,6 +274,8 @@ the instance list.
Deletes an instance.
It supports the ``dry-run`` argument.
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
......@@ -260,6 +292,9 @@ Reboots the instance.
The URI takes optional ``type=hard|soft|full`` and
``ignore_secondaries=False|True`` parameters.
It supports the ``dry-run`` argument.
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
......@@ -272,6 +307,8 @@ It supports the following commands: ``PUT``.
Shutdowns an instance.
It supports the ``dry-run`` argument.
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
......@@ -288,6 +325,9 @@ Startup an instance.
The URI takes an optional ``force=False|True`` parameter to start the
instance if even if secondary disks are failing.
It supports the ``dry-run`` argument.
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
......@@ -312,6 +352,9 @@ Add a set of tags.
The request as a list of strings should be ``PUT`` to this URI. The
result willl be a job id.
It supports the ``dry-run`` argument.
``DELETE``
~~~~~~~~~~
......@@ -322,6 +365,9 @@ addressed to URI like::
/tags?tag=[tag]&tag=[tag]
It supports the ``dry-run`` argument.
``/2/jobs``
+++++++++++
......@@ -436,6 +482,8 @@ 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``
~~~~~~~~~~
......@@ -446,6 +494,9 @@ addressed to URI like::
/tags?tag=[tag]&tag=[tag]
It supports the ``dry-run`` argument.
``/2/os``
+++++++++
......@@ -490,6 +541,9 @@ Adds 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``
~~~~~~~~~~
......@@ -500,6 +554,9 @@ addressed to URI like::
/tags?tag=[tag]&tag=[tag]
It supports the ``dry-run`` argument.
``/version``
++++++++++++
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment