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