Statistics
| Branch: | Tag: | Revision:

root / doc / rapi.rst @ d2baa21d

History | View | Annotate | Download (18.2 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
Generic parameters
75
------------------
76

    
77
A few parameter mean the same thing across all resources which implement
78
it.
79

    
80
``bulk``
81
++++++++
82

    
83
Bulk-mode means that for the resources which usually return just a list
84
of child resources (e.g. ``/2/instances`` which returns just instance
85
names), the output will instead contain detailed data for all these
86
subresources. This is more efficient than query-ing the sub-resources
87
themselves.
88

    
89
``dry-run``
90
+++++++++++
91

    
92
The optional *dry-run* argument, if provided and set to a positive
93
integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
94
should not be executed, only the pre-execution checks will be done.
95

    
96
This is useful in trying to determine (without guarantees though, as in
97
the meantime the cluster state could have changed) if the operation is
98
likely to succeed or at least start executing.
99

    
100
``force``
101
+++++++++++
102

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

    
106
Usage examples
107
--------------
108

    
109
You can access the API using your favorite programming language as long
110
as it supports network connections.
111

    
112
Shell
113
+++++
114

    
115
.. highlight:: sh
116

    
117
Using wget::
118

    
119
   wget -q -O - https://CLUSTERNAME:5080/2/info
120

    
121
or curl::
122

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

    
125

    
126
Python
127
++++++
128

    
129
.. highlight:: python
130

    
131
::
132

    
133
  import urllib2
134
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
135
  print f.read()
136

    
137

    
138
JavaScript
139
++++++++++
140

    
141
.. warning:: While it's possible to use JavaScript, it poses several
142
   potential problems, including browser blocking request due to
143
   non-standard ports or different domain names. Fetching the data on
144
   the webserver is easier.
145

    
146
.. highlight:: javascript
147

    
148
::
149

    
150
  var url = 'https://CLUSTERNAME:5080/2/info';
151
  var info;
152
  var xmlreq = new XMLHttpRequest();
153
  xmlreq.onreadystatechange = function () {
154
    if (xmlreq.readyState != 4) return;
155
    if (xmlreq.status == 200) {
156
      info = eval("(" + xmlreq.responseText + ")");
157
      alert(info);
158
    } else {
159
      alert('Error fetching cluster info');
160
    }
161
    xmlreq = null;
162
  };
163
  xmlreq.open('GET', url, true);
164
  xmlreq.send(null);
165

    
166
Resources
167
---------
168

    
169
.. highlight:: javascript
170

    
171
``/``
172
+++++
173

    
174
The root resource.
175

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

    
178
``GET``
179
~~~~~~~
180

    
181
Shows the list of mapped resources.
182

    
183
Returns: a dictionary with 'name' and 'uri' keys for each of them.
184

    
185
``/2``
186
++++++
187

    
188
The ``/2`` resource, the root of the version 2 API.
189

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

    
192
``GET``
193
~~~~~~~
194

    
195
Show the list of mapped resources.
196

    
197
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
198

    
199
``/2/info``
200
+++++++++++
201

    
202
Cluster information resource.
203

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

    
206
``GET``
207
~~~~~~~
208

    
209
Returns cluster information.
210

    
211
Example::
212

    
213
  {
214
    "config_version": 2000000,
215
    "name": "cluster",
216
    "software_version": "2.0.0~beta2",
217
    "os_api_version": 10,
218
    "export_version": 0,
219
    "candidate_pool_size": 10,
220
    "enabled_hypervisors": [
221
      "fake"
222
    ],
223
    "hvparams": {
224
      "fake": {}
225
     },
226
    "default_hypervisor": "fake",
227
    "master": "node1.example.com",
228
    "architecture": [
229
      "64bit",
230
      "x86_64"
231
    ],
232
    "protocol_version": 20,
233
    "beparams": {
234
      "default": {
235
        "auto_balance": true,
236
        "vcpus": 1,
237
        "memory": 128
238
       }
239
      }
240
    }
241

    
242

    
243
``/2/redistribute-config``
244
++++++++++++++++++++++++++
245

    
246
Redistribute configuration to all nodes.
247

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

    
250
``PUT``
251
~~~~~~~
252

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

    
255

    
256
``/2/instances``
257
++++++++++++++++
258

    
259
The instances resource.
260

    
261
It supports the following commands: ``GET``, ``POST``.
262

    
263
``GET``
264
~~~~~~~
265

    
266
Returns a list of all available instances.
267

    
268
Example::
269

    
270
    [
271
      {
272
        "name": "web.example.com",
273
        "uri": "\/instances\/web.example.com"
274
      },
275
      {
276
        "name": "mail.example.com",
277
        "uri": "\/instances\/mail.example.com"
278
      }
279
    ]
280

    
281
If the optional *bulk* argument is provided and set to a true value (i.e
282
``?bulk=1``), the output contains detailed information about instances
283
as a list.
284

    
285
Example::
286

    
287
    [
288
      {
289
         "status": "running",
290
         "disk_usage": 20480,
291
         "nic.bridges": [
292
           "xen-br0"
293
          ],
294
         "name": "web.example.com",
295
         "tags": ["tag1", "tag2"],
296
         "beparams": {
297
           "vcpus": 2,
298
           "memory": 512
299
         },
300
         "disk.sizes": [
301
             20480
302
         ],
303
         "pnode": "node1.example.com",
304
         "nic.macs": ["01:23:45:67:89:01"],
305
         "snodes": ["node2.example.com"],
306
         "disk_template": "drbd",
307
         "admin_state": true,
308
         "os": "debian-etch",
309
         "oper_state": true
310
      },
311
      ...
312
    ]
313

    
314

    
315
``POST``
316
~~~~~~~~
317

    
318
Creates an instance.
319

    
320
If the optional *dry-run* argument is provided and set to a positive
321
integer valu (e.g. ``?dry-run=1``), the job will not be actually
322
executed, only the pre-execution checks will be done. Query-ing the job
323
result will return, in both dry-run and normal case, the list of nodes
324
selected for the instance.
325

    
326
Returns: a job ID that can be used later for polling.
327

    
328
``/2/instances/[instance_name]``
329
++++++++++++++++++++++++++++++++
330

    
331
Instance-specific resource.
332

    
333
It supports the following commands: ``GET``, ``DELETE``.
334

    
335
``GET``
336
~~~~~~~
337

    
338
Returns information about an instance, similar to the bulk output from
339
the instance list.
340

    
341
``DELETE``
342
~~~~~~~~~~
343

    
344
Deletes an instance.
345

    
346
It supports the ``dry-run`` argument.
347

    
348

    
349
``/2/instances/[instance_name]/info``
350
+++++++++++++++++++++++++++++++++++++++
351

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

    
354
``GET``
355
~~~~~~~
356

    
357
Requests detailed information about the instance. An optional parameter,
358
``static`` (bool), can be set to return only static information from the
359
configuration without querying the instance's nodes. The result will be
360
a job id.
361

    
362

    
363
``/2/instances/[instance_name]/reboot``
364
+++++++++++++++++++++++++++++++++++++++
365

    
366
Reboots URI for an instance.
367

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

    
370
``POST``
371
~~~~~~~~
372

    
373
Reboots the instance.
374

    
375
The URI takes optional ``type=hard|soft|full`` and
376
``ignore_secondaries=False|True`` parameters.
377

    
378
It supports the ``dry-run`` argument.
379

    
380

    
381
``/2/instances/[instance_name]/shutdown``
382
+++++++++++++++++++++++++++++++++++++++++
383

    
384
Instance shutdown URI.
385

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

    
388
``PUT``
389
~~~~~~~
390

    
391
Shutdowns an instance.
392

    
393
It supports the ``dry-run`` argument.
394

    
395

    
396
``/2/instances/[instance_name]/startup``
397
++++++++++++++++++++++++++++++++++++++++
398

    
399
Instance startup URI.
400

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

    
403
``PUT``
404
~~~~~~~
405

    
406
Startup an instance.
407

    
408
The URI takes an optional ``force=False|True`` parameter to start the
409
instance if even if secondary disks are failing.
410

    
411
It supports the ``dry-run`` argument.
412

    
413
``/2/instances/[instance_name]/reinstall``
414
++++++++++++++++++++++++++++++++++++++++++++++
415

    
416
Installs the operating system again.
417

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

    
420
``POST``
421
~~~~~~~~
422

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

    
425

    
426
``/2/instances/[instance_name]/replace-disks``
427
++++++++++++++++++++++++++++++++++++++++++++++
428

    
429
Replaces disks on an instance.
430

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

    
433
``POST``
434
~~~~~~~~
435

    
436
Takes the parameters ``mode`` (one of ``replace_on_primary``,
437
``replace_on_secondary``, ``replace_new_secondary`` or
438
``replace_auto``), ``disks`` (comma separated list of disk indexes),
439
``remote_node`` and ``iallocator``.
440

    
441

    
442
``/2/instances/[instance_name]/tags``
443
+++++++++++++++++++++++++++++++++++++
444

    
445
Manages per-instance tags.
446

    
447
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
448

    
449
``GET``
450
~~~~~~~
451

    
452
Returns a list of tags.
453

    
454
Example::
455

    
456
    ["tag1", "tag2", "tag3"]
457

    
458
``PUT``
459
~~~~~~~
460

    
461
Add a set of tags.
462

    
463
The request as a list of strings should be ``PUT`` to this URI. The
464
result will be a job id.
465

    
466
It supports the ``dry-run`` argument.
467

    
468

    
469
``DELETE``
470
~~~~~~~~~~
471

    
472
Delete a tag.
473

    
474
In order to delete a set of tags, the DELETE request should be addressed
475
to URI like::
476

    
477
    /tags?tag=[tag]&tag=[tag]
478

    
479
It supports the ``dry-run`` argument.
480

    
481

    
482
``/2/jobs``
483
+++++++++++
484

    
485
The ``/2/jobs`` resource.
486

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

    
489
``GET``
490
~~~~~~~
491

    
492
Returns a dictionary of jobs.
493

    
494
Returns: a dictionary with jobs id and uri.
495

    
496
``/2/jobs/[job_id]``
497
++++++++++++++++++++
498

    
499

    
500
Individual job URI.
501

    
502
It supports the following commands: ``GET``, ``DELETE``.
503

    
504
``GET``
505
~~~~~~~
506

    
507
Returns a job status.
508

    
509
Returns: a dictionary with job parameters.
510

    
511
The result includes:
512

    
513
- id: job ID as a number
514
- status: current job status as a string
515
- ops: involved OpCodes as a list of dictionaries for each opcodes in
516
  the job
517
- opstatus: OpCodes status as a list
518
- opresult: OpCodes results as a list
519

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
579

    
580
``DELETE``
581
~~~~~~~~~~
582

    
583
Cancel a not-yet-started job.
584

    
585
``/2/nodes``
586
++++++++++++
587

    
588
Nodes resource.
589

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

    
592
``GET``
593
~~~~~~~
594

    
595
Returns a list of all nodes.
596

    
597
Example::
598

    
599
    [
600
      {
601
        "id": "node1.example.com",
602
        "uri": "\/nodes\/node1.example.com"
603
      },
604
      {
605
        "id": "node2.example.com",
606
        "uri": "\/nodes\/node2.example.com"
607
      }
608
    ]
609

    
610
If the optional 'bulk' argument is provided and set to 'true' value (i.e
611
'?bulk=1'), the output contains detailed information about nodes as a
612
list.
613

    
614
Example::
615

    
616
    [
617
      {
618
        "pinst_cnt": 1,
619
        "mfree": 31280,
620
        "mtotal": 32763,
621
        "name": "www.example.com",
622
        "tags": [],
623
        "mnode": 512,
624
        "dtotal": 5246208,
625
        "sinst_cnt": 2,
626
        "dfree": 5171712,
627
        "offline": false
628
      },
629
      ...
630
    ]
631

    
632
``/2/nodes/[node_name]``
633
+++++++++++++++++++++++++++++++++
634

    
635
Returns information about a node.
636

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

    
639
``/2/nodes/[node_name]/evacuate``
640
+++++++++++++++++++++++++++++++++
641

    
642
Evacuates all secondary instances off a node.
643

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

    
646
``POST``
647
~~~~~~~~
648

    
649
To evacuate a node, either one of the ``iallocator`` or ``remote_node``
650
parameters must be passed:
651

    
652
    evacuate?iallocator=[iallocator]
653
    evacuate?remote_node=[nodeX.example.com]
654

    
655
``/2/nodes/[node_name]/migrate``
656
+++++++++++++++++++++++++++++++++
657

    
658
Migrates all primary instances from a node.
659

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

    
662
``POST``
663
~~~~~~~~
664

    
665
No parameters are required, but ``live`` can be set to a boolean value.
666

    
667
    migrate?live=[0|1]
668

    
669
``/2/nodes/[node_name]/role``
670
+++++++++++++++++++++++++++++
671

    
672
Manages node role.
673

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

    
676
The role is always one of the following:
677

    
678
  - drained
679
  - master
680
  - master-candidate
681
  - offline
682
  - regular
683

    
684
``GET``
685
~~~~~~~
686

    
687
Returns the current node role.
688

    
689
Example::
690

    
691
    "master-candidate"
692

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

    
696
Change the node role.
697

    
698
The request is a string which should be PUT to this URI. The result will
699
be a job id.
700

    
701
It supports the ``force`` argument.
702

    
703
``/2/nodes/[node_name]/storage``
704
++++++++++++++++++++++++++++++++
705

    
706
Manages storage units on the node.
707

    
708
``GET``
709
~~~~~~~
710

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

    
716
``/2/nodes/[node_name]/storage/modify``
717
+++++++++++++++++++++++++++++++++++++++
718

    
719
Modifies storage units on the node.
720

    
721
``PUT``
722
~~~~~~~
723

    
724
Modifies parameters of storage units on the node. Requires the
725
parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
726
and ``name`` (name of the storage unit).  Parameters can be passed
727
additionally. Currently only ``allocatable`` (bool) is supported. The
728
result will be a job id.
729

    
730
``/2/nodes/[node_name]/storage/repair``
731
+++++++++++++++++++++++++++++++++++++++
732

    
733
Repairs a storage unit on the node.
734

    
735
``PUT``
736
~~~~~~~
737

    
738
Repairs a storage unit on the node. Requires the parameters
739
``storage_type`` (currently only ``lvm-vg`` can be repaired) and
740
``name`` (name of the storage unit). The result will be a job id.
741

    
742
``/2/nodes/[node_name]/tags``
743
+++++++++++++++++++++++++++++
744

    
745
Manages per-node tags.
746

    
747
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
748

    
749
``GET``
750
~~~~~~~
751

    
752
Returns a list of tags.
753

    
754
Example::
755

    
756
    ["tag1", "tag2", "tag3"]
757

    
758
``PUT``
759
~~~~~~~
760

    
761
Add a set of tags.
762

    
763
The request as a list of strings should be PUT to this URI. The result
764
will be a job id.
765

    
766
It supports the ``dry-run`` argument.
767

    
768
``DELETE``
769
~~~~~~~~~~
770

    
771
Deletes tags.
772

    
773
In order to delete a set of tags, the DELETE request should be addressed
774
to URI like::
775

    
776
    /tags?tag=[tag]&tag=[tag]
777

    
778
It supports the ``dry-run`` argument.
779

    
780

    
781
``/2/os``
782
+++++++++
783

    
784
OS resource.
785

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

    
788
``GET``
789
~~~~~~~
790

    
791
Return a list of all OSes.
792

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

    
796
Example::
797

    
798
    ["debian-etch"]
799

    
800
``/2/tags``
801
+++++++++++
802

    
803
Manages cluster tags.
804

    
805
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
806

    
807
``GET``
808
~~~~~~~
809

    
810
Returns the cluster tags.
811

    
812
Example::
813

    
814
    ["tag1", "tag2", "tag3"]
815

    
816
``PUT``
817
~~~~~~~
818

    
819
Adds a set of tags.
820

    
821
The request as a list of strings should be PUT to this URI. The result
822
will be a job id.
823

    
824
It supports the ``dry-run`` argument.
825

    
826

    
827
``DELETE``
828
~~~~~~~~~~
829

    
830
Deletes tags.
831

    
832
In order to delete a set of tags, the DELETE request should be addressed
833
to URI like::
834

    
835
    /tags?tag=[tag]&tag=[tag]
836

    
837
It supports the ``dry-run`` argument.
838

    
839

    
840
``/version``
841
++++++++++++
842

    
843
The version resource.
844

    
845
This resource should be used to determine the remote API version and to
846
adapt clients accordingly.
847

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

    
850
``GET``
851
~~~~~~~
852

    
853
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
854
returns ``2``.
855

    
856
.. vim: set textwidth=72 :
857
.. Local Variables:
858
.. mode: rst
859
.. fill-column: 72
860
.. End: