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