4 Documents Ganeti version |version|
11 Ganeti supports a remote API for enable external tools to easily
12 retrieve information about a cluster's state. The remote API daemon,
13 *ganeti-rapi*, is automatically started on the master node. By default
14 it runs on TCP port 5080, but this can be changed either in
15 ``.../constants.py`` or via the command line parameter *-p*. SSL mode,
16 which is used by default, can also be disabled by passing command line
22 The protocol used is JSON_ over HTTP designed after the REST_
25 .. _JSON: http://www.json.org/
26 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
31 You can access the API using your favorite programming language as
32 long as it supports network connections.
41 wget -q -O - https://CLUSTERNAME:5080/2/info
45 curl https://CLUSTERNAME:5080/2/info
54 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
61 .. warning:: While it's possible to use JavaScript, it poses several potential
62 problems, including browser blocking request due to
63 non-standard ports or different domain names. Fetching the data
64 on the webserver is easier.
66 .. highlight:: javascript
70 var url = 'https://CLUSTERNAME:5080/2/info';
72 var xmlreq = new XMLHttpRequest();
73 xmlreq.onreadystatechange = function () {
74 if (xmlreq.readyState != 4) return;
75 if (xmlreq.status == 200) {
76 info = eval("(" + xmlreq.responseText + ")");
79 alert('Error fetching cluster info');
83 xmlreq.open('GET', url, true);
89 .. highlight:: javascript
96 It supports the following commands: ``GET``.
101 Shows the list of mapped resources.
103 Returns: a dictionary with 'name' and 'uri' keys for each of them.
108 The ``/2`` resource, the root of the version 2 API.
110 It supports the following commands: ``GET``.
115 Show the list of mapped resources.
117 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
122 Cluster information resource.
124 It supports the following commands: ``GET``.
129 Returns cluster information.
134 "config_version": 2000000,
136 "software_version": "2.0.0~beta2",
137 "os_api_version": 10,
139 "candidate_pool_size": 10,
140 "enabled_hypervisors": [
146 "default_hypervisor": "fake",
147 "master": "node1.example.com",
152 "protocol_version": 20,
155 "auto_balance": true,
165 The instances resource.
167 It supports the following commands: ``GET``, ``POST``.
172 Returns a list of all available instances.
179 "name": "web.example.com",
180 "uri": "\/instances\/web.example.com"
183 "name": "mail.example.com",
184 "uri": "\/instances\/mail.example.com"
188 If the optional *bulk* argument is provided and set to a true value
189 (i.e ``?bulk=1``), the output contains detailed information about
201 "name": "web.example.com",
202 "tags": ["tag1", "tag2"],
210 "pnode": "node1.example.com",
211 "nic.macs": ["01:23:45:67:89:01"],
212 "snodes": ["node2.example.com"],
213 "disk_template": "drbd",
227 Returns: a job ID that can be used later for polling.
229 ``/2/instances/[instance_name]``
230 ++++++++++++++++++++++++++++++++
232 Instance-specific resource.
234 It supports the following commands: ``GET``, ``DELETE``.
239 Returns information about an instance, similar to the bulk output from
248 ``/2/instances/[instance_name]/reboot``
249 +++++++++++++++++++++++++++++++++++++++
251 Reboots URI for an instance.
253 It supports the following commands: ``POST``.
258 Reboots the instance.
260 The URI takes optional ``type=hard|soft|full`` and
261 ``ignore_secondaries=False|True`` parameters.
263 ``/2/instances/[instance_name]/shutdown``
264 +++++++++++++++++++++++++++++++++++++++++
266 Instance shutdown URI.
268 It supports the following commands: ``PUT``.
273 Shutdowns an instance.
276 ``/2/instances/[instance_name]/startup``
277 ++++++++++++++++++++++++++++++++++++++++
279 Instance startup URI.
281 It supports the following commands: ``PUT``.
288 The URI takes an optional ``force=False|True`` parameter to start the
289 instance if even if secondary disks are failing.
291 ``/2/instances/[instance_name]/tags``
292 +++++++++++++++++++++++++++++++++++++
294 Manages per-instance tags.
296 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
301 Returns a list of tags.
305 ["tag1", "tag2", "tag3"]
312 The request as a list of strings should be ``PUT`` to this URI. The
313 result willl be a job id.
320 In order to delete a set of tags, the DELETE request should be
321 addressed to URI like::
323 /tags?tag=[tag]&tag=[tag]
328 The ``/2/jobs`` resource.
330 It supports the following commands: ``GET``.
335 Returns a dictionary of jobs.
337 Returns: a dictionary with jobs id and uri.
345 It supports the following commands: ``GET``, ``DELETE``.
350 Returns a job status.
352 Returns: a dictionary with job parameters.
356 - id: job ID as a number
357 - status: current job status as a string
358 - ops: involved OpCodes as a list of dictionaries for each
360 - opstatus: OpCodes status as a list
361 - opresult: OpCodes results as a list of lists
366 Cancel a not-yet-started job.
373 It supports the following commands: ``GET``.
378 Returns a list of all nodes.
384 "id": "node1.example.com",
385 "uri": "\/instances\/node1.example.com"
388 "id": "node2.example.com",
389 "uri": "\/instances\/node2.example.com"
393 If the optional 'bulk' argument is provided and set to 'true' value
394 (i.e '?bulk=1'), the output contains detailed information about nodes
404 "name": "www.example.com",
415 ``/2/nodes/[node_name]/tags``
416 +++++++++++++++++++++++++++++
418 Manages per-node tags.
420 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
425 Returns a list of tags.
429 ["tag1", "tag2", "tag3"]
436 The request as a list of strings should be PUT to this URI. The result
444 In order to delete a set of tags, the DELETE request should be
445 addressed to URI like::
447 /tags?tag=[tag]&tag=[tag]
454 It supports the following commands: ``GET``.
459 Return a list of all OSes.
461 Can return error 500 in case of a problem. Since this is a costly
462 operation for Ganeti 2.0, it is not recommended to execute it too
472 Manages cluster tags.
474 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
479 Returns the cluster tags.
483 ["tag1", "tag2", "tag3"]
490 The request as a list of strings should be PUT to this URI. The result
498 In order to delete a set of tags, the DELETE request should be
499 addressed to URI like::
501 /tags?tag=[tag]&tag=[tag]
506 The version resource.
508 This resource should be used to determine the remote API version and
509 to adapt clients accordingly.
511 It supports the following commands: ``GET``.
516 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti