code.grnet.gr Git - ganeti-local/blob - doc/rapi.rst

   1 Ganeti remote API
   2 =================
   3
   4 Documents Ganeti version 2.0
   5
   6 .. contents::
   7
   8 Introduction
   9 ------------
  10
  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
  17 parameters.
  18
  19 Protocol
  20 --------
  21
  22 The protocol used is JSON_ over HTTP designed after the REST_
  23 principle.
  24
  25 .. _JSON: http://www.json.org/
  26 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
  27
  28 Usage examples
  29 --------------
  30
  31 You can access the API using your favorite programming language as
  32 long as it supports network connections.
  33
  34 Shell
  35 +++++
  36
  37 Using wget::
  38
  39   wget -q -O - https://CLUSTERNAME:5080/2/info
  40
  41 or curl::
  42
  43   curl https://CLUSTERNAME:5080/2/info
  44
  45
  46 Python
  47 ++++++
  48
  49 ::
  50
  51   import urllib2
  52   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
  53   print f.read()
  54
  55
  56 JavaScript
  57 ++++++++++
  58
  59 .. warning:: While it's possible to use JavaScript, it poses several potential
  60   problems, including browser blocking request due to
  61   non-standard ports or different domain names. Fetching the data
  62   on the webserver is easier.
  63
  64 ::
  65
  66   var url = 'https://CLUSTERNAME:5080/2/info';
  67   var info;
  68   var xmlreq = new XMLHttpRequest();
  69   xmlreq.onreadystatechange = function () {
  70     if (xmlreq.readyState != 4) return;
  71     if (xmlreq.status == 200) {
  72       info = eval("(" + xmlreq.responseText + ")");
  73       alert(info);
  74     } else {
  75       alert('Error fetching cluster info');
  76     }
  77     xmlreq = null;
  78   };
  79   xmlreq.open('GET', url, true);
  80   xmlreq.send(null);
  81
  82 Resources
  83 ---------
  84
  85 .. include:: rapi-resources.gen