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

Iustin Pop's avatar
Iustin Pop committed
4
Documents Ganeti version |version|
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

.. contents::

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

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

Protocol
--------

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

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

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
Generic parameters
------------------

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

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

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

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

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

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

53 54 55 56 57 58
``force``
+++++++++++

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

59 60 61 62 63 64 65 66 67
Usage examples
--------------

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

Shell
+++++

Iustin Pop's avatar
Iustin Pop committed
68 69
.. highlight:: sh

70 71
Using wget::

Iustin Pop's avatar
Iustin Pop committed
72
   wget -q -O - https://CLUSTERNAME:5080/2/info
73 74 75 76 77 78 79 80 81

or curl::

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


Python
++++++

Iustin Pop's avatar
Iustin Pop committed
82
.. highlight: python
83 84

  import urllib2
Tim Boring's avatar
Tim Boring committed
85
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
86 87 88 89 90 91
  print f.read()


JavaScript
++++++++++

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

Iustin Pop's avatar
Iustin Pop committed
97 98
.. highlight:: javascript

99 100
::

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

Resources
---------

Iustin Pop's avatar
Iustin Pop committed
120
.. highlight:: javascript
121

Iustin Pop's avatar
Iustin Pop committed
122 123
``/``
+++++
124

Iustin Pop's avatar
Iustin Pop committed
125
The root resource.
126

Iustin Pop's avatar
Iustin Pop committed
127
It supports the following commands: ``GET``.
128

Iustin Pop's avatar
Iustin Pop committed
129 130
``GET``
~~~~~~~
131

Iustin Pop's avatar
Iustin Pop committed
132
Shows the list of mapped resources.
133

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

Iustin Pop's avatar
Iustin Pop committed
136 137
``/2``
++++++
138

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

Iustin Pop's avatar
Iustin Pop committed
141
It supports the following commands: ``GET``.
142

Iustin Pop's avatar
Iustin Pop committed
143 144
``GET``
~~~~~~~
145

Iustin Pop's avatar
Iustin Pop committed
146
Show the list of mapped resources.
147

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

Iustin Pop's avatar
Iustin Pop committed
150 151
``/2/info``
+++++++++++
152

Iustin Pop's avatar
Iustin Pop committed
153
Cluster information resource.
154

Iustin Pop's avatar
Iustin Pop committed
155
It supports the following commands: ``GET``.
156

Iustin Pop's avatar
Iustin Pop committed
157 158
``GET``
~~~~~~~
159

Iustin Pop's avatar
Iustin Pop committed
160
Returns cluster information.
161

Iustin Pop's avatar
Iustin Pop committed
162
Example::
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192

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

Iustin Pop's avatar
Iustin Pop committed
193 194
``/2/instances``
++++++++++++++++
195

Iustin Pop's avatar
Iustin Pop committed
196
The instances resource.
197

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

Iustin Pop's avatar
Iustin Pop committed
200 201
``GET``
~~~~~~~
202

Iustin Pop's avatar
Iustin Pop committed
203
Returns a list of all available instances.
204

Iustin Pop's avatar
Iustin Pop committed
205
Example::
206 207 208 209 210 211 212 213 214 215 216 217

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

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

Iustin Pop's avatar
Iustin Pop committed
222
Example::
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

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


Iustin Pop's avatar
Iustin Pop committed
252 253
``POST``
~~~~~~~~
254

Iustin Pop's avatar
Iustin Pop committed
255
Creates an instance.
256

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

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

Iustin Pop's avatar
Iustin Pop committed
265 266
``/2/instances/[instance_name]``
++++++++++++++++++++++++++++++++
267

Iustin Pop's avatar
Iustin Pop committed
268
Instance-specific resource.
269

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

Iustin Pop's avatar
Iustin Pop committed
272 273
``GET``
~~~~~~~
274

Iustin Pop's avatar
Iustin Pop committed
275 276
Returns information about an instance, similar to the bulk output from
the instance list.
277

Iustin Pop's avatar
Iustin Pop committed
278 279
``DELETE``
~~~~~~~~~~
280

Iustin Pop's avatar
Iustin Pop committed
281
Deletes an instance.
282

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

285

286 287 288 289 290 291 292 293 294 295 296 297 298 299
``/2/instances/[instance_name]/info``
+++++++++++++++++++++++++++++++++++++++

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

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

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


Iustin Pop's avatar
Iustin Pop committed
300 301
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
302

Iustin Pop's avatar
Iustin Pop committed
303
Reboots URI for an instance.
304

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

Iustin Pop's avatar
Iustin Pop committed
307 308
``POST``
~~~~~~~~
309

Iustin Pop's avatar
Iustin Pop committed
310
Reboots the instance.
311

Iustin Pop's avatar
Iustin Pop committed
312 313
The URI takes optional ``type=hard|soft|full`` and
``ignore_secondaries=False|True`` parameters.
314

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


Iustin Pop's avatar
Iustin Pop committed
318 319
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
320

Iustin Pop's avatar
Iustin Pop committed
321
Instance shutdown URI.
322

Iustin Pop's avatar
Iustin Pop committed
323
It supports the following commands: ``PUT``.
324

Iustin Pop's avatar
Iustin Pop committed
325 326
``PUT``
~~~~~~~
327

Iustin Pop's avatar
Iustin Pop committed
328
Shutdowns an instance.
329

330 331
It supports the ``dry-run`` argument.

332

Iustin Pop's avatar
Iustin Pop committed
333 334
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
335

Iustin Pop's avatar
Iustin Pop committed
336
Instance startup URI.
337

Iustin Pop's avatar
Iustin Pop committed
338
It supports the following commands: ``PUT``.
339

Iustin Pop's avatar
Iustin Pop committed
340 341
``PUT``
~~~~~~~
342

Iustin Pop's avatar
Iustin Pop committed
343
Startup an instance.
344

Iustin Pop's avatar
Iustin Pop committed
345 346
The URI takes an optional ``force=False|True`` parameter to start the
instance if even if secondary disks are failing.
347

348 349 350
It supports the ``dry-run`` argument.


351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
``/2/instances/[instance_name]/replace-disks``
++++++++++++++++++++++++++++++++++++++++++++++

Replaces disks on an instance.

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

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

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


Iustin Pop's avatar
Iustin Pop committed
367 368
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
369

Iustin Pop's avatar
Iustin Pop committed
370
Manages per-instance tags.
371

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

Iustin Pop's avatar
Iustin Pop committed
374 375
``GET``
~~~~~~~
376

Iustin Pop's avatar
Iustin Pop committed
377
Returns a list of tags.
378

Iustin Pop's avatar
Iustin Pop committed
379
Example::
380

Iustin Pop's avatar
Iustin Pop committed
381
    ["tag1", "tag2", "tag3"]
382

Iustin Pop's avatar
Iustin Pop committed
383 384
``PUT``
~~~~~~~
385

Iustin Pop's avatar
Iustin Pop committed
386
Add a set of tags.
387

Iustin Pop's avatar
Iustin Pop committed
388 389
The request as a list of strings should be ``PUT`` to this URI. The
result willl be a job id.
390

391 392 393
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
394 395
``DELETE``
~~~~~~~~~~
396

Iustin Pop's avatar
Iustin Pop committed
397
Delete a tag.
398

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

Iustin Pop's avatar
Iustin Pop committed
402
    /tags?tag=[tag]&tag=[tag]
403

404 405 406
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
407 408
``/2/jobs``
+++++++++++
409

Iustin Pop's avatar
Iustin Pop committed
410
The ``/2/jobs`` resource.
411

Iustin Pop's avatar
Iustin Pop committed
412
It supports the following commands: ``GET``.
413

Iustin Pop's avatar
Iustin Pop committed
414 415
``GET``
~~~~~~~
416

Iustin Pop's avatar
Iustin Pop committed
417
Returns a dictionary of jobs.
418

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

Iustin Pop's avatar
Iustin Pop committed
421 422
``/2/jobs/[job_id]``
++++++++++++++++++++
423 424


Iustin Pop's avatar
Iustin Pop committed
425
Individual job URI.
426

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

Iustin Pop's avatar
Iustin Pop committed
429 430
``GET``
~~~~~~~
431

Iustin Pop's avatar
Iustin Pop committed
432
Returns a job status.
433

Iustin Pop's avatar
Iustin Pop committed
434
Returns: a dictionary with job parameters.
435

Iustin Pop's avatar
Iustin Pop committed
436
The result includes:
437

Iustin Pop's avatar
Iustin Pop committed
438 439 440 441 442 443
- id: job ID as a number
- status: current job status as a string
- ops: involved OpCodes as a list of dictionaries for each
  opcodes in the job
- opstatus: OpCodes status as a list
- opresult: OpCodes results as a list of lists
444

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

Iustin Pop's avatar
Iustin Pop committed
448
Cancel a not-yet-started job.
449

Iustin Pop's avatar
Iustin Pop committed
450 451
``/2/nodes``
++++++++++++
452

Iustin Pop's avatar
Iustin Pop committed
453
Nodes resource.
454

Iustin Pop's avatar
Iustin Pop committed
455
It supports the following commands: ``GET``.
456

Iustin Pop's avatar
Iustin Pop committed
457 458
``GET``
~~~~~~~
459

Iustin Pop's avatar
Iustin Pop committed
460
Returns a list of all nodes.
461

Iustin Pop's avatar
Iustin Pop committed
462
Example::
463 464 465 466 467 468 469 470 471 472 473 474

    [
      {
        "id": "node1.example.com",
        "uri": "\/instances\/node1.example.com"
      },
      {
        "id": "node2.example.com",
        "uri": "\/instances\/node2.example.com"
      }
    ]

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

Iustin Pop's avatar
Iustin Pop committed
479
Example::
480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496

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

497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512
``/2/nodes/[node_name]/evacuate``
+++++++++++++++++++++++++++++++++

Evacuates all secondary instances off a node.

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

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

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

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

513 514 515 516 517 518 519 520 521 522 523 524 525 526
``/2/nodes/[node_name]/migrate``
+++++++++++++++++++++++++++++++++

Migrates all primary instances from a node.

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

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

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

    migrate?live=[0|1]

527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560
``/2/nodes/[node_name]/role``
+++++++++++++++++++++++++++++

Manages node role.

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

The role is always one of the following:

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

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

Returns the current node role.

Example::

    "master-candidate"

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

Change the node role.

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

It supports the ``force`` argument.

561 562 563 564 565 566 567 568 569 570 571 572 573
``/2/nodes/[node_name]/storage``
++++++++++++++++++++++++++++++++

Manages storage units on the node.

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

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

574 575 576 577 578 579 580 581 582 583 584 585 586
``/2/nodes/[node_name]/storage/modify``
+++++++++++++++++++++++++++++++++++++++

Modifies storage units on the node.

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

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

587 588 589 590 591 592 593 594 595 596 597 598
``/2/nodes/[node_name]/storage/repair``
+++++++++++++++++++++++++++++++++++++++

Repairs a storage unit on the node.

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

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

Iustin Pop's avatar
Iustin Pop committed
599 600
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
601

Iustin Pop's avatar
Iustin Pop committed
602
Manages per-node tags.
603

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

Iustin Pop's avatar
Iustin Pop committed
606 607
``GET``
~~~~~~~
608

Iustin Pop's avatar
Iustin Pop committed
609
Returns a list of tags.
610

Iustin Pop's avatar
Iustin Pop committed
611
Example::
612

Iustin Pop's avatar
Iustin Pop committed
613
    ["tag1", "tag2", "tag3"]
614

Iustin Pop's avatar
Iustin Pop committed
615 616
``PUT``
~~~~~~~
617

Iustin Pop's avatar
Iustin Pop committed
618
Add a set of tags.
619

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

623 624
It supports the ``dry-run`` argument.

Iustin Pop's avatar
Iustin Pop committed
625 626
``DELETE``
~~~~~~~~~~
627

Iustin Pop's avatar
Iustin Pop committed
628
Deletes tags.
629

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

Iustin Pop's avatar
Iustin Pop committed
633
    /tags?tag=[tag]&tag=[tag]
634

635 636 637
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
638 639
``/2/os``
+++++++++
640

Iustin Pop's avatar
Iustin Pop committed
641
OS resource.
642

Iustin Pop's avatar
Iustin Pop committed
643
It supports the following commands: ``GET``.
644

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

Iustin Pop's avatar
Iustin Pop committed
648
Return a list of all OSes.
649

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

Iustin Pop's avatar
Iustin Pop committed
654
Example::
655

Iustin Pop's avatar
Iustin Pop committed
656
    ["debian-etch"]
657

Iustin Pop's avatar
Iustin Pop committed
658 659
``/2/tags``
+++++++++++
660

Iustin Pop's avatar
Iustin Pop committed
661
Manages cluster tags.
662

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

Iustin Pop's avatar
Iustin Pop committed
665 666
``GET``
~~~~~~~
667

Iustin Pop's avatar
Iustin Pop committed
668
Returns the cluster tags.
669

Iustin Pop's avatar
Iustin Pop committed
670
Example::
671

Iustin Pop's avatar
Iustin Pop committed
672
    ["tag1", "tag2", "tag3"]
673

Iustin Pop's avatar
Iustin Pop committed
674 675
``PUT``
~~~~~~~
676

Iustin Pop's avatar
Iustin Pop committed
677
Adds a set of tags.
678

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

682 683 684
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
685 686
``DELETE``
~~~~~~~~~~
687

Iustin Pop's avatar
Iustin Pop committed
688
Deletes tags.
689

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

Iustin Pop's avatar
Iustin Pop committed
693
    /tags?tag=[tag]&tag=[tag]
694

695 696 697
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
698 699
``/version``
++++++++++++
700

Iustin Pop's avatar
Iustin Pop committed
701
The version resource.
702

Iustin Pop's avatar
Iustin Pop committed
703 704
This resource should be used to determine the remote API version and
to adapt clients accordingly.
705

Iustin Pop's avatar
Iustin Pop committed
706
It supports the following commands: ``GET``.
707

Iustin Pop's avatar
Iustin Pop committed
708 709
``GET``
~~~~~~~
710

Iustin Pop's avatar
Iustin Pop committed
711 712
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
2.0 returns ``2``.