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
  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
  75 PUT or POST?
  76 ------------
  77
  78 According to RFC2616 the main difference between PUT and POST is that
  79 POST can create new resources but PUT can only create the resource the
  80 URI was pointing to on the PUT request.
  81
  82 Unfortunately, due to historic reasons, the Ganeti RAPI library is not
  83 consistent with this usage, so just use the methods as documented below
  84 for each resource.
  85
  86 For more details have a look in the source code at
  87 ``lib/rapi/rlib2.py``.
  88
  89
  90 Generic parameter types
  91 -----------------------
  92
  93 A few generic refered parameter types and the values they allow.
  94
  95 ``bool``
  96 ++++++++
  97
  98 A boolean option will accept ``1`` or ``0`` as numbers but not
  99 i.e. ``True`` or ``False``.
 100
 101 Generic parameters
 102 ------------------
 103
 104 A few parameter mean the same thing across all resources which implement
 105 it.
 106
 107 ``bulk``
 108 ++++++++
 109
 110 Bulk-mode means that for the resources which usually return just a list
 111 of child resources (e.g. ``/2/instances`` which returns just instance
 112 names), the output will instead contain detailed data for all these
 113 subresources. This is more efficient than query-ing the sub-resources
 114 themselves.
 115
 116 ``dry-run``
 117 +++++++++++
 118
 119 The boolean *dry-run* argument, if provided and set, signals to Ganeti
 120 that the job should not be executed, only the pre-execution checks will
 121 be done.
 122
 123 This is useful in trying to determine (without guarantees though, as in
 124 the meantime the cluster state could have changed) if the operation is
 125 likely to succeed or at least start executing.
 126
 127 ``force``
 128 +++++++++++
 129
 130 Force operation to continue even if it will cause the cluster to become
 131 inconsistent (e.g. because there are not enough master candidates).
 132
 133 Usage examples
 134 --------------
 135
 136 You can access the API using your favorite programming language as long
 137 as it supports network connections.
 138
 139 Ganeti RAPI client
 140 ++++++++++++++++++
 141
 142 Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.
 143
 144 Shell
 145 +++++
 146
 147 .. highlight:: sh
 148
 149 Using wget::
 150
 151    wget -q -O - https://CLUSTERNAME:5080/2/info
 152
 153 or curl::
 154
 155   curl https://CLUSTERNAME:5080/2/info
 156
 157
 158 Python
 159 ++++++
 160
 161 .. highlight:: python
 162
 163 ::
 164
 165   import urllib2
 166   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
 167   print f.read()
 168
 169
 170 JavaScript
 171 ++++++++++
 172
 173 .. warning:: While it's possible to use JavaScript, it poses several
 174    potential problems, including browser blocking request due to
 175    non-standard ports or different domain names. Fetching the data on
 176    the webserver is easier.
 177
 178 .. highlight:: javascript
 179
 180 ::
 181
 182   var url = 'https://CLUSTERNAME:5080/2/info';
 183   var info;
 184   var xmlreq = new XMLHttpRequest();
 185   xmlreq.onreadystatechange = function () {
 186     if (xmlreq.readyState != 4) return;
 187     if (xmlreq.status == 200) {
 188       info = eval("(" + xmlreq.responseText + ")");
 189       alert(info);
 190     } else {
 191       alert('Error fetching cluster info');
 192     }
 193     xmlreq = null;
 194   };
 195   xmlreq.open('GET', url, true);
 196   xmlreq.send(null);
 197
 198 Resources
 199 ---------
 200
 201 .. highlight:: javascript
 202
 203 ``/``
 204 +++++
 205
 206 The root resource.
 207
 208 It supports the following commands: ``GET``.
 209
 210 ``GET``
 211 ~~~~~~~
 212
 213 Shows the list of mapped resources.
 214
 215 Returns: a dictionary with 'name' and 'uri' keys for each of them.
 216
 217 ``/2``
 218 ++++++
 219
 220 The ``/2`` resource, the root of the version 2 API.
 221
 222 It supports the following commands: ``GET``.
 223
 224 ``GET``
 225 ~~~~~~~
 226
 227 Show the list of mapped resources.
 228
 229 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
 230
 231 ``/2/info``
 232 +++++++++++
 233
 234 Cluster information resource.
 235
 236 It supports the following commands: ``GET``.
 237
 238 ``GET``
 239 ~~~~~~~
 240
 241 Returns cluster information.
 242
 243 Example::
 244
 245   {
 246     "config_version": 2000000,
 247     "name": "cluster",
 248     "software_version": "2.0.0~beta2",
 249     "os_api_version": 10,
 250     "export_version": 0,
 251     "candidate_pool_size": 10,
 252     "enabled_hypervisors": [
 253       "fake"
 254     ],
 255     "hvparams": {
 256       "fake": {}
 257      },
 258     "default_hypervisor": "fake",
 259     "master": "node1.example.com",
 260     "architecture": [
 261       "64bit",
 262       "x86_64"
 263     ],
 264     "protocol_version": 20,
 265     "beparams": {
 266       "default": {
 267         "auto_balance": true,
 268         "vcpus": 1,
 269         "memory": 128
 270        }
 271       }
 272     }
 273
 274
 275 ``/2/redistribute-config``
 276 ++++++++++++++++++++++++++
 277
 278 Redistribute configuration to all nodes.
 279
 280 It supports the following commands: ``PUT``.
 281
 282 ``PUT``
 283 ~~~~~~~
 284
 285 Redistribute configuration to all nodes. The result will be a job id.
 286
 287
 288 ``/2/features``
 289 +++++++++++++++
 290
 291 ``GET``
 292 ~~~~~~~
 293
 294 Returns a list of features supported by the RAPI server. Available
 295 features:
 296
 297 ``instance-create-reqv1``
 298   Instance creation request data version 1 supported.
 299
 300
 301 ``/2/instances``
 302 ++++++++++++++++
 303
 304 The instances resource.
 305
 306 It supports the following commands: ``GET``, ``POST``.
 307
 308 ``GET``
 309 ~~~~~~~
 310
 311 Returns a list of all available instances.
 312
 313 Example::
 314
 315     [
 316       {
 317         "name": "web.example.com",
 318         "uri": "\/instances\/web.example.com"
 319       },
 320       {
 321         "name": "mail.example.com",
 322         "uri": "\/instances\/mail.example.com"
 323       }
 324     ]
 325
 326 If the optional bool *bulk* argument is provided and set to a true value
 327 (i.e ``?bulk=1``), the output contains detailed information about
 328 instances as a list.
 329
 330 Example::
 331
 332     [
 333       {
 334          "status": "running",
 335          "disk_usage": 20480,
 336          "nic.bridges": [
 337            "xen-br0"
 338           ],
 339          "name": "web.example.com",
 340          "tags": ["tag1", "tag2"],
 341          "beparams": {
 342            "vcpus": 2,
 343            "memory": 512
 344          },
 345          "disk.sizes": [
 346              20480
 347          ],
 348          "pnode": "node1.example.com",
 349          "nic.macs": ["01:23:45:67:89:01"],
 350          "snodes": ["node2.example.com"],
 351          "disk_template": "drbd",
 352          "admin_state": true,
 353          "os": "debian-etch",
 354          "oper_state": true
 355       },
 356       ...
 357     ]
 358
 359
 360 ``POST``
 361 ~~~~~~~~
 362
 363 Creates an instance.
 364
 365 If the optional bool *dry-run* argument is provided, the job will not be
 366 actually executed, only the pre-execution checks will be done. Query-ing
 367 the job result will return, in both dry-run and normal case, the list of
 368 nodes selected for the instance.
 369
 370 Returns: a job ID that can be used later for polling.
 371
 372 Body parameters:
 373
 374 ``__version__`` (int, required)
 375   Must be ``1`` (older Ganeti versions used a different format for
 376   instance creation requests, version ``0``, but that format is not
 377   documented).
 378 ``mode``
 379   Instance creation mode (string, required).
 380 ``name`` (string, required)
 381   Instance name
 382 ``disk_template`` (string, required)
 383   Disk template for instance
 384 ``disks`` (list, required)
 385   List of disk definitions. Example: ``[{"size": 100}, {"size": 5}]``.
 386   Each disk definition must contain a ``size`` value and can contain an
 387   optional ``mode`` value denoting the disk access mode (``ro`` or
 388   ``rw``).
 389 ``nics`` (list, required)
 390   List of NIC (network interface) definitions. Example: ``[{}, {},
 391   {"ip": "198.51.100.4"}]``. Each NIC definition can contain the
 392   optional values ``ip``, ``mode``, ``link`` and ``bridge``.
 393 ``os`` (string, required)
 394   Instance operating system.
 395 ``osparams`` (dictionary)
 396   Dictionary with OS parameters. If not valid for the given OS, the job
 397   will fail.
 398 ``force_variant`` (bool)
 399   Whether to force an unknown variant.
 400 ``pnode`` (string)
 401   Primary node.
 402 ``snode`` (string)
 403   Secondary node.
 404 ``src_node`` (string)
 405   Source node for import.
 406 ``src_path`` (string)
 407   Source directory for import.
 408 ``start`` (bool)
 409   Whether to start instance after creation.
 410 ``ip_check`` (bool)
 411   Whether to ensure instance's IP address is inactive.
 412 ``name_check`` (bool)
 413   Whether to ensure instance's name is resolvable.
 414 ``file_storage_dir`` (string)
 415   File storage directory.
 416 ``file_driver`` (string)
 417   File storage driver.
 418 ``iallocator`` (string)
 419   Instance allocator name.
 420 ``source_handshake``
 421   Signed handshake from source (remote import only).
 422 ``source_x509_ca`` (string)
 423   Source X509 CA in PEM format (remote import only).
 424 ``source_instance_name`` (string)
 425   Source instance name (remote import only).
 426 ``hypervisor`` (string)
 427   Hypervisor name.
 428 ``hvparams`` (dict)
 429   Hypervisor parameters, hypervisor-dependent.
 430 ``beparams``
 431   Backend parameters.
 432
 433
 434 ``/2/instances/[instance_name]``
 435 ++++++++++++++++++++++++++++++++
 436
 437 Instance-specific resource.
 438
 439 It supports the following commands: ``GET``, ``DELETE``.
 440
 441 ``GET``
 442 ~~~~~~~
 443
 444 Returns information about an instance, similar to the bulk output from
 445 the instance list.
 446
 447 ``DELETE``
 448 ~~~~~~~~~~
 449
 450 Deletes an instance.
 451
 452 It supports the ``dry-run`` argument.
 453
 454
 455 ``/2/instances/[instance_name]/info``
 456 +++++++++++++++++++++++++++++++++++++++
 457
 458 It supports the following commands: ``GET``.
 459
 460 ``GET``
 461 ~~~~~~~
 462
 463 Requests detailed information about the instance. An optional parameter,
 464 ``static`` (bool), can be set to return only static information from the
 465 configuration without querying the instance's nodes. The result will be
 466 a job id.
 467
 468
 469 ``/2/instances/[instance_name]/reboot``
 470 +++++++++++++++++++++++++++++++++++++++
 471
 472 Reboots URI for an instance.
 473
 474 It supports the following commands: ``POST``.
 475
 476 ``POST``
 477 ~~~~~~~~
 478
 479 Reboots the instance.
 480
 481 The URI takes optional ``type=soft|hard|full`` and
 482 ``ignore_secondaries=0|1`` parameters.
 483
 484 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
 485 without terminating the hypervisor. ``hard`` means full shutdown
 486 (including terminating the hypervisor process) and startup again.
 487 ``full`` is like ``hard`` but also recreates the configuration from
 488 ground up as if you would have done a ``gnt-instance shutdown`` and
 489 ``gnt-instance start`` on it.
 490
 491 ``ignore_secondaries`` is a bool argument indicating if we start the
 492 instance even if secondary disks are failing.
 493
 494 It supports the ``dry-run`` argument.
 495
 496
 497 ``/2/instances/[instance_name]/shutdown``
 498 +++++++++++++++++++++++++++++++++++++++++
 499
 500 Instance shutdown URI.
 501
 502 It supports the following commands: ``PUT``.
 503
 504 ``PUT``
 505 ~~~~~~~
 506
 507 Shutdowns an instance.
 508
 509 It supports the ``dry-run`` argument.
 510
 511
 512 ``/2/instances/[instance_name]/startup``
 513 ++++++++++++++++++++++++++++++++++++++++
 514
 515 Instance startup URI.
 516
 517 It supports the following commands: ``PUT``.
 518
 519 ``PUT``
 520 ~~~~~~~
 521
 522 Startup an instance.
 523
 524 The URI takes an optional ``force=1|0`` parameter to start the
 525 instance even if secondary disks are failing.
 526
 527 It supports the ``dry-run`` argument.
 528
 529 ``/2/instances/[instance_name]/reinstall``
 530 ++++++++++++++++++++++++++++++++++++++++++++++
 531
 532 Installs the operating system again.
 533
 534 It supports the following commands: ``POST``.
 535
 536 ``POST``
 537 ~~~~~~~~
 538
 539 Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
 540
 541
 542 ``/2/instances/[instance_name]/replace-disks``
 543 ++++++++++++++++++++++++++++++++++++++++++++++
 544
 545 Replaces disks on an instance.
 546
 547 It supports the following commands: ``POST``.
 548
 549 ``POST``
 550 ~~~~~~~~
 551
 552 Takes the parameters ``mode`` (one of ``replace_on_primary``,
 553 ``replace_on_secondary``, ``replace_new_secondary`` or
 554 ``replace_auto``), ``disks`` (comma separated list of disk indexes),
 555 ``remote_node`` and ``iallocator``.
 556
 557 Either ``remote_node`` or ``iallocator`` needs to be defined when using
 558 ``mode=replace_new_secondary``.
 559
 560 ``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
 561 the broken disk(s) on its own and replacing it.
 562
 563
 564 ``/2/instances/[instance_name]/activate-disks``
 565 +++++++++++++++++++++++++++++++++++++++++++++++
 566
 567 Activate disks on an instance.
 568
 569 It supports the following commands: ``PUT``.
 570
 571 ``PUT``
 572 ~~~~~~~
 573
 574 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 575 size (useful for forcing activation when recorded size is wrong).
 576
 577
 578 ``/2/instances/[instance_name]/deactivate-disks``
 579 +++++++++++++++++++++++++++++++++++++++++++++++++
 580
 581 Deactivate disks on an instance.
 582
 583 It supports the following commands: ``PUT``.
 584
 585 ``PUT``
 586 ~~~~~~~
 587
 588 Takes no parameters.
 589
 590
 591 ``/2/instances/[instance_name]/prepare-export``
 592 +++++++++++++++++++++++++++++++++++++++++++++++++
 593
 594 Prepares an export of an instance.
 595
 596 It supports the following commands: ``PUT``.
 597
 598 ``PUT``
 599 ~~~~~~~
 600
 601 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 602
 603
 604 ``/2/instances/[instance_name]/export``
 605 +++++++++++++++++++++++++++++++++++++++++++++++++
 606
 607 Exports an instance.
 608
 609 It supports the following commands: ``PUT``.
 610
 611 ``PUT``
 612 ~~~~~~~
 613
 614 Returns a job ID.
 615
 616 Body parameters:
 617
 618 ``mode`` (string)
 619   Export mode.
 620 ``destination`` (required)
 621   Destination information, depends on export mode.
 622 ``shutdown`` (bool, required)
 623   Whether to shutdown instance before export.
 624 ``remove_instance`` (bool)
 625   Whether to remove instance after export.
 626 ``x509_key_name``
 627   Name of X509 key (remote export only).
 628 ``destination_x509_ca``
 629   Destination X509 CA (remote export only).
 630
 631
 632 ``/2/instances/[instance_name]/migrate``
 633 ++++++++++++++++++++++++++++++++++++++++
 634
 635 Migrates an instance.
 636
 637 Supports the following commands: ``PUT``.
 638
 639 ``PUT``
 640 ~~~~~~~
 641
 642 Returns a job ID.
 643
 644 Body parameters:
 645
 646 ``mode`` (string)
 647   Migration mode.
 648 ``cleanup`` (bool)
 649   Whether a previously failed migration should be cleaned up.
 650
 651
 652 ``/2/instances/[instance_name]/rename``
 653 ++++++++++++++++++++++++++++++++++++++++
 654
 655 Renames an instance.
 656
 657 Supports the following commands: ``PUT``.
 658
 659 ``PUT``
 660 ~~~~~~~
 661
 662 Returns a job ID.
 663
 664 Body parameters:
 665
 666 ``new_name`` (string, required)
 667   New instance name.
 668 ``ip_check`` (bool)
 669   Whether to ensure instance's IP address is inactive.
 670 ``name_check`` (bool)
 671   Whether to ensure instance's name is resolvable.
 672
 673
 674 ``/2/instances/[instance_name]/tags``
 675 +++++++++++++++++++++++++++++++++++++
 676
 677 Manages per-instance tags.
 678
 679 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 680
 681 ``GET``
 682 ~~~~~~~
 683
 684 Returns a list of tags.
 685
 686 Example::
 687
 688     ["tag1", "tag2", "tag3"]
 689
 690 ``PUT``
 691 ~~~~~~~
 692
 693 Add a set of tags.
 694
 695 The request as a list of strings should be ``PUT`` to this URI. The
 696 result will be a job id.
 697
 698 It supports the ``dry-run`` argument.
 699
 700
 701 ``DELETE``
 702 ~~~~~~~~~~
 703
 704 Delete a tag.
 705
 706 In order to delete a set of tags, the DELETE request should be addressed
 707 to URI like::
 708
 709     /tags?tag=[tag]&tag=[tag]
 710
 711 It supports the ``dry-run`` argument.
 712
 713
 714 ``/2/jobs``
 715 +++++++++++
 716
 717 The ``/2/jobs`` resource.
 718
 719 It supports the following commands: ``GET``.
 720
 721 ``GET``
 722 ~~~~~~~
 723
 724 Returns a dictionary of jobs.
 725
 726 Returns: a dictionary with jobs id and uri.
 727
 728 ``/2/jobs/[job_id]``
 729 ++++++++++++++++++++
 730
 731
 732 Individual job URI.
 733
 734 It supports the following commands: ``GET``, ``DELETE``.
 735
 736 ``GET``
 737 ~~~~~~~
 738
 739 Returns a job status.
 740
 741 Returns: a dictionary with job parameters.
 742
 743 The result includes:
 744
 745 - id: job ID as a number
 746 - status: current job status as a string
 747 - ops: involved OpCodes as a list of dictionaries for each opcodes in
 748   the job
 749 - opstatus: OpCodes status as a list
 750 - opresult: OpCodes results as a list
 751
 752 For a successful opcode, the ``opresult`` field corresponding to it will
 753 contain the raw result from its :term:`LogicalUnit`. In case an opcode
 754 has failed, its element in the opresult list will be a list of two
 755 elements:
 756
 757 - first element the error type (the Ganeti internal error name)
 758 - second element a list of either one or two elements:
 759
 760   - the first element is the textual error description
 761   - the second element, if any, will hold an error classification
 762
 763 The error classification is most useful for the ``OpPrereqError``
 764 error type - these errors happen before the OpCode has started
 765 executing, so it's possible to retry the OpCode without side
 766 effects. But whether it make sense to retry depends on the error
 767 classification:
 768
 769 ``resolver_error``
 770   Resolver errors. This usually means that a name doesn't exist in DNS,
 771   so if it's a case of slow DNS propagation the operation can be retried
 772   later.
 773
 774 ``insufficient_resources``
 775   Not enough resources (iallocator failure, disk space, memory,
 776   etc.). If the resources on the cluster increase, the operation might
 777   succeed.
 778
 779 ``wrong_input``
 780   Wrong arguments (at syntax level). The operation will not ever be
 781   accepted unless the arguments change.
 782
 783 ``wrong_state``
 784   Wrong entity state. For example, live migration has been requested for
 785   a down instance, or instance creation on an offline node. The
 786   operation can be retried once the resource has changed state.
 787
 788 ``unknown_entity``
 789   Entity not found. For example, information has been requested for an
 790   unknown instance.
 791
 792 ``already_exists``
 793   Entity already exists. For example, instance creation has been
 794   requested for an already-existing instance.
 795
 796 ``resource_not_unique``
 797   Resource not unique (e.g. MAC or IP duplication).
 798
 799 ``internal_error``
 800   Internal cluster error. For example, a node is unreachable but not set
 801   offline, or the ganeti node daemons are not working, etc. A
 802   ``gnt-cluster verify`` should be run.
 803
 804 ``environment_error``
 805   Environment error (e.g. node disk error). A ``gnt-cluster verify``
 806   should be run.
 807
 808 Note that in the above list, by entity we refer to a node or instance,
 809 while by a resource we refer to an instance's disk, or NIC, etc.
 810
 811
 812 ``DELETE``
 813 ~~~~~~~~~~
 814
 815 Cancel a not-yet-started job.
 816
 817
 818 ``/2/jobs/[job_id]/wait``
 819 +++++++++++++++++++++++++
 820
 821 ``GET``
 822 ~~~~~~~
 823
 824 Waits for changes on a job. Takes the following body parameters in a
 825 dict:
 826
 827 ``fields``
 828   The job fields on which to watch for changes.
 829
 830 ``previous_job_info``
 831   Previously received field values or None if not yet available.
 832
 833 ``previous_log_serial``
 834   Highest log serial number received so far or None if not yet
 835   available.
 836
 837 Returns None if no changes have been detected and a dict with two keys,
 838 ``job_info`` and ``log_entries`` otherwise.
 839
 840
 841 ``/2/nodes``
 842 ++++++++++++
 843
 844 Nodes resource.
 845
 846 It supports the following commands: ``GET``.
 847
 848 ``GET``
 849 ~~~~~~~
 850
 851 Returns a list of all nodes.
 852
 853 Example::
 854
 855     [
 856       {
 857         "id": "node1.example.com",
 858         "uri": "\/nodes\/node1.example.com"
 859       },
 860       {
 861         "id": "node2.example.com",
 862         "uri": "\/nodes\/node2.example.com"
 863       }
 864     ]
 865
 866 If the optional 'bulk' argument is provided and set to 'true' value (i.e
 867 '?bulk=1'), the output contains detailed information about nodes as a
 868 list.
 869
 870 Example::
 871
 872     [
 873       {
 874         "pinst_cnt": 1,
 875         "mfree": 31280,
 876         "mtotal": 32763,
 877         "name": "www.example.com",
 878         "tags": [],
 879         "mnode": 512,
 880         "dtotal": 5246208,
 881         "sinst_cnt": 2,
 882         "dfree": 5171712,
 883         "offline": false
 884       },
 885       ...
 886     ]
 887
 888 ``/2/nodes/[node_name]``
 889 +++++++++++++++++++++++++++++++++
 890
 891 Returns information about a node.
 892
 893 It supports the following commands: ``GET``.
 894
 895 ``/2/nodes/[node_name]/evacuate``
 896 +++++++++++++++++++++++++++++++++
 897
 898 Evacuates all secondary instances off a node.
 899
 900 It supports the following commands: ``POST``.
 901
 902 ``POST``
 903 ~~~~~~~~
 904
 905 To evacuate a node, either one of the ``iallocator`` or ``remote_node``
 906 parameters must be passed::
 907
 908     evacuate?iallocator=[iallocator]
 909     evacuate?remote_node=[nodeX.example.com]
 910
 911 The result value will be a list, each element being a triple of the job
 912 id (for this specific evacuation), the instance which is being evacuated
 913 by this job, and the node to which it is being relocated. In case the
 914 node is already empty, the result will be an empty list (without any
 915 jobs being submitted).
 916
 917 And additional parameter ``early_release`` signifies whether to try to
 918 parallelize the evacuations, at the risk of increasing I/O contention
 919 and increasing the chances of data loss, if the primary node of any of
 920 the instances being evacuated is not fully healthy.
 921
 922 If the dry-run parameter was specified, then the evacuation jobs were
 923 not actually submitted, and the job IDs will be null.
 924
 925
 926 ``/2/nodes/[node_name]/migrate``
 927 +++++++++++++++++++++++++++++++++
 928
 929 Migrates all primary instances from a node.
 930
 931 It supports the following commands: ``POST``.
 932
 933 ``POST``
 934 ~~~~~~~~
 935
 936 No parameters are required, but the bool parameter ``live`` can be set
 937 to use live migration (if available).
 938
 939     migrate?live=[0|1]
 940
 941 ``/2/nodes/[node_name]/role``
 942 +++++++++++++++++++++++++++++
 943
 944 Manages node role.
 945
 946 It supports the following commands: ``GET``, ``PUT``.
 947
 948 The role is always one of the following:
 949
 950   - drained
 951   - master
 952   - master-candidate
 953   - offline
 954   - regular
 955
 956 ``GET``
 957 ~~~~~~~
 958
 959 Returns the current node role.
 960
 961 Example::
 962
 963     "master-candidate"
 964
 965 ``PUT``
 966 ~~~~~~~
 967
 968 Change the node role.
 969
 970 The request is a string which should be PUT to this URI. The result will
 971 be a job id.
 972
 973 It supports the bool ``force`` argument.
 974
 975 ``/2/nodes/[node_name]/storage``
 976 ++++++++++++++++++++++++++++++++
 977
 978 Manages storage units on the node.
 979
 980 ``GET``
 981 ~~~~~~~
 982
 983 Requests a list of storage units on a node. Requires the parameters
 984 ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
 985 ``output_fields``. The result will be a job id, using which the result
 986 can be retrieved.
 987
 988 ``/2/nodes/[node_name]/storage/modify``
 989 +++++++++++++++++++++++++++++++++++++++
 990
 991 Modifies storage units on the node.
 992
 993 ``PUT``
 994 ~~~~~~~
 995
 996 Modifies parameters of storage units on the node. Requires the
 997 parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
 998 and ``name`` (name of the storage unit).  Parameters can be passed
 999 additionally. Currently only ``allocatable`` (bool) is supported. The
1000 result will be a job id.
1001
1002 ``/2/nodes/[node_name]/storage/repair``
1003 +++++++++++++++++++++++++++++++++++++++
1004
1005 Repairs a storage unit on the node.
1006
1007 ``PUT``
1008 ~~~~~~~
1009
1010 Repairs a storage unit on the node. Requires the parameters
1011 ``storage_type`` (currently only ``lvm-vg`` can be repaired) and
1012 ``name`` (name of the storage unit). The result will be a job id.
1013
1014 ``/2/nodes/[node_name]/tags``
1015 +++++++++++++++++++++++++++++
1016
1017 Manages per-node tags.
1018
1019 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1020
1021 ``GET``
1022 ~~~~~~~
1023
1024 Returns a list of tags.
1025
1026 Example::
1027
1028     ["tag1", "tag2", "tag3"]
1029
1030 ``PUT``
1031 ~~~~~~~
1032
1033 Add a set of tags.
1034
1035 The request as a list of strings should be PUT to this URI. The result
1036 will be a job id.
1037
1038 It supports the ``dry-run`` argument.
1039
1040 ``DELETE``
1041 ~~~~~~~~~~
1042
1043 Deletes tags.
1044
1045 In order to delete a set of tags, the DELETE request should be addressed
1046 to URI like::
1047
1048     /tags?tag=[tag]&tag=[tag]
1049
1050 It supports the ``dry-run`` argument.
1051
1052
1053 ``/2/os``
1054 +++++++++
1055
1056 OS resource.
1057
1058 It supports the following commands: ``GET``.
1059
1060 ``GET``
1061 ~~~~~~~
1062
1063 Return a list of all OSes.
1064
1065 Can return error 500 in case of a problem. Since this is a costly
1066 operation for Ganeti 2.0, it is not recommended to execute it too often.
1067
1068 Example::
1069
1070     ["debian-etch"]
1071
1072 ``/2/tags``
1073 +++++++++++
1074
1075 Manages cluster tags.
1076
1077 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1078
1079 ``GET``
1080 ~~~~~~~
1081
1082 Returns the cluster tags.
1083
1084 Example::
1085
1086     ["tag1", "tag2", "tag3"]
1087
1088 ``PUT``
1089 ~~~~~~~
1090
1091 Adds a set of tags.
1092
1093 The request as a list of strings should be PUT to this URI. The result
1094 will be a job id.
1095
1096 It supports the ``dry-run`` argument.
1097
1098
1099 ``DELETE``
1100 ~~~~~~~~~~
1101
1102 Deletes tags.
1103
1104 In order to delete a set of tags, the DELETE request should be addressed
1105 to URI like::
1106
1107     /tags?tag=[tag]&tag=[tag]
1108
1109 It supports the ``dry-run`` argument.
1110
1111
1112 ``/version``
1113 ++++++++++++
1114
1115 The version resource.
1116
1117 This resource should be used to determine the remote API version and to
1118 adapt clients accordingly.
1119
1120 It supports the following commands: ``GET``.
1121
1122 ``GET``
1123 ~~~~~~~
1124
1125 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1126 returns ``2``.
1127
1128 .. vim: set textwidth=72 :
1129 .. Local Variables:
1130 .. mode: rst
1131 .. fill-column: 72
1132 .. End: