Statistics
| Branch: | Tag: | Revision:

root / doc / rapi.rst @ ebeb600f

History | View | Annotate | Download (23.5 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. After modifying the password
25
file, ``ganeti-rapi`` must be restarted.
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 RFC2617_ ("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 RFC2617_ is supported.
69

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

    
74

    
75
PUT or POST?
76
------------
77

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

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

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

    
89

    
90
Generic parameter types
91
-----------------------
92

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

    
95
``bool``
96
++++++++
97

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

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

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

    
107
``bulk``
108
++++++++
109

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

    
116
``dry-run``
117
+++++++++++
118

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

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

    
127
``force``
128
+++++++++++
129

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

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

    
136
You can access the API using your favorite programming language as long
137
as it supports network connections.
138

    
139
Ganeti RAPI client
140
++++++++++++++++++
141

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

    
144
Shell
145
+++++
146

    
147
.. highlight:: sh
148

    
149
Using wget::
150

    
151
   wget -q -O - https://CLUSTERNAME:5080/2/info
152

    
153
or curl::
154

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

    
157

    
158
Python
159
++++++
160

    
161
.. highlight:: python
162

    
163
::
164

    
165
  import urllib2
166
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
167
  print f.read()
168

    
169

    
170
JavaScript
171
++++++++++
172

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

    
178
.. highlight:: javascript
179

    
180
::
181

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

    
198
Resources
199
---------
200

    
201
.. highlight:: javascript
202

    
203
``/``
204
+++++
205

    
206
The root resource.
207

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

    
210
``GET``
211
~~~~~~~
212

    
213
Shows the list of mapped resources.
214

    
215
Returns: a dictionary with 'name' and 'uri' keys for each of them.
216

    
217
``/2``
218
++++++
219

    
220
The ``/2`` resource, the root of the version 2 API.
221

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

    
224
``GET``
225
~~~~~~~
226

    
227
Show the list of mapped resources.
228

    
229
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
230

    
231
``/2/info``
232
+++++++++++
233

    
234
Cluster information resource.
235

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

    
238
``GET``
239
~~~~~~~
240

    
241
Returns cluster information.
242

    
243
Example::
244

    
245
  {
246
    "config_version": 2000000,
247
    "name": "cluster",
248
    "software_version": "2.0.0~beta2",
249
    "os_api_version": 10,
250
    "export_version": 0,
251
    "candidate_pool_size": 10,
252
    "enabled_hypervisors": [
253
      "fake"
254
    ],
255
    "hvparams": {
256
      "fake": {}
257
     },
258
    "default_hypervisor": "fake",
259
    "master": "node1.example.com",
260
    "architecture": [
261
      "64bit",
262
      "x86_64"
263
    ],
264
    "protocol_version": 20,
265
    "beparams": {
266
      "default": {
267
        "auto_balance": true,
268
        "vcpus": 1,
269
        "memory": 128
270
       }
271
      }
272
    }
273

    
274

    
275
``/2/redistribute-config``
276
++++++++++++++++++++++++++
277

    
278
Redistribute configuration to all nodes.
279

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

    
282
``PUT``
283
~~~~~~~
284

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

    
287

    
288
``/2/features``
289
+++++++++++++++
290

    
291
``GET``
292
~~~~~~~
293

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

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

    
300

    
301
``/2/instances``
302
++++++++++++++++
303

    
304
The instances resource.
305

    
306
It supports the following commands: ``GET``, ``POST``.
307

    
308
``GET``
309
~~~~~~~
310

    
311
Returns a list of all available instances.
312

    
313
Example::
314

    
315
    [
316
      {
317
        "name": "web.example.com",
318
        "uri": "\/instances\/web.example.com"
319
      },
320
      {
321
        "name": "mail.example.com",
322
        "uri": "\/instances\/mail.example.com"
323
      }
324
    ]
325

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

    
330
Example::
331

    
332
    [
333
      {
334
         "status": "running",
335
         "disk_usage": 20480,
336
         "nic.bridges": [
337
           "xen-br0"
338
          ],
339
         "name": "web.example.com",
340
         "tags": ["tag1", "tag2"],
341
         "beparams": {
342
           "vcpus": 2,
343
           "memory": 512
344
         },
345
         "disk.sizes": [
346
             20480
347
         ],
348
         "pnode": "node1.example.com",
349
         "nic.macs": ["01:23:45:67:89:01"],
350
         "snodes": ["node2.example.com"],
351
         "disk_template": "drbd",
352
         "admin_state": true,
353
         "os": "debian-etch",
354
         "oper_state": true
355
      },
356
      ...
357
    ]
358

    
359

    
360
``POST``
361
~~~~~~~~
362

    
363
Creates an instance.
364

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

    
370
Returns: a job ID that can be used later for polling.
371

    
372
Body parameters:
373

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

    
430

    
431
``/2/instances/[instance_name]``
432
++++++++++++++++++++++++++++++++
433

    
434
Instance-specific resource.
435

    
436
It supports the following commands: ``GET``, ``DELETE``.
437

    
438
``GET``
439
~~~~~~~
440

    
441
Returns information about an instance, similar to the bulk output from
442
the instance list.
443

    
444
``DELETE``
445
~~~~~~~~~~
446

    
447
Deletes an instance.
448

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

    
451

    
452
``/2/instances/[instance_name]/info``
453
+++++++++++++++++++++++++++++++++++++++
454

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

    
457
``GET``
458
~~~~~~~
459

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

    
465

    
466
``/2/instances/[instance_name]/reboot``
467
+++++++++++++++++++++++++++++++++++++++
468

    
469
Reboots URI for an instance.
470

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

    
473
``POST``
474
~~~~~~~~
475

    
476
Reboots the instance.
477

    
478
The URI takes optional ``type=soft|hard|full`` and
479
``ignore_secondaries=0|1`` parameters.
480

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

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

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

    
493

    
494
``/2/instances/[instance_name]/shutdown``
495
+++++++++++++++++++++++++++++++++++++++++
496

    
497
Instance shutdown URI.
498

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

    
501
``PUT``
502
~~~~~~~
503

    
504
Shutdowns an instance.
505

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

    
508

    
509
``/2/instances/[instance_name]/startup``
510
++++++++++++++++++++++++++++++++++++++++
511

    
512
Instance startup URI.
513

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

    
516
``PUT``
517
~~~~~~~
518

    
519
Startup an instance.
520

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

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

    
526
``/2/instances/[instance_name]/reinstall``
527
++++++++++++++++++++++++++++++++++++++++++++++
528

    
529
Installs the operating system again.
530

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

    
533
``POST``
534
~~~~~~~~
535

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

    
538

    
539
``/2/instances/[instance_name]/replace-disks``
540
++++++++++++++++++++++++++++++++++++++++++++++
541

    
542
Replaces disks on an instance.
543

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

    
546
``POST``
547
~~~~~~~~
548

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

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

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

    
560

    
561
``/2/instances/[instance_name]/activate-disks``
562
+++++++++++++++++++++++++++++++++++++++++++++++
563

    
564
Activate disks on an instance.
565

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

    
568
``PUT``
569
~~~~~~~
570

    
571
Takes the bool parameter ``ignore_size``. When set ignore the recorded
572
size (useful for forcing activation when recorded size is wrong).
573

    
574

    
575
``/2/instances/[instance_name]/deactivate-disks``
576
+++++++++++++++++++++++++++++++++++++++++++++++++
577

    
578
Deactivate disks on an instance.
579

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

    
582
``PUT``
583
~~~~~~~
584

    
585
Takes no parameters.
586

    
587

    
588
``/2/instances/[instance_name]/prepare-export``
589
+++++++++++++++++++++++++++++++++++++++++++++++++
590

    
591
Prepares an export of an instance.
592

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

    
595
``PUT``
596
~~~~~~~
597

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

    
600

    
601
``/2/instances/[instance_name]/export``
602
+++++++++++++++++++++++++++++++++++++++++++++++++
603

    
604
Exports an instance.
605

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

    
608
``PUT``
609
~~~~~~~
610

    
611
Returns a job ID.
612

    
613
Body parameters:
614

    
615
``mode`` (string)
616
  Export mode.
617
``destination`` (required)
618
  Destination information, depends on export mode.
619
``shutdown`` (bool, required)
620
  Whether to shutdown instance before export.
621
``remove_instance`` (bool)
622
  Whether to remove instance after export.
623
``x509_key_name``
624
  Name of X509 key (remote export only).
625
``destination_x509_ca``
626
  Destination X509 CA (remote export only).
627

    
628

    
629
``/2/instances/[instance_name]/tags``
630
+++++++++++++++++++++++++++++++++++++
631

    
632
Manages per-instance tags.
633

    
634
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
635

    
636
``GET``
637
~~~~~~~
638

    
639
Returns a list of tags.
640

    
641
Example::
642

    
643
    ["tag1", "tag2", "tag3"]
644

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

    
648
Add a set of tags.
649

    
650
The request as a list of strings should be ``PUT`` to this URI. The
651
result will be a job id.
652

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

    
655

    
656
``DELETE``
657
~~~~~~~~~~
658

    
659
Delete a tag.
660

    
661
In order to delete a set of tags, the DELETE request should be addressed
662
to URI like::
663

    
664
    /tags?tag=[tag]&tag=[tag]
665

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

    
668

    
669
``/2/jobs``
670
+++++++++++
671

    
672
The ``/2/jobs`` resource.
673

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

    
676
``GET``
677
~~~~~~~
678

    
679
Returns a dictionary of jobs.
680

    
681
Returns: a dictionary with jobs id and uri.
682

    
683
``/2/jobs/[job_id]``
684
++++++++++++++++++++
685

    
686

    
687
Individual job URI.
688

    
689
It supports the following commands: ``GET``, ``DELETE``.
690

    
691
``GET``
692
~~~~~~~
693

    
694
Returns a job status.
695

    
696
Returns: a dictionary with job parameters.
697

    
698
The result includes:
699

    
700
- id: job ID as a number
701
- status: current job status as a string
702
- ops: involved OpCodes as a list of dictionaries for each opcodes in
703
  the job
704
- opstatus: OpCodes status as a list
705
- opresult: OpCodes results as a list
706

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
766

    
767
``DELETE``
768
~~~~~~~~~~
769

    
770
Cancel a not-yet-started job.
771

    
772

    
773
``/2/jobs/[job_id]/wait``
774
+++++++++++++++++++++++++
775

    
776
``GET``
777
~~~~~~~
778

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

    
782
``fields``
783
  The job fields on which to watch for changes.
784

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

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

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

    
795

    
796
``/2/nodes``
797
++++++++++++
798

    
799
Nodes resource.
800

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

    
803
``GET``
804
~~~~~~~
805

    
806
Returns a list of all nodes.
807

    
808
Example::
809

    
810
    [
811
      {
812
        "id": "node1.example.com",
813
        "uri": "\/nodes\/node1.example.com"
814
      },
815
      {
816
        "id": "node2.example.com",
817
        "uri": "\/nodes\/node2.example.com"
818
      }
819
    ]
820

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

    
825
Example::
826

    
827
    [
828
      {
829
        "pinst_cnt": 1,
830
        "mfree": 31280,
831
        "mtotal": 32763,
832
        "name": "www.example.com",
833
        "tags": [],
834
        "mnode": 512,
835
        "dtotal": 5246208,
836
        "sinst_cnt": 2,
837
        "dfree": 5171712,
838
        "offline": false
839
      },
840
      ...
841
    ]
842

    
843
``/2/nodes/[node_name]``
844
+++++++++++++++++++++++++++++++++
845

    
846
Returns information about a node.
847

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

    
850
``/2/nodes/[node_name]/evacuate``
851
+++++++++++++++++++++++++++++++++
852

    
853
Evacuates all secondary instances off a node.
854

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

    
857
``POST``
858
~~~~~~~~
859

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

    
863
    evacuate?iallocator=[iallocator]
864
    evacuate?remote_node=[nodeX.example.com]
865

    
866
``/2/nodes/[node_name]/migrate``
867
+++++++++++++++++++++++++++++++++
868

    
869
Migrates all primary instances from a node.
870

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

    
873
``POST``
874
~~~~~~~~
875

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

    
879
    migrate?live=[0|1]
880

    
881
``/2/nodes/[node_name]/role``
882
+++++++++++++++++++++++++++++
883

    
884
Manages node role.
885

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

    
888
The role is always one of the following:
889

    
890
  - drained
891
  - master
892
  - master-candidate
893
  - offline
894
  - regular
895

    
896
``GET``
897
~~~~~~~
898

    
899
Returns the current node role.
900

    
901
Example::
902

    
903
    "master-candidate"
904

    
905
``PUT``
906
~~~~~~~
907

    
908
Change the node role.
909

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

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

    
915
``/2/nodes/[node_name]/storage``
916
++++++++++++++++++++++++++++++++
917

    
918
Manages storage units on the node.
919

    
920
``GET``
921
~~~~~~~
922

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

    
928
``/2/nodes/[node_name]/storage/modify``
929
+++++++++++++++++++++++++++++++++++++++
930

    
931
Modifies storage units on the node.
932

    
933
``PUT``
934
~~~~~~~
935

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

    
942
``/2/nodes/[node_name]/storage/repair``
943
+++++++++++++++++++++++++++++++++++++++
944

    
945
Repairs a storage unit on the node.
946

    
947
``PUT``
948
~~~~~~~
949

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

    
954
``/2/nodes/[node_name]/tags``
955
+++++++++++++++++++++++++++++
956

    
957
Manages per-node tags.
958

    
959
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
960

    
961
``GET``
962
~~~~~~~
963

    
964
Returns a list of tags.
965

    
966
Example::
967

    
968
    ["tag1", "tag2", "tag3"]
969

    
970
``PUT``
971
~~~~~~~
972

    
973
Add a set of tags.
974

    
975
The request as a list of strings should be PUT to this URI. The result
976
will be a job id.
977

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

    
980
``DELETE``
981
~~~~~~~~~~
982

    
983
Deletes tags.
984

    
985
In order to delete a set of tags, the DELETE request should be addressed
986
to URI like::
987

    
988
    /tags?tag=[tag]&tag=[tag]
989

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

    
992

    
993
``/2/os``
994
+++++++++
995

    
996
OS resource.
997

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

    
1000
``GET``
1001
~~~~~~~
1002

    
1003
Return a list of all OSes.
1004

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

    
1008
Example::
1009

    
1010
    ["debian-etch"]
1011

    
1012
``/2/tags``
1013
+++++++++++
1014

    
1015
Manages cluster tags.
1016

    
1017
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1018

    
1019
``GET``
1020
~~~~~~~
1021

    
1022
Returns the cluster tags.
1023

    
1024
Example::
1025

    
1026
    ["tag1", "tag2", "tag3"]
1027

    
1028
``PUT``
1029
~~~~~~~
1030

    
1031
Adds a set of tags.
1032

    
1033
The request as a list of strings should be PUT to this URI. The result
1034
will be a job id.
1035

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

    
1038

    
1039
``DELETE``
1040
~~~~~~~~~~
1041

    
1042
Deletes tags.
1043

    
1044
In order to delete a set of tags, the DELETE request should be addressed
1045
to URI like::
1046

    
1047
    /tags?tag=[tag]&tag=[tag]
1048

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

    
1051

    
1052
``/version``
1053
++++++++++++
1054

    
1055
The version resource.
1056

    
1057
This resource should be used to determine the remote API version and to
1058
adapt clients accordingly.
1059

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

    
1062
``GET``
1063
~~~~~~~
1064

    
1065
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1066
returns ``2``.
1067

    
1068
.. vim: set textwidth=72 :
1069
.. Local Variables:
1070
.. mode: rst
1071
.. fill-column: 72
1072
.. End: