Statistics
| Branch: | Tag: | Revision:

root / doc / rapi.rst @ fdd9ac5b

History | View | Annotate | Download (27.4 kB)

1
Ganeti remote API
2
=================
3

    
4
Documents Ganeti version |version|
5

    
6
.. contents::
7

    
8
Introduction
9
------------
10

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

    
19

    
20
Users and passwords
21
-------------------
22

    
23
``ganeti-rapi`` reads users and passwords from a file (usually
24
``/var/lib/ganeti/rapi/users``) on startup. Changes to the file will be
25
read automatically.
26

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

    
34
Passwords can either be written in clear text or as a hash. Clear text
35
passwords may not start with an opening brace (``{``) or they must be
36
prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash
37
of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n
38
'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix
39
it with ``{ha1}``. Using the scheme prefix for all passwords is
40
recommended. Scheme prefixes are not case sensitive.
41

    
42
Example::
43

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

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

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

    
54

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

    
63

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

    
67
The protocol used is JSON_ over HTTP designed after the REST_ principle.
68
HTTP Basic authentication as per :rfc:`2617` is supported.
69

    
70
.. _JSON: http://www.json.org/
71
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
72

    
73

    
74
A note on JSON as used by RAPI
75
++++++++++++++++++++++++++++++
76

    
77
JSON_ as used by Ganeti RAPI does not conform to the specification in
78
:rfc:`4627`. Section 2 defines a JSON text to be either an object
79
(``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
80
of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
81
some requests or responses. Changing this now would likely break
82
existing clients and cause a lot of trouble.
83

    
84
.. highlight:: ruby
85

    
86
Unlike Python's `JSON encoder and decoder
87
<http://docs.python.org/library/json.html>`_, other programming
88
languages or libraries may only provide a strict implementation, not
89
allowing plain values. For those, responses can usually be wrapped in an
90
array whose first element is then used, e.g. the response ``"1234"``
91
becomes ``["1234"]``. This works equally well for more complex values.
92
Example in Ruby::
93

    
94
  require "json"
95

    
96
  # Insert code to get response here
97
  response = "\"1234\""
98

    
99
  decoded = JSON.parse("[#{response}]").first
100

    
101
Short of modifying the encoder to allow encoding to a less strict
102
format, requests will have to be formatted by hand. Newer RAPI requests
103
already use a dictionary as their input data and shouldn't cause any
104
problems.
105

    
106

    
107
PUT or POST?
108
------------
109

    
110
According to :rfc:`2616` the main difference between PUT and POST is
111
that POST can create new resources but PUT can only create the resource
112
the URI was pointing to on the PUT request.
113

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

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

    
121

    
122
Generic parameter types
123
-----------------------
124

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

    
127
``bool``
128
++++++++
129

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

    
133
Generic parameters
134
------------------
135

    
136
A few parameter mean the same thing across all resources which implement
137
it.
138

    
139
``bulk``
140
++++++++
141

    
142
Bulk-mode means that for the resources which usually return just a list
143
of child resources (e.g. ``/2/instances`` which returns just instance
144
names), the output will instead contain detailed data for all these
145
subresources. This is more efficient than query-ing the sub-resources
146
themselves.
147

    
148
``dry-run``
149
+++++++++++
150

    
151
The boolean *dry-run* argument, if provided and set, signals to Ganeti
152
that the job should not be executed, only the pre-execution checks will
153
be done.
154

    
155
This is useful in trying to determine (without guarantees though, as in
156
the meantime the cluster state could have changed) if the operation is
157
likely to succeed or at least start executing.
158

    
159
``force``
160
+++++++++++
161

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

    
165
Usage examples
166
--------------
167

    
168
You can access the API using your favorite programming language as long
169
as it supports network connections.
170

    
171
Ganeti RAPI client
172
++++++++++++++++++
173

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

    
176
Shell
177
+++++
178

    
179
.. highlight:: sh
180

    
181
Using wget::
182

    
183
   wget -q -O - https://CLUSTERNAME:5080/2/info
184

    
185
or curl::
186

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

    
189

    
190
Python
191
++++++
192

    
193
.. highlight:: python
194

    
195
::
196

    
197
  import urllib2
198
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
199
  print f.read()
200

    
201

    
202
JavaScript
203
++++++++++
204

    
205
.. warning:: While it's possible to use JavaScript, it poses several
206
   potential problems, including browser blocking request due to
207
   non-standard ports or different domain names. Fetching the data on
208
   the webserver is easier.
209

    
210
.. highlight:: javascript
211

    
212
::
213

    
214
  var url = 'https://CLUSTERNAME:5080/2/info';
215
  var info;
216
  var xmlreq = new XMLHttpRequest();
217
  xmlreq.onreadystatechange = function () {
218
    if (xmlreq.readyState != 4) return;
219
    if (xmlreq.status == 200) {
220
      info = eval("(" + xmlreq.responseText + ")");
221
      alert(info);
222
    } else {
223
      alert('Error fetching cluster info');
224
    }
225
    xmlreq = null;
226
  };
227
  xmlreq.open('GET', url, true);
228
  xmlreq.send(null);
229

    
230
Resources
231
---------
232

    
233
.. highlight:: javascript
234

    
235
``/``
236
+++++
237

    
238
The root resource.
239

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

    
242
``GET``
243
~~~~~~~
244

    
245
Shows the list of mapped resources.
246

    
247
Returns: a dictionary with 'name' and 'uri' keys for each of them.
248

    
249
``/2``
250
++++++
251

    
252
The ``/2`` resource, the root of the version 2 API.
253

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

    
256
``GET``
257
~~~~~~~
258

    
259
Show the list of mapped resources.
260

    
261
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
262

    
263
``/2/info``
264
+++++++++++
265

    
266
Cluster information resource.
267

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

    
270
``GET``
271
~~~~~~~
272

    
273
Returns cluster information.
274

    
275
Example::
276

    
277
  {
278
    "config_version": 2000000,
279
    "name": "cluster",
280
    "software_version": "2.0.0~beta2",
281
    "os_api_version": 10,
282
    "export_version": 0,
283
    "candidate_pool_size": 10,
284
    "enabled_hypervisors": [
285
      "fake"
286
    ],
287
    "hvparams": {
288
      "fake": {}
289
     },
290
    "default_hypervisor": "fake",
291
    "master": "node1.example.com",
292
    "architecture": [
293
      "64bit",
294
      "x86_64"
295
    ],
296
    "protocol_version": 20,
297
    "beparams": {
298
      "default": {
299
        "auto_balance": true,
300
        "vcpus": 1,
301
        "memory": 128
302
       }
303
      }
304
    }
305

    
306

    
307
``/2/redistribute-config``
308
++++++++++++++++++++++++++
309

    
310
Redistribute configuration to all nodes.
311

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

    
314
``PUT``
315
~~~~~~~
316

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

    
319

    
320
``/2/features``
321
+++++++++++++++
322

    
323
``GET``
324
~~~~~~~
325

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

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

    
332

    
333
``/2/instances``
334
++++++++++++++++
335

    
336
The instances resource.
337

    
338
It supports the following commands: ``GET``, ``POST``.
339

    
340
``GET``
341
~~~~~~~
342

    
343
Returns a list of all available instances.
344

    
345
Example::
346

    
347
    [
348
      {
349
        "name": "web.example.com",
350
        "uri": "\/instances\/web.example.com"
351
      },
352
      {
353
        "name": "mail.example.com",
354
        "uri": "\/instances\/mail.example.com"
355
      }
356
    ]
357

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

    
362
Example::
363

    
364
    [
365
      {
366
         "status": "running",
367
         "disk_usage": 20480,
368
         "nic.bridges": [
369
           "xen-br0"
370
          ],
371
         "name": "web.example.com",
372
         "tags": ["tag1", "tag2"],
373
         "beparams": {
374
           "vcpus": 2,
375
           "memory": 512
376
         },
377
         "disk.sizes": [
378
             20480
379
         ],
380
         "pnode": "node1.example.com",
381
         "nic.macs": ["01:23:45:67:89:01"],
382
         "snodes": ["node2.example.com"],
383
         "disk_template": "drbd",
384
         "admin_state": true,
385
         "os": "debian-etch",
386
         "oper_state": true
387
      },
388
      ...
389
    ]
390

    
391

    
392
``POST``
393
~~~~~~~~
394

    
395
Creates an instance.
396

    
397
If the optional bool *dry-run* argument is provided, the job will not be
398
actually executed, only the pre-execution checks will be done. Query-ing
399
the job result will return, in both dry-run and normal case, the list of
400
nodes selected for the instance.
401

    
402
Returns: a job ID that can be used later for polling.
403

    
404
Body parameters:
405

    
406
``__version__`` (int, required)
407
  Must be ``1`` (older Ganeti versions used a different format for
408
  instance creation requests, version ``0``, but that format is not
409
  documented).
410
``mode`` (string, required)
411
  Instance creation mode.
412
``name`` (string, required)
413
  Instance name.
414
``disk_template`` (string, required)
415
  Disk template for instance.
416
``disks`` (list, required)
417
  List of disk definitions. Example: ``[{"size": 100}, {"size": 5}]``.
418
  Each disk definition must contain a ``size`` value and can contain an
419
  optional ``mode`` value denoting the disk access mode (``ro`` or
420
  ``rw``).
421
``nics`` (list, required)
422
  List of NIC (network interface) definitions. Example: ``[{}, {},
423
  {"ip": "198.51.100.4"}]``. Each NIC definition can contain the
424
  optional values ``ip``, ``mode``, ``link`` and ``bridge``.
425
``os`` (string, required)
426
  Instance operating system.
427
``osparams`` (dictionary)
428
  Dictionary with OS parameters. If not valid for the given OS, the job
429
  will fail.
430
``force_variant`` (bool)
431
  Whether to force an unknown variant.
432
``no_install`` (bool)
433
  Do not install the OS (will enable no-start)
434
``pnode`` (string)
435
  Primary node.
436
``snode`` (string)
437
  Secondary node.
438
``src_node`` (string)
439
  Source node for import.
440
``src_path`` (string)
441
  Source directory for import.
442
``start`` (bool)
443
  Whether to start instance after creation.
444
``ip_check`` (bool)
445
  Whether to ensure instance's IP address is inactive.
446
``name_check`` (bool)
447
  Whether to ensure instance's name is resolvable.
448
``file_storage_dir`` (string)
449
  File storage directory.
450
``file_driver`` (string)
451
  File storage driver.
452
``iallocator`` (string)
453
  Instance allocator name.
454
``source_handshake`` (list)
455
  Signed handshake from source (remote import only).
456
``source_x509_ca`` (string)
457
  Source X509 CA in PEM format (remote import only).
458
``source_instance_name`` (string)
459
  Source instance name (remote import only).
460
``hypervisor`` (string)
461
  Hypervisor name.
462
``hvparams`` (dict)
463
  Hypervisor parameters, hypervisor-dependent.
464
``beparams`` (dict)
465
  Backend parameters.
466

    
467

    
468
``/2/instances/[instance_name]``
469
++++++++++++++++++++++++++++++++
470

    
471
Instance-specific resource.
472

    
473
It supports the following commands: ``GET``, ``DELETE``.
474

    
475
``GET``
476
~~~~~~~
477

    
478
Returns information about an instance, similar to the bulk output from
479
the instance list.
480

    
481
``DELETE``
482
~~~~~~~~~~
483

    
484
Deletes an instance.
485

    
486
It supports the ``dry-run`` argument.
487

    
488

    
489
``/2/instances/[instance_name]/info``
490
+++++++++++++++++++++++++++++++++++++++
491

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

    
494
``GET``
495
~~~~~~~
496

    
497
Requests detailed information about the instance. An optional parameter,
498
``static`` (bool), can be set to return only static information from the
499
configuration without querying the instance's nodes. The result will be
500
a job id.
501

    
502

    
503
``/2/instances/[instance_name]/reboot``
504
+++++++++++++++++++++++++++++++++++++++
505

    
506
Reboots URI for an instance.
507

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

    
510
``POST``
511
~~~~~~~~
512

    
513
Reboots the instance.
514

    
515
The URI takes optional ``type=soft|hard|full`` and
516
``ignore_secondaries=0|1`` parameters.
517

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

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

    
528
It supports the ``dry-run`` argument.
529

    
530

    
531
``/2/instances/[instance_name]/shutdown``
532
+++++++++++++++++++++++++++++++++++++++++
533

    
534
Instance shutdown URI.
535

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

    
538
``PUT``
539
~~~~~~~
540

    
541
Shutdowns an instance.
542

    
543
It supports the ``dry-run`` argument.
544

    
545

    
546
``/2/instances/[instance_name]/startup``
547
++++++++++++++++++++++++++++++++++++++++
548

    
549
Instance startup URI.
550

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

    
553
``PUT``
554
~~~~~~~
555

    
556
Startup an instance.
557

    
558
The URI takes an optional ``force=1|0`` parameter to start the
559
instance even if secondary disks are failing.
560

    
561
It supports the ``dry-run`` argument.
562

    
563
``/2/instances/[instance_name]/reinstall``
564
++++++++++++++++++++++++++++++++++++++++++++++
565

    
566
Installs the operating system again.
567

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

    
570
``POST``
571
~~~~~~~~
572

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

    
575

    
576
``/2/instances/[instance_name]/replace-disks``
577
++++++++++++++++++++++++++++++++++++++++++++++
578

    
579
Replaces disks on an instance.
580

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

    
583
``POST``
584
~~~~~~~~
585

    
586
Takes the parameters ``mode`` (one of ``replace_on_primary``,
587
``replace_on_secondary``, ``replace_new_secondary`` or
588
``replace_auto``), ``disks`` (comma separated list of disk indexes),
589
``remote_node`` and ``iallocator``.
590

    
591
Either ``remote_node`` or ``iallocator`` needs to be defined when using
592
``mode=replace_new_secondary``.
593

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

    
597

    
598
``/2/instances/[instance_name]/activate-disks``
599
+++++++++++++++++++++++++++++++++++++++++++++++
600

    
601
Activate disks on an instance.
602

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

    
605
``PUT``
606
~~~~~~~
607

    
608
Takes the bool parameter ``ignore_size``. When set ignore the recorded
609
size (useful for forcing activation when recorded size is wrong).
610

    
611

    
612
``/2/instances/[instance_name]/deactivate-disks``
613
+++++++++++++++++++++++++++++++++++++++++++++++++
614

    
615
Deactivate disks on an instance.
616

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

    
619
``PUT``
620
~~~~~~~
621

    
622
Takes no parameters.
623

    
624

    
625
``/2/instances/[instance_name]/prepare-export``
626
+++++++++++++++++++++++++++++++++++++++++++++++++
627

    
628
Prepares an export of an instance.
629

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

    
632
``PUT``
633
~~~~~~~
634

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

    
637

    
638
``/2/instances/[instance_name]/export``
639
+++++++++++++++++++++++++++++++++++++++++++++++++
640

    
641
Exports an instance.
642

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

    
645
``PUT``
646
~~~~~~~
647

    
648
Returns a job ID.
649

    
650
Body parameters:
651

    
652
``mode`` (string)
653
  Export mode.
654
``destination`` (required)
655
  Destination information, depends on export mode.
656
``shutdown`` (bool, required)
657
  Whether to shutdown instance before export.
658
``remove_instance`` (bool)
659
  Whether to remove instance after export.
660
``x509_key_name``
661
  Name of X509 key (remote export only).
662
``destination_x509_ca``
663
  Destination X509 CA (remote export only).
664

    
665

    
666
``/2/instances/[instance_name]/migrate``
667
++++++++++++++++++++++++++++++++++++++++
668

    
669
Migrates an instance.
670

    
671
Supports the following commands: ``PUT``.
672

    
673
``PUT``
674
~~~~~~~
675

    
676
Returns a job ID.
677

    
678
Body parameters:
679

    
680
``mode`` (string)
681
  Migration mode.
682
``cleanup`` (bool)
683
  Whether a previously failed migration should be cleaned up.
684

    
685

    
686
``/2/instances/[instance_name]/rename``
687
++++++++++++++++++++++++++++++++++++++++
688

    
689
Renames an instance.
690

    
691
Supports the following commands: ``PUT``.
692

    
693
``PUT``
694
~~~~~~~
695

    
696
Returns a job ID.
697

    
698
Body parameters:
699

    
700
``new_name`` (string, required)
701
  New instance name.
702
``ip_check`` (bool)
703
  Whether to ensure instance's IP address is inactive.
704
``name_check`` (bool)
705
  Whether to ensure instance's name is resolvable.
706

    
707

    
708
``/2/instances/[instance_name]/modify``
709
++++++++++++++++++++++++++++++++++++++++
710

    
711
Modifies an instance.
712

    
713
Supports the following commands: ``PUT``.
714

    
715
``PUT``
716
~~~~~~~
717

    
718
Returns a job ID.
719

    
720
Body parameters:
721

    
722
``osparams`` (dict)
723
  Dictionary with OS parameters.
724
``hvparams`` (dict)
725
  Hypervisor parameters, hypervisor-dependent.
726
``beparams`` (dict)
727
  Backend parameters.
728
``force`` (bool)
729
  Whether to force the operation.
730
``nics`` (list)
731
  List of NIC changes. Each item is of the form ``(op, settings)``.
732
  ``op`` can be ``add`` to add a new NIC with the specified settings,
733
  ``remove`` to remove the last NIC or a number to modify the settings
734
  of the NIC with that index.
735
``disks`` (list)
736
  List of disk changes. See ``nics``.
737
``disk_template`` (string)
738
  Disk template for instance.
739
``remote_node`` (string)
740
  Secondary node (used when changing disk template).
741
``os_name`` (string)
742
  Change instance's OS name. Does not reinstall the instance.
743
``force_variant`` (bool)
744
  Whether to force an unknown variant.
745

    
746

    
747
``/2/instances/[instance_name]/tags``
748
+++++++++++++++++++++++++++++++++++++
749

    
750
Manages per-instance tags.
751

    
752
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
753

    
754
``GET``
755
~~~~~~~
756

    
757
Returns a list of tags.
758

    
759
Example::
760

    
761
    ["tag1", "tag2", "tag3"]
762

    
763
``PUT``
764
~~~~~~~
765

    
766
Add a set of tags.
767

    
768
The request as a list of strings should be ``PUT`` to this URI. The
769
result will be a job id.
770

    
771
It supports the ``dry-run`` argument.
772

    
773

    
774
``DELETE``
775
~~~~~~~~~~
776

    
777
Delete a tag.
778

    
779
In order to delete a set of tags, the DELETE request should be addressed
780
to URI like::
781

    
782
    /tags?tag=[tag]&tag=[tag]
783

    
784
It supports the ``dry-run`` argument.
785

    
786

    
787
``/2/jobs``
788
+++++++++++
789

    
790
The ``/2/jobs`` resource.
791

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

    
794
``GET``
795
~~~~~~~
796

    
797
Returns a dictionary of jobs.
798

    
799
Returns: a dictionary with jobs id and uri.
800

    
801
``/2/jobs/[job_id]``
802
++++++++++++++++++++
803

    
804

    
805
Individual job URI.
806

    
807
It supports the following commands: ``GET``, ``DELETE``.
808

    
809
``GET``
810
~~~~~~~
811

    
812
Returns a job status.
813

    
814
Returns: a dictionary with job parameters.
815

    
816
The result includes:
817

    
818
- id: job ID as a number
819
- status: current job status as a string
820
- ops: involved OpCodes as a list of dictionaries for each opcodes in
821
  the job
822
- opstatus: OpCodes status as a list
823
- opresult: OpCodes results as a list
824

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
884

    
885
``DELETE``
886
~~~~~~~~~~
887

    
888
Cancel a not-yet-started job.
889

    
890

    
891
``/2/jobs/[job_id]/wait``
892
+++++++++++++++++++++++++
893

    
894
``GET``
895
~~~~~~~
896

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

    
900
``fields``
901
  The job fields on which to watch for changes.
902

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

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

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

    
913

    
914
``/2/nodes``
915
++++++++++++
916

    
917
Nodes resource.
918

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

    
921
``GET``
922
~~~~~~~
923

    
924
Returns a list of all nodes.
925

    
926
Example::
927

    
928
    [
929
      {
930
        "id": "node1.example.com",
931
        "uri": "\/nodes\/node1.example.com"
932
      },
933
      {
934
        "id": "node2.example.com",
935
        "uri": "\/nodes\/node2.example.com"
936
      }
937
    ]
938

    
939
If the optional 'bulk' argument is provided and set to 'true' value (i.e
940
'?bulk=1'), the output contains detailed information about nodes as a
941
list.
942

    
943
Example::
944

    
945
    [
946
      {
947
        "pinst_cnt": 1,
948
        "mfree": 31280,
949
        "mtotal": 32763,
950
        "name": "www.example.com",
951
        "tags": [],
952
        "mnode": 512,
953
        "dtotal": 5246208,
954
        "sinst_cnt": 2,
955
        "dfree": 5171712,
956
        "offline": false
957
      },
958
      ...
959
    ]
960

    
961
``/2/nodes/[node_name]``
962
+++++++++++++++++++++++++++++++++
963

    
964
Returns information about a node.
965

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

    
968
``/2/nodes/[node_name]/evacuate``
969
+++++++++++++++++++++++++++++++++
970

    
971
Evacuates all secondary instances off a node.
972

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

    
975
``POST``
976
~~~~~~~~
977

    
978
To evacuate a node, either one of the ``iallocator`` or ``remote_node``
979
parameters must be passed::
980

    
981
    evacuate?iallocator=[iallocator]
982
    evacuate?remote_node=[nodeX.example.com]
983

    
984
The result value will be a list, each element being a triple of the job
985
id (for this specific evacuation), the instance which is being evacuated
986
by this job, and the node to which it is being relocated. In case the
987
node is already empty, the result will be an empty list (without any
988
jobs being submitted).
989

    
990
And additional parameter ``early_release`` signifies whether to try to
991
parallelize the evacuations, at the risk of increasing I/O contention
992
and increasing the chances of data loss, if the primary node of any of
993
the instances being evacuated is not fully healthy.
994

    
995
If the dry-run parameter was specified, then the evacuation jobs were
996
not actually submitted, and the job IDs will be null.
997

    
998

    
999
``/2/nodes/[node_name]/migrate``
1000
+++++++++++++++++++++++++++++++++
1001

    
1002
Migrates all primary instances from a node.
1003

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

    
1006
``POST``
1007
~~~~~~~~
1008

    
1009
If no mode is explicitly specified, each instances' hypervisor default
1010
migration mode will be used. Query parameters:
1011

    
1012
``live`` (bool)
1013
  If set, use live migration if available.
1014
``mode`` (string)
1015
  Sets migration mode, ``live`` for live migration and ``non-live`` for
1016
  non-live migration. Supported by Ganeti 2.2 and above.
1017

    
1018

    
1019
``/2/nodes/[node_name]/role``
1020
+++++++++++++++++++++++++++++
1021

    
1022
Manages node role.
1023

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

    
1026
The role is always one of the following:
1027

    
1028
  - drained
1029
  - master
1030
  - master-candidate
1031
  - offline
1032
  - regular
1033

    
1034
``GET``
1035
~~~~~~~
1036

    
1037
Returns the current node role.
1038

    
1039
Example::
1040

    
1041
    "master-candidate"
1042

    
1043
``PUT``
1044
~~~~~~~
1045

    
1046
Change the node role.
1047

    
1048
The request is a string which should be PUT to this URI. The result will
1049
be a job id.
1050

    
1051
It supports the bool ``force`` argument.
1052

    
1053
``/2/nodes/[node_name]/storage``
1054
++++++++++++++++++++++++++++++++
1055

    
1056
Manages storage units on the node.
1057

    
1058
``GET``
1059
~~~~~~~
1060

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

    
1066
``/2/nodes/[node_name]/storage/modify``
1067
+++++++++++++++++++++++++++++++++++++++
1068

    
1069
Modifies storage units on the node.
1070

    
1071
``PUT``
1072
~~~~~~~
1073

    
1074
Modifies parameters of storage units on the node. Requires the
1075
parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
1076
and ``name`` (name of the storage unit).  Parameters can be passed
1077
additionally. Currently only ``allocatable`` (bool) is supported. The
1078
result will be a job id.
1079

    
1080
``/2/nodes/[node_name]/storage/repair``
1081
+++++++++++++++++++++++++++++++++++++++
1082

    
1083
Repairs a storage unit on the node.
1084

    
1085
``PUT``
1086
~~~~~~~
1087

    
1088
Repairs a storage unit on the node. Requires the parameters
1089
``storage_type`` (currently only ``lvm-vg`` can be repaired) and
1090
``name`` (name of the storage unit). The result will be a job id.
1091

    
1092
``/2/nodes/[node_name]/tags``
1093
+++++++++++++++++++++++++++++
1094

    
1095
Manages per-node tags.
1096

    
1097
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1098

    
1099
``GET``
1100
~~~~~~~
1101

    
1102
Returns a list of tags.
1103

    
1104
Example::
1105

    
1106
    ["tag1", "tag2", "tag3"]
1107

    
1108
``PUT``
1109
~~~~~~~
1110

    
1111
Add a set of tags.
1112

    
1113
The request as a list of strings should be PUT to this URI. The result
1114
will be a job id.
1115

    
1116
It supports the ``dry-run`` argument.
1117

    
1118
``DELETE``
1119
~~~~~~~~~~
1120

    
1121
Deletes tags.
1122

    
1123
In order to delete a set of tags, the DELETE request should be addressed
1124
to URI like::
1125

    
1126
    /tags?tag=[tag]&tag=[tag]
1127

    
1128
It supports the ``dry-run`` argument.
1129

    
1130

    
1131
``/2/os``
1132
+++++++++
1133

    
1134
OS resource.
1135

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

    
1138
``GET``
1139
~~~~~~~
1140

    
1141
Return a list of all OSes.
1142

    
1143
Can return error 500 in case of a problem. Since this is a costly
1144
operation for Ganeti 2.0, it is not recommended to execute it too often.
1145

    
1146
Example::
1147

    
1148
    ["debian-etch"]
1149

    
1150
``/2/tags``
1151
+++++++++++
1152

    
1153
Manages cluster tags.
1154

    
1155
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1156

    
1157
``GET``
1158
~~~~~~~
1159

    
1160
Returns the cluster tags.
1161

    
1162
Example::
1163

    
1164
    ["tag1", "tag2", "tag3"]
1165

    
1166
``PUT``
1167
~~~~~~~
1168

    
1169
Adds a set of tags.
1170

    
1171
The request as a list of strings should be PUT to this URI. The result
1172
will be a job id.
1173

    
1174
It supports the ``dry-run`` argument.
1175

    
1176

    
1177
``DELETE``
1178
~~~~~~~~~~
1179

    
1180
Deletes tags.
1181

    
1182
In order to delete a set of tags, the DELETE request should be addressed
1183
to URI like::
1184

    
1185
    /tags?tag=[tag]&tag=[tag]
1186

    
1187
It supports the ``dry-run`` argument.
1188

    
1189

    
1190
``/version``
1191
++++++++++++
1192

    
1193
The version resource.
1194

    
1195
This resource should be used to determine the remote API version and to
1196
adapt clients accordingly.
1197

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

    
1200
``GET``
1201
~~~~~~~
1202

    
1203
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1204
returns ``2``.
1205

    
1206
.. vim: set textwidth=72 :
1207
.. Local Variables:
1208
.. mode: rst
1209
.. fill-column: 72
1210
.. End: