rapi.rst 23.5 KB
Newer Older
1
2
3
Ganeti remote API
=================

Iustin Pop's avatar
Iustin Pop committed
4
Documents Ganeti version |version|
5
6
7
8
9
10
11
12
13
14
15
16
17
18

.. contents::

Introduction
------------

Ganeti supports a remote API for enable external tools to easily
retrieve information about a cluster's state. The remote API daemon,
*ganeti-rapi*, is automatically started on the master node. By default
it runs on TCP port 5080, but this can be changed either in
``.../constants.py`` or via the command line parameter *-p*. SSL mode,
which is used by default, can also be disabled by passing command line
parameters.

19
20
21
22
23
24
25
26
27
28
29
30

Users and passwords
-------------------

``ganeti-rapi`` reads users and passwords from a file (usually
``/var/lib/ganeti/rapi_users``) on startup. After modifying the password
file, ``ganeti-rapi`` must be restarted.

Each line consists of two or three fields separated by whitespace. The
first two fields are for username and password. The third field is
optional and can be used to specify per-user options. Currently,
``write`` is the only option supported and enables the user to execute
31
32
operations modifying the cluster. Lines starting with the hash sign
(``#``) are treated as comments.
33
34
35
36
37

Passwords can either be written in clear text or as a hash. Clear text
passwords may not start with an opening brace (``{``) or they must be
prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash
of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n
38
39
40
'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix
it with ``{ha1}``. Using the scheme prefix for all passwords is
recommended. Scheme prefixes are not case sensitive.
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

Example::

  # Give Jack and Fred read-only access
  jack abc123
  fred {cleartext}foo555

  # Give write access to an imaginary instance creation script
  autocreator xyz789 write

  # Hashed password for Jessica
  jessica {HA1}7046452df2cbb530877058712cf17bd4 write


.. [#pwhash] Using the MD5 hash of username, realm and password is
   described in RFC2617_ ("HTTP Authentication"), sections 3.2.2.2 and
   3.3. The reason for using it over another algorithm is forward
   compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
   authentication in the future, the same hash could be used.
   In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
   API``, can only be changed by modifying the source code.


64
65
66
Protocol
--------

67
68
The protocol used is JSON_ over HTTP designed after the REST_ principle.
HTTP Basic authentication as per RFC2617_ is supported.
69
70
71

.. _JSON: http://www.json.org/
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
72
.. _RFC2617: http://tools.ietf.org/rfc/rfc2617.txt
73

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

PUT or POST?
------------

According to RFC2616 the main difference between PUT and POST is that
POST can create new resources but PUT can only create the resource the
URI was pointing to on the PUT request.

Unfortunately, due to historic reasons, the Ganeti RAPI library is not
consistent with this usage, so just use the methods as documented below
for each resource.

For more details have a look in the source code at
``lib/rapi/rlib2.py``.


Generic parameter types
-----------------------

A few generic refered parameter types and the values they allow.

``bool``
++++++++

A boolean option will accept ``1`` or ``0`` as numbers but not
i.e. ``True`` or ``False``.

101
102
103
Generic parameters
------------------

104
105
A few parameter mean the same thing across all resources which implement
it.
106
107
108
109

``bulk``
++++++++

Iustin Pop's avatar
Iustin Pop committed
110
111
112
113
114
Bulk-mode means that for the resources which usually return just a list
of child resources (e.g. ``/2/instances`` which returns just instance
names), the output will instead contain detailed data for all these
subresources. This is more efficient than query-ing the sub-resources
themselves.
115
116
117
118

``dry-run``
+++++++++++

119
120
121
The boolean *dry-run* argument, if provided and set, signals to Ganeti
that the job should not be executed, only the pre-execution checks will
be done.
122

Iustin Pop's avatar
Iustin Pop committed
123
124
125
This is useful in trying to determine (without guarantees though, as in
the meantime the cluster state could have changed) if the operation is
likely to succeed or at least start executing.
126

127
128
129
130
131
132
``force``
+++++++++++

Force operation to continue even if it will cause the cluster to become
inconsistent (e.g. because there are not enough master candidates).

133
134
135
Usage examples
--------------

Iustin Pop's avatar
Iustin Pop committed
136
137
You can access the API using your favorite programming language as long
as it supports network connections.
138

139
140
141
142
143
Ganeti RAPI client
++++++++++++++++++

Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.

144
145
146
Shell
+++++

Iustin Pop's avatar
Iustin Pop committed
147
148
.. highlight:: sh

149
150
Using wget::

Iustin Pop's avatar
Iustin Pop committed
151
   wget -q -O - https://CLUSTERNAME:5080/2/info
152
153
154
155
156
157
158
159
160

or curl::

  curl https://CLUSTERNAME:5080/2/info


Python
++++++

Iustin Pop's avatar
Iustin Pop committed
161
162
163
.. highlight:: python

::
164
165

  import urllib2
Tim Boring's avatar
Tim Boring committed
166
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
167
168
169
170
171
172
  print f.read()


JavaScript
++++++++++

173
.. warning:: While it's possible to use JavaScript, it poses several
Iustin Pop's avatar
Iustin Pop committed
174
175
176
   potential problems, including browser blocking request due to
   non-standard ports or different domain names. Fetching the data on
   the webserver is easier.
177

Iustin Pop's avatar
Iustin Pop committed
178
179
.. highlight:: javascript

180
181
::

Tim Boring's avatar
Tim Boring committed
182
  var url = 'https://CLUSTERNAME:5080/2/info';
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
  var info;
  var xmlreq = new XMLHttpRequest();
  xmlreq.onreadystatechange = function () {
    if (xmlreq.readyState != 4) return;
    if (xmlreq.status == 200) {
      info = eval("(" + xmlreq.responseText + ")");
      alert(info);
    } else {
      alert('Error fetching cluster info');
    }
    xmlreq = null;
  };
  xmlreq.open('GET', url, true);
  xmlreq.send(null);

Resources
---------

Iustin Pop's avatar
Iustin Pop committed
201
.. highlight:: javascript
202

Iustin Pop's avatar
Iustin Pop committed
203
204
``/``
+++++
205

Iustin Pop's avatar
Iustin Pop committed
206
The root resource.
207

Iustin Pop's avatar
Iustin Pop committed
208
It supports the following commands: ``GET``.
209

Iustin Pop's avatar
Iustin Pop committed
210
211
``GET``
~~~~~~~
212

Iustin Pop's avatar
Iustin Pop committed
213
Shows the list of mapped resources.
214

Iustin Pop's avatar
Iustin Pop committed
215
Returns: a dictionary with 'name' and 'uri' keys for each of them.
216

Iustin Pop's avatar
Iustin Pop committed
217
218
``/2``
++++++
219

Iustin Pop's avatar
Iustin Pop committed
220
The ``/2`` resource, the root of the version 2 API.
221

Iustin Pop's avatar
Iustin Pop committed
222
It supports the following commands: ``GET``.
223

Iustin Pop's avatar
Iustin Pop committed
224
225
``GET``
~~~~~~~
226

Iustin Pop's avatar
Iustin Pop committed
227
Show the list of mapped resources.
228

Iustin Pop's avatar
Iustin Pop committed
229
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
230

Iustin Pop's avatar
Iustin Pop committed
231
232
``/2/info``
+++++++++++
233

Iustin Pop's avatar
Iustin Pop committed
234
Cluster information resource.
235

Iustin Pop's avatar
Iustin Pop committed
236
It supports the following commands: ``GET``.
237

Iustin Pop's avatar
Iustin Pop committed
238
239
``GET``
~~~~~~~
240

Iustin Pop's avatar
Iustin Pop committed
241
Returns cluster information.
242

Iustin Pop's avatar
Iustin Pop committed
243
Example::
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273

  {
    "config_version": 2000000,
    "name": "cluster",
    "software_version": "2.0.0~beta2",
    "os_api_version": 10,
    "export_version": 0,
    "candidate_pool_size": 10,
    "enabled_hypervisors": [
      "fake"
    ],
    "hvparams": {
      "fake": {}
     },
    "default_hypervisor": "fake",
    "master": "node1.example.com",
    "architecture": [
      "64bit",
      "x86_64"
    ],
    "protocol_version": 20,
    "beparams": {
      "default": {
        "auto_balance": true,
        "vcpus": 1,
        "memory": 128
       }
      }
    }

274
275
276
277
278
279
280
281
282
283
284
285
286
287

``/2/redistribute-config``
++++++++++++++++++++++++++

Redistribute configuration to all nodes.

It supports the following commands: ``PUT``.

``PUT``
~~~~~~~

Redistribute configuration to all nodes. The result will be a job id.


288
289
290
291
292
293
294
295
296
297
298
299
300
``/2/features``
+++++++++++++++

``GET``
~~~~~~~

Returns a list of features supported by the RAPI server. Available
features:

``instance-create-reqv1``
  Instance creation request data version 1 supported.


Iustin Pop's avatar
Iustin Pop committed
301
302
``/2/instances``
++++++++++++++++
303

Iustin Pop's avatar
Iustin Pop committed
304
The instances resource.
305

Iustin Pop's avatar
Iustin Pop committed
306
It supports the following commands: ``GET``, ``POST``.
307

Iustin Pop's avatar
Iustin Pop committed
308
309
``GET``
~~~~~~~
310

Iustin Pop's avatar
Iustin Pop committed
311
Returns a list of all available instances.
312

Iustin Pop's avatar
Iustin Pop committed
313
Example::
314
315
316
317
318
319
320
321
322
323
324
325

    [
      {
        "name": "web.example.com",
        "uri": "\/instances\/web.example.com"
      },
      {
        "name": "mail.example.com",
        "uri": "\/instances\/mail.example.com"
      }
    ]

326
327
328
If the optional bool *bulk* argument is provided and set to a true value
(i.e ``?bulk=1``), the output contains detailed information about
instances as a list.
329

Iustin Pop's avatar
Iustin Pop committed
330
Example::
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359

    [
      {
         "status": "running",
         "disk_usage": 20480,
         "nic.bridges": [
           "xen-br0"
          ],
         "name": "web.example.com",
         "tags": ["tag1", "tag2"],
         "beparams": {
           "vcpus": 2,
           "memory": 512
         },
         "disk.sizes": [
             20480
         ],
         "pnode": "node1.example.com",
         "nic.macs": ["01:23:45:67:89:01"],
         "snodes": ["node2.example.com"],
         "disk_template": "drbd",
         "admin_state": true,
         "os": "debian-etch",
         "oper_state": true
      },
      ...
    ]


Iustin Pop's avatar
Iustin Pop committed
360
361
``POST``
~~~~~~~~
362

Iustin Pop's avatar
Iustin Pop committed
363
Creates an instance.
364

365
366
367
368
If the optional bool *dry-run* argument is provided, the job will not be
actually executed, only the pre-execution checks will be done. Query-ing
the job result will return, in both dry-run and normal case, the list of
nodes selected for the instance.
369

Iustin Pop's avatar
Iustin Pop committed
370
Returns: a job ID that can be used later for polling.
371

372
373
374
375
376
377
Body parameters:

``__version__`` (int, required)
  Must be ``1`` (older Ganeti versions used a different format for
  instance creation requests, version ``0``, but that format is not
  documented).
378
379
``mode``
  Instance creation mode (string, required).
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
``name`` (string, required)
  Instance name
``disk_template`` (string, required)
  Disk template for instance
``disks`` (list, required)
  List of disk definitions. Example: ``[{"size": 100}, {"size": 5}]``.
  Each disk definition must contain a ``size`` value and can contain an
  optional ``mode`` value denoting the disk access mode (``ro`` or
  ``rw``).
``nics`` (list, required)
  List of NIC (network interface) definitions. Example: ``[{}, {},
  {"ip": "1.2.3.4"}]``. Each NIC definition can contain the optional
  values ``ip``, ``mode``, ``link`` and ``bridge``.
``os`` (string)
  Instance operating system.
``force_variant`` (bool)
  Whether to force an unknown variant.
``pnode`` (string)
  Primary node.
``snode`` (string)
  Secondary node.
``src_node`` (string)
  Source node for import.
``src_path`` (string)
  Source directory for import.
``start`` (bool)
  Whether to start instance after creation.
``ip_check`` (bool)
  Whether to ensure instance's IP address is inactive.
``name_check`` (bool)
  Whether to ensure instance's name is resolvable.
``file_storage_dir`` (string)
  File storage directory.
``file_driver`` (string)
  File storage driver.
``iallocator`` (string)
  Instance allocator name.
417
418
419
420
421
422
``source_handshake``
  Signed handshake from source (remote import only).
``source_x509_ca`` (string)
  Source X509 CA in PEM format (remote import only).
``source_instance_name`` (string)
  Source instance name (remote import only).
423
424
425
426
427
428
429
430
``hypervisor`` (string)
  Hypervisor name.
``hvparams`` (dict)
  Hypervisor parameters, hypervisor-dependent.
``beparams``
  Backend parameters.


Iustin Pop's avatar
Iustin Pop committed
431
432
``/2/instances/[instance_name]``
++++++++++++++++++++++++++++++++
433

Iustin Pop's avatar
Iustin Pop committed
434
Instance-specific resource.
435

Iustin Pop's avatar
Iustin Pop committed
436
It supports the following commands: ``GET``, ``DELETE``.
437

Iustin Pop's avatar
Iustin Pop committed
438
439
``GET``
~~~~~~~
440

Iustin Pop's avatar
Iustin Pop committed
441
442
Returns information about an instance, similar to the bulk output from
the instance list.
443

Iustin Pop's avatar
Iustin Pop committed
444
445
``DELETE``
~~~~~~~~~~
446

Iustin Pop's avatar
Iustin Pop committed
447
Deletes an instance.
448

449
450
It supports the ``dry-run`` argument.

451

452
453
454
455
456
457
458
459
460
461
``/2/instances/[instance_name]/info``
+++++++++++++++++++++++++++++++++++++++

It supports the following commands: ``GET``.

``GET``
~~~~~~~

Requests detailed information about the instance. An optional parameter,
``static`` (bool), can be set to return only static information from the
462
463
configuration without querying the instance's nodes. The result will be
a job id.
464
465


Iustin Pop's avatar
Iustin Pop committed
466
467
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
468

Iustin Pop's avatar
Iustin Pop committed
469
Reboots URI for an instance.
470

Iustin Pop's avatar
Iustin Pop committed
471
It supports the following commands: ``POST``.
472

Iustin Pop's avatar
Iustin Pop committed
473
474
``POST``
~~~~~~~~
475

Iustin Pop's avatar
Iustin Pop committed
476
Reboots the instance.
477

478
479
480
481
482
483
484
485
486
487
488
489
The URI takes optional ``type=soft|hard|full`` and
``ignore_secondaries=0|1`` parameters.

``type`` defines the reboot type. ``soft`` is just a normal reboot,
without terminating the hypervisor. ``hard`` means full shutdown
(including terminating the hypervisor process) and startup again.
``full`` is like ``hard`` but also recreates the configuration from
ground up as if you would have done a ``gnt-instance shutdown`` and
``gnt-instance start`` on it.

``ignore_secondaries`` is a bool argument indicating if we start the
instance even if secondary disks are failing.
490

491
492
493
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
494
495
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
496

Iustin Pop's avatar
Iustin Pop committed
497
Instance shutdown URI.
498

Iustin Pop's avatar
Iustin Pop committed
499
It supports the following commands: ``PUT``.
500

Iustin Pop's avatar
Iustin Pop committed
501
502
``PUT``
~~~~~~~
503

Iustin Pop's avatar
Iustin Pop committed
504
Shutdowns an instance.
505

506
507
It supports the ``dry-run`` argument.

508

Iustin Pop's avatar
Iustin Pop committed
509
510
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
511

Iustin Pop's avatar
Iustin Pop committed
512
Instance startup URI.
513

Iustin Pop's avatar
Iustin Pop committed
514
It supports the following commands: ``PUT``.
515

Iustin Pop's avatar
Iustin Pop committed
516
517
``PUT``
~~~~~~~
518

Iustin Pop's avatar
Iustin Pop committed
519
Startup an instance.
520

521
522
The URI takes an optional ``force=1|0`` parameter to start the
instance even if secondary disks are failing.
523

524
525
It supports the ``dry-run`` argument.

526
527
528
529
530
531
532
533
534
535
536
537
``/2/instances/[instance_name]/reinstall``
++++++++++++++++++++++++++++++++++++++++++++++

Installs the operating system again.

It supports the following commands: ``POST``.

``POST``
~~~~~~~~

Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).

538

539
540
541
542
543
544
545
546
547
548
549
``/2/instances/[instance_name]/replace-disks``
++++++++++++++++++++++++++++++++++++++++++++++

Replaces disks on an instance.

It supports the following commands: ``POST``.

``POST``
~~~~~~~~

Takes the parameters ``mode`` (one of ``replace_on_primary``,
550
551
552
``replace_on_secondary``, ``replace_new_secondary`` or
``replace_auto``), ``disks`` (comma separated list of disk indexes),
``remote_node`` and ``iallocator``.
553

554
555
556
557
558
559
Either ``remote_node`` or ``iallocator`` needs to be defined when using
``mode=replace_new_secondary``.

``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
the broken disk(s) on its own and replacing it.

560

561
562
563
564
565
566
567
568
569
570
``/2/instances/[instance_name]/activate-disks``
+++++++++++++++++++++++++++++++++++++++++++++++

Activate disks on an instance.

It supports the following commands: ``PUT``.

``PUT``
~~~~~~~

571
Takes the bool parameter ``ignore_size``. When set ignore the recorded
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
size (useful for forcing activation when recorded size is wrong).


``/2/instances/[instance_name]/deactivate-disks``
+++++++++++++++++++++++++++++++++++++++++++++++++

Deactivate disks on an instance.

It supports the following commands: ``PUT``.

``PUT``
~~~~~~~

Takes no parameters.


588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
``/2/instances/[instance_name]/prepare-export``
+++++++++++++++++++++++++++++++++++++++++++++++++

Prepares an export of an instance.

It supports the following commands: ``PUT``.

``PUT``
~~~~~~~

Takes one parameter, ``mode``, for the export mode. Returns a job ID.


``/2/instances/[instance_name]/export``
+++++++++++++++++++++++++++++++++++++++++++++++++

Exports an instance.

It supports the following commands: ``PUT``.

``PUT``
~~~~~~~

Returns a job ID.

Body parameters:

``mode`` (string)
  Export mode.
``destination`` (required)
  Destination information, depends on export mode.
``shutdown`` (bool, required)
  Whether to shutdown instance before export.
``remove_instance`` (bool)
  Whether to remove instance after export.
``x509_key_name``
  Name of X509 key (remote export only).
``destination_x509_ca``
  Destination X509 CA (remote export only).


Iustin Pop's avatar
Iustin Pop committed
629
630
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
631

Iustin Pop's avatar
Iustin Pop committed
632
Manages per-instance tags.
633

Iustin Pop's avatar
Iustin Pop committed
634
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
635

Iustin Pop's avatar
Iustin Pop committed
636
637
``GET``
~~~~~~~
638

Iustin Pop's avatar
Iustin Pop committed
639
Returns a list of tags.
640

Iustin Pop's avatar
Iustin Pop committed
641
Example::
642

Iustin Pop's avatar
Iustin Pop committed
643
    ["tag1", "tag2", "tag3"]
644

Iustin Pop's avatar
Iustin Pop committed
645
646
``PUT``
~~~~~~~
647

Iustin Pop's avatar
Iustin Pop committed
648
Add a set of tags.
649

Iustin Pop's avatar
Iustin Pop committed
650
The request as a list of strings should be ``PUT`` to this URI. The
651
result will be a job id.
652

653
654
655
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
656
657
``DELETE``
~~~~~~~~~~
658

Iustin Pop's avatar
Iustin Pop committed
659
Delete a tag.
660

Iustin Pop's avatar
Iustin Pop committed
661
662
In order to delete a set of tags, the DELETE request should be addressed
to URI like::
663

Iustin Pop's avatar
Iustin Pop committed
664
    /tags?tag=[tag]&tag=[tag]
665

666
667
668
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
669
670
``/2/jobs``
+++++++++++
671

Iustin Pop's avatar
Iustin Pop committed
672
The ``/2/jobs`` resource.
673

Iustin Pop's avatar
Iustin Pop committed
674
It supports the following commands: ``GET``.
675

Iustin Pop's avatar
Iustin Pop committed
676
677
``GET``
~~~~~~~
678

Iustin Pop's avatar
Iustin Pop committed
679
Returns a dictionary of jobs.
680

Iustin Pop's avatar
Iustin Pop committed
681
Returns: a dictionary with jobs id and uri.
682

Iustin Pop's avatar
Iustin Pop committed
683
684
``/2/jobs/[job_id]``
++++++++++++++++++++
685
686


Iustin Pop's avatar
Iustin Pop committed
687
Individual job URI.
688

Iustin Pop's avatar
Iustin Pop committed
689
It supports the following commands: ``GET``, ``DELETE``.
690

Iustin Pop's avatar
Iustin Pop committed
691
692
``GET``
~~~~~~~
693

Iustin Pop's avatar
Iustin Pop committed
694
Returns a job status.
695

Iustin Pop's avatar
Iustin Pop committed
696
Returns: a dictionary with job parameters.
697

Iustin Pop's avatar
Iustin Pop committed
698
The result includes:
699

Iustin Pop's avatar
Iustin Pop committed
700
701
- id: job ID as a number
- status: current job status as a string
Iustin Pop's avatar
Iustin Pop committed
702
703
- ops: involved OpCodes as a list of dictionaries for each opcodes in
  the job
Iustin Pop's avatar
Iustin Pop committed
704
- opstatus: OpCodes status as a list
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
- opresult: OpCodes results as a list

For a successful opcode, the ``opresult`` field corresponding to it will
contain the raw result from its :term:`LogicalUnit`. In case an opcode
has failed, its element in the opresult list will be a list of two
elements:

- first element the error type (the Ganeti internal error name)
- second element a list of either one or two elements:

  - the first element is the textual error description
  - the second element, if any, will hold an error classification

The error classification is most useful for the ``OpPrereqError``
error type - these errors happen before the OpCode has started
executing, so it's possible to retry the OpCode without side
effects. But whether it make sense to retry depends on the error
classification:

``resolver_error``
  Resolver errors. This usually means that a name doesn't exist in DNS,
  so if it's a case of slow DNS propagation the operation can be retried
  later.

``insufficient_resources``
  Not enough resources (iallocator failure, disk space, memory,
  etc.). If the resources on the cluster increase, the operation might
  succeed.

``wrong_input``
  Wrong arguments (at syntax level). The operation will not ever be
  accepted unless the arguments change.

``wrong_state``
  Wrong entity state. For example, live migration has been requested for
  a down instance, or instance creation on an offline node. The
  operation can be retried once the resource has changed state.

``unknown_entity``
  Entity not found. For example, information has been requested for an
  unknown instance.

``already_exists``
  Entity already exists. For example, instance creation has been
  requested for an already-existing instance.

``resource_not_unique``
  Resource not unique (e.g. MAC or IP duplication).

``internal_error``
  Internal cluster error. For example, a node is unreachable but not set
  offline, or the ganeti node daemons are not working, etc. A
  ``gnt-cluster verify`` should be run.

``environment_error``
  Environment error (e.g. node disk error). A ``gnt-cluster verify``
  should be run.

Note that in the above list, by entity we refer to a node or instance,
while by a resource we refer to an instance's disk, or NIC, etc.

766

Iustin Pop's avatar
Iustin Pop committed
767
768
``DELETE``
~~~~~~~~~~
769

Iustin Pop's avatar
Iustin Pop committed
770
Cancel a not-yet-started job.
771

772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795

``/2/jobs/[job_id]/wait``
+++++++++++++++++++++++++

``GET``
~~~~~~~

Waits for changes on a job. Takes the following body parameters in a
dict:

``fields``
  The job fields on which to watch for changes.

``previous_job_info``
  Previously received field values or None if not yet available.

``previous_log_serial``
  Highest log serial number received so far or None if not yet
  available.

Returns None if no changes have been detected and a dict with two keys,
``job_info`` and ``log_entries`` otherwise.


Iustin Pop's avatar
Iustin Pop committed
796
797
``/2/nodes``
++++++++++++
798

Iustin Pop's avatar
Iustin Pop committed
799
Nodes resource.
800

Iustin Pop's avatar
Iustin Pop committed
801
It supports the following commands: ``GET``.
802

Iustin Pop's avatar
Iustin Pop committed
803
804
``GET``
~~~~~~~
805

Iustin Pop's avatar
Iustin Pop committed
806
Returns a list of all nodes.
807

Iustin Pop's avatar
Iustin Pop committed
808
Example::
809
810
811
812

    [
      {
        "id": "node1.example.com",
Iustin Pop's avatar
Iustin Pop committed
813
        "uri": "\/nodes\/node1.example.com"
814
815
816
      },
      {
        "id": "node2.example.com",
Iustin Pop's avatar
Iustin Pop committed
817
        "uri": "\/nodes\/node2.example.com"
818
819
820
      }
    ]

Iustin Pop's avatar
Iustin Pop committed
821
822
823
If the optional 'bulk' argument is provided and set to 'true' value (i.e
'?bulk=1'), the output contains detailed information about nodes as a
list.
824

Iustin Pop's avatar
Iustin Pop committed
825
Example::
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842

    [
      {
        "pinst_cnt": 1,
        "mfree": 31280,
        "mtotal": 32763,
        "name": "www.example.com",
        "tags": [],
        "mnode": 512,
        "dtotal": 5246208,
        "sinst_cnt": 2,
        "dfree": 5171712,
        "offline": false
      },
      ...
    ]

843
844
845
846
847
848
849
``/2/nodes/[node_name]``
+++++++++++++++++++++++++++++++++

Returns information about a node.

It supports the following commands: ``GET``.

850
851
852
853
854
855
856
857
858
859
860
``/2/nodes/[node_name]/evacuate``
+++++++++++++++++++++++++++++++++

Evacuates all secondary instances off a node.

It supports the following commands: ``POST``.

``POST``
~~~~~~~~

To evacuate a node, either one of the ``iallocator`` or ``remote_node``
861
parameters must be passed::
862
863
864
865

    evacuate?iallocator=[iallocator]
    evacuate?remote_node=[nodeX.example.com]

866
867
868
869
870
871
872
873
874
875
``/2/nodes/[node_name]/migrate``
+++++++++++++++++++++++++++++++++

Migrates all primary instances from a node.

It supports the following commands: ``POST``.

``POST``
~~~~~~~~

876
877
No parameters are required, but the bool parameter ``live`` can be set
to use live migration (if available).
878
879
880

    migrate?live=[0|1]

881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
``/2/nodes/[node_name]/role``
+++++++++++++++++++++++++++++

Manages node role.

It supports the following commands: ``GET``, ``PUT``.

The role is always one of the following:

  - drained
  - master
  - master-candidate
  - offline
  - regular

``GET``
~~~~~~~

Returns the current node role.

Example::

    "master-candidate"

``PUT``
~~~~~~~

Change the node role.

910
911
The request is a string which should be PUT to this URI. The result will
be a job id.
912

913
It supports the bool ``force`` argument.
914

915
916
917
918
919
920
921
922
923
924
``/2/nodes/[node_name]/storage``
++++++++++++++++++++++++++++++++

Manages storage units on the node.

``GET``
~~~~~~~

Requests a list of storage units on a node. Requires the parameters
``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
925
926
``output_fields``. The result will be a job id, using which the result
can be retrieved.
927

928
929
930
931
932
933
934
935
``/2/nodes/[node_name]/storage/modify``
+++++++++++++++++++++++++++++++++++++++

Modifies storage units on the node.

``PUT``
~~~~~~~

936
937
938
939
940
Modifies parameters of storage units on the node. Requires the
parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
and ``name`` (name of the storage unit).  Parameters can be passed
additionally. Currently only ``allocatable`` (bool) is supported. The
result will be a job id.
941

942
943
944
945
946
947
948
949
``/2/nodes/[node_name]/storage/repair``
+++++++++++++++++++++++++++++++++++++++

Repairs a storage unit on the node.

``PUT``
~~~~~~~

950
951
952
Repairs a storage unit on the node. Requires the parameters
``storage_type`` (currently only ``lvm-vg`` can be repaired) and
``name`` (name of the storage unit). The result will be a job id.
953

Iustin Pop's avatar
Iustin Pop committed
954
955
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
956

Iustin Pop's avatar
Iustin Pop committed
957
Manages per-node tags.
958

Iustin Pop's avatar
Iustin Pop committed
959
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
960

Iustin Pop's avatar
Iustin Pop committed
961
962
``GET``
~~~~~~~
963

Iustin Pop's avatar
Iustin Pop committed
964
Returns a list of tags.
965

Iustin Pop's avatar
Iustin Pop committed
966
Example::
967

Iustin Pop's avatar
Iustin Pop committed
968
    ["tag1", "tag2", "tag3"]
969

Iustin Pop's avatar
Iustin Pop committed
970
971
``PUT``
~~~~~~~
972

Iustin Pop's avatar
Iustin Pop committed
973
Add a set of tags.
974

Iustin Pop's avatar
Iustin Pop committed
975
976
The request as a list of strings should be PUT to this URI. The result
will be a job id.
977

978
979
It supports the ``dry-run`` argument.

Iustin Pop's avatar
Iustin Pop committed
980
981
``DELETE``
~~~~~~~~~~
982

Iustin Pop's avatar
Iustin Pop committed
983
Deletes tags.
984

Iustin Pop's avatar
Iustin Pop committed
985
986
In order to delete a set of tags, the DELETE request should be addressed
to URI like::
987

Iustin Pop's avatar
Iustin Pop committed
988
    /tags?tag=[tag]&tag=[tag]
989

990
991
992
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
993
994
``/2/os``
+++++++++
995

Iustin Pop's avatar
Iustin Pop committed
996
OS resource.
997

Iustin Pop's avatar
Iustin Pop committed
998
It supports the following commands: ``GET``.
999

Iustin Pop's avatar
Iustin Pop committed
1000
1001
``GET``
~~~~~~~
1002

Iustin Pop's avatar
Iustin Pop committed
1003
Return a list of all OSes.
1004

Iustin Pop's avatar
Iustin Pop committed
1005
Can return error 500 in case of a problem. Since this is a costly
Iustin Pop's avatar
Iustin Pop committed
1006
operation for Ganeti 2.0, it is not recommended to execute it too often.
1007

Iustin Pop's avatar
Iustin Pop committed
1008
Example::
1009

Iustin Pop's avatar
Iustin Pop committed
1010
    ["debian-etch"]
1011

Iustin Pop's avatar
Iustin Pop committed
1012
1013
``/2/tags``
+++++++++++
1014

Iustin Pop's avatar
Iustin Pop committed
1015
Manages cluster tags.
1016

Iustin Pop's avatar
Iustin Pop committed
1017
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1018

Iustin Pop's avatar
Iustin Pop committed
1019
1020
``GET``
~~~~~~~
1021

Iustin Pop's avatar
Iustin Pop committed
1022
Returns the cluster tags.
1023

Iustin Pop's avatar
Iustin Pop committed
1024
Example::
1025

Iustin Pop's avatar
Iustin Pop committed
1026
    ["tag1", "tag2", "tag3"]
1027

Iustin Pop's avatar
Iustin Pop committed
1028
1029
``PUT``
~~~~~~~
1030

Iustin Pop's avatar
Iustin Pop committed
1031
Adds a set of tags.
1032

Iustin Pop's avatar
Iustin Pop committed
1033
1034
The request as a list of strings should be PUT to this URI. The result
will be a job id.
1035

1036
1037
1038
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
1039
1040
``DELETE``
~~~~~~~~~~
1041

Iustin Pop's avatar
Iustin Pop committed
1042
Deletes tags.
1043

Iustin Pop's avatar
Iustin Pop committed
1044
1045
In order to delete a set of tags, the DELETE request should be addressed
to URI like::
1046

Iustin Pop's avatar
Iustin Pop committed
1047
    /tags?tag=[tag]&tag=[tag]
1048

1049
1050
1051
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
1052
1053
``/version``
++++++++++++
1054

Iustin Pop's avatar
Iustin Pop committed
1055
The version resource.
1056

Iustin Pop's avatar
Iustin Pop committed
1057
1058
This resource should be used to determine the remote API version and to
adapt clients accordingly.
1059

Iustin Pop's avatar
Iustin Pop committed
1060
It supports the following commands: ``GET``.
1061

Iustin Pop's avatar
Iustin Pop committed
1062
1063
``GET``
~~~~~~~
1064

Iustin Pop's avatar
Iustin Pop committed
1065
1066
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
returns ``2``.
1067
1068

.. vim: set textwidth=72 :
Iustin Pop's avatar
Iustin Pop committed
1069
1070
1071
1072
.. Local Variables:
.. mode: rst
.. fill-column: 72
.. End: