code.grnet.gr Git - ganeti-local/blob - doc/rapi.rst

   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
  32 it.
  33
  34 ``bulk``
  35 ++++++++
  36
  37 Bulk-mode means that for the resources which usually return just a list
  38 of child resources (e.g. ``/2/instances`` which returns just instance
  39 names), the output will instead contain detailed data for all these
  40 subresources. This is more efficient than query-ing the sub-resources
  41 themselves.
  42
  43 ``dry-run``
  44 +++++++++++
  45
  46 The optional *dry-run* argument, if provided and set to a positive
  47 integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
  48 should not be executed, only the pre-execution checks will be done.
  49
  50 This is useful in trying to determine (without guarantees though, as in
  51 the meantime the cluster state could have changed) if the operation is
  52 likely to succeed or at least start executing.
  53
  54 ``force``
  55 +++++++++++
  56
  57 Force operation to continue even if it will cause the cluster to become
  58 inconsistent (e.g. because there are not enough master candidates).
  59
  60 Usage examples
  61 --------------
  62
  63 You can access the API using your favorite programming language as long
  64 as it supports network connections.
  65
  66 Shell
  67 +++++
  68
  69 .. highlight:: sh
  70
  71 Using wget::
  72
  73    wget -q -O - https://CLUSTERNAME:5080/2/info
  74
  75 or curl::
  76
  77   curl https://CLUSTERNAME:5080/2/info
  78
  79
  80 Python
  81 ++++++
  82
  83 .. highlight:: python
  84
  85 ::
  86
  87   import urllib2
  88   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
  89   print f.read()
  90
  91
  92 JavaScript
  93 ++++++++++
  94
  95 .. warning:: While it's possible to use JavaScript, it poses several
  96    potential problems, including browser blocking request due to
  97    non-standard ports or different domain names. Fetching the data on
  98    the webserver is easier.
  99
 100 .. highlight:: javascript
 101
 102 ::
 103
 104   var url = 'https://CLUSTERNAME:5080/2/info';
 105   var info;
 106   var xmlreq = new XMLHttpRequest();
 107   xmlreq.onreadystatechange = function () {
 108     if (xmlreq.readyState != 4) return;
 109     if (xmlreq.status == 200) {
 110       info = eval("(" + xmlreq.responseText + ")");
 111       alert(info);
 112     } else {
 113       alert('Error fetching cluster info');
 114     }
 115     xmlreq = null;
 116   };
 117   xmlreq.open('GET', url, true);
 118   xmlreq.send(null);
 119
 120 Resources
 121 ---------
 122
 123 .. highlight:: javascript
 124
 125 ``/``
 126 +++++
 127
 128 The root resource.
 129
 130 It supports the following commands: ``GET``.
 131
 132 ``GET``
 133 ~~~~~~~
 134
 135 Shows the list of mapped resources.
 136
 137 Returns: a dictionary with 'name' and 'uri' keys for each of them.
 138
 139 ``/2``
 140 ++++++
 141
 142 The ``/2`` resource, the root of the version 2 API.
 143
 144 It supports the following commands: ``GET``.
 145
 146 ``GET``
 147 ~~~~~~~
 148
 149 Show the list of mapped resources.
 150
 151 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
 152
 153 ``/2/info``
 154 +++++++++++
 155
 156 Cluster information resource.
 157
 158 It supports the following commands: ``GET``.
 159
 160 ``GET``
 161 ~~~~~~~
 162
 163 Returns cluster information.
 164
 165 Example::
 166
 167   {
 168     "config_version": 2000000,
 169     "name": "cluster",
 170     "software_version": "2.0.0~beta2",
 171     "os_api_version": 10,
 172     "export_version": 0,
 173     "candidate_pool_size": 10,
 174     "enabled_hypervisors": [
 175       "fake"
 176     ],
 177     "hvparams": {
 178       "fake": {}
 179      },
 180     "default_hypervisor": "fake",
 181     "master": "node1.example.com",
 182     "architecture": [
 183       "64bit",
 184       "x86_64"
 185     ],
 186     "protocol_version": 20,
 187     "beparams": {
 188       "default": {
 189         "auto_balance": true,
 190         "vcpus": 1,
 191         "memory": 128
 192        }
 193       }
 194     }
 195
 196
 197 ``/2/redistribute-config``
 198 ++++++++++++++++++++++++++
 199
 200 Redistribute configuration to all nodes.
 201
 202 It supports the following commands: ``PUT``.
 203
 204 ``PUT``
 205 ~~~~~~~
 206
 207 Redistribute configuration to all nodes. The result will be a job id.
 208
 209
 210 ``/2/instances``
 211 ++++++++++++++++
 212
 213 The instances resource.
 214
 215 It supports the following commands: ``GET``, ``POST``.
 216
 217 ``GET``
 218 ~~~~~~~
 219
 220 Returns a list of all available instances.
 221
 222 Example::
 223
 224     [
 225       {
 226         "name": "web.example.com",
 227         "uri": "\/instances\/web.example.com"
 228       },
 229       {
 230         "name": "mail.example.com",
 231         "uri": "\/instances\/mail.example.com"
 232       }
 233     ]
 234
 235 If the optional *bulk* argument is provided and set to a true value (i.e
 236 ``?bulk=1``), the output contains detailed information about instances
 237 as a list.
 238
 239 Example::
 240
 241     [
 242       {
 243          "status": "running",
 244          "disk_usage": 20480,
 245          "nic.bridges": [
 246            "xen-br0"
 247           ],
 248          "name": "web.example.com",
 249          "tags": ["tag1", "tag2"],
 250          "beparams": {
 251            "vcpus": 2,
 252            "memory": 512
 253          },
 254          "disk.sizes": [
 255              20480
 256          ],
 257          "pnode": "node1.example.com",
 258          "nic.macs": ["01:23:45:67:89:01"],
 259          "snodes": ["node2.example.com"],
 260          "disk_template": "drbd",
 261          "admin_state": true,
 262          "os": "debian-etch",
 263          "oper_state": true
 264       },
 265       ...
 266     ]
 267
 268
 269 ``POST``
 270 ~~~~~~~~
 271
 272 Creates an instance.
 273
 274 If the optional *dry-run* argument is provided and set to a positive
 275 integer valu (e.g. ``?dry-run=1``), the job will not be actually
 276 executed, only the pre-execution checks will be done. Query-ing the job
 277 result will return, in both dry-run and normal case, the list of nodes
 278 selected for the instance.
 279
 280 Returns: a job ID that can be used later for polling.
 281
 282 ``/2/instances/[instance_name]``
 283 ++++++++++++++++++++++++++++++++
 284
 285 Instance-specific resource.
 286
 287 It supports the following commands: ``GET``, ``DELETE``.
 288
 289 ``GET``
 290 ~~~~~~~
 291
 292 Returns information about an instance, similar to the bulk output from
 293 the instance list.
 294
 295 ``DELETE``
 296 ~~~~~~~~~~
 297
 298 Deletes an instance.
 299
 300 It supports the ``dry-run`` argument.
 301
 302
 303 ``/2/instances/[instance_name]/info``
 304 +++++++++++++++++++++++++++++++++++++++
 305
 306 It supports the following commands: ``GET``.
 307
 308 ``GET``
 309 ~~~~~~~
 310
 311 Requests detailed information about the instance. An optional parameter,
 312 ``static`` (bool), can be set to return only static information from the
 313 configuration without querying the instance's nodes. The result will be
 314 a job id.
 315
 316
 317 ``/2/instances/[instance_name]/reboot``
 318 +++++++++++++++++++++++++++++++++++++++
 319
 320 Reboots URI for an instance.
 321
 322 It supports the following commands: ``POST``.
 323
 324 ``POST``
 325 ~~~~~~~~
 326
 327 Reboots the instance.
 328
 329 The URI takes optional ``type=hard|soft|full`` and
 330 ``ignore_secondaries=False|True`` parameters.
 331
 332 It supports the ``dry-run`` argument.
 333
 334
 335 ``/2/instances/[instance_name]/shutdown``
 336 +++++++++++++++++++++++++++++++++++++++++
 337
 338 Instance shutdown URI.
 339
 340 It supports the following commands: ``PUT``.
 341
 342 ``PUT``
 343 ~~~~~~~
 344
 345 Shutdowns an instance.
 346
 347 It supports the ``dry-run`` argument.
 348
 349
 350 ``/2/instances/[instance_name]/startup``
 351 ++++++++++++++++++++++++++++++++++++++++
 352
 353 Instance startup URI.
 354
 355 It supports the following commands: ``PUT``.
 356
 357 ``PUT``
 358 ~~~~~~~
 359
 360 Startup an instance.
 361
 362 The URI takes an optional ``force=False|True`` parameter to start the
 363 instance if even if secondary disks are failing.
 364
 365 It supports the ``dry-run`` argument.
 366
 367 ``/2/instances/[instance_name]/reinstall``
 368 ++++++++++++++++++++++++++++++++++++++++++++++
 369
 370 Installs the operating system again.
 371
 372 It supports the following commands: ``POST``.
 373
 374 ``POST``
 375 ~~~~~~~~
 376
 377 Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
 378
 379
 380 ``/2/instances/[instance_name]/replace-disks``
 381 ++++++++++++++++++++++++++++++++++++++++++++++
 382
 383 Replaces disks on an instance.
 384
 385 It supports the following commands: ``POST``.
 386
 387 ``POST``
 388 ~~~~~~~~
 389
 390 Takes the parameters ``mode`` (one of ``replace_on_primary``,
 391 ``replace_on_secondary``, ``replace_new_secondary`` or
 392 ``replace_auto``), ``disks`` (comma separated list of disk indexes),
 393 ``remote_node`` and ``iallocator``.
 394
 395
 396 ``/2/instances/[instance_name]/tags``
 397 +++++++++++++++++++++++++++++++++++++
 398
 399 Manages per-instance tags.
 400
 401 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 402
 403 ``GET``
 404 ~~~~~~~
 405
 406 Returns a list of tags.
 407
 408 Example::
 409
 410     ["tag1", "tag2", "tag3"]
 411
 412 ``PUT``
 413 ~~~~~~~
 414
 415 Add a set of tags.
 416
 417 The request as a list of strings should be ``PUT`` to this URI. The
 418 result will be a job id.
 419
 420 It supports the ``dry-run`` argument.
 421
 422
 423 ``DELETE``
 424 ~~~~~~~~~~
 425
 426 Delete a tag.
 427
 428 In order to delete a set of tags, the DELETE request should be addressed
 429 to URI like::
 430
 431     /tags?tag=[tag]&tag=[tag]
 432
 433 It supports the ``dry-run`` argument.
 434
 435
 436 ``/2/jobs``
 437 +++++++++++
 438
 439 The ``/2/jobs`` resource.
 440
 441 It supports the following commands: ``GET``.
 442
 443 ``GET``
 444 ~~~~~~~
 445
 446 Returns a dictionary of jobs.
 447
 448 Returns: a dictionary with jobs id and uri.
 449
 450 ``/2/jobs/[job_id]``
 451 ++++++++++++++++++++
 452
 453
 454 Individual job URI.
 455
 456 It supports the following commands: ``GET``, ``DELETE``.
 457
 458 ``GET``
 459 ~~~~~~~
 460
 461 Returns a job status.
 462
 463 Returns: a dictionary with job parameters.
 464
 465 The result includes:
 466
 467 - id: job ID as a number
 468 - status: current job status as a string
 469 - ops: involved OpCodes as a list of dictionaries for each opcodes in
 470   the job
 471 - opstatus: OpCodes status as a list
 472 - opresult: OpCodes results as a list of lists
 473
 474 ``DELETE``
 475 ~~~~~~~~~~
 476
 477 Cancel a not-yet-started job.
 478
 479 ``/2/nodes``
 480 ++++++++++++
 481
 482 Nodes resource.
 483
 484 It supports the following commands: ``GET``.
 485
 486 ``GET``
 487 ~~~~~~~
 488
 489 Returns a list of all nodes.
 490
 491 Example::
 492
 493     [
 494       {
 495         "id": "node1.example.com",
 496         "uri": "\/instances\/node1.example.com"
 497       },
 498       {
 499         "id": "node2.example.com",
 500         "uri": "\/instances\/node2.example.com"
 501       }
 502     ]
 503
 504 If the optional 'bulk' argument is provided and set to 'true' value (i.e
 505 '?bulk=1'), the output contains detailed information about nodes as a
 506 list.
 507
 508 Example::
 509
 510     [
 511       {
 512         "pinst_cnt": 1,
 513         "mfree": 31280,
 514         "mtotal": 32763,
 515         "name": "www.example.com",
 516         "tags": [],
 517         "mnode": 512,
 518         "dtotal": 5246208,
 519         "sinst_cnt": 2,
 520         "dfree": 5171712,
 521         "offline": false
 522       },
 523       ...
 524     ]
 525
 526 ``/2/nodes/[node_name]``
 527 +++++++++++++++++++++++++++++++++
 528
 529 Returns information about a node.
 530
 531 It supports the following commands: ``GET``.
 532
 533 ``/2/nodes/[node_name]/evacuate``
 534 +++++++++++++++++++++++++++++++++
 535
 536 Evacuates all secondary instances off a node.
 537
 538 It supports the following commands: ``POST``.
 539
 540 ``POST``
 541 ~~~~~~~~
 542
 543 To evacuate a node, either one of the ``iallocator`` or ``remote_node``
 544 parameters must be passed:
 545
 546     evacuate?iallocator=[iallocator]
 547     evacuate?remote_node=[nodeX.example.com]
 548
 549 ``/2/nodes/[node_name]/migrate``
 550 +++++++++++++++++++++++++++++++++
 551
 552 Migrates all primary instances from a node.
 553
 554 It supports the following commands: ``POST``.
 555
 556 ``POST``
 557 ~~~~~~~~
 558
 559 No parameters are required, but ``live`` can be set to a boolean value.
 560
 561     migrate?live=[0|1]
 562
 563 ``/2/nodes/[node_name]/role``
 564 +++++++++++++++++++++++++++++
 565
 566 Manages node role.
 567
 568 It supports the following commands: ``GET``, ``PUT``.
 569
 570 The role is always one of the following:
 571
 572   - drained
 573   - master
 574   - master-candidate
 575   - offline
 576   - regular
 577
 578 ``GET``
 579 ~~~~~~~
 580
 581 Returns the current node role.
 582
 583 Example::
 584
 585     "master-candidate"
 586
 587 ``PUT``
 588 ~~~~~~~
 589
 590 Change the node role.
 591
 592 The request is a string which should be PUT to this URI. The result will
 593 be a job id.
 594
 595 It supports the ``force`` argument.
 596
 597 ``/2/nodes/[node_name]/storage``
 598 ++++++++++++++++++++++++++++++++
 599
 600 Manages storage units on the node.
 601
 602 ``GET``
 603 ~~~~~~~
 604
 605 Requests a list of storage units on a node. Requires the parameters
 606 ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
 607 ``output_fields``. The result will be a job id, using which the result
 608 can be retrieved.
 609
 610 ``/2/nodes/[node_name]/storage/modify``
 611 +++++++++++++++++++++++++++++++++++++++
 612
 613 Modifies storage units on the node.
 614
 615 ``PUT``
 616 ~~~~~~~
 617
 618 Modifies parameters of storage units on the node. Requires the
 619 parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
 620 and ``name`` (name of the storage unit).  Parameters can be passed
 621 additionally. Currently only ``allocatable`` (bool) is supported. The
 622 result will be a job id.
 623
 624 ``/2/nodes/[node_name]/storage/repair``
 625 +++++++++++++++++++++++++++++++++++++++
 626
 627 Repairs a storage unit on the node.
 628
 629 ``PUT``
 630 ~~~~~~~
 631
 632 Repairs a storage unit on the node. Requires the parameters
 633 ``storage_type`` (currently only ``lvm-vg`` can be repaired) and
 634 ``name`` (name of the storage unit). The result will be a job id.
 635
 636 ``/2/nodes/[node_name]/tags``
 637 +++++++++++++++++++++++++++++
 638
 639 Manages per-node tags.
 640
 641 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 642
 643 ``GET``
 644 ~~~~~~~
 645
 646 Returns a list of tags.
 647
 648 Example::
 649
 650     ["tag1", "tag2", "tag3"]
 651
 652 ``PUT``
 653 ~~~~~~~
 654
 655 Add a set of tags.
 656
 657 The request as a list of strings should be PUT to this URI. The result
 658 will be a job id.
 659
 660 It supports the ``dry-run`` argument.
 661
 662 ``DELETE``
 663 ~~~~~~~~~~
 664
 665 Deletes tags.
 666
 667 In order to delete a set of tags, the DELETE request should be addressed
 668 to URI like::
 669
 670     /tags?tag=[tag]&tag=[tag]
 671
 672 It supports the ``dry-run`` argument.
 673
 674
 675 ``/2/os``
 676 +++++++++
 677
 678 OS resource.
 679
 680 It supports the following commands: ``GET``.
 681
 682 ``GET``
 683 ~~~~~~~
 684
 685 Return a list of all OSes.
 686
 687 Can return error 500 in case of a problem. Since this is a costly
 688 operation for Ganeti 2.0, it is not recommended to execute it too often.
 689
 690 Example::
 691
 692     ["debian-etch"]
 693
 694 ``/2/tags``
 695 +++++++++++
 696
 697 Manages cluster tags.
 698
 699 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 700
 701 ``GET``
 702 ~~~~~~~
 703
 704 Returns the cluster tags.
 705
 706 Example::
 707
 708     ["tag1", "tag2", "tag3"]
 709
 710 ``PUT``
 711 ~~~~~~~
 712
 713 Adds a set of tags.
 714
 715 The request as a list of strings should be PUT to this URI. The result
 716 will be a job id.
 717
 718 It supports the ``dry-run`` argument.
 719
 720
 721 ``DELETE``
 722 ~~~~~~~~~~
 723
 724 Deletes tags.
 725
 726 In order to delete a set of tags, the DELETE request should be addressed
 727 to URI like::
 728
 729     /tags?tag=[tag]&tag=[tag]
 730
 731 It supports the ``dry-run`` argument.
 732
 733
 734 ``/version``
 735 ++++++++++++
 736
 737 The version resource.
 738
 739 This resource should be used to determine the remote API version and to
 740 adapt clients accordingly.
 741
 742 It supports the following commands: ``GET``.
 743
 744 ``GET``
 745 ~~~~~~~
 746
 747 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
 748 returns ``2``.
 749
 750 .. vim: set textwidth=72 :
 751 .. Local Variables:
 752 .. mode: rst
 753 .. fill-column: 72
 754 .. End: