Statistics
| Branch: | Tag: | Revision:

root / doc / rapi.rst @ 723f4565

History | View | Annotate | Download (13.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
Protocol
20
--------
21

    
22
The protocol used is JSON_ over HTTP designed after the REST_
23
principle.
24

    
25
.. _JSON: http://www.json.org/
26
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
27

    
28
Generic parameters
29
------------------
30

    
31
A few parameter mean the same thing across all resources which implement it.
32

    
33
``bulk``
34
++++++++
35

    
36
Bulk-mode means that for the resources which usually return just a
37
list of child resources (e.g. ``/2/instances`` which returns just
38
instance names), the output will instead contain detailed data for all
39
these subresources. This is more efficient than query-ing the
40
sub-resources themselves.
41

    
42
``dry-run``
43
+++++++++++
44

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

    
49
This is useful in trying to determine (without guarantees though, as
50
in the meantime the cluster state could have changed) if the operation
51
is likely to succeed or at least start executing.
52

    
53
``force``
54
+++++++++++
55

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

    
59
Usage examples
60
--------------
61

    
62
You can access the API using your favorite programming language as
63
long as it supports network connections.
64

    
65
Shell
66
+++++
67

    
68
.. highlight:: sh
69

    
70
Using wget::
71

    
72
   wget -q -O - https://CLUSTERNAME:5080/2/info
73

    
74
or curl::
75

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

    
78

    
79
Python
80
++++++
81

    
82
.. highlight: python
83

    
84
  import urllib2
85
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
86
  print f.read()
87

    
88

    
89
JavaScript
90
++++++++++
91

    
92
.. warning:: While it's possible to use JavaScript, it poses several
93
  potential problems, including browser blocking request due to
94
  non-standard ports or different domain names. Fetching the data on
95
  the webserver is easier.
96

    
97
.. highlight:: javascript
98

    
99
::
100

    
101
  var url = 'https://CLUSTERNAME:5080/2/info';
102
  var info;
103
  var xmlreq = new XMLHttpRequest();
104
  xmlreq.onreadystatechange = function () {
105
    if (xmlreq.readyState != 4) return;
106
    if (xmlreq.status == 200) {
107
      info = eval("(" + xmlreq.responseText + ")");
108
      alert(info);
109
    } else {
110
      alert('Error fetching cluster info');
111
    }
112
    xmlreq = null;
113
  };
114
  xmlreq.open('GET', url, true);
115
  xmlreq.send(null);
116

    
117
Resources
118
---------
119

    
120
.. highlight:: javascript
121

    
122
``/``
123
+++++
124

    
125
The root resource.
126

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

    
129
``GET``
130
~~~~~~~
131

    
132
Shows the list of mapped resources.
133

    
134
Returns: a dictionary with 'name' and 'uri' keys for each of them.
135

    
136
``/2``
137
++++++
138

    
139
The ``/2`` resource, the root of the version 2 API.
140

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

    
143
``GET``
144
~~~~~~~
145

    
146
Show the list of mapped resources.
147

    
148
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
149

    
150
``/2/info``
151
+++++++++++
152

    
153
Cluster information resource.
154

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

    
157
``GET``
158
~~~~~~~
159

    
160
Returns cluster information.
161

    
162
Example::
163

    
164
  {
165
    "config_version": 2000000,
166
    "name": "cluster",
167
    "software_version": "2.0.0~beta2",
168
    "os_api_version": 10,
169
    "export_version": 0,
170
    "candidate_pool_size": 10,
171
    "enabled_hypervisors": [
172
      "fake"
173
    ],
174
    "hvparams": {
175
      "fake": {}
176
     },
177
    "default_hypervisor": "fake",
178
    "master": "node1.example.com",
179
    "architecture": [
180
      "64bit",
181
      "x86_64"
182
    ],
183
    "protocol_version": 20,
184
    "beparams": {
185
      "default": {
186
        "auto_balance": true,
187
        "vcpus": 1,
188
        "memory": 128
189
       }
190
      }
191
    }
192

    
193
``/2/instances``
194
++++++++++++++++
195

    
196
The instances resource.
197

    
198
It supports the following commands: ``GET``, ``POST``.
199

    
200
``GET``
201
~~~~~~~
202

    
203
Returns a list of all available instances.
204

    
205
Example::
206

    
207
    [
208
      {
209
        "name": "web.example.com",
210
        "uri": "\/instances\/web.example.com"
211
      },
212
      {
213
        "name": "mail.example.com",
214
        "uri": "\/instances\/mail.example.com"
215
      }
216
    ]
217

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

    
222
Example::
223

    
224
    [
225
      {
226
         "status": "running",
227
         "disk_usage": 20480,
228
         "nic.bridges": [
229
           "xen-br0"
230
          ],
231
         "name": "web.example.com",
232
         "tags": ["tag1", "tag2"],
233
         "beparams": {
234
           "vcpus": 2,
235
           "memory": 512
236
         },
237
         "disk.sizes": [
238
             20480
239
         ],
240
         "pnode": "node1.example.com",
241
         "nic.macs": ["01:23:45:67:89:01"],
242
         "snodes": ["node2.example.com"],
243
         "disk_template": "drbd",
244
         "admin_state": true,
245
         "os": "debian-etch",
246
         "oper_state": true
247
      },
248
      ...
249
    ]
250

    
251

    
252
``POST``
253
~~~~~~~~
254

    
255
Creates an instance.
256

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

    
263
Returns: a job ID that can be used later for polling.
264

    
265
``/2/instances/[instance_name]``
266
++++++++++++++++++++++++++++++++
267

    
268
Instance-specific resource.
269

    
270
It supports the following commands: ``GET``, ``DELETE``.
271

    
272
``GET``
273
~~~~~~~
274

    
275
Returns information about an instance, similar to the bulk output from
276
the instance list.
277

    
278
``DELETE``
279
~~~~~~~~~~
280

    
281
Deletes an instance.
282

    
283
It supports the ``dry-run`` argument.
284

    
285

    
286
``/2/instances/[instance_name]/reboot``
287
+++++++++++++++++++++++++++++++++++++++
288

    
289
Reboots URI for an instance.
290

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

    
293
``POST``
294
~~~~~~~~
295

    
296
Reboots the instance.
297

    
298
The URI takes optional ``type=hard|soft|full`` and
299
``ignore_secondaries=False|True`` parameters.
300

    
301
It supports the ``dry-run`` argument.
302

    
303

    
304
``/2/instances/[instance_name]/shutdown``
305
+++++++++++++++++++++++++++++++++++++++++
306

    
307
Instance shutdown URI.
308

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

    
311
``PUT``
312
~~~~~~~
313

    
314
Shutdowns an instance.
315

    
316
It supports the ``dry-run`` argument.
317

    
318

    
319
``/2/instances/[instance_name]/startup``
320
++++++++++++++++++++++++++++++++++++++++
321

    
322
Instance startup URI.
323

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

    
326
``PUT``
327
~~~~~~~
328

    
329
Startup an instance.
330

    
331
The URI takes an optional ``force=False|True`` parameter to start the
332
instance if even if secondary disks are failing.
333

    
334
It supports the ``dry-run`` argument.
335

    
336

    
337
``/2/instances/[instance_name]/replace-disks``
338
++++++++++++++++++++++++++++++++++++++++++++++
339

    
340
Replaces disks on an instance.
341

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

    
344
``POST``
345
~~~~~~~~
346

    
347
Takes the parameters ``mode`` (one of ``replace_on_primary``,
348
``replace_on_secondary``, ``replace_new_secondary`` or ``replace_auto``),
349
``disks`` (comma separated list of disk indexes), ``remote_node`` and
350
``iallocator``.
351

    
352

    
353
``/2/instances/[instance_name]/tags``
354
+++++++++++++++++++++++++++++++++++++
355

    
356
Manages per-instance tags.
357

    
358
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
359

    
360
``GET``
361
~~~~~~~
362

    
363
Returns a list of tags.
364

    
365
Example::
366

    
367
    ["tag1", "tag2", "tag3"]
368

    
369
``PUT``
370
~~~~~~~
371

    
372
Add a set of tags.
373

    
374
The request as a list of strings should be ``PUT`` to this URI. The
375
result willl be a job id.
376

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

    
379

    
380
``DELETE``
381
~~~~~~~~~~
382

    
383
Delete a tag.
384

    
385
In order to delete a set of tags, the DELETE request should be
386
addressed to URI like::
387

    
388
    /tags?tag=[tag]&tag=[tag]
389

    
390
It supports the ``dry-run`` argument.
391

    
392

    
393
``/2/jobs``
394
+++++++++++
395

    
396
The ``/2/jobs`` resource.
397

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

    
400
``GET``
401
~~~~~~~
402

    
403
Returns a dictionary of jobs.
404

    
405
Returns: a dictionary with jobs id and uri.
406

    
407
``/2/jobs/[job_id]``
408
++++++++++++++++++++
409

    
410

    
411
Individual job URI.
412

    
413
It supports the following commands: ``GET``, ``DELETE``.
414

    
415
``GET``
416
~~~~~~~
417

    
418
Returns a job status.
419

    
420
Returns: a dictionary with job parameters.
421

    
422
The result includes:
423

    
424
- id: job ID as a number
425
- status: current job status as a string
426
- ops: involved OpCodes as a list of dictionaries for each
427
  opcodes in the job
428
- opstatus: OpCodes status as a list
429
- opresult: OpCodes results as a list of lists
430

    
431
``DELETE``
432
~~~~~~~~~~
433

    
434
Cancel a not-yet-started job.
435

    
436
``/2/nodes``
437
++++++++++++
438

    
439
Nodes resource.
440

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

    
443
``GET``
444
~~~~~~~
445

    
446
Returns a list of all nodes.
447

    
448
Example::
449

    
450
    [
451
      {
452
        "id": "node1.example.com",
453
        "uri": "\/instances\/node1.example.com"
454
      },
455
      {
456
        "id": "node2.example.com",
457
        "uri": "\/instances\/node2.example.com"
458
      }
459
    ]
460

    
461
If the optional 'bulk' argument is provided and set to 'true' value
462
(i.e '?bulk=1'), the output contains detailed information about nodes
463
as a list.
464

    
465
Example::
466

    
467
    [
468
      {
469
        "pinst_cnt": 1,
470
        "mfree": 31280,
471
        "mtotal": 32763,
472
        "name": "www.example.com",
473
        "tags": [],
474
        "mnode": 512,
475
        "dtotal": 5246208,
476
        "sinst_cnt": 2,
477
        "dfree": 5171712,
478
        "offline": false
479
      },
480
      ...
481
    ]
482

    
483
``/2/nodes/[node_name]/evacuate``
484
+++++++++++++++++++++++++++++++++
485

    
486
Evacuates all secondary instances off a node.
487

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

    
490
``POST``
491
~~~~~~~~
492

    
493
To evacuate a node, either one of the ``iallocator`` or ``remote_node``
494
parameters must be passed:
495

    
496
    evacuate?iallocator=[iallocator]
497
    evacuate?remote_node=[nodeX.example.com]
498

    
499
``/2/nodes/[node_name]/migrate``
500
+++++++++++++++++++++++++++++++++
501

    
502
Migrates all primary instances from a node.
503

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

    
506
``POST``
507
~~~~~~~~
508

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

    
511
    migrate?live=[0|1]
512

    
513
``/2/nodes/[node_name]/role``
514
+++++++++++++++++++++++++++++
515

    
516
Manages node role.
517

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

    
520
The role is always one of the following:
521

    
522
  - drained
523
  - master
524
  - master-candidate
525
  - offline
526
  - regular
527

    
528
``GET``
529
~~~~~~~
530

    
531
Returns the current node role.
532

    
533
Example::
534

    
535
    "master-candidate"
536

    
537
``PUT``
538
~~~~~~~
539

    
540
Change the node role.
541

    
542
The request is a string which should be PUT to this URI. The result will be a
543
job id.
544

    
545
It supports the ``force`` argument.
546

    
547
``/2/nodes/[node_name]/storage``
548
++++++++++++++++++++++++++++++++
549

    
550
Manages storage units on the node.
551

    
552
``GET``
553
~~~~~~~
554

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

    
560
``/2/nodes/[node_name]/storage/modify``
561
+++++++++++++++++++++++++++++++++++++++
562

    
563
Modifies storage units on the node.
564

    
565
``PUT``
566
~~~~~~~
567

    
568
Modifies parameters of storage units on the node. Requires the parameters
569
``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and ``name`` (name
570
of the storage unit).  Parameters can be passed additionally. Currently only
571
``allocatable`` (bool) is supported. The result will be a job id.
572

    
573
``/2/nodes/[node_name]/storage/repair``
574
+++++++++++++++++++++++++++++++++++++++
575

    
576
Repairs a storage unit on the node.
577

    
578
``PUT``
579
~~~~~~~
580

    
581
Repairs a storage unit on the node. Requires the parameters ``storage_type``
582
(currently only ``lvm-vg`` can be repaired) and ``name`` (name of the storage
583
unit). The result will be a job id.
584

    
585
``/2/nodes/[node_name]/tags``
586
+++++++++++++++++++++++++++++
587

    
588
Manages per-node tags.
589

    
590
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
591

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

    
595
Returns a list of tags.
596

    
597
Example::
598

    
599
    ["tag1", "tag2", "tag3"]
600

    
601
``PUT``
602
~~~~~~~
603

    
604
Add a set of tags.
605

    
606
The request as a list of strings should be PUT to this URI. The result
607
will be a job id.
608

    
609
It supports the ``dry-run`` argument.
610

    
611
``DELETE``
612
~~~~~~~~~~
613

    
614
Deletes tags.
615

    
616
In order to delete a set of tags, the DELETE request should be
617
addressed to URI like::
618

    
619
    /tags?tag=[tag]&tag=[tag]
620

    
621
It supports the ``dry-run`` argument.
622

    
623

    
624
``/2/os``
625
+++++++++
626

    
627
OS resource.
628

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

    
631
``GET``
632
~~~~~~~
633

    
634
Return a list of all OSes.
635

    
636
Can return error 500 in case of a problem. Since this is a costly
637
operation for Ganeti 2.0, it is not recommended to execute it too
638
often.
639

    
640
Example::
641

    
642
    ["debian-etch"]
643

    
644
``/2/tags``
645
+++++++++++
646

    
647
Manages cluster tags.
648

    
649
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
650

    
651
``GET``
652
~~~~~~~
653

    
654
Returns the cluster tags.
655

    
656
Example::
657

    
658
    ["tag1", "tag2", "tag3"]
659

    
660
``PUT``
661
~~~~~~~
662

    
663
Adds a set of tags.
664

    
665
The request as a list of strings should be PUT to this URI. The result
666
will be a job id.
667

    
668
It supports the ``dry-run`` argument.
669

    
670

    
671
``DELETE``
672
~~~~~~~~~~
673

    
674
Deletes tags.
675

    
676
In order to delete a set of tags, the DELETE request should be
677
addressed to URI like::
678

    
679
    /tags?tag=[tag]&tag=[tag]
680

    
681
It supports the ``dry-run`` argument.
682

    
683

    
684
``/version``
685
++++++++++++
686

    
687
The version resource.
688

    
689
This resource should be used to determine the remote API version and
690
to adapt clients accordingly.
691

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

    
694
``GET``
695
~~~~~~~
696

    
697
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
698
2.0 returns ``2``.