Ganeti remote API
=================
-Documents Ganeti version 2.0
+Documents Ganeti version |version|
.. contents::
.. _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.
+
+``force``
++++++++++++
+
+Force operation to continue even if it will cause the cluster to become
+inconsistent (e.g. because there are not enough master candidates).
+
Usage examples
--------------
Shell
+++++
+.. highlight:: sh
+
Using wget::
- wget -q -O - https://CLUSTERNAME:5080/2/info
+ wget -q -O - https://CLUSTERNAME:5080/2/info
or curl::
Python
++++++
-::
+.. highlight: python
import urllib2
- f = urllib2.urlopen('https://CLUSTERNAME:5080/info')
+ f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
print f.read()
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
::
- var url = 'https://CLUSTERNAME:5080/info';
+ var url = 'https://CLUSTERNAME:5080/2/info';
var info;
var xmlreq = new XMLHttpRequest();
xmlreq.onreadystatechange = function () {
Resources
---------
-/
-+
-
-::
-
- / resource.
-
-It supports the following commands: GET.
-
-GET
-~~~
+.. highlight:: javascript
-::
-
- Show the list of mapped resources.
+``/``
++++++
- Returns: a dictionary with 'name' and 'uri' keys for each of them.
+The root resource.
-/2
-++
+It supports the following commands: ``GET``.
-::
+``GET``
+~~~~~~~
- /2 resource, the root of the version 2 API.
+Shows the list of mapped resources.
-It supports the following commands: GET.
+Returns: a dictionary with 'name' and 'uri' keys for each of them.
-GET
-~~~
+``/2``
+++++++
-::
+The ``/2`` resource, the root of the version 2 API.
- Show the list of mapped resources.
+It supports the following commands: ``GET``.
- Returns: a dictionary with 'name' and 'uri' keys for each of them.
+``GET``
+~~~~~~~
-/2/info
-+++++++
+Show the list of mapped resources.
-::
+Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
- Cluster info.
+``/2/info``
++++++++++++
-It supports the following commands: GET.
+Cluster information resource.
-GET
-~~~
+It supports the following commands: ``GET``.
-::
+``GET``
+~~~~~~~
- Returns cluster information.
+Returns cluster information.
- Example::
+Example::
{
"config_version": 2000000,
}
}
-/2/instances
-++++++++++++
-::
+``/2/redistribute-config``
+++++++++++++++++++++++++++
- /2/instances resource.
+Redistribute configuration to all nodes.
-It supports the following commands: GET, POST.
+It supports the following commands: ``PUT``.
-GET
-~~~
+``PUT``
+~~~~~~~
-::
+Redistribute configuration to all nodes. The result will be a job id.
+
+
+``/2/instances``
+++++++++++++++++
- Returns a list of all available instances.
+The instances resource.
+It supports the following commands: ``GET``, ``POST``.
- Example::
+``GET``
+~~~~~~~
+
+Returns a list of all available instances.
+
+Example::
[
{
}
]
- If the optional 'bulk' argument is provided and set to 'true'
- value (i.e '?bulk=1'), the output contains detailed
- information about instances as a list.
+If the optional *bulk* argument is provided and set to a true value
+(i.e ``?bulk=1``), the output contains detailed information about
+instances as a list.
- Example::
+Example::
[
{
...
]
- Returns: a dictionary with 'name' and 'uri' keys for each of them.
-POST
-~~~~
+``POST``
+~~~~~~~~
-::
+Creates an instance.
- Create 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
+Returns: a job ID that can be used later for polling.
-/2/instances/[instance_name]
-++++++++++++++++++++++++++++
+``/2/instances/[instance_name]``
+++++++++++++++++++++++++++++++++
-::
+Instance-specific resource.
- /2/instances/[instance_name] resources.
+It supports the following commands: ``GET``, ``DELETE``.
-It supports the following commands: GET, DELETE.
+``GET``
+~~~~~~~
-GET
-~~~
+Returns information about an instance, similar to the bulk output from
+the instance list.
-::
+``DELETE``
+~~~~~~~~~~
- Send information about an instance.
+Deletes an instance.
+It supports the ``dry-run`` argument.
-DELETE
-~~~~~~
+``/2/instances/[instance_name]/info``
++++++++++++++++++++++++++++++++++++++++
-::
+It supports the following commands: ``GET``.
- Delete an instance.
+``GET``
+~~~~~~~
+Requests detailed information about the instance. An optional parameter,
+``static`` (bool), can be set to return only static information from the
+configuration without querying the instance's nodes. The result will be
+a job id.
-/2/instances/[instance_name]/reboot
-+++++++++++++++++++++++++++++++++++
+``/2/instances/[instance_name]/reboot``
++++++++++++++++++++++++++++++++++++++++
-::
+Reboots URI for an instance.
- /2/instances/[instance_name]/reboot resource.
+It supports the following commands: ``POST``.
- Implements an instance reboot.
+``POST``
+~~~~~~~~
-It supports the following commands: POST.
+Reboots the instance.
-POST
-~~~~
+The URI takes optional ``type=hard|soft|full`` and
+``ignore_secondaries=False|True`` parameters.
-::
+It supports the ``dry-run`` argument.
- Reboot an instance.
- The URI takes type=[hard|soft|full] and
- ignore_secondaries=[False|True] parameters.
+``/2/instances/[instance_name]/shutdown``
++++++++++++++++++++++++++++++++++++++++++
-/2/instances/[instance_name]/shutdown
-+++++++++++++++++++++++++++++++++++++
+Instance shutdown URI.
-::
+It supports the following commands: ``PUT``.
- /2/instances/[instance_name]/shutdown resource.
+``PUT``
+~~~~~~~
- Implements an instance shutdown.
+Shutdowns an instance.
-It supports the following commands: PUT.
+It supports the ``dry-run`` argument.
-PUT
-~~~
-::
+``/2/instances/[instance_name]/startup``
+++++++++++++++++++++++++++++++++++++++++
- Shutdown an instance.
+Instance startup URI.
+It supports the following commands: ``PUT``.
+``PUT``
+~~~~~~~
-/2/instances/[instance_name]/startup
-++++++++++++++++++++++++++++++++++++
+Startup an instance.
-::
+The URI takes an optional ``force=False|True`` parameter to start the
+instance if even if secondary disks are failing.
- /2/instances/[instance_name]/startup resource.
+It supports the ``dry-run`` argument.
- Implements an instance startup.
+``/2/instances/[instance_name]/reinstall``
+++++++++++++++++++++++++++++++++++++++++++++++
-It supports the following commands: PUT.
+Installs the operating system again.
-PUT
-~~~
+It supports the following commands: ``POST``.
-::
+``POST``
+~~~~~~~~
- Startup an instance.
+Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
- The URI takes force=[False|True] parameter to start the instance
- if even if secondary disks are failing.
-/2/instances/[instance_name]/tags
-+++++++++++++++++++++++++++++++++
+``/2/instances/[instance_name]/replace-disks``
+++++++++++++++++++++++++++++++++++++++++++++++
-::
+Replaces disks on an instance.
- /2/instances/[instance_name]/tags resource.
+It supports the following commands: ``POST``.
- Manages per-instance tags.
+``POST``
+~~~~~~~~
-It supports the following commands: GET, PUT, DELETE.
+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``.
-GET
-~~~
-::
+``/2/instances/[instance_name]/tags``
++++++++++++++++++++++++++++++++++++++
- Returns a list of tags.
+Manages per-instance tags.
- Example: ["tag1", "tag2", "tag3"]
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
-PUT
-~~~
+``GET``
+~~~~~~~
-::
+Returns a list of tags.
- Add a set of tags.
+Example::
- The request as a list of strings should be PUT to this URI. And
- you'll have back a job id.
+ ["tag1", "tag2", "tag3"]
-DELETE
-~~~~~~
+``PUT``
+~~~~~~~
-::
+Add a set of tags.
- Delete a tag.
+The request as a list of strings should be ``PUT`` to this URI. The
+result will be a job id.
- 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/jobs
-+++++++
-::
+``DELETE``
+~~~~~~~~~~
- /2/jobs resource.
+Delete a tag.
-It supports the following commands: GET.
+In order to delete a set of tags, the DELETE request should be
+addressed to URI like::
-GET
-~~~
+ /tags?tag=[tag]&tag=[tag]
-::
+It supports the ``dry-run`` argument.
- Returns a dictionary of jobs.
- Returns: a dictionary with jobs id and uri.
+``/2/jobs``
++++++++++++
-/2/jobs/[job_id]
-++++++++++++++++
+The ``/2/jobs`` resource.
-::
+It supports the following commands: ``GET``.
- /2/jobs/[job_id] resource.
+``GET``
+~~~~~~~
-It supports the following commands: GET, DELETE.
+Returns a dictionary of jobs.
-GET
-~~~
+Returns: a dictionary with jobs id and uri.
-::
+``/2/jobs/[job_id]``
+++++++++++++++++++++
- Returns a job status.
- Returns: a dictionary with job parameters.
- The result includes:
- - id: job ID as a number
- - status: current job status as a string
- - ops: involved OpCodes as a list of dictionaries for each
- opcodes in the job
- - opstatus: OpCodes status as a list
- - opresult: OpCodes results as a list of lists
+Individual job URI.
-DELETE
-~~~~~~
+It supports the following commands: ``GET``, ``DELETE``.
-::
+``GET``
+~~~~~~~
- Cancel not-yet-started job.
+Returns a job status.
+Returns: a dictionary with job parameters.
+The result includes:
-/2/nodes
-++++++++
+- id: job ID as a number
+- status: current job status as a string
+- ops: involved OpCodes as a list of dictionaries for each
+ opcodes in the job
+- opstatus: OpCodes status as a list
+- opresult: OpCodes results as a list of lists
-::
+``DELETE``
+~~~~~~~~~~
- /2/nodes resource.
+Cancel a not-yet-started job.
-It supports the following commands: GET.
+``/2/nodes``
+++++++++++++
-GET
-~~~
+Nodes resource.
-::
+It supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
- Returns a list of all nodes.
+Returns a list of all nodes.
- Example::
+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 'bulk' argument is provided and set to 'true' value
+(i.e '?bulk=1'), the output contains detailed information about nodes
+as a list.
- Example::
+Example::
[
{
...
]
- Returns: a dictionary with 'name' and 'uri' keys for each of them
+``/2/nodes/[node_name]``
++++++++++++++++++++++++++++++++++
-/2/nodes/[node_name]/tags
-+++++++++++++++++++++++++
+Returns information about a node.
-::
+It supports the following commands: ``GET``.
- /2/nodes/[node_name]/tags resource.
+``/2/nodes/[node_name]/evacuate``
++++++++++++++++++++++++++++++++++
- Manages per-node tags.
+Evacuates all secondary instances off a node.
-It supports the following commands: GET, PUT, DELETE.
+It supports the following commands: ``POST``.
-GET
-~~~
+``POST``
+~~~~~~~~
-::
+To evacuate a node, either one of the ``iallocator`` or ``remote_node``
+parameters must be passed:
- Returns a list of tags.
+ evacuate?iallocator=[iallocator]
+ evacuate?remote_node=[nodeX.example.com]
- Example: ["tag1", "tag2", "tag3"]
+``/2/nodes/[node_name]/migrate``
++++++++++++++++++++++++++++++++++
-PUT
-~~~
+Migrates all primary instances from a node.
-::
+It supports the following commands: ``POST``.
- Add a set of tags.
+``POST``
+~~~~~~~~
- The request as a list of strings should be PUT to this URI. And
- you'll have back a job id.
+No parameters are required, but ``live`` can be set to a boolean value.
-DELETE
-~~~~~~
+ migrate?live=[0|1]
-::
+``/2/nodes/[node_name]/role``
++++++++++++++++++++++++++++++
- Delete a tag.
+Manages node role.
- 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 following commands: ``GET``, ``PUT``.
-/2/os
-+++++
+The role is always one of the following:
-::
+ - drained
+ - master
+ - master-candidate
+ - offline
+ - regular
- /2/os resource.
+``GET``
+~~~~~~~
-It supports the following commands: GET.
+Returns the current node role.
-GET
-~~~
+Example::
-::
+ "master-candidate"
- Return a list of all OSes.
+``PUT``
+~~~~~~~
- Can return error 500 in case of a problem.
+Change the node role.
- Example: ["debian-etch"]
+The request is a string which should be PUT to this URI. The result will
+be a job id.
-/2/tags
-+++++++
+It supports the ``force`` argument.
-::
+``/2/nodes/[node_name]/storage``
+++++++++++++++++++++++++++++++++
- /2/instances/tags resource.
+Manages storage units on the node.
- Manages cluster tags.
+``GET``
+~~~~~~~
-It supports the following commands: GET, PUT, DELETE.
+Requests a list of storage units on a node. Requires the parameters
+``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
+``output_fields``. The result will be a job id, using which the result
+can be retrieved.
-GET
-~~~
+``/2/nodes/[node_name]/storage/modify``
++++++++++++++++++++++++++++++++++++++++
-::
+Modifies storage units on the node.
- Returns a list of tags.
+``PUT``
+~~~~~~~
- Example: ["tag1", "tag2", "tag3"]
+Modifies parameters of storage units on the node. Requires the
+parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
+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.
-PUT
-~~~
+``/2/nodes/[node_name]/storage/repair``
++++++++++++++++++++++++++++++++++++++++
-::
+Repairs a storage unit on the node.
- Add a set of tags.
+``PUT``
+~~~~~~~
- The request as a list of strings should be PUT to this URI. And
- you'll have back a job id.
+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.
-DELETE
-~~~~~~
+``/2/nodes/[node_name]/tags``
++++++++++++++++++++++++++++++
-::
+Manages per-node tags.
- Delete a tag.
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
- In order to delete a set of tags, the DELETE
- request should be addressed to URI like:
- /tags?tag=[tag]&tag=[tag]
+``GET``
+~~~~~~~
-/nodes/[node_name]
-++++++++++++++++++
+Returns a list of tags.
-::
+Example::
- /2/nodes/[node_name] resources.
+ ["tag1", "tag2", "tag3"]
-It supports the following commands: GET.
+``PUT``
+~~~~~~~
-GET
-~~~
+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.
- Send information about a node.
+It supports the ``dry-run`` argument.
+``DELETE``
+~~~~~~~~~~
+Deletes tags.
-/version
-++++++++
+In order to delete a set of tags, the DELETE request should be
+addressed to URI like::
-::
+ /tags?tag=[tag]&tag=[tag]
- /version resource.
+It supports the ``dry-run`` argument.
- This resource should be used to determine the remote API version and
- to adapt clients accordingly.
-It supports the following commands: GET.
+``/2/os``
++++++++++
-GET
-~~~
+OS resource.
-::
+It supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Return a list of all OSes.
+
+Can return error 500 in case of a problem. Since this is a costly
+operation for Ganeti 2.0, it is not recommended to execute it too
+often.
+
+Example::
+
+ ["debian-etch"]
+
+``/2/tags``
++++++++++++
+
+Manages cluster tags.
+
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns the cluster tags.
+
+Example::
+
+ ["tag1", "tag2", "tag3"]
+
+``PUT``
+~~~~~~~
+
+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``
+~~~~~~~~~~
+
+Deletes tags.
+
+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.
+
+
+``/version``
+++++++++++++
+
+The version resource.
+
+This resource should be used to determine the remote API version and
+to adapt clients accordingly.
+
+It supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
+2.0 returns ``2``.
- Returns the remote API version.
+.. vim: set textwidth=72 :
projects / ganeti-local / blobdiff