| Branch: | Tag: | Revision:

root / doc / rapi.rst @ d2baa21d

History | View | Annotate | Download (18.2 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 ab2e463a Michael Hanselmann
operations modifying the cluster. Lines starting with the hash sign
32 ab2e463a 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 ab2e463a Michael Hanselmann
'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix
39 ab2e463a Michael Hanselmann
it with ``{ha1}``. Using the scheme prefix for all passwords is
40 ab2e463a Michael Hanselmann
recommended. Scheme prefixes are not 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 e91cfc2a Iustin Pop
- opresult: OpCodes results as a list
519 e91cfc2a Iustin Pop
520 e91cfc2a Iustin Pop
For a successful opcode, the ``opresult`` field corresponding to it will
521 e91cfc2a Iustin Pop
contain the raw result from its :term:`LogicalUnit`. In case an opcode
522 e91cfc2a Iustin Pop
has failed, its element in the opresult list will be a list of two
523 e91cfc2a Iustin Pop
524 e91cfc2a Iustin Pop
525 e91cfc2a Iustin Pop
- first element the error type (the Ganeti internal error name)
526 e91cfc2a Iustin Pop
- second element a list of either one or two elements:
527 e91cfc2a Iustin Pop
528 e91cfc2a Iustin Pop
  - the first element is the textual error description
529 e91cfc2a Iustin Pop
  - the second element, if any, will hold an error classification
530 e91cfc2a Iustin Pop
531 e91cfc2a Iustin Pop
The error classification is most useful for the ``OpPrereqError``
532 e91cfc2a Iustin Pop
error type - these errors happen before the OpCode has started
533 e91cfc2a Iustin Pop
executing, so it's possible to retry the OpCode without side
534 e91cfc2a Iustin Pop
effects. But whether it make sense to retry depends on the error
535 e91cfc2a Iustin Pop
536 e91cfc2a Iustin Pop
537 e91cfc2a Iustin Pop
538 e91cfc2a Iustin Pop
  Resolver errors. This usually means that a name doesn't exist in DNS,
539 e91cfc2a Iustin Pop
  so if it's a case of slow DNS propagation the operation can be retried
540 e91cfc2a Iustin Pop
541 e91cfc2a Iustin Pop
542 e91cfc2a Iustin Pop
543 e91cfc2a Iustin Pop
  Not enough resources (iallocator failure, disk space, memory,
544 e91cfc2a Iustin Pop
  etc.). If the resources on the cluster increase, the operation might
545 e91cfc2a Iustin Pop
546 e91cfc2a Iustin Pop
547 e91cfc2a Iustin Pop
548 e91cfc2a Iustin Pop
  Wrong arguments (at syntax level). The operation will not ever be
549 e91cfc2a Iustin Pop
  accepted unless the arguments change.
550 e91cfc2a Iustin Pop
551 e91cfc2a Iustin Pop
552 e91cfc2a Iustin Pop
  Wrong entity state. For example, live migration has been requested for
553 e91cfc2a Iustin Pop
  a down instance, or instance creation on an offline node. The
554 e91cfc2a Iustin Pop
  operation can be retried once the resource has changed state.
555 e91cfc2a Iustin Pop
556 e91cfc2a Iustin Pop
557 e91cfc2a Iustin Pop
  Entity not found. For example, information has been requested for an
558 e91cfc2a Iustin Pop
  unknown instance.
559 e91cfc2a Iustin Pop
560 e91cfc2a Iustin Pop
561 e91cfc2a Iustin Pop
  Entity already exists. For example, instance creation has been
562 e91cfc2a Iustin Pop
  requested for an already-existing instance.
563 e91cfc2a Iustin Pop
564 e91cfc2a Iustin Pop
565 e91cfc2a Iustin Pop
  Resource not unique (e.g. MAC or IP duplication).
566 e91cfc2a Iustin Pop
567 e91cfc2a Iustin Pop
568 e91cfc2a Iustin Pop
  Internal cluster error. For example, a node is unreachable but not set
569 e91cfc2a Iustin Pop
  offline, or the ganeti node daemons are not working, etc. A
570 e91cfc2a Iustin Pop
  ``gnt-cluster verify`` should be run.
571 e91cfc2a Iustin Pop
572 e91cfc2a Iustin Pop
573 e91cfc2a Iustin Pop
  Environment error (e.g. node disk error). A ``gnt-cluster verify``
574 e91cfc2a Iustin Pop
  should be run.
575 e91cfc2a Iustin Pop
576 e91cfc2a Iustin Pop
Note that in the above list, by entity we refer to a node or instance,
577 e91cfc2a Iustin Pop
while by a resource we refer to an instance's disk, or NIC, etc.
578 e91cfc2a Iustin Pop
579 6d81475c Iustin Pop
580 c8e0a534 Iustin Pop
581 c8e0a534 Iustin Pop
582 6d81475c Iustin Pop
583 c8e0a534 Iustin Pop
Cancel a not-yet-started job.
584 6d81475c Iustin Pop
585 c8e0a534 Iustin Pop
586 c8e0a534 Iustin Pop
587 6d81475c Iustin Pop
588 c8e0a534 Iustin Pop
Nodes resource.
589 6d81475c Iustin Pop
590 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
591 6d81475c Iustin Pop
592 c8e0a534 Iustin Pop
593 c8e0a534 Iustin Pop
594 6d81475c Iustin Pop
595 c8e0a534 Iustin Pop
Returns a list of all nodes.
596 6d81475c Iustin Pop
597 c8e0a534 Iustin Pop
598 6d81475c Iustin Pop
599 6d81475c Iustin Pop
600 6d81475c Iustin Pop
601 6d81475c Iustin Pop
        "id": "",
602 20b1bd80 Iustin Pop
        "uri": "\/nodes\/"
603 6d81475c Iustin Pop
604 6d81475c Iustin Pop
605 6d81475c Iustin Pop
        "id": "",
606 20b1bd80 Iustin Pop
        "uri": "\/nodes\/"
607 6d81475c Iustin Pop
608 6d81475c Iustin Pop
609 6d81475c Iustin Pop
610 c71a1a3d Iustin Pop
If the optional 'bulk' argument is provided and set to 'true' value (i.e
611 c71a1a3d Iustin Pop
'?bulk=1'), the output contains detailed information about nodes as a
612 c71a1a3d Iustin Pop
613 6d81475c Iustin Pop
614 c8e0a534 Iustin Pop
615 6d81475c Iustin Pop
616 6d81475c Iustin Pop
617 6d81475c Iustin Pop
618 6d81475c Iustin Pop
        "pinst_cnt": 1,
619 6d81475c Iustin Pop
        "mfree": 31280,
620 6d81475c Iustin Pop
        "mtotal": 32763,
621 6d81475c Iustin Pop
        "name": "",
622 6d81475c Iustin Pop
        "tags": [],
623 6d81475c Iustin Pop
        "mnode": 512,
624 6d81475c Iustin Pop
        "dtotal": 5246208,
625 6d81475c Iustin Pop
        "sinst_cnt": 2,
626 6d81475c Iustin Pop
        "dfree": 5171712,
627 6d81475c Iustin Pop
        "offline": false
628 6d81475c Iustin Pop
629 6d81475c Iustin Pop
630 6d81475c Iustin Pop
631 6d81475c Iustin Pop
632 f72542cc Michael Hanselmann
633 f72542cc Michael Hanselmann
634 f72542cc Michael Hanselmann
635 f72542cc Michael Hanselmann
Returns information about a node.
636 f72542cc Michael Hanselmann
637 f72542cc Michael Hanselmann
It supports the following commands: ``GET``.
638 f72542cc Michael Hanselmann
639 73452f12 Michael Hanselmann
640 73452f12 Michael Hanselmann
641 73452f12 Michael Hanselmann
642 73452f12 Michael Hanselmann
Evacuates all secondary instances off a node.
643 73452f12 Michael Hanselmann
644 73452f12 Michael Hanselmann
It supports the following commands: ``POST``.
645 73452f12 Michael Hanselmann
646 73452f12 Michael Hanselmann
647 73452f12 Michael Hanselmann
648 73452f12 Michael Hanselmann
649 73452f12 Michael Hanselmann
To evacuate a node, either one of the ``iallocator`` or ``remote_node``
650 73452f12 Michael Hanselmann
parameters must be passed:
651 73452f12 Michael Hanselmann
652 73452f12 Michael Hanselmann
653 73452f12 Michael Hanselmann
654 73452f12 Michael Hanselmann
655 1c482bab Michael Hanselmann
656 1c482bab Michael Hanselmann
657 1c482bab Michael Hanselmann
658 1c482bab Michael Hanselmann
Migrates all primary instances from a node.
659 1c482bab Michael Hanselmann
660 1c482bab Michael Hanselmann
It supports the following commands: ``POST``.
661 1c482bab Michael Hanselmann
662 1c482bab Michael Hanselmann
663 1c482bab Michael Hanselmann
664 1c482bab Michael Hanselmann
665 1c482bab Michael Hanselmann
No parameters are required, but ``live`` can be set to a boolean value.
666 1c482bab Michael Hanselmann
667 1c482bab Michael Hanselmann
668 1c482bab Michael Hanselmann
669 64dae8fc Michael Hanselmann
670 64dae8fc Michael Hanselmann
671 64dae8fc Michael Hanselmann
672 64dae8fc Michael Hanselmann
Manages node role.
673 64dae8fc Michael Hanselmann
674 64dae8fc Michael Hanselmann
It supports the following commands: ``GET``, ``PUT``.
675 64dae8fc Michael Hanselmann
676 64dae8fc Michael Hanselmann
The role is always one of the following:
677 64dae8fc Michael Hanselmann
678 64dae8fc Michael Hanselmann
  - drained
679 64dae8fc Michael Hanselmann
  - master
680 64dae8fc Michael Hanselmann
  - master-candidate
681 64dae8fc Michael Hanselmann
  - offline
682 64dae8fc Michael Hanselmann
  - regular
683 64dae8fc Michael Hanselmann
684 64dae8fc Michael Hanselmann
685 64dae8fc Michael Hanselmann
686 64dae8fc Michael Hanselmann
687 64dae8fc Michael Hanselmann
Returns the current node role.
688 64dae8fc Michael Hanselmann
689 64dae8fc Michael Hanselmann
690 64dae8fc Michael Hanselmann
691 64dae8fc Michael Hanselmann
692 64dae8fc Michael Hanselmann
693 64dae8fc Michael Hanselmann
694 64dae8fc Michael Hanselmann
695 64dae8fc Michael Hanselmann
696 64dae8fc Michael Hanselmann
Change the node role.
697 64dae8fc Michael Hanselmann
698 7faf5110 Michael Hanselmann
The request is a string which should be PUT to this URI. The result will
699 7faf5110 Michael Hanselmann
be a job id.
700 64dae8fc Michael Hanselmann
701 64dae8fc Michael Hanselmann
It supports the ``force`` argument.
702 64dae8fc Michael Hanselmann
703 7a95a954 Michael Hanselmann
704 7a95a954 Michael Hanselmann
705 7a95a954 Michael Hanselmann
706 7a95a954 Michael Hanselmann
Manages storage units on the node.
707 7a95a954 Michael Hanselmann
708 7a95a954 Michael Hanselmann
709 7a95a954 Michael Hanselmann
710 7a95a954 Michael Hanselmann
711 7a95a954 Michael Hanselmann
Requests a list of storage units on a node. Requires the parameters
712 7a95a954 Michael Hanselmann
``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
713 7faf5110 Michael Hanselmann
``output_fields``. The result will be a job id, using which the result
714 7faf5110 Michael Hanselmann
can be retrieved.
715 7a95a954 Michael Hanselmann
716 1e82bc80 Michael Hanselmann
717 1e82bc80 Michael Hanselmann
718 1e82bc80 Michael Hanselmann
719 1e82bc80 Michael Hanselmann
Modifies storage units on the node.
720 1e82bc80 Michael Hanselmann
721 1e82bc80 Michael Hanselmann
722 1e82bc80 Michael Hanselmann
723 1e82bc80 Michael Hanselmann
724 7faf5110 Michael Hanselmann
Modifies parameters of storage units on the node. Requires the
725 7faf5110 Michael Hanselmann
parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
726 7faf5110 Michael Hanselmann
and ``name`` (name of the storage unit).  Parameters can be passed
727 7faf5110 Michael Hanselmann
additionally. Currently only ``allocatable`` (bool) is supported. The
728 7faf5110 Michael Hanselmann
result will be a job id.
729 1e82bc80 Michael Hanselmann
730 723f4565 Michael Hanselmann
731 723f4565 Michael Hanselmann
732 723f4565 Michael Hanselmann
733 723f4565 Michael Hanselmann
Repairs a storage unit on the node.
734 723f4565 Michael Hanselmann
735 723f4565 Michael Hanselmann
736 723f4565 Michael Hanselmann
737 723f4565 Michael Hanselmann
738 7faf5110 Michael Hanselmann
Repairs a storage unit on the node. Requires the parameters
739 7faf5110 Michael Hanselmann
``storage_type`` (currently only ``lvm-vg`` can be repaired) and
740 7faf5110 Michael Hanselmann
``name`` (name of the storage unit). The result will be a job id.
741 723f4565 Michael Hanselmann
742 c8e0a534 Iustin Pop
743 c8e0a534 Iustin Pop
744 6d81475c Iustin Pop
745 c8e0a534 Iustin Pop
Manages per-node tags.
746 6d81475c Iustin Pop
747 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
748 6d81475c Iustin Pop
749 c8e0a534 Iustin Pop
750 c8e0a534 Iustin Pop
751 6d81475c Iustin Pop
752 c8e0a534 Iustin Pop
Returns a list of tags.
753 6d81475c Iustin Pop
754 c8e0a534 Iustin Pop
755 6d81475c Iustin Pop
756 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
757 6d81475c Iustin Pop
758 c8e0a534 Iustin Pop
759 c8e0a534 Iustin Pop
760 6d81475c Iustin Pop
761 c8e0a534 Iustin Pop
Add a set of tags.
762 6d81475c Iustin Pop
763 c8e0a534 Iustin Pop
The request as a list of strings should be PUT to this URI. The result
764 c8e0a534 Iustin Pop
will be a job id.
765 6d81475c Iustin Pop
766 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
767 2cad4b91 Iustin Pop
768 c8e0a534 Iustin Pop
769 c8e0a534 Iustin Pop
770 6d81475c Iustin Pop
771 c8e0a534 Iustin Pop
Deletes tags.
772 6d81475c Iustin Pop
773 c71a1a3d Iustin Pop
In order to delete a set of tags, the DELETE request should be addressed
774 c71a1a3d Iustin Pop
to URI like::
775 6d81475c Iustin Pop
776 c8e0a534 Iustin Pop
777 6d81475c Iustin Pop
778 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
779 2cad4b91 Iustin Pop
780 2cad4b91 Iustin Pop
781 c8e0a534 Iustin Pop
782 c8e0a534 Iustin Pop
783 6d81475c Iustin Pop
784 c8e0a534 Iustin Pop
OS resource.
785 6d81475c Iustin Pop
786 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
787 6d81475c Iustin Pop
788 c8e0a534 Iustin Pop
789 c8e0a534 Iustin Pop
790 6d81475c Iustin Pop
791 c8e0a534 Iustin Pop
Return a list of all OSes.
792 6d81475c Iustin Pop
793 c8e0a534 Iustin Pop
Can return error 500 in case of a problem. Since this is a costly
794 c71a1a3d Iustin Pop
operation for Ganeti 2.0, it is not recommended to execute it too often.
795 6d81475c Iustin Pop
796 c8e0a534 Iustin Pop
797 6d81475c Iustin Pop
798 c8e0a534 Iustin Pop
799 6d81475c Iustin Pop
800 c8e0a534 Iustin Pop
801 c8e0a534 Iustin Pop
802 6d81475c Iustin Pop
803 c8e0a534 Iustin Pop
Manages cluster tags.
804 6d81475c Iustin Pop
805 c8e0a534 Iustin Pop
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
806 6d81475c Iustin Pop
807 c8e0a534 Iustin Pop
808 c8e0a534 Iustin Pop
809 6d81475c Iustin Pop
810 c8e0a534 Iustin Pop
Returns the cluster tags.
811 6d81475c Iustin Pop
812 c8e0a534 Iustin Pop
813 6d81475c Iustin Pop
814 c8e0a534 Iustin Pop
    ["tag1", "tag2", "tag3"]
815 6d81475c Iustin Pop
816 c8e0a534 Iustin Pop
817 c8e0a534 Iustin Pop
818 6d81475c Iustin Pop
819 c8e0a534 Iustin Pop
Adds a set of tags.
820 6d81475c Iustin Pop
821 c8e0a534 Iustin Pop
The request as a list of strings should be PUT to this URI. The result
822 c8e0a534 Iustin Pop
will be a job id.
823 6d81475c Iustin Pop
824 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
825 2cad4b91 Iustin Pop
826 2cad4b91 Iustin Pop
827 c8e0a534 Iustin Pop
828 c8e0a534 Iustin Pop
829 6d81475c Iustin Pop
830 c8e0a534 Iustin Pop
Deletes tags.
831 6d81475c Iustin Pop
832 c71a1a3d Iustin Pop
In order to delete a set of tags, the DELETE request should be addressed
833 c71a1a3d Iustin Pop
to URI like::
834 6d81475c Iustin Pop
835 c8e0a534 Iustin Pop
836 6d81475c Iustin Pop
837 2cad4b91 Iustin Pop
It supports the ``dry-run`` argument.
838 2cad4b91 Iustin Pop
839 2cad4b91 Iustin Pop
840 c8e0a534 Iustin Pop
841 c8e0a534 Iustin Pop
842 6d81475c Iustin Pop
843 c8e0a534 Iustin Pop
The version resource.
844 6d81475c Iustin Pop
845 c71a1a3d Iustin Pop
This resource should be used to determine the remote API version and to
846 c71a1a3d Iustin Pop
adapt clients accordingly.
847 6d81475c Iustin Pop
848 c8e0a534 Iustin Pop
It supports the following commands: ``GET``.
849 6d81475c Iustin Pop
850 c8e0a534 Iustin Pop
851 c8e0a534 Iustin Pop
852 6d81475c Iustin Pop
853 c71a1a3d Iustin Pop
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
854 c71a1a3d Iustin Pop
returns ``2``.
855 558fd122 Michael Hanselmann
856 558fd122 Michael Hanselmann
.. vim: set textwidth=72 :
857 c71a1a3d Iustin Pop
.. Local Variables:
858 c71a1a3d Iustin Pop
.. mode: rst
859 c71a1a3d Iustin Pop
.. fill-column: 72
860 c71a1a3d Iustin Pop
.. End: