Ganeti remote API
=================
-Documents Ganeti version 2.0
+Documents Ganeti version |version|
.. contents::
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/2/info')
non-standard ports or different domain names. Fetching the data
on the webserver is easier.
+.. highlight:: javascript
+
::
var url = 'https://CLUSTERNAME:5080/2/info';
Resources
---------
-/
-+
-
-::
-
- / resource.
-
-It supports the following commands: GET.
+.. highlight:: javascript
-GET
-~~~
+``/``
++++++
-::
+The root resource.
- 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
-++
+Shows the list of mapped resources.
-::
+Returns: a dictionary with 'name' and 'uri' keys for each of them.
- /2 resource, the root of the version 2 API.
+``/2``
+++++++
-It supports the following commands: GET.
+The ``/2`` resource, the root of the version 2 API.
-GET
-~~~
+It supports the following commands: ``GET``.
-::
+``GET``
+~~~~~~~
- Show the list of mapped resources.
+Show the list of mapped resources.
- Returns: a dictionary with 'name' and 'uri' keys for each of them.
+Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
-/2/info
-+++++++
+``/2/info``
++++++++++++
-::
+Cluster information resource.
- Cluster info.
+It supports the following commands: ``GET``.
-It supports the following commands: GET.
+``GET``
+~~~~~~~
-GET
-~~~
+Returns cluster information.
-::
-
- Returns cluster information.
-
- Example::
+Example::
{
"config_version": 2000000,
}
}
-/2/instances
-++++++++++++
-
-::
+``/2/instances``
+++++++++++++++++
- /2/instances resource.
+The instances resource.
-It supports the following commands: GET, POST.
+It supports the following commands: ``GET``, ``POST``.
-GET
-~~~
+``GET``
+~~~~~~~
-::
+Returns a list of all available instances.
- Returns a list of all available instances.
-
- Example::
+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
-~~~~
-
-::
-
- Create an instance.
-
- Returns: a job id
-
-/2/instances/[instance_name]
-++++++++++++++++++++++++++++
-
-::
-
- /2/instances/[instance_name] resources.
-
-It supports the following commands: GET, DELETE.
-
-GET
-~~~
-
-::
-
- Send information about an instance.
-
-
-
-DELETE
-~~~~~~
-
-::
-
- Delete an instance.
-
-
-
-/2/instances/[instance_name]/reboot
-+++++++++++++++++++++++++++++++++++
-
-::
-
- /2/instances/[instance_name]/reboot resource.
-
- Implements an instance reboot.
-
-It supports the following commands: POST.
-
-POST
-~~~~
-
-::
-
- Reboot an instance.
- The URI takes type=[hard|soft|full] and
- ignore_secondaries=[False|True] parameters.
+``POST``
+~~~~~~~~
-/2/instances/[instance_name]/shutdown
-+++++++++++++++++++++++++++++++++++++
+Creates an instance.
-::
+Returns: a job ID that can be used later for polling.
- /2/instances/[instance_name]/shutdown resource.
+``/2/instances/[instance_name]``
+++++++++++++++++++++++++++++++++
- Implements an instance shutdown.
+Instance-specific resource.
-It supports the following commands: PUT.
+It supports the following commands: ``GET``, ``DELETE``.
-PUT
-~~~
+``GET``
+~~~~~~~
-::
+Returns information about an instance, similar to the bulk output from
+the instance list.
- Shutdown an instance.
+``DELETE``
+~~~~~~~~~~
+Deletes an instance.
-/2/instances/[instance_name]/startup
-++++++++++++++++++++++++++++++++++++
+``/2/instances/[instance_name]/reboot``
++++++++++++++++++++++++++++++++++++++++
-::
+Reboots URI for an instance.
- /2/instances/[instance_name]/startup resource.
+It supports the following commands: ``POST``.
- Implements an instance startup.
+``POST``
+~~~~~~~~
-It supports the following commands: PUT.
+Reboots the instance.
-PUT
-~~~
+The URI takes optional ``type=hard|soft|full`` and
+``ignore_secondaries=False|True`` parameters.
-::
+``/2/instances/[instance_name]/shutdown``
++++++++++++++++++++++++++++++++++++++++++
- Startup an instance.
+Instance shutdown URI.
- The URI takes force=[False|True] parameter to start the instance
- if even if secondary disks are failing.
+It supports the following commands: ``PUT``.
-/2/instances/[instance_name]/tags
-+++++++++++++++++++++++++++++++++
+``PUT``
+~~~~~~~
-::
+Shutdowns an instance.
- /2/instances/[instance_name]/tags resource.
- Manages per-instance tags.
+``/2/instances/[instance_name]/startup``
+++++++++++++++++++++++++++++++++++++++++
-It supports the following commands: GET, PUT, DELETE.
+Instance startup URI.
-GET
-~~~
+It supports the following commands: ``PUT``.
-::
+``PUT``
+~~~~~~~
- Returns a list of tags.
+Startup an instance.
- Example: ["tag1", "tag2", "tag3"]
+The URI takes an optional ``force=False|True`` parameter to start the
+instance if even if secondary disks are failing.
-PUT
-~~~
+``/2/instances/[instance_name]/tags``
++++++++++++++++++++++++++++++++++++++
-::
+Manages per-instance tags.
- Add a set of tags.
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
- The request as a list of strings should be PUT to this URI. And
- you'll have back a job id.
+``GET``
+~~~~~~~
-DELETE
-~~~~~~
+Returns a list of tags.
-::
+Example::
- Delete a tag.
+ ["tag1", "tag2", "tag3"]
- In order to delete a set of tags, the DELETE
- request should be addressed to URI like:
- /tags?tag=[tag]&tag=[tag]
+``PUT``
+~~~~~~~
-/2/jobs
-+++++++
+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.
- /2/jobs resource.
+``DELETE``
+~~~~~~~~~~
-It supports the following commands: GET.
+Delete a tag.
-GET
-~~~
+In order to delete a set of tags, the DELETE request should be
+addressed to URI like::
-::
+ /tags?tag=[tag]&tag=[tag]
- Returns a dictionary of jobs.
+``/2/jobs``
++++++++++++
- Returns: a dictionary with jobs id and uri.
+The ``/2/jobs`` resource.
-/2/jobs/[job_id]
-++++++++++++++++
+It supports the following commands: ``GET``.
-::
+``GET``
+~~~~~~~
- /2/jobs/[job_id] resource.
+Returns a dictionary of jobs.
-It supports the following commands: GET, DELETE.
+Returns: a dictionary with jobs id and uri.
-GET
-~~~
+``/2/jobs/[job_id]``
+++++++++++++++++++++
-::
- Returns a job status.
+Individual job URI.
- 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
+It supports the following commands: ``GET``, ``DELETE``.
-DELETE
-~~~~~~
+``GET``
+~~~~~~~
-::
+Returns a job status.
- Cancel not-yet-started job.
+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
-/2/nodes
-++++++++
+``DELETE``
+~~~~~~~~~~
-::
+Cancel a not-yet-started job.
- /2/nodes resource.
+``/2/nodes``
+++++++++++++
-It supports the following commands: GET.
+Nodes resource.
-GET
-~~~
+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]/tags
-+++++++++++++++++++++++++
-
-::
-
- /2/nodes/[node_name]/tags resource.
-
- Manages per-node tags.
-
-It supports the following commands: GET, PUT, DELETE.
-
-GET
-~~~
-
-::
-
- Returns a list of tags.
+``/2/nodes/[node_name]/tags``
++++++++++++++++++++++++++++++
- Example: ["tag1", "tag2", "tag3"]
+Manages per-node tags.
-PUT
-~~~
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
-::
+``GET``
+~~~~~~~
- Add a set of tags.
+Returns a list of tags.
- The request as a list of strings should be PUT to this URI. And
- you'll have back a job id.
+Example::
-DELETE
-~~~~~~
+ ["tag1", "tag2", "tag3"]
-::
+``PUT``
+~~~~~~~
- 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]
-
-/2/os
-+++++
+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.
- /2/os resource.
+``DELETE``
+~~~~~~~~~~
-It supports the following commands: GET.
+Deletes tags.
-GET
-~~~
+In order to delete a set of tags, the DELETE request should be
+addressed to URI like::
-::
+ /tags?tag=[tag]&tag=[tag]
- Return a list of all OSes.
+``/2/os``
++++++++++
- Can return error 500 in case of a problem.
+OS resource.
- Example: ["debian-etch"]
+It supports the following commands: ``GET``.
-/2/tags
-+++++++
+``GET``
+~~~~~~~
-::
+Return a list of all OSes.
- /2/instances/tags resource.
+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.
- Manages cluster tags.
+Example::
-It supports the following commands: GET, PUT, DELETE.
+ ["debian-etch"]
-GET
-~~~
+``/2/tags``
++++++++++++
-::
+Manages cluster tags.
- Returns a list of tags.
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
- Example: ["tag1", "tag2", "tag3"]
+``GET``
+~~~~~~~
-PUT
-~~~
+Returns the cluster tags.
-::
+Example::
- Add a set of tags.
+ ["tag1", "tag2", "tag3"]
- The request as a list of strings should be PUT to this URI. And
- you'll have back a job id.
+``PUT``
+~~~~~~~
-DELETE
-~~~~~~
+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.
- Delete a tag.
+``DELETE``
+~~~~~~~~~~
- In order to delete a set of tags, the DELETE
- request should be addressed to URI like:
- /tags?tag=[tag]&tag=[tag]
+Deletes tags.
-/nodes/[node_name]
-++++++++++++++++++
+In order to delete a set of tags, the DELETE request should be
+addressed to URI like::
-::
+ /tags?tag=[tag]&tag=[tag]
- /2/nodes/[node_name] resources.
-
-It supports the following commands: GET.
-
-GET
-~~~
-
-::
-
- Send information about a node.
-
-
-
-/version
-++++++++
-
-::
-
- /version resource.
+``/version``
+++++++++++++
- This resource should be used to determine the remote API version and
- to adapt clients accordingly.
+The version resource.
-It supports the following commands: GET.
+This resource should be used to determine the remote API version and
+to adapt clients accordingly.
-GET
-~~~
+It supports the following commands: ``GET``.
-::
+``GET``
+~~~~~~~
- Returns the remote API version.
+Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
+2.0 returns ``2``.
projects / ganeti-local / blobdiff