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": "1.2.3.4"}]``. Each NIC definition can contain the optional
 392   values ``ip``, ``mode``, ``link`` and ``bridge``.
 393 ``os`` (string)
 394   Instance operating system.
 395 ``force_variant`` (bool)
 396   Whether to force an unknown variant.
 397 ``pnode`` (string)
 398   Primary node.
 399 ``snode`` (string)
 400   Secondary node.
 401 ``src_node`` (string)
 402   Source node for import.
 403 ``src_path`` (string)
 404   Source directory for import.
 405 ``start`` (bool)
 406   Whether to start instance after creation.
 407 ``ip_check`` (bool)
 408   Whether to ensure instance's IP address is inactive.
 409 ``name_check`` (bool)
 410   Whether to ensure instance's name is resolvable.
 411 ``file_storage_dir`` (string)
 412   File storage directory.
 413 ``file_driver`` (string)
 414   File storage driver.
 415 ``iallocator`` (string)
 416   Instance allocator name.
 417 ``source_handshake``
 418   Signed handshake from source (remote import only).
 419 ``source_x509_ca`` (string)
 420   Source X509 CA in PEM format (remote import only).
 421 ``source_instance_name`` (string)
 422   Source instance name (remote import only).
 423 ``hypervisor`` (string)
 424   Hypervisor name.
 425 ``hvparams`` (dict)
 426   Hypervisor parameters, hypervisor-dependent.
 427 ``beparams``
 428   Backend parameters.
 429
 430
 431 ``/2/instances/[instance_name]``
 432 ++++++++++++++++++++++++++++++++
 433
 434 Instance-specific resource.
 435
 436 It supports the following commands: ``GET``, ``DELETE``.
 437
 438 ``GET``
 439 ~~~~~~~
 440
 441 Returns information about an instance, similar to the bulk output from
 442 the instance list.
 443
 444 ``DELETE``
 445 ~~~~~~~~~~
 446
 447 Deletes an instance.
 448
 449 It supports the ``dry-run`` argument.
 450
 451
 452 ``/2/instances/[instance_name]/info``
 453 +++++++++++++++++++++++++++++++++++++++
 454
 455 It supports the following commands: ``GET``.
 456
 457 ``GET``
 458 ~~~~~~~
 459
 460 Requests detailed information about the instance. An optional parameter,
 461 ``static`` (bool), can be set to return only static information from the
 462 configuration without querying the instance's nodes. The result will be
 463 a job id.
 464
 465
 466 ``/2/instances/[instance_name]/reboot``
 467 +++++++++++++++++++++++++++++++++++++++
 468
 469 Reboots URI for an instance.
 470
 471 It supports the following commands: ``POST``.
 472
 473 ``POST``
 474 ~~~~~~~~
 475
 476 Reboots the instance.
 477
 478 The URI takes optional ``type=soft|hard|full`` and
 479 ``ignore_secondaries=0|1`` parameters.
 480
 481 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
 482 without terminating the hypervisor. ``hard`` means full shutdown
 483 (including terminating the hypervisor process) and startup again.
 484 ``full`` is like ``hard`` but also recreates the configuration from
 485 ground up as if you would have done a ``gnt-instance shutdown`` and
 486 ``gnt-instance start`` on it.
 487
 488 ``ignore_secondaries`` is a bool argument indicating if we start the
 489 instance even if secondary disks are failing.
 490
 491 It supports the ``dry-run`` argument.
 492
 493
 494 ``/2/instances/[instance_name]/shutdown``
 495 +++++++++++++++++++++++++++++++++++++++++
 496
 497 Instance shutdown URI.
 498
 499 It supports the following commands: ``PUT``.
 500
 501 ``PUT``
 502 ~~~~~~~
 503
 504 Shutdowns an instance.
 505
 506 It supports the ``dry-run`` argument.
 507
 508
 509 ``/2/instances/[instance_name]/startup``
 510 ++++++++++++++++++++++++++++++++++++++++
 511
 512 Instance startup URI.
 513
 514 It supports the following commands: ``PUT``.
 515
 516 ``PUT``
 517 ~~~~~~~
 518
 519 Startup an instance.
 520
 521 The URI takes an optional ``force=1|0`` parameter to start the
 522 instance even if secondary disks are failing.
 523
 524 It supports the ``dry-run`` argument.
 525
 526 ``/2/instances/[instance_name]/reinstall``
 527 ++++++++++++++++++++++++++++++++++++++++++++++
 528
 529 Installs the operating system again.
 530
 531 It supports the following commands: ``POST``.
 532
 533 ``POST``
 534 ~~~~~~~~
 535
 536 Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
 537
 538
 539 ``/2/instances/[instance_name]/replace-disks``
 540 ++++++++++++++++++++++++++++++++++++++++++++++
 541
 542 Replaces disks on an instance.
 543
 544 It supports the following commands: ``POST``.
 545
 546 ``POST``
 547 ~~~~~~~~
 548
 549 Takes the parameters ``mode`` (one of ``replace_on_primary``,
 550 ``replace_on_secondary``, ``replace_new_secondary`` or
 551 ``replace_auto``), ``disks`` (comma separated list of disk indexes),
 552 ``remote_node`` and ``iallocator``.
 553
 554 Either ``remote_node`` or ``iallocator`` needs to be defined when using
 555 ``mode=replace_new_secondary``.
 556
 557 ``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
 558 the broken disk(s) on its own and replacing it.
 559
 560
 561 ``/2/instances/[instance_name]/activate-disks``
 562 +++++++++++++++++++++++++++++++++++++++++++++++
 563
 564 Activate disks on an instance.
 565
 566 It supports the following commands: ``PUT``.
 567
 568 ``PUT``
 569 ~~~~~~~
 570
 571 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 572 size (useful for forcing activation when recorded size is wrong).
 573
 574
 575 ``/2/instances/[instance_name]/deactivate-disks``
 576 +++++++++++++++++++++++++++++++++++++++++++++++++
 577
 578 Deactivate disks on an instance.
 579
 580 It supports the following commands: ``PUT``.
 581
 582 ``PUT``
 583 ~~~~~~~
 584
 585 Takes no parameters.
 586
 587
 588 ``/2/instances/[instance_name]/prepare-export``
 589 +++++++++++++++++++++++++++++++++++++++++++++++++
 590
 591 Prepares an export of an instance.
 592
 593 It supports the following commands: ``PUT``.
 594
 595 ``PUT``
 596 ~~~~~~~
 597
 598 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 599
 600
 601 ``/2/instances/[instance_name]/export``
 602 +++++++++++++++++++++++++++++++++++++++++++++++++
 603
 604 Exports an instance.
 605
 606 It supports the following commands: ``PUT``.
 607
 608 ``PUT``
 609 ~~~~~~~
 610
 611 Returns a job ID.
 612
 613 Body parameters:
 614
 615 ``mode`` (string)
 616   Export mode.
 617 ``destination`` (required)
 618   Destination information, depends on export mode.
 619 ``shutdown`` (bool, required)
 620   Whether to shutdown instance before export.
 621 ``remove_instance`` (bool)
 622   Whether to remove instance after export.
 623 ``x509_key_name``
 624   Name of X509 key (remote export only).
 625 ``destination_x509_ca``
 626   Destination X509 CA (remote export only).
 627
 628
 629 ``/2/instances/[instance_name]/tags``
 630 +++++++++++++++++++++++++++++++++++++
 631
 632 Manages per-instance tags.
 633
 634 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 635
 636 ``GET``
 637 ~~~~~~~
 638
 639 Returns a list of tags.
 640
 641 Example::
 642
 643     ["tag1", "tag2", "tag3"]
 644
 645 ``PUT``
 646 ~~~~~~~
 647
 648 Add a set of tags.
 649
 650 The request as a list of strings should be ``PUT`` to this URI. The
 651 result will be a job id.
 652
 653 It supports the ``dry-run`` argument.
 654
 655
 656 ``DELETE``
 657 ~~~~~~~~~~
 658
 659 Delete a tag.
 660
 661 In order to delete a set of tags, the DELETE request should be addressed
 662 to URI like::
 663
 664     /tags?tag=[tag]&tag=[tag]
 665
 666 It supports the ``dry-run`` argument.
 667
 668
 669 ``/2/jobs``
 670 +++++++++++
 671
 672 The ``/2/jobs`` resource.
 673
 674 It supports the following commands: ``GET``.
 675
 676 ``GET``
 677 ~~~~~~~
 678
 679 Returns a dictionary of jobs.
 680
 681 Returns: a dictionary with jobs id and uri.
 682
 683 ``/2/jobs/[job_id]``
 684 ++++++++++++++++++++
 685
 686
 687 Individual job URI.
 688
 689 It supports the following commands: ``GET``, ``DELETE``.
 690
 691 ``GET``
 692 ~~~~~~~
 693
 694 Returns a job status.
 695
 696 Returns: a dictionary with job parameters.
 697
 698 The result includes:
 699
 700 - id: job ID as a number
 701 - status: current job status as a string
 702 - ops: involved OpCodes as a list of dictionaries for each opcodes in
 703   the job
 704 - opstatus: OpCodes status as a list
 705 - opresult: OpCodes results as a list
 706
 707 For a successful opcode, the ``opresult`` field corresponding to it will
 708 contain the raw result from its :term:`LogicalUnit`. In case an opcode
 709 has failed, its element in the opresult list will be a list of two
 710 elements:
 711
 712 - first element the error type (the Ganeti internal error name)
 713 - second element a list of either one or two elements:
 714
 715   - the first element is the textual error description
 716   - the second element, if any, will hold an error classification
 717
 718 The error classification is most useful for the ``OpPrereqError``
 719 error type - these errors happen before the OpCode has started
 720 executing, so it's possible to retry the OpCode without side
 721 effects. But whether it make sense to retry depends on the error
 722 classification:
 723
 724 ``resolver_error``
 725   Resolver errors. This usually means that a name doesn't exist in DNS,
 726   so if it's a case of slow DNS propagation the operation can be retried
 727   later.
 728
 729 ``insufficient_resources``
 730   Not enough resources (iallocator failure, disk space, memory,
 731   etc.). If the resources on the cluster increase, the operation might
 732   succeed.
 733
 734 ``wrong_input``
 735   Wrong arguments (at syntax level). The operation will not ever be
 736   accepted unless the arguments change.
 737
 738 ``wrong_state``
 739   Wrong entity state. For example, live migration has been requested for
 740   a down instance, or instance creation on an offline node. The
 741   operation can be retried once the resource has changed state.
 742
 743 ``unknown_entity``
 744   Entity not found. For example, information has been requested for an
 745   unknown instance.
 746
 747 ``already_exists``
 748   Entity already exists. For example, instance creation has been
 749   requested for an already-existing instance.
 750
 751 ``resource_not_unique``
 752   Resource not unique (e.g. MAC or IP duplication).
 753
 754 ``internal_error``
 755   Internal cluster error. For example, a node is unreachable but not set
 756   offline, or the ganeti node daemons are not working, etc. A
 757   ``gnt-cluster verify`` should be run.
 758
 759 ``environment_error``
 760   Environment error (e.g. node disk error). A ``gnt-cluster verify``
 761   should be run.
 762
 763 Note that in the above list, by entity we refer to a node or instance,
 764 while by a resource we refer to an instance's disk, or NIC, etc.
 765
 766
 767 ``DELETE``
 768 ~~~~~~~~~~
 769
 770 Cancel a not-yet-started job.
 771
 772
 773 ``/2/jobs/[job_id]/wait``
 774 +++++++++++++++++++++++++
 775
 776 ``GET``
 777 ~~~~~~~
 778
 779 Waits for changes on a job. Takes the following body parameters in a
 780 dict:
 781
 782 ``fields``
 783   The job fields on which to watch for changes.
 784
 785 ``previous_job_info``
 786   Previously received field values or None if not yet available.
 787
 788 ``previous_log_serial``
 789   Highest log serial number received so far or None if not yet
 790   available.
 791
 792 Returns None if no changes have been detected and a dict with two keys,
 793 ``job_info`` and ``log_entries`` otherwise.
 794
 795
 796 ``/2/nodes``
 797 ++++++++++++
 798
 799 Nodes resource.
 800
 801 It supports the following commands: ``GET``.
 802
 803 ``GET``
 804 ~~~~~~~
 805
 806 Returns a list of all nodes.
 807
 808 Example::
 809
 810     [
 811       {
 812         "id": "node1.example.com",
 813         "uri": "\/nodes\/node1.example.com"
 814       },
 815       {
 816         "id": "node2.example.com",
 817         "uri": "\/nodes\/node2.example.com"
 818       }
 819     ]
 820
 821 If the optional 'bulk' argument is provided and set to 'true' value (i.e
 822 '?bulk=1'), the output contains detailed information about nodes as a
 823 list.
 824
 825 Example::
 826
 827     [
 828       {
 829         "pinst_cnt": 1,
 830         "mfree": 31280,
 831         "mtotal": 32763,
 832         "name": "www.example.com",
 833         "tags": [],
 834         "mnode": 512,
 835         "dtotal": 5246208,
 836         "sinst_cnt": 2,
 837         "dfree": 5171712,
 838         "offline": false
 839       },
 840       ...
 841     ]
 842
 843 ``/2/nodes/[node_name]``
 844 +++++++++++++++++++++++++++++++++
 845
 846 Returns information about a node.
 847
 848 It supports the following commands: ``GET``.
 849
 850 ``/2/nodes/[node_name]/evacuate``
 851 +++++++++++++++++++++++++++++++++
 852
 853 Evacuates all secondary instances off a node.
 854
 855 It supports the following commands: ``POST``.
 856
 857 ``POST``
 858 ~~~~~~~~
 859
 860 To evacuate a node, either one of the ``iallocator`` or ``remote_node``
 861 parameters must be passed::
 862
 863     evacuate?iallocator=[iallocator]
 864     evacuate?remote_node=[nodeX.example.com]
 865
 866 ``/2/nodes/[node_name]/migrate``
 867 +++++++++++++++++++++++++++++++++
 868
 869 Migrates all primary instances from a node.
 870
 871 It supports the following commands: ``POST``.
 872
 873 ``POST``
 874 ~~~~~~~~
 875
 876 No parameters are required, but the bool parameter ``live`` can be set
 877 to use live migration (if available).
 878
 879     migrate?live=[0|1]
 880
 881 ``/2/nodes/[node_name]/role``
 882 +++++++++++++++++++++++++++++
 883
 884 Manages node role.
 885
 886 It supports the following commands: ``GET``, ``PUT``.
 887
 888 The role is always one of the following:
 889
 890   - drained
 891   - master
 892   - master-candidate
 893   - offline
 894   - regular
 895
 896 ``GET``
 897 ~~~~~~~
 898
 899 Returns the current node role.
 900
 901 Example::
 902
 903     "master-candidate"
 904
 905 ``PUT``
 906 ~~~~~~~
 907
 908 Change the node role.
 909
 910 The request is a string which should be PUT to this URI. The result will
 911 be a job id.
 912
 913 It supports the bool ``force`` argument.
 914
 915 ``/2/nodes/[node_name]/storage``
 916 ++++++++++++++++++++++++++++++++
 917
 918 Manages storage units on the node.
 919
 920 ``GET``
 921 ~~~~~~~
 922
 923 Requests a list of storage units on a node. Requires the parameters
 924 ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
 925 ``output_fields``. The result will be a job id, using which the result
 926 can be retrieved.
 927
 928 ``/2/nodes/[node_name]/storage/modify``
 929 +++++++++++++++++++++++++++++++++++++++
 930
 931 Modifies storage units on the node.
 932
 933 ``PUT``
 934 ~~~~~~~
 935
 936 Modifies parameters of storage units on the node. Requires the
 937 parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
 938 and ``name`` (name of the storage unit).  Parameters can be passed
 939 additionally. Currently only ``allocatable`` (bool) is supported. The
 940 result will be a job id.
 941
 942 ``/2/nodes/[node_name]/storage/repair``
 943 +++++++++++++++++++++++++++++++++++++++
 944
 945 Repairs a storage unit on the node.
 946
 947 ``PUT``
 948 ~~~~~~~
 949
 950 Repairs a storage unit on the node. Requires the parameters
 951 ``storage_type`` (currently only ``lvm-vg`` can be repaired) and
 952 ``name`` (name of the storage unit). The result will be a job id.
 953
 954 ``/2/nodes/[node_name]/tags``
 955 +++++++++++++++++++++++++++++
 956
 957 Manages per-node tags.
 958
 959 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 960
 961 ``GET``
 962 ~~~~~~~
 963
 964 Returns a list of tags.
 965
 966 Example::
 967
 968     ["tag1", "tag2", "tag3"]
 969
 970 ``PUT``
 971 ~~~~~~~
 972
 973 Add a set of tags.
 974
 975 The request as a list of strings should be PUT to this URI. The result
 976 will be a job id.
 977
 978 It supports the ``dry-run`` argument.
 979
 980 ``DELETE``
 981 ~~~~~~~~~~
 982
 983 Deletes tags.
 984
 985 In order to delete a set of tags, the DELETE request should be addressed
 986 to URI like::
 987
 988     /tags?tag=[tag]&tag=[tag]
 989
 990 It supports the ``dry-run`` argument.
 991
 992
 993 ``/2/os``
 994 +++++++++
 995
 996 OS resource.
 997
 998 It supports the following commands: ``GET``.
 999
1000 ``GET``
1001 ~~~~~~~
1002
1003 Return a list of all OSes.
1004
1005 Can return error 500 in case of a problem. Since this is a costly
1006 operation for Ganeti 2.0, it is not recommended to execute it too often.
1007
1008 Example::
1009
1010     ["debian-etch"]
1011
1012 ``/2/tags``
1013 +++++++++++
1014
1015 Manages cluster tags.
1016
1017 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1018
1019 ``GET``
1020 ~~~~~~~
1021
1022 Returns the cluster tags.
1023
1024 Example::
1025
1026     ["tag1", "tag2", "tag3"]
1027
1028 ``PUT``
1029 ~~~~~~~
1030
1031 Adds a set of tags.
1032
1033 The request as a list of strings should be PUT to this URI. The result
1034 will be a job id.
1035
1036 It supports the ``dry-run`` argument.
1037
1038
1039 ``DELETE``
1040 ~~~~~~~~~~
1041
1042 Deletes tags.
1043
1044 In order to delete a set of tags, the DELETE request should be addressed
1045 to URI like::
1046
1047     /tags?tag=[tag]&tag=[tag]
1048
1049 It supports the ``dry-run`` argument.
1050
1051
1052 ``/version``
1053 ++++++++++++
1054
1055 The version resource.
1056
1057 This resource should be used to determine the remote API version and to
1058 adapt clients accordingly.
1059
1060 It supports the following commands: ``GET``.
1061
1062 ``GET``
1063 ~~~~~~~
1064
1065 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1066 returns ``2``.
1067
1068 .. vim: set textwidth=72 :
1069 .. Local Variables:
1070 .. mode: rst
1071 .. fill-column: 72
1072 .. End: