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 A few parameter mean the same thing across all resources which implement
37 Bulk-mode means that for the resources which usually return just a
38 list of child resources (e.g. ``/2/instances`` which returns just
39 instance names), the output will instead contain detailed data for all
40 these subresources. This is more efficient than query-ing the
41 sub-resources themselves.
46 The optional *dry-run* argument, if provided and set to a positive
47 integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
48 should not be executed, only the pre-execution checks will be done.
50 This is useful in trying to determine (without guarantees though, as
51 in the meantime the cluster state could have changed) if the operation
52 is likely to succeed or at least start executing.
57 Force operation to continue even if it will cause the cluster to become
58 inconsistent (e.g. because there are not enough master candidates).
63 You can access the API using your favorite programming language as
64 long as it supports network connections.
73 wget -q -O - https://CLUSTERNAME:5080/2/info
77 curl https://CLUSTERNAME:5080/2/info
86 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
93 .. warning:: While it's possible to use JavaScript, it poses several
94 potential problems, including browser blocking request due to
95 non-standard ports or different domain names. Fetching the data on
96 the webserver is easier.
98 .. highlight:: javascript
102 var url = 'https://CLUSTERNAME:5080/2/info';
104 var xmlreq = new XMLHttpRequest();
105 xmlreq.onreadystatechange = function () {
106 if (xmlreq.readyState != 4) return;
107 if (xmlreq.status == 200) {
108 info = eval("(" + xmlreq.responseText + ")");
111 alert('Error fetching cluster info');
115 xmlreq.open('GET', url, true);
121 .. highlight:: javascript
128 It supports the following commands: ``GET``.
133 Shows the list of mapped resources.
135 Returns: a dictionary with 'name' and 'uri' keys for each of them.
140 The ``/2`` resource, the root of the version 2 API.
142 It supports the following commands: ``GET``.
147 Show the list of mapped resources.
149 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
154 Cluster information resource.
156 It supports the following commands: ``GET``.
161 Returns cluster information.
166 "config_version": 2000000,
168 "software_version": "2.0.0~beta2",
169 "os_api_version": 10,
171 "candidate_pool_size": 10,
172 "enabled_hypervisors": [
178 "default_hypervisor": "fake",
179 "master": "node1.example.com",
184 "protocol_version": 20,
187 "auto_balance": true,
195 ``/2/redistribute-config``
196 ++++++++++++++++++++++++++
198 Redistribute configuration to all nodes.
200 It supports the following commands: ``PUT``.
205 Redistribute configuration to all nodes. The result will be a job id.
211 The instances resource.
213 It supports the following commands: ``GET``, ``POST``.
218 Returns a list of all available instances.
224 "name": "web.example.com",
225 "uri": "\/instances\/web.example.com"
228 "name": "mail.example.com",
229 "uri": "\/instances\/mail.example.com"
233 If the optional *bulk* argument is provided and set to a true value
234 (i.e ``?bulk=1``), the output contains detailed information about
246 "name": "web.example.com",
247 "tags": ["tag1", "tag2"],
255 "pnode": "node1.example.com",
256 "nic.macs": ["01:23:45:67:89:01"],
257 "snodes": ["node2.example.com"],
258 "disk_template": "drbd",
272 If the optional *dry-run* argument is provided and set to a positive
273 integer valu (e.g. ``?dry-run=1``), the job will not be actually
274 executed, only the pre-execution checks will be done. Query-ing the
275 job result will return, in both dry-run and normal case, the list of
276 nodes selected for the instance.
278 Returns: a job ID that can be used later for polling.
280 ``/2/instances/[instance_name]``
281 ++++++++++++++++++++++++++++++++
283 Instance-specific resource.
285 It supports the following commands: ``GET``, ``DELETE``.
290 Returns information about an instance, similar to the bulk output from
298 It supports the ``dry-run`` argument.
301 ``/2/instances/[instance_name]/info``
302 +++++++++++++++++++++++++++++++++++++++
304 It supports the following commands: ``GET``.
309 Requests detailed information about the instance. An optional parameter,
310 ``static`` (bool), can be set to return only static information from the
311 configuration without querying the instance's nodes. The result will be
315 ``/2/instances/[instance_name]/reboot``
316 +++++++++++++++++++++++++++++++++++++++
318 Reboots URI for an instance.
320 It supports the following commands: ``POST``.
325 Reboots the instance.
327 The URI takes optional ``type=hard|soft|full`` and
328 ``ignore_secondaries=False|True`` parameters.
330 It supports the ``dry-run`` argument.
333 ``/2/instances/[instance_name]/shutdown``
334 +++++++++++++++++++++++++++++++++++++++++
336 Instance shutdown URI.
338 It supports the following commands: ``PUT``.
343 Shutdowns an instance.
345 It supports the ``dry-run`` argument.
348 ``/2/instances/[instance_name]/startup``
349 ++++++++++++++++++++++++++++++++++++++++
351 Instance startup URI.
353 It supports the following commands: ``PUT``.
360 The URI takes an optional ``force=False|True`` parameter to start the
361 instance if even if secondary disks are failing.
363 It supports the ``dry-run`` argument.
365 ``/2/instances/[instance_name]/reinstall``
366 ++++++++++++++++++++++++++++++++++++++++++++++
368 Installs the operating system again.
370 It supports the following commands: ``POST``.
375 Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
378 ``/2/instances/[instance_name]/replace-disks``
379 ++++++++++++++++++++++++++++++++++++++++++++++
381 Replaces disks on an instance.
383 It supports the following commands: ``POST``.
388 Takes the parameters ``mode`` (one of ``replace_on_primary``,
389 ``replace_on_secondary``, ``replace_new_secondary`` or
390 ``replace_auto``), ``disks`` (comma separated list of disk indexes),
391 ``remote_node`` and ``iallocator``.
394 ``/2/instances/[instance_name]/tags``
395 +++++++++++++++++++++++++++++++++++++
397 Manages per-instance tags.
399 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
404 Returns a list of tags.
408 ["tag1", "tag2", "tag3"]
415 The request as a list of strings should be ``PUT`` to this URI. The
416 result will be a job id.
418 It supports the ``dry-run`` argument.
426 In order to delete a set of tags, the DELETE request should be
427 addressed to URI like::
429 /tags?tag=[tag]&tag=[tag]
431 It supports the ``dry-run`` argument.
437 The ``/2/jobs`` resource.
439 It supports the following commands: ``GET``.
444 Returns a dictionary of jobs.
446 Returns: a dictionary with jobs id and uri.
454 It supports the following commands: ``GET``, ``DELETE``.
459 Returns a job status.
461 Returns: a dictionary with job parameters.
465 - id: job ID as a number
466 - status: current job status as a string
467 - ops: involved OpCodes as a list of dictionaries for each
469 - opstatus: OpCodes status as a list
470 - opresult: OpCodes results as a list of lists
475 Cancel a not-yet-started job.
482 It supports the following commands: ``GET``.
487 Returns a list of all nodes.
493 "id": "node1.example.com",
494 "uri": "\/instances\/node1.example.com"
497 "id": "node2.example.com",
498 "uri": "\/instances\/node2.example.com"
502 If the optional 'bulk' argument is provided and set to 'true' value
503 (i.e '?bulk=1'), the output contains detailed information about nodes
513 "name": "www.example.com",
524 ``/2/nodes/[node_name]``
525 +++++++++++++++++++++++++++++++++
527 Returns information about a node.
529 It supports the following commands: ``GET``.
531 ``/2/nodes/[node_name]/evacuate``
532 +++++++++++++++++++++++++++++++++
534 Evacuates all secondary instances off a node.
536 It supports the following commands: ``POST``.
541 To evacuate a node, either one of the ``iallocator`` or ``remote_node``
542 parameters must be passed:
544 evacuate?iallocator=[iallocator]
545 evacuate?remote_node=[nodeX.example.com]
547 ``/2/nodes/[node_name]/migrate``
548 +++++++++++++++++++++++++++++++++
550 Migrates all primary instances from a node.
552 It supports the following commands: ``POST``.
557 No parameters are required, but ``live`` can be set to a boolean value.
561 ``/2/nodes/[node_name]/role``
562 +++++++++++++++++++++++++++++
566 It supports the following commands: ``GET``, ``PUT``.
568 The role is always one of the following:
579 Returns the current node role.
588 Change the node role.
590 The request is a string which should be PUT to this URI. The result will
593 It supports the ``force`` argument.
595 ``/2/nodes/[node_name]/storage``
596 ++++++++++++++++++++++++++++++++
598 Manages storage units on the node.
603 Requests a list of storage units on a node. Requires the parameters
604 ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
605 ``output_fields``. The result will be a job id, using which the result
608 ``/2/nodes/[node_name]/storage/modify``
609 +++++++++++++++++++++++++++++++++++++++
611 Modifies storage units on the node.
616 Modifies parameters of storage units on the node. Requires the
617 parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
618 and ``name`` (name of the storage unit). Parameters can be passed
619 additionally. Currently only ``allocatable`` (bool) is supported. The
620 result will be a job id.
622 ``/2/nodes/[node_name]/storage/repair``
623 +++++++++++++++++++++++++++++++++++++++
625 Repairs a storage unit on the node.
630 Repairs a storage unit on the node. Requires the parameters
631 ``storage_type`` (currently only ``lvm-vg`` can be repaired) and
632 ``name`` (name of the storage unit). The result will be a job id.
634 ``/2/nodes/[node_name]/tags``
635 +++++++++++++++++++++++++++++
637 Manages per-node tags.
639 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
644 Returns a list of tags.
648 ["tag1", "tag2", "tag3"]
655 The request as a list of strings should be PUT to this URI. The result
658 It supports the ``dry-run`` argument.
665 In order to delete a set of tags, the DELETE request should be
666 addressed to URI like::
668 /tags?tag=[tag]&tag=[tag]
670 It supports the ``dry-run`` argument.
678 It supports the following commands: ``GET``.
683 Return a list of all OSes.
685 Can return error 500 in case of a problem. Since this is a costly
686 operation for Ganeti 2.0, it is not recommended to execute it too
696 Manages cluster tags.
698 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
703 Returns the cluster tags.
707 ["tag1", "tag2", "tag3"]
714 The request as a list of strings should be PUT to this URI. The result
717 It supports the ``dry-run`` argument.
725 In order to delete a set of tags, the DELETE request should be
726 addressed to URI like::
728 /tags?tag=[tag]&tag=[tag]
730 It supports the ``dry-run`` argument.
736 The version resource.
738 This resource should be used to determine the remote API version and
739 to adapt clients accordingly.
741 It supports the following commands: ``GET``.
746 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
749 .. vim: set textwidth=72 :