root / doc / rapi.sgml @ 47eb4b45
History | View | Annotate | Download (2.8 kB)
1 |
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ |
---|---|
2 |
<!ENTITY JsonLink "http://www.json.org/"> |
3 |
<!ENTITY WikipediaRESTLink |
4 |
"http://en.wikipedia.org/wiki/Representational_State_Transfer"> |
5 |
]> |
6 |
<article class="specification"> |
7 |
<articleinfo> |
8 |
<title>Ganeti remote API</title> |
9 |
</articleinfo> |
10 |
|
11 |
<para>Documents Ganeti version 1.2</para> |
12 |
|
13 |
<sect1> |
14 |
<title>Introduction</title> |
15 |
|
16 |
<para>Ganeti supports a remote API for enable external tools to easily |
17 |
retrieve information about a cluster's state. The remote API daemon, |
18 |
<computeroutput>ganeti-rapi</computeroutput>, is automatically started on |
19 |
the master node if the <computeroutput>--enable-rapi</computeroutput> |
20 |
parameter is passed to the <computeroutput>configure</computeroutput> |
21 |
script. Alternatively you can start it manually. By default it runs on TCP |
22 |
port 5080, but this can be changed either in |
23 |
<filename>…/constants.py</filename> or via the command line |
24 |
parameter <computeroutput>-p</computeroutput>. SSL support can also be |
25 |
enabled by passing command line parameters.</para> |
26 |
|
27 |
<note> |
28 |
<para>Ganeti 1.2 only supports a limited set of calls, all of them |
29 |
read-only. The next major version will have support for write |
30 |
operations.</para> |
31 |
</note> |
32 |
</sect1> |
33 |
|
34 |
<sect1> |
35 |
<title>Protocol</title> |
36 |
|
37 |
<para>The protocol used is <ulink url="&JsonLink;">JSON</ulink> over HTTP |
38 |
designed after the <ulink url="&WikipediaRESTLink;">REST</ulink> principle. |
39 |
</para> |
40 |
</sect1> |
41 |
|
42 |
<sect1> |
43 |
<title>Usage examples</title> |
44 |
|
45 |
<para>You can access the API using your favorite programming language as long |
46 |
as it supports network connections.</para> |
47 |
|
48 |
<sect2> |
49 |
<title>Shell</title> |
50 |
<screen>wget -q -O - http://<replaceable>CLUSTERNAME</replaceable>:5080/info</screen> |
51 |
</sect2> |
52 |
|
53 |
<sect2> |
54 |
<title>Python</title> |
55 |
<screen>import urllib2 |
56 |
f = urllib2.urlopen('http://<replaceable>CLUSTERNAME</replaceable>:5080/info') |
57 |
print f.read()</screen> |
58 |
</sect2> |
59 |
|
60 |
<sect2> |
61 |
<title>JavaScript</title> |
62 |
<note> |
63 |
<para>While it's possible to use JavaScript, it poses several potential |
64 |
problems, including browser blocking request due to non-standard ports |
65 |
or different domain names. Fetching the data on the webserver is |
66 |
easier.</para> |
67 |
</note> |
68 |
<screen>var url = 'http://<replaceable>CLUSTERNAME</replaceable>:5080/info'; |
69 |
var info; |
70 |
|
71 |
var xmlreq = new XMLHttpRequest(); |
72 |
xmlreq.onreadystatechange = function () { |
73 |
if (xmlreq.readyState != 4) return; |
74 |
if (xmlreq.status == 200) { |
75 |
info = eval("(" + xmlreq.responseText + ")"); |
76 |
alert(info); |
77 |
} else { |
78 |
alert('Error fetching cluster info'); |
79 |
} |
80 |
xmlreq = null; |
81 |
}; |
82 |
xmlreq.open('GET', url, true); |
83 |
xmlreq.send(null);</screen> |
84 |
</sect2> |
85 |
|
86 |
</sect1> |
87 |
|
88 |
<sect1> |
89 |
<title>Resources</title> |
90 |
@INCLUDE_RAPI_RESOURCES@ |
91 |
</sect1> |
92 |
|
93 |
</article> |