| 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
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
``.../`` 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
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
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 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
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:
71 4352bf6d Iustin Pop
.. _REST:
72 c099b8d8 Michael Hanselmann
.. _RFC2617:
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
79 2cad4b91 Iustin Pop
80 2cad4b91 Iustin Pop
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
88 2cad4b91 Iustin Pop
89 2cad4b91 Iustin Pop
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
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
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
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
136 4352bf6d Iustin Pop
137 4352bf6d Iustin Pop
138 4352bf6d Iustin Pop
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
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'GET', url, true);
164 4352bf6d Iustin Pop
165 4352bf6d Iustin Pop
166 4352bf6d Iustin Pop
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
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
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
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
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
207 c8e0a534 Iustin Pop
208 6d81475c Iustin Pop
209 c8e0a534 Iustin Pop
Returns cluster information.
210 6d81475c Iustin Pop
211 c8e0a534 Iustin Pop
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
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": "",
228 6d81475c Iustin Pop
    "architecture": [
229 6d81475c Iustin Pop
230 6d81475c Iustin Pop
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
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
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
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
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
269 6d81475c Iustin Pop
270 6d81475c Iustin Pop
271 6d81475c Iustin Pop
272 6d81475c Iustin Pop
        "name": "",
273 6d81475c Iustin Pop
        "uri": "\/instances\/"
274 6d81475c Iustin Pop
275 6d81475c Iustin Pop
276 6d81475c Iustin Pop
        "name": "",
277 6d81475c Iustin Pop
        "uri": "\/instances\/"
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
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
293 6d81475c Iustin Pop
294 6d81475c Iustin Pop
         "name": "",
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
302 6d81475c Iustin Pop
303 6d81475c Iustin Pop
         "pnode": "",
304 6d81475c Iustin Pop
         "nic.macs": ["01:23:45:67:89:01"],
305 6d81475c Iustin Pop
         "snodes": [""],
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
455 6d81475c Iustin Pop
456 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
457 6d81475c Iustin Pop
458 c8e0a534 Iustin Pop
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
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
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
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
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
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
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
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
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
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
538 6d81475c Iustin Pop
539 6d81475c Iustin Pop
540 6d81475c Iustin Pop
541 6d81475c Iustin Pop
        "id": "",
542 6d81475c Iustin Pop
        "uri": "\/instances\/"
543 6d81475c Iustin Pop
544 6d81475c Iustin Pop
545 6d81475c Iustin Pop
        "id": "",
546 6d81475c Iustin Pop
        "uri": "\/instances\/"
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
553 6d81475c Iustin Pop
554 c8e0a534 Iustin Pop
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": "",
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
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
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
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
593 73452f12 Michael Hanselmann
594 73452f12 Michael Hanselmann
595 1c482bab Michael Hanselmann
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
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
608 1c482bab Michael Hanselmann
609 64dae8fc Michael Hanselmann
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
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
630 64dae8fc Michael Hanselmann
631 64dae8fc Michael Hanselmann
632 64dae8fc Michael Hanselmann
633 64dae8fc Michael Hanselmann
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
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
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
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
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
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
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
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
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
695 6d81475c Iustin Pop
696 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
697 6d81475c Iustin Pop
698 c8e0a534 Iustin Pop
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
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
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
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
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
737 6d81475c Iustin Pop
738 c8e0a534 Iustin Pop
739 6d81475c Iustin Pop
740 c8e0a534 Iustin Pop
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
748 c8e0a534 Iustin Pop
749 6d81475c Iustin Pop
750 c8e0a534 Iustin Pop
Returns the cluster tags.
751 6d81475c Iustin Pop
752 c8e0a534 Iustin Pop
753 6d81475c Iustin Pop
754 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
755 6d81475c Iustin Pop
756 c8e0a534 Iustin Pop
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
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
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
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
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: