Statistics
| Branch: | Tag: | Revision:

root / doc / rapi.rst @ f154a7a3

History | View | Annotate | Download (16.1 kB)

1 4352bf6d Iustin Pop
Ganeti remote API
2 4352bf6d Iustin Pop
=================
3 4352bf6d Iustin Pop
4 c8e0a534 Iustin Pop
Documents Ganeti version |version|
5 4352bf6d Iustin Pop
6 4352bf6d Iustin Pop
.. contents::
7 4352bf6d Iustin Pop
8 4352bf6d Iustin Pop
Introduction
9 4352bf6d Iustin Pop
------------
10 4352bf6d Iustin Pop
11 4352bf6d Iustin Pop
Ganeti supports a remote API for enable external tools to easily
12 4352bf6d Iustin Pop
retrieve information about a cluster's state. The remote API daemon,
13 4352bf6d Iustin Pop
*ganeti-rapi*, is automatically started on the master node. By default
14 4352bf6d Iustin Pop
it runs on TCP port 5080, but this can be changed either in
15 4352bf6d Iustin Pop
``.../constants.py`` or via the command line parameter *-p*. SSL mode,
16 4352bf6d Iustin Pop
which is used by default, can also be disabled by passing command line
17 4352bf6d Iustin Pop
parameters.
18 4352bf6d Iustin Pop
19 c099b8d8 Michael Hanselmann
20 c099b8d8 Michael Hanselmann
Users and passwords
21 c099b8d8 Michael Hanselmann
-------------------
22 c099b8d8 Michael Hanselmann
23 c099b8d8 Michael Hanselmann
``ganeti-rapi`` reads users and passwords from a file (usually
24 c099b8d8 Michael Hanselmann
``/var/lib/ganeti/rapi_users``) on startup. After modifying the password
25 c099b8d8 Michael Hanselmann
file, ``ganeti-rapi`` must be restarted.
26 c099b8d8 Michael Hanselmann
27 c099b8d8 Michael Hanselmann
Each line consists of two or three fields separated by whitespace. The
28 c099b8d8 Michael Hanselmann
first two fields are for username and password. The third field is
29 c099b8d8 Michael Hanselmann
optional and can be used to specify per-user options. Currently,
30 c099b8d8 Michael Hanselmann
``write`` is the only option supported and enables the user to execute
31 c099b8d8 Michael Hanselmann
operations modifying the cluster. Lines starting with the hash sign (#)
32 c099b8d8 Michael Hanselmann
are treated as comments.
33 c099b8d8 Michael Hanselmann
34 c099b8d8 Michael Hanselmann
Passwords can either be written in clear text or as a hash. Clear text
35 c099b8d8 Michael Hanselmann
passwords may not start with an opening brace (``{``) or they must be
36 c099b8d8 Michael Hanselmann
prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash
37 c099b8d8 Michael Hanselmann
of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n
38 c099b8d8 Michael Hanselmann
'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_. Using the
39 c099b8d8 Michael Hanselmann
scheme prefix for all passwords is recommended. Scheme prefixes are not
40 c099b8d8 Michael Hanselmann
case sensitive.
41 c099b8d8 Michael Hanselmann
42 c099b8d8 Michael Hanselmann
Example::
43 c099b8d8 Michael Hanselmann
44 c099b8d8 Michael Hanselmann
  # Give Jack and Fred read-only access
45 c099b8d8 Michael Hanselmann
  jack abc123
46 c099b8d8 Michael Hanselmann
  fred {cleartext}foo555
47 c099b8d8 Michael Hanselmann
48 c099b8d8 Michael Hanselmann
  # Give write access to an imaginary instance creation script
49 c099b8d8 Michael Hanselmann
  autocreator xyz789 write
50 c099b8d8 Michael Hanselmann
51 c099b8d8 Michael Hanselmann
  # Hashed password for Jessica
52 c099b8d8 Michael Hanselmann
  jessica {HA1}7046452df2cbb530877058712cf17bd4 write
53 c099b8d8 Michael Hanselmann
54 c099b8d8 Michael Hanselmann
55 c099b8d8 Michael Hanselmann
.. [#pwhash] Using the MD5 hash of username, realm and password is
56 c099b8d8 Michael Hanselmann
   described in RFC2617_ ("HTTP Authentication"), sections 3.2.2.2 and
57 c099b8d8 Michael Hanselmann
   3.3. The reason for using it over another algorithm is forward
58 c099b8d8 Michael Hanselmann
   compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
59 c099b8d8 Michael Hanselmann
   authentication in the future, the same hash could be used.
60 c099b8d8 Michael Hanselmann
   In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
61 c099b8d8 Michael Hanselmann
   API``, can only be changed by modifying the source code.
62 c099b8d8 Michael Hanselmann
63 c099b8d8 Michael Hanselmann
64 4352bf6d Iustin Pop
Protocol
65 4352bf6d Iustin Pop
--------
66 4352bf6d Iustin Pop
67 c099b8d8 Michael Hanselmann
The protocol used is JSON_ over HTTP designed after the REST_ principle.
68 c099b8d8 Michael Hanselmann
HTTP Basic authentication as per RFC2617_ is supported.
69 4352bf6d Iustin Pop
70 4352bf6d Iustin Pop
.. _JSON: http://www.json.org/
71 4352bf6d Iustin Pop
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
72 c099b8d8 Michael Hanselmann
.. _RFC2617: http://tools.ietf.org/rfc/rfc2617.txt
73 4352bf6d Iustin Pop
74 2cad4b91 Iustin Pop
Generic parameters
75 2cad4b91 Iustin Pop
------------------
76 2cad4b91 Iustin Pop
77 7faf5110 Michael Hanselmann
A few parameter mean the same thing across all resources which implement
78 7faf5110 Michael Hanselmann
it.
79 2cad4b91 Iustin Pop
80 2cad4b91 Iustin Pop
``bulk``
81 2cad4b91 Iustin Pop
++++++++
82 2cad4b91 Iustin Pop
83 c71a1a3d Iustin Pop
Bulk-mode means that for the resources which usually return just a list
84 c71a1a3d Iustin Pop
of child resources (e.g. ``/2/instances`` which returns just instance
85 c71a1a3d Iustin Pop
names), the output will instead contain detailed data for all these
86 c71a1a3d Iustin Pop
subresources. This is more efficient than query-ing the sub-resources
87 c71a1a3d Iustin Pop
themselves.
88 2cad4b91 Iustin Pop
89 2cad4b91 Iustin Pop
``dry-run``
90 2cad4b91 Iustin Pop
+++++++++++
91 2cad4b91 Iustin Pop
92 2cad4b91 Iustin Pop
The optional *dry-run* argument, if provided and set to a positive
93 2cad4b91 Iustin Pop
integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
94 2cad4b91 Iustin Pop
should not be executed, only the pre-execution checks will be done.
95 2cad4b91 Iustin Pop
96 c71a1a3d Iustin Pop
This is useful in trying to determine (without guarantees though, as in
97 c71a1a3d Iustin Pop
the meantime the cluster state could have changed) if the operation is
98 c71a1a3d Iustin Pop
likely to succeed or at least start executing.
99 2cad4b91 Iustin Pop
100 3427d34f Michael Hanselmann
``force``
101 3427d34f Michael Hanselmann
+++++++++++
102 3427d34f Michael Hanselmann
103 3427d34f Michael Hanselmann
Force operation to continue even if it will cause the cluster to become
104 3427d34f Michael Hanselmann
inconsistent (e.g. because there are not enough master candidates).
105 3427d34f Michael Hanselmann
106 4352bf6d Iustin Pop
Usage examples
107 4352bf6d Iustin Pop
--------------
108 4352bf6d Iustin Pop
109 c71a1a3d Iustin Pop
You can access the API using your favorite programming language as long
110 c71a1a3d Iustin Pop
as it supports network connections.
111 4352bf6d Iustin Pop
112 4352bf6d Iustin Pop
Shell
113 4352bf6d Iustin Pop
+++++
114 4352bf6d Iustin Pop
115 c8e0a534 Iustin Pop
.. highlight:: sh
116 c8e0a534 Iustin Pop
117 4352bf6d Iustin Pop
Using wget::
118 4352bf6d Iustin Pop
119 c8e0a534 Iustin Pop
   wget -q -O - https://CLUSTERNAME:5080/2/info
120 4352bf6d Iustin Pop
121 4352bf6d Iustin Pop
or curl::
122 4352bf6d Iustin Pop
123 4352bf6d Iustin Pop
  curl https://CLUSTERNAME:5080/2/info
124 4352bf6d Iustin Pop
125 4352bf6d Iustin Pop
126 4352bf6d Iustin Pop
Python
127 4352bf6d Iustin Pop
++++++
128 4352bf6d Iustin Pop
129 c71a1a3d Iustin Pop
.. highlight:: python
130 c71a1a3d Iustin Pop
131 c71a1a3d Iustin Pop
::
132 4352bf6d Iustin Pop
133 4352bf6d Iustin Pop
  import urllib2
134 4fb301b5 Tim Boring
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
135 4352bf6d Iustin Pop
  print f.read()
136 4352bf6d Iustin Pop
137 4352bf6d Iustin Pop
138 4352bf6d Iustin Pop
JavaScript
139 4352bf6d Iustin Pop
++++++++++
140 4352bf6d Iustin Pop
141 2cad4b91 Iustin Pop
.. warning:: While it's possible to use JavaScript, it poses several
142 c71a1a3d Iustin Pop
   potential problems, including browser blocking request due to
143 c71a1a3d Iustin Pop
   non-standard ports or different domain names. Fetching the data on
144 c71a1a3d Iustin Pop
   the webserver is easier.
145 4352bf6d Iustin Pop
146 c8e0a534 Iustin Pop
.. highlight:: javascript
147 c8e0a534 Iustin Pop
148 4352bf6d Iustin Pop
::
149 4352bf6d Iustin Pop
150 4fb301b5 Tim Boring
  var url = 'https://CLUSTERNAME:5080/2/info';
151 4352bf6d Iustin Pop
  var info;
152 4352bf6d Iustin Pop
  var xmlreq = new XMLHttpRequest();
153 4352bf6d Iustin Pop
  xmlreq.onreadystatechange = function () {
154 4352bf6d Iustin Pop
    if (xmlreq.readyState != 4) return;
155 4352bf6d Iustin Pop
    if (xmlreq.status == 200) {
156 4352bf6d Iustin Pop
      info = eval("(" + xmlreq.responseText + ")");
157 4352bf6d Iustin Pop
      alert(info);
158 4352bf6d Iustin Pop
    } else {
159 4352bf6d Iustin Pop
      alert('Error fetching cluster info');
160 4352bf6d Iustin Pop
    }
161 4352bf6d Iustin Pop
    xmlreq = null;
162 4352bf6d Iustin Pop
  };
163 4352bf6d Iustin Pop
  xmlreq.open('GET', url, true);
164 4352bf6d Iustin Pop
  xmlreq.send(null);
165 4352bf6d Iustin Pop
166 4352bf6d Iustin Pop
Resources
167 4352bf6d Iustin Pop
---------
168 4352bf6d Iustin Pop
169 c8e0a534 Iustin Pop
.. highlight:: javascript
170 6d81475c Iustin Pop
171 c8e0a534 Iustin Pop
``/``
172 c8e0a534 Iustin Pop
+++++
173 6d81475c Iustin Pop
174 c8e0a534 Iustin Pop
The root resource.
175 6d81475c Iustin Pop
176 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
177 6d81475c Iustin Pop
178 c8e0a534 Iustin Pop
``GET``
179 c8e0a534 Iustin Pop
~~~~~~~
180 6d81475c Iustin Pop
181 c8e0a534 Iustin Pop
Shows the list of mapped resources.
182 6d81475c Iustin Pop
183 c8e0a534 Iustin Pop
Returns: a dictionary with 'name' and 'uri' keys for each of them.
184 6d81475c Iustin Pop
185 c8e0a534 Iustin Pop
``/2``
186 c8e0a534 Iustin Pop
++++++
187 6d81475c Iustin Pop
188 c8e0a534 Iustin Pop
The ``/2`` resource, the root of the version 2 API.
189 6d81475c Iustin Pop
190 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
191 6d81475c Iustin Pop
192 c8e0a534 Iustin Pop
``GET``
193 c8e0a534 Iustin Pop
~~~~~~~
194 6d81475c Iustin Pop
195 c8e0a534 Iustin Pop
Show the list of mapped resources.
196 6d81475c Iustin Pop
197 c8e0a534 Iustin Pop
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
198 6d81475c Iustin Pop
199 c8e0a534 Iustin Pop
``/2/info``
200 c8e0a534 Iustin Pop
+++++++++++
201 6d81475c Iustin Pop
202 c8e0a534 Iustin Pop
Cluster information resource.
203 6d81475c Iustin Pop
204 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
205 6d81475c Iustin Pop
206 c8e0a534 Iustin Pop
``GET``
207 c8e0a534 Iustin Pop
~~~~~~~
208 6d81475c Iustin Pop
209 c8e0a534 Iustin Pop
Returns cluster information.
210 6d81475c Iustin Pop
211 c8e0a534 Iustin Pop
Example::
212 6d81475c Iustin Pop
213 6d81475c Iustin Pop
  {
214 6d81475c Iustin Pop
    "config_version": 2000000,
215 6d81475c Iustin Pop
    "name": "cluster",
216 6d81475c Iustin Pop
    "software_version": "2.0.0~beta2",
217 6d81475c Iustin Pop
    "os_api_version": 10,
218 6d81475c Iustin Pop
    "export_version": 0,
219 6d81475c Iustin Pop
    "candidate_pool_size": 10,
220 6d81475c Iustin Pop
    "enabled_hypervisors": [
221 6d81475c Iustin Pop
      "fake"
222 6d81475c Iustin Pop
    ],
223 6d81475c Iustin Pop
    "hvparams": {
224 6d81475c Iustin Pop
      "fake": {}
225 6d81475c Iustin Pop
     },
226 6d81475c Iustin Pop
    "default_hypervisor": "fake",
227 6d81475c Iustin Pop
    "master": "node1.example.com",
228 6d81475c Iustin Pop
    "architecture": [
229 6d81475c Iustin Pop
      "64bit",
230 6d81475c Iustin Pop
      "x86_64"
231 6d81475c Iustin Pop
    ],
232 6d81475c Iustin Pop
    "protocol_version": 20,
233 6d81475c Iustin Pop
    "beparams": {
234 6d81475c Iustin Pop
      "default": {
235 6d81475c Iustin Pop
        "auto_balance": true,
236 6d81475c Iustin Pop
        "vcpus": 1,
237 6d81475c Iustin Pop
        "memory": 128
238 6d81475c Iustin Pop
       }
239 6d81475c Iustin Pop
      }
240 6d81475c Iustin Pop
    }
241 6d81475c Iustin Pop
242 508e9b20 Michael Hanselmann
243 508e9b20 Michael Hanselmann
``/2/redistribute-config``
244 508e9b20 Michael Hanselmann
++++++++++++++++++++++++++
245 508e9b20 Michael Hanselmann
246 508e9b20 Michael Hanselmann
Redistribute configuration to all nodes.
247 508e9b20 Michael Hanselmann
248 508e9b20 Michael Hanselmann
It supports the following commands: ``PUT``.
249 508e9b20 Michael Hanselmann
250 508e9b20 Michael Hanselmann
``PUT``
251 508e9b20 Michael Hanselmann
~~~~~~~
252 508e9b20 Michael Hanselmann
253 508e9b20 Michael Hanselmann
Redistribute configuration to all nodes. The result will be a job id.
254 508e9b20 Michael Hanselmann
255 508e9b20 Michael Hanselmann
256 c8e0a534 Iustin Pop
``/2/instances``
257 c8e0a534 Iustin Pop
++++++++++++++++
258 6d81475c Iustin Pop
259 c8e0a534 Iustin Pop
The instances resource.
260 6d81475c Iustin Pop
261 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``POST``.
262 6d81475c Iustin Pop
263 c8e0a534 Iustin Pop
``GET``
264 c8e0a534 Iustin Pop
~~~~~~~
265 6d81475c Iustin Pop
266 c8e0a534 Iustin Pop
Returns a list of all available instances.
267 6d81475c Iustin Pop
268 c8e0a534 Iustin Pop
Example::
269 6d81475c Iustin Pop
270 6d81475c Iustin Pop
    [
271 6d81475c Iustin Pop
      {
272 6d81475c Iustin Pop
        "name": "web.example.com",
273 6d81475c Iustin Pop
        "uri": "\/instances\/web.example.com"
274 6d81475c Iustin Pop
      },
275 6d81475c Iustin Pop
      {
276 6d81475c Iustin Pop
        "name": "mail.example.com",
277 6d81475c Iustin Pop
        "uri": "\/instances\/mail.example.com"
278 6d81475c Iustin Pop
      }
279 6d81475c Iustin Pop
    ]
280 6d81475c Iustin Pop
281 c71a1a3d Iustin Pop
If the optional *bulk* argument is provided and set to a true value (i.e
282 c71a1a3d Iustin Pop
``?bulk=1``), the output contains detailed information about instances
283 c71a1a3d Iustin Pop
as a list.
284 6d81475c Iustin Pop
285 c8e0a534 Iustin Pop
Example::
286 6d81475c Iustin Pop
287 6d81475c Iustin Pop
    [
288 6d81475c Iustin Pop
      {
289 6d81475c Iustin Pop
         "status": "running",
290 6d81475c Iustin Pop
         "disk_usage": 20480,
291 6d81475c Iustin Pop
         "nic.bridges": [
292 6d81475c Iustin Pop
           "xen-br0"
293 6d81475c Iustin Pop
          ],
294 6d81475c Iustin Pop
         "name": "web.example.com",
295 6d81475c Iustin Pop
         "tags": ["tag1", "tag2"],
296 6d81475c Iustin Pop
         "beparams": {
297 6d81475c Iustin Pop
           "vcpus": 2,
298 6d81475c Iustin Pop
           "memory": 512
299 6d81475c Iustin Pop
         },
300 6d81475c Iustin Pop
         "disk.sizes": [
301 6d81475c Iustin Pop
             20480
302 6d81475c Iustin Pop
         ],
303 6d81475c Iustin Pop
         "pnode": "node1.example.com",
304 6d81475c Iustin Pop
         "nic.macs": ["01:23:45:67:89:01"],
305 6d81475c Iustin Pop
         "snodes": ["node2.example.com"],
306 6d81475c Iustin Pop
         "disk_template": "drbd",
307 6d81475c Iustin Pop
         "admin_state": true,
308 6d81475c Iustin Pop
         "os": "debian-etch",
309 6d81475c Iustin Pop
         "oper_state": true
310 6d81475c Iustin Pop
      },
311 6d81475c Iustin Pop
      ...
312 6d81475c Iustin Pop
    ]
313 6d81475c Iustin Pop
314 6d81475c Iustin Pop
315 c8e0a534 Iustin Pop
``POST``
316 c8e0a534 Iustin Pop
~~~~~~~~
317 6d81475c Iustin Pop
318 c8e0a534 Iustin Pop
Creates an instance.
319 6d81475c Iustin Pop
320 2cad4b91 Iustin Pop
If the optional *dry-run* argument is provided and set to a positive
321 2cad4b91 Iustin Pop
integer valu (e.g. ``?dry-run=1``), the job will not be actually
322 c71a1a3d Iustin Pop
executed, only the pre-execution checks will be done. Query-ing the job
323 c71a1a3d Iustin Pop
result will return, in both dry-run and normal case, the list of nodes
324 c71a1a3d Iustin Pop
selected for the instance.
325 2cad4b91 Iustin Pop
326 c8e0a534 Iustin Pop
Returns: a job ID that can be used later for polling.
327 6d81475c Iustin Pop
328 c8e0a534 Iustin Pop
``/2/instances/[instance_name]``
329 c8e0a534 Iustin Pop
++++++++++++++++++++++++++++++++
330 6d81475c Iustin Pop
331 c8e0a534 Iustin Pop
Instance-specific resource.
332 6d81475c Iustin Pop
333 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``DELETE``.
334 6d81475c Iustin Pop
335 c8e0a534 Iustin Pop
``GET``
336 c8e0a534 Iustin Pop
~~~~~~~
337 6d81475c Iustin Pop
338 c8e0a534 Iustin Pop
Returns information about an instance, similar to the bulk output from
339 c8e0a534 Iustin Pop
the instance list.
340 6d81475c Iustin Pop
341 c8e0a534 Iustin Pop
``DELETE``
342 c8e0a534 Iustin Pop
~~~~~~~~~~
343 6d81475c Iustin Pop
344 c8e0a534 Iustin Pop
Deletes an instance.
345 6d81475c Iustin Pop
346 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
347 2cad4b91 Iustin Pop
348 6d81475c Iustin Pop
349 d8260842 Michael Hanselmann
``/2/instances/[instance_name]/info``
350 d8260842 Michael Hanselmann
+++++++++++++++++++++++++++++++++++++++
351 d8260842 Michael Hanselmann
352 d8260842 Michael Hanselmann
It supports the following commands: ``GET``.
353 d8260842 Michael Hanselmann
354 d8260842 Michael Hanselmann
``GET``
355 d8260842 Michael Hanselmann
~~~~~~~
356 d8260842 Michael Hanselmann
357 d8260842 Michael Hanselmann
Requests detailed information about the instance. An optional parameter,
358 d8260842 Michael Hanselmann
``static`` (bool), can be set to return only static information from the
359 7faf5110 Michael Hanselmann
configuration without querying the instance's nodes. The result will be
360 7faf5110 Michael Hanselmann
a job id.
361 d8260842 Michael Hanselmann
362 d8260842 Michael Hanselmann
363 c8e0a534 Iustin Pop
``/2/instances/[instance_name]/reboot``
364 c8e0a534 Iustin Pop
+++++++++++++++++++++++++++++++++++++++
365 6d81475c Iustin Pop
366 c8e0a534 Iustin Pop
Reboots URI for an instance.
367 6d81475c Iustin Pop
368 c8e0a534 Iustin Pop
It supports the following commands: ``POST``.
369 6d81475c Iustin Pop
370 c8e0a534 Iustin Pop
``POST``
371 c8e0a534 Iustin Pop
~~~~~~~~
372 6d81475c Iustin Pop
373 c8e0a534 Iustin Pop
Reboots the instance.
374 6d81475c Iustin Pop
375 c8e0a534 Iustin Pop
The URI takes optional ``type=hard|soft|full`` and
376 c8e0a534 Iustin Pop
``ignore_secondaries=False|True`` parameters.
377 6d81475c Iustin Pop
378 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
379 2cad4b91 Iustin Pop
380 2cad4b91 Iustin Pop
381 c8e0a534 Iustin Pop
``/2/instances/[instance_name]/shutdown``
382 c8e0a534 Iustin Pop
+++++++++++++++++++++++++++++++++++++++++
383 6d81475c Iustin Pop
384 c8e0a534 Iustin Pop
Instance shutdown URI.
385 6d81475c Iustin Pop
386 c8e0a534 Iustin Pop
It supports the following commands: ``PUT``.
387 6d81475c Iustin Pop
388 c8e0a534 Iustin Pop
``PUT``
389 c8e0a534 Iustin Pop
~~~~~~~
390 6d81475c Iustin Pop
391 c8e0a534 Iustin Pop
Shutdowns an instance.
392 6d81475c Iustin Pop
393 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
394 2cad4b91 Iustin Pop
395 6d81475c Iustin Pop
396 c8e0a534 Iustin Pop
``/2/instances/[instance_name]/startup``
397 c8e0a534 Iustin Pop
++++++++++++++++++++++++++++++++++++++++
398 6d81475c Iustin Pop
399 c8e0a534 Iustin Pop
Instance startup URI.
400 6d81475c Iustin Pop
401 c8e0a534 Iustin Pop
It supports the following commands: ``PUT``.
402 6d81475c Iustin Pop
403 c8e0a534 Iustin Pop
``PUT``
404 c8e0a534 Iustin Pop
~~~~~~~
405 6d81475c Iustin Pop
406 c8e0a534 Iustin Pop
Startup an instance.
407 6d81475c Iustin Pop
408 c8e0a534 Iustin Pop
The URI takes an optional ``force=False|True`` parameter to start the
409 c8e0a534 Iustin Pop
instance if even if secondary disks are failing.
410 6d81475c Iustin Pop
411 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
412 2cad4b91 Iustin Pop
413 f72542cc Michael Hanselmann
``/2/instances/[instance_name]/reinstall``
414 f72542cc Michael Hanselmann
++++++++++++++++++++++++++++++++++++++++++++++
415 f72542cc Michael Hanselmann
416 f72542cc Michael Hanselmann
Installs the operating system again.
417 f72542cc Michael Hanselmann
418 f72542cc Michael Hanselmann
It supports the following commands: ``POST``.
419 f72542cc Michael Hanselmann
420 f72542cc Michael Hanselmann
``POST``
421 f72542cc Michael Hanselmann
~~~~~~~~
422 f72542cc Michael Hanselmann
423 f72542cc Michael Hanselmann
Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
424 f72542cc Michael Hanselmann
425 2cad4b91 Iustin Pop
426 4c98b915 Michael Hanselmann
``/2/instances/[instance_name]/replace-disks``
427 4c98b915 Michael Hanselmann
++++++++++++++++++++++++++++++++++++++++++++++
428 4c98b915 Michael Hanselmann
429 4c98b915 Michael Hanselmann
Replaces disks on an instance.
430 4c98b915 Michael Hanselmann
431 4c98b915 Michael Hanselmann
It supports the following commands: ``POST``.
432 4c98b915 Michael Hanselmann
433 4c98b915 Michael Hanselmann
``POST``
434 4c98b915 Michael Hanselmann
~~~~~~~~
435 4c98b915 Michael Hanselmann
436 4c98b915 Michael Hanselmann
Takes the parameters ``mode`` (one of ``replace_on_primary``,
437 7faf5110 Michael Hanselmann
``replace_on_secondary``, ``replace_new_secondary`` or
438 7faf5110 Michael Hanselmann
``replace_auto``), ``disks`` (comma separated list of disk indexes),
439 7faf5110 Michael Hanselmann
``remote_node`` and ``iallocator``.
440 4c98b915 Michael Hanselmann
441 4c98b915 Michael Hanselmann
442 c8e0a534 Iustin Pop
``/2/instances/[instance_name]/tags``
443 c8e0a534 Iustin Pop
+++++++++++++++++++++++++++++++++++++
444 6d81475c Iustin Pop
445 c8e0a534 Iustin Pop
Manages per-instance tags.
446 6d81475c Iustin Pop
447 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
448 6d81475c Iustin Pop
449 c8e0a534 Iustin Pop
``GET``
450 c8e0a534 Iustin Pop
~~~~~~~
451 6d81475c Iustin Pop
452 c8e0a534 Iustin Pop
Returns a list of tags.
453 6d81475c Iustin Pop
454 c8e0a534 Iustin Pop
Example::
455 6d81475c Iustin Pop
456 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
457 6d81475c Iustin Pop
458 c8e0a534 Iustin Pop
``PUT``
459 c8e0a534 Iustin Pop
~~~~~~~
460 6d81475c Iustin Pop
461 c8e0a534 Iustin Pop
Add a set of tags.
462 6d81475c Iustin Pop
463 c8e0a534 Iustin Pop
The request as a list of strings should be ``PUT`` to this URI. The
464 508e9b20 Michael Hanselmann
result will be a job id.
465 6d81475c Iustin Pop
466 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
467 2cad4b91 Iustin Pop
468 2cad4b91 Iustin Pop
469 c8e0a534 Iustin Pop
``DELETE``
470 c8e0a534 Iustin Pop
~~~~~~~~~~
471 6d81475c Iustin Pop
472 c8e0a534 Iustin Pop
Delete a tag.
473 6d81475c Iustin Pop
474 c71a1a3d Iustin Pop
In order to delete a set of tags, the DELETE request should be addressed
475 c71a1a3d Iustin Pop
to URI like::
476 6d81475c Iustin Pop
477 c8e0a534 Iustin Pop
    /tags?tag=[tag]&tag=[tag]
478 6d81475c Iustin Pop
479 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
480 2cad4b91 Iustin Pop
481 2cad4b91 Iustin Pop
482 c8e0a534 Iustin Pop
``/2/jobs``
483 c8e0a534 Iustin Pop
+++++++++++
484 6d81475c Iustin Pop
485 c8e0a534 Iustin Pop
The ``/2/jobs`` resource.
486 6d81475c Iustin Pop
487 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
488 6d81475c Iustin Pop
489 c8e0a534 Iustin Pop
``GET``
490 c8e0a534 Iustin Pop
~~~~~~~
491 6d81475c Iustin Pop
492 c8e0a534 Iustin Pop
Returns a dictionary of jobs.
493 6d81475c Iustin Pop
494 c8e0a534 Iustin Pop
Returns: a dictionary with jobs id and uri.
495 6d81475c Iustin Pop
496 c8e0a534 Iustin Pop
``/2/jobs/[job_id]``
497 c8e0a534 Iustin Pop
++++++++++++++++++++
498 6d81475c Iustin Pop
499 6d81475c Iustin Pop
500 c8e0a534 Iustin Pop
Individual job URI.
501 6d81475c Iustin Pop
502 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``DELETE``.
503 6d81475c Iustin Pop
504 c8e0a534 Iustin Pop
``GET``
505 c8e0a534 Iustin Pop
~~~~~~~
506 6d81475c Iustin Pop
507 c8e0a534 Iustin Pop
Returns a job status.
508 6d81475c Iustin Pop
509 c8e0a534 Iustin Pop
Returns: a dictionary with job parameters.
510 6d81475c Iustin Pop
511 c8e0a534 Iustin Pop
The result includes:
512 6d81475c Iustin Pop
513 c8e0a534 Iustin Pop
- id: job ID as a number
514 c8e0a534 Iustin Pop
- status: current job status as a string
515 c71a1a3d Iustin Pop
- ops: involved OpCodes as a list of dictionaries for each opcodes in
516 c71a1a3d Iustin Pop
  the job
517 c8e0a534 Iustin Pop
- opstatus: OpCodes status as a list
518 c8e0a534 Iustin Pop
- opresult: OpCodes results as a list of lists
519 6d81475c Iustin Pop
520 c8e0a534 Iustin Pop
``DELETE``
521 c8e0a534 Iustin Pop
~~~~~~~~~~
522 6d81475c Iustin Pop
523 c8e0a534 Iustin Pop
Cancel a not-yet-started job.
524 6d81475c Iustin Pop
525 c8e0a534 Iustin Pop
``/2/nodes``
526 c8e0a534 Iustin Pop
++++++++++++
527 6d81475c Iustin Pop
528 c8e0a534 Iustin Pop
Nodes resource.
529 6d81475c Iustin Pop
530 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
531 6d81475c Iustin Pop
532 c8e0a534 Iustin Pop
``GET``
533 c8e0a534 Iustin Pop
~~~~~~~
534 6d81475c Iustin Pop
535 c8e0a534 Iustin Pop
Returns a list of all nodes.
536 6d81475c Iustin Pop
537 c8e0a534 Iustin Pop
Example::
538 6d81475c Iustin Pop
539 6d81475c Iustin Pop
    [
540 6d81475c Iustin Pop
      {
541 6d81475c Iustin Pop
        "id": "node1.example.com",
542 6d81475c Iustin Pop
        "uri": "\/instances\/node1.example.com"
543 6d81475c Iustin Pop
      },
544 6d81475c Iustin Pop
      {
545 6d81475c Iustin Pop
        "id": "node2.example.com",
546 6d81475c Iustin Pop
        "uri": "\/instances\/node2.example.com"
547 6d81475c Iustin Pop
      }
548 6d81475c Iustin Pop
    ]
549 6d81475c Iustin Pop
550 c71a1a3d Iustin Pop
If the optional 'bulk' argument is provided and set to 'true' value (i.e
551 c71a1a3d Iustin Pop
'?bulk=1'), the output contains detailed information about nodes as a
552 c71a1a3d Iustin Pop
list.
553 6d81475c Iustin Pop
554 c8e0a534 Iustin Pop
Example::
555 6d81475c Iustin Pop
556 6d81475c Iustin Pop
    [
557 6d81475c Iustin Pop
      {
558 6d81475c Iustin Pop
        "pinst_cnt": 1,
559 6d81475c Iustin Pop
        "mfree": 31280,
560 6d81475c Iustin Pop
        "mtotal": 32763,
561 6d81475c Iustin Pop
        "name": "www.example.com",
562 6d81475c Iustin Pop
        "tags": [],
563 6d81475c Iustin Pop
        "mnode": 512,
564 6d81475c Iustin Pop
        "dtotal": 5246208,
565 6d81475c Iustin Pop
        "sinst_cnt": 2,
566 6d81475c Iustin Pop
        "dfree": 5171712,
567 6d81475c Iustin Pop
        "offline": false
568 6d81475c Iustin Pop
      },
569 6d81475c Iustin Pop
      ...
570 6d81475c Iustin Pop
    ]
571 6d81475c Iustin Pop
572 f72542cc Michael Hanselmann
``/2/nodes/[node_name]``
573 f72542cc Michael Hanselmann
+++++++++++++++++++++++++++++++++
574 f72542cc Michael Hanselmann
575 f72542cc Michael Hanselmann
Returns information about a node.
576 f72542cc Michael Hanselmann
577 f72542cc Michael Hanselmann
It supports the following commands: ``GET``.
578 f72542cc Michael Hanselmann
579 73452f12 Michael Hanselmann
``/2/nodes/[node_name]/evacuate``
580 73452f12 Michael Hanselmann
+++++++++++++++++++++++++++++++++
581 73452f12 Michael Hanselmann
582 73452f12 Michael Hanselmann
Evacuates all secondary instances off a node.
583 73452f12 Michael Hanselmann
584 73452f12 Michael Hanselmann
It supports the following commands: ``POST``.
585 73452f12 Michael Hanselmann
586 73452f12 Michael Hanselmann
``POST``
587 73452f12 Michael Hanselmann
~~~~~~~~
588 73452f12 Michael Hanselmann
589 73452f12 Michael Hanselmann
To evacuate a node, either one of the ``iallocator`` or ``remote_node``
590 73452f12 Michael Hanselmann
parameters must be passed:
591 73452f12 Michael Hanselmann
592 73452f12 Michael Hanselmann
    evacuate?iallocator=[iallocator]
593 73452f12 Michael Hanselmann
    evacuate?remote_node=[nodeX.example.com]
594 73452f12 Michael Hanselmann
595 1c482bab Michael Hanselmann
``/2/nodes/[node_name]/migrate``
596 1c482bab Michael Hanselmann
+++++++++++++++++++++++++++++++++
597 1c482bab Michael Hanselmann
598 1c482bab Michael Hanselmann
Migrates all primary instances from a node.
599 1c482bab Michael Hanselmann
600 1c482bab Michael Hanselmann
It supports the following commands: ``POST``.
601 1c482bab Michael Hanselmann
602 1c482bab Michael Hanselmann
``POST``
603 1c482bab Michael Hanselmann
~~~~~~~~
604 1c482bab Michael Hanselmann
605 1c482bab Michael Hanselmann
No parameters are required, but ``live`` can be set to a boolean value.
606 1c482bab Michael Hanselmann
607 1c482bab Michael Hanselmann
    migrate?live=[0|1]
608 1c482bab Michael Hanselmann
609 64dae8fc Michael Hanselmann
``/2/nodes/[node_name]/role``
610 64dae8fc Michael Hanselmann
+++++++++++++++++++++++++++++
611 64dae8fc Michael Hanselmann
612 64dae8fc Michael Hanselmann
Manages node role.
613 64dae8fc Michael Hanselmann
614 64dae8fc Michael Hanselmann
It supports the following commands: ``GET``, ``PUT``.
615 64dae8fc Michael Hanselmann
616 64dae8fc Michael Hanselmann
The role is always one of the following:
617 64dae8fc Michael Hanselmann
618 64dae8fc Michael Hanselmann
  - drained
619 64dae8fc Michael Hanselmann
  - master
620 64dae8fc Michael Hanselmann
  - master-candidate
621 64dae8fc Michael Hanselmann
  - offline
622 64dae8fc Michael Hanselmann
  - regular
623 64dae8fc Michael Hanselmann
624 64dae8fc Michael Hanselmann
``GET``
625 64dae8fc Michael Hanselmann
~~~~~~~
626 64dae8fc Michael Hanselmann
627 64dae8fc Michael Hanselmann
Returns the current node role.
628 64dae8fc Michael Hanselmann
629 64dae8fc Michael Hanselmann
Example::
630 64dae8fc Michael Hanselmann
631 64dae8fc Michael Hanselmann
    "master-candidate"
632 64dae8fc Michael Hanselmann
633 64dae8fc Michael Hanselmann
``PUT``
634 64dae8fc Michael Hanselmann
~~~~~~~
635 64dae8fc Michael Hanselmann
636 64dae8fc Michael Hanselmann
Change the node role.
637 64dae8fc Michael Hanselmann
638 7faf5110 Michael Hanselmann
The request is a string which should be PUT to this URI. The result will
639 7faf5110 Michael Hanselmann
be a job id.
640 64dae8fc Michael Hanselmann
641 64dae8fc Michael Hanselmann
It supports the ``force`` argument.
642 64dae8fc Michael Hanselmann
643 7a95a954 Michael Hanselmann
``/2/nodes/[node_name]/storage``
644 7a95a954 Michael Hanselmann
++++++++++++++++++++++++++++++++
645 7a95a954 Michael Hanselmann
646 7a95a954 Michael Hanselmann
Manages storage units on the node.
647 7a95a954 Michael Hanselmann
648 7a95a954 Michael Hanselmann
``GET``
649 7a95a954 Michael Hanselmann
~~~~~~~
650 7a95a954 Michael Hanselmann
651 7a95a954 Michael Hanselmann
Requests a list of storage units on a node. Requires the parameters
652 7a95a954 Michael Hanselmann
``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
653 7faf5110 Michael Hanselmann
``output_fields``. The result will be a job id, using which the result
654 7faf5110 Michael Hanselmann
can be retrieved.
655 7a95a954 Michael Hanselmann
656 1e82bc80 Michael Hanselmann
``/2/nodes/[node_name]/storage/modify``
657 1e82bc80 Michael Hanselmann
+++++++++++++++++++++++++++++++++++++++
658 1e82bc80 Michael Hanselmann
659 1e82bc80 Michael Hanselmann
Modifies storage units on the node.
660 1e82bc80 Michael Hanselmann
661 1e82bc80 Michael Hanselmann
``PUT``
662 1e82bc80 Michael Hanselmann
~~~~~~~
663 1e82bc80 Michael Hanselmann
664 7faf5110 Michael Hanselmann
Modifies parameters of storage units on the node. Requires the
665 7faf5110 Michael Hanselmann
parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
666 7faf5110 Michael Hanselmann
and ``name`` (name of the storage unit).  Parameters can be passed
667 7faf5110 Michael Hanselmann
additionally. Currently only ``allocatable`` (bool) is supported. The
668 7faf5110 Michael Hanselmann
result will be a job id.
669 1e82bc80 Michael Hanselmann
670 723f4565 Michael Hanselmann
``/2/nodes/[node_name]/storage/repair``
671 723f4565 Michael Hanselmann
+++++++++++++++++++++++++++++++++++++++
672 723f4565 Michael Hanselmann
673 723f4565 Michael Hanselmann
Repairs a storage unit on the node.
674 723f4565 Michael Hanselmann
675 723f4565 Michael Hanselmann
``PUT``
676 723f4565 Michael Hanselmann
~~~~~~~
677 723f4565 Michael Hanselmann
678 7faf5110 Michael Hanselmann
Repairs a storage unit on the node. Requires the parameters
679 7faf5110 Michael Hanselmann
``storage_type`` (currently only ``lvm-vg`` can be repaired) and
680 7faf5110 Michael Hanselmann
``name`` (name of the storage unit). The result will be a job id.
681 723f4565 Michael Hanselmann
682 c8e0a534 Iustin Pop
``/2/nodes/[node_name]/tags``
683 c8e0a534 Iustin Pop
+++++++++++++++++++++++++++++
684 6d81475c Iustin Pop
685 c8e0a534 Iustin Pop
Manages per-node tags.
686 6d81475c Iustin Pop
687 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
688 6d81475c Iustin Pop
689 c8e0a534 Iustin Pop
``GET``
690 c8e0a534 Iustin Pop
~~~~~~~
691 6d81475c Iustin Pop
692 c8e0a534 Iustin Pop
Returns a list of tags.
693 6d81475c Iustin Pop
694 c8e0a534 Iustin Pop
Example::
695 6d81475c Iustin Pop
696 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
697 6d81475c Iustin Pop
698 c8e0a534 Iustin Pop
``PUT``
699 c8e0a534 Iustin Pop
~~~~~~~
700 6d81475c Iustin Pop
701 c8e0a534 Iustin Pop
Add a set of tags.
702 6d81475c Iustin Pop
703 c8e0a534 Iustin Pop
The request as a list of strings should be PUT to this URI. The result
704 c8e0a534 Iustin Pop
will be a job id.
705 6d81475c Iustin Pop
706 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
707 2cad4b91 Iustin Pop
708 c8e0a534 Iustin Pop
``DELETE``
709 c8e0a534 Iustin Pop
~~~~~~~~~~
710 6d81475c Iustin Pop
711 c8e0a534 Iustin Pop
Deletes tags.
712 6d81475c Iustin Pop
713 c71a1a3d Iustin Pop
In order to delete a set of tags, the DELETE request should be addressed
714 c71a1a3d Iustin Pop
to URI like::
715 6d81475c Iustin Pop
716 c8e0a534 Iustin Pop
    /tags?tag=[tag]&tag=[tag]
717 6d81475c Iustin Pop
718 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
719 2cad4b91 Iustin Pop
720 2cad4b91 Iustin Pop
721 c8e0a534 Iustin Pop
``/2/os``
722 c8e0a534 Iustin Pop
+++++++++
723 6d81475c Iustin Pop
724 c8e0a534 Iustin Pop
OS resource.
725 6d81475c Iustin Pop
726 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
727 6d81475c Iustin Pop
728 c8e0a534 Iustin Pop
``GET``
729 c8e0a534 Iustin Pop
~~~~~~~
730 6d81475c Iustin Pop
731 c8e0a534 Iustin Pop
Return a list of all OSes.
732 6d81475c Iustin Pop
733 c8e0a534 Iustin Pop
Can return error 500 in case of a problem. Since this is a costly
734 c71a1a3d Iustin Pop
operation for Ganeti 2.0, it is not recommended to execute it too often.
735 6d81475c Iustin Pop
736 c8e0a534 Iustin Pop
Example::
737 6d81475c Iustin Pop
738 c8e0a534 Iustin Pop
    ["debian-etch"]
739 6d81475c Iustin Pop
740 c8e0a534 Iustin Pop
``/2/tags``
741 c8e0a534 Iustin Pop
+++++++++++
742 6d81475c Iustin Pop
743 c8e0a534 Iustin Pop
Manages cluster tags.
744 6d81475c Iustin Pop
745 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
746 6d81475c Iustin Pop
747 c8e0a534 Iustin Pop
``GET``
748 c8e0a534 Iustin Pop
~~~~~~~
749 6d81475c Iustin Pop
750 c8e0a534 Iustin Pop
Returns the cluster tags.
751 6d81475c Iustin Pop
752 c8e0a534 Iustin Pop
Example::
753 6d81475c Iustin Pop
754 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
755 6d81475c Iustin Pop
756 c8e0a534 Iustin Pop
``PUT``
757 c8e0a534 Iustin Pop
~~~~~~~
758 6d81475c Iustin Pop
759 c8e0a534 Iustin Pop
Adds a set of tags.
760 6d81475c Iustin Pop
761 c8e0a534 Iustin Pop
The request as a list of strings should be PUT to this URI. The result
762 c8e0a534 Iustin Pop
will be a job id.
763 6d81475c Iustin Pop
764 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
765 2cad4b91 Iustin Pop
766 2cad4b91 Iustin Pop
767 c8e0a534 Iustin Pop
``DELETE``
768 c8e0a534 Iustin Pop
~~~~~~~~~~
769 6d81475c Iustin Pop
770 c8e0a534 Iustin Pop
Deletes tags.
771 6d81475c Iustin Pop
772 c71a1a3d Iustin Pop
In order to delete a set of tags, the DELETE request should be addressed
773 c71a1a3d Iustin Pop
to URI like::
774 6d81475c Iustin Pop
775 c8e0a534 Iustin Pop
    /tags?tag=[tag]&tag=[tag]
776 6d81475c Iustin Pop
777 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
778 2cad4b91 Iustin Pop
779 2cad4b91 Iustin Pop
780 c8e0a534 Iustin Pop
``/version``
781 c8e0a534 Iustin Pop
++++++++++++
782 6d81475c Iustin Pop
783 c8e0a534 Iustin Pop
The version resource.
784 6d81475c Iustin Pop
785 c71a1a3d Iustin Pop
This resource should be used to determine the remote API version and to
786 c71a1a3d Iustin Pop
adapt clients accordingly.
787 6d81475c Iustin Pop
788 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
789 6d81475c Iustin Pop
790 c8e0a534 Iustin Pop
``GET``
791 c8e0a534 Iustin Pop
~~~~~~~
792 6d81475c Iustin Pop
793 c71a1a3d Iustin Pop
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
794 c71a1a3d Iustin Pop
returns ``2``.
795 558fd122 Michael Hanselmann
796 558fd122 Michael Hanselmann
.. vim: set textwidth=72 :
797 c71a1a3d Iustin Pop
.. Local Variables:
798 c71a1a3d Iustin Pop
.. mode: rst
799 c71a1a3d Iustin Pop
.. fill-column: 72
800 c71a1a3d Iustin Pop
.. End: