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 ``name`` (string, required)
 416   Node group name.
 417
 418
 419 ``/2/groups/[group_name]``
 420 ++++++++++++++++++++++++++
 421
 422 Returns information about a node group.
 423
 424 It supports the following commands: ``GET``, ``DELETE``.
 425
 426 ``GET``
 427 ~~~~~~~
 428
 429 Returns information about a node group, similar to the bulk output from
 430 the node group list.
 431
 432 ``DELETE``
 433 ~~~~~~~~~~
 434
 435 Deletes a node group.
 436
 437 It supports the ``dry-run`` argument.
 438
 439
 440 ``/2/groups/[group_name]/modify``
 441 +++++++++++++++++++++++++++++++++
 442
 443 Modifies the parameters of a node group.
 444
 445 Supports the following commands: ``PUT``.
 446
 447 ``PUT``
 448 ~~~~~~~
 449
 450 Returns a job ID.
 451
 452 Body parameters:
 453
 454 .. opcode_params:: OP_GROUP_SET_PARAMS
 455    :exclude: group_name
 456
 457
 458 ``/2/groups/[group_name]/rename``
 459 +++++++++++++++++++++++++++++++++
 460
 461 Renames a node group.
 462
 463 Supports the following commands: ``PUT``.
 464
 465 ``PUT``
 466 ~~~~~~~
 467
 468 Returns a job ID.
 469
 470 Body parameters:
 471
 472 ``new_name`` (string, required)
 473   New node group name.
 474
 475
 476 ``/2/groups/[group_name]/assign-nodes``
 477 +++++++++++++++++++++++++++++++++++++++
 478
 479 Assigns nodes to a group.
 480
 481 Supports the following commands: ``PUT``.
 482
 483 ``PUT``
 484 ~~~~~~~
 485
 486 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
 487
 488 Body parameters:
 489
 490 .. opcode_params:: OP_GROUP_ASSIGN_NODES
 491    :exclude: group_name, force, dry_run
 492
 493
 494 ``/2/instances``
 495 ++++++++++++++++
 496
 497 The instances resource.
 498
 499 It supports the following commands: ``GET``, ``POST``.
 500
 501 ``GET``
 502 ~~~~~~~
 503
 504 Returns a list of all available instances.
 505
 506 Example::
 507
 508     [
 509       {
 510         "name": "web.example.com",
 511         "uri": "\/instances\/web.example.com"
 512       },
 513       {
 514         "name": "mail.example.com",
 515         "uri": "\/instances\/mail.example.com"
 516       }
 517     ]
 518
 519 If the optional bool *bulk* argument is provided and set to a true value
 520 (i.e ``?bulk=1``), the output contains detailed information about
 521 instances as a list.
 522
 523 Example::
 524
 525     [
 526       {
 527          "status": "running",
 528          "disk_usage": 20480,
 529          "nic.bridges": [
 530            "xen-br0"
 531           ],
 532          "name": "web.example.com",
 533          "tags": ["tag1", "tag2"],
 534          "beparams": {
 535            "vcpus": 2,
 536            "memory": 512
 537          },
 538          "disk.sizes": [
 539              20480
 540          ],
 541          "pnode": "node1.example.com",
 542          "nic.macs": ["01:23:45:67:89:01"],
 543          "snodes": ["node2.example.com"],
 544          "disk_template": "drbd",
 545          "admin_state": true,
 546          "os": "debian-etch",
 547          "oper_state": true
 548       },
 549       ...
 550     ]
 551
 552
 553 ``POST``
 554 ~~~~~~~~
 555
 556 Creates an instance.
 557
 558 If the optional bool *dry-run* argument is provided, the job will not be
 559 actually executed, only the pre-execution checks will be done. Query-ing
 560 the job result will return, in both dry-run and normal case, the list of
 561 nodes selected for the instance.
 562
 563 Returns: a job ID that can be used later for polling.
 564
 565 Body parameters:
 566
 567 ``__version__`` (int, required)
 568   Must be ``1`` (older Ganeti versions used a different format for
 569   instance creation requests, version ``0``, but that format is not
 570   documented and should no longer be used).
 571
 572 .. opcode_params:: OP_INSTANCE_CREATE
 573
 574 Earlier versions used parameters named ``name`` and ``os``. These have
 575 been replaced by ``instance_name`` and ``os_type`` to match the
 576 underlying opcode. The old names can still be used.
 577
 578
 579 ``/2/instances/[instance_name]``
 580 ++++++++++++++++++++++++++++++++
 581
 582 Instance-specific resource.
 583
 584 It supports the following commands: ``GET``, ``DELETE``.
 585
 586 ``GET``
 587 ~~~~~~~
 588
 589 Returns information about an instance, similar to the bulk output from
 590 the instance list.
 591
 592 ``DELETE``
 593 ~~~~~~~~~~
 594
 595 Deletes an instance.
 596
 597 It supports the ``dry-run`` argument.
 598
 599
 600 ``/2/instances/[instance_name]/info``
 601 +++++++++++++++++++++++++++++++++++++++
 602
 603 It supports the following commands: ``GET``.
 604
 605 ``GET``
 606 ~~~~~~~
 607
 608 Requests detailed information about the instance. An optional parameter,
 609 ``static`` (bool), can be set to return only static information from the
 610 configuration without querying the instance's nodes. The result will be
 611 a job id.
 612
 613
 614 ``/2/instances/[instance_name]/reboot``
 615 +++++++++++++++++++++++++++++++++++++++
 616
 617 Reboots URI for an instance.
 618
 619 It supports the following commands: ``POST``.
 620
 621 ``POST``
 622 ~~~~~~~~
 623
 624 Reboots the instance.
 625
 626 The URI takes optional ``type=soft|hard|full`` and
 627 ``ignore_secondaries=0|1`` parameters.
 628
 629 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
 630 without terminating the hypervisor. ``hard`` means full shutdown
 631 (including terminating the hypervisor process) and startup again.
 632 ``full`` is like ``hard`` but also recreates the configuration from
 633 ground up as if you would have done a ``gnt-instance shutdown`` and
 634 ``gnt-instance start`` on it.
 635
 636 ``ignore_secondaries`` is a bool argument indicating if we start the
 637 instance even if secondary disks are failing.
 638
 639 It supports the ``dry-run`` argument.
 640
 641
 642 ``/2/instances/[instance_name]/shutdown``
 643 +++++++++++++++++++++++++++++++++++++++++
 644
 645 Instance shutdown URI.
 646
 647 It supports the following commands: ``PUT``.
 648
 649 ``PUT``
 650 ~~~~~~~
 651
 652 Shutdowns an instance.
 653
 654 It supports the ``dry-run`` argument.
 655
 656
 657 ``/2/instances/[instance_name]/startup``
 658 ++++++++++++++++++++++++++++++++++++++++
 659
 660 Instance startup URI.
 661
 662 It supports the following commands: ``PUT``.
 663
 664 ``PUT``
 665 ~~~~~~~
 666
 667 Startup an instance.
 668
 669 The URI takes an optional ``force=1|0`` parameter to start the
 670 instance even if secondary disks are failing.
 671
 672 It supports the ``dry-run`` argument.
 673
 674 ``/2/instances/[instance_name]/reinstall``
 675 ++++++++++++++++++++++++++++++++++++++++++++++
 676
 677 Installs the operating system again.
 678
 679 It supports the following commands: ``POST``.
 680
 681 ``POST``
 682 ~~~~~~~~
 683
 684 Returns a job ID.
 685
 686 Body parameters:
 687
 688 ``os`` (string, required)
 689   Instance operating system.
 690 ``start`` (bool, defaults to true)
 691   Whether to start instance after reinstallation.
 692 ``osparams`` (dict)
 693   Dictionary with (temporary) OS parameters.
 694
 695 For backwards compatbility, this resource also takes the query
 696 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
 697 clients should use the body parameters.
 698
 699
 700 ``/2/instances/[instance_name]/replace-disks``
 701 ++++++++++++++++++++++++++++++++++++++++++++++
 702
 703 Replaces disks on an instance.
 704
 705 It supports the following commands: ``POST``.
 706
 707 ``POST``
 708 ~~~~~~~~
 709
 710 Takes the parameters ``mode`` (one of ``replace_on_primary``,
 711 ``replace_on_secondary``, ``replace_new_secondary`` or
 712 ``replace_auto``), ``disks`` (comma separated list of disk indexes),
 713 ``remote_node`` and ``iallocator``.
 714
 715 Either ``remote_node`` or ``iallocator`` needs to be defined when using
 716 ``mode=replace_new_secondary``.
 717
 718 ``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
 719 the broken disk(s) on its own and replacing it.
 720
 721
 722 ``/2/instances/[instance_name]/activate-disks``
 723 +++++++++++++++++++++++++++++++++++++++++++++++
 724
 725 Activate disks on an instance.
 726
 727 It supports the following commands: ``PUT``.
 728
 729 ``PUT``
 730 ~~~~~~~
 731
 732 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 733 size (useful for forcing activation when recorded size is wrong).
 734
 735
 736 ``/2/instances/[instance_name]/deactivate-disks``
 737 +++++++++++++++++++++++++++++++++++++++++++++++++
 738
 739 Deactivate disks on an instance.
 740
 741 It supports the following commands: ``PUT``.
 742
 743 ``PUT``
 744 ~~~~~~~
 745
 746 Takes no parameters.
 747
 748
 749 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
 750 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 751
 752 Grows one disk of an instance.
 753
 754 Supports the following commands: ``POST``.
 755
 756 ``POST``
 757 ~~~~~~~~
 758
 759 Returns a job ID.
 760
 761 Body parameters:
 762
 763 .. opcode_params:: OP_INSTANCE_GROW_DISK
 764    :exclude: instance_name, disk
 765
 766
 767 ``/2/instances/[instance_name]/prepare-export``
 768 +++++++++++++++++++++++++++++++++++++++++++++++++
 769
 770 Prepares an export of an instance.
 771
 772 It supports the following commands: ``PUT``.
 773
 774 ``PUT``
 775 ~~~~~~~
 776
 777 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 778
 779
 780 ``/2/instances/[instance_name]/export``
 781 +++++++++++++++++++++++++++++++++++++++++++++++++
 782
 783 Exports an instance.
 784
 785 It supports the following commands: ``PUT``.
 786
 787 ``PUT``
 788 ~~~~~~~
 789
 790 Returns a job ID.
 791
 792 Body parameters:
 793
 794 .. opcode_params:: OP_BACKUP_EXPORT
 795    :exclude: instance_name
 796    :alias: target_node=destination
 797
 798
 799 ``/2/instances/[instance_name]/migrate``
 800 ++++++++++++++++++++++++++++++++++++++++
 801
 802 Migrates an instance.
 803
 804 Supports the following commands: ``PUT``.
 805
 806 ``PUT``
 807 ~~~~~~~
 808
 809 Returns a job ID.
 810
 811 Body parameters:
 812
 813 .. opcode_params:: OP_INSTANCE_MIGRATE
 814    :exclude: instance_name, live
 815
 816
 817 ``/2/instances/[instance_name]/rename``
 818 ++++++++++++++++++++++++++++++++++++++++
 819
 820 Renames an instance.
 821
 822 Supports the following commands: ``PUT``.
 823
 824 ``PUT``
 825 ~~~~~~~
 826
 827 Returns a job ID.
 828
 829 Body parameters:
 830
 831 .. opcode_params:: OP_INSTANCE_RENAME
 832    :exclude: instance_name
 833
 834
 835 ``/2/instances/[instance_name]/modify``
 836 ++++++++++++++++++++++++++++++++++++++++
 837
 838 Modifies an instance.
 839
 840 Supports the following commands: ``PUT``.
 841
 842 ``PUT``
 843 ~~~~~~~
 844
 845 Returns a job ID.
 846
 847 Body parameters:
 848
 849 .. opcode_params:: OP_INSTANCE_SET_PARAMS
 850    :exclude: instance_name
 851
 852
 853 ``/2/instances/[instance_name]/tags``
 854 +++++++++++++++++++++++++++++++++++++
 855
 856 Manages per-instance tags.
 857
 858 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 859
 860 ``GET``
 861 ~~~~~~~
 862
 863 Returns a list of tags.
 864
 865 Example::
 866
 867     ["tag1", "tag2", "tag3"]
 868
 869 ``PUT``
 870 ~~~~~~~
 871
 872 Add a set of tags.
 873
 874 The request as a list of strings should be ``PUT`` to this URI. The
 875 result will be a job id.
 876
 877 It supports the ``dry-run`` argument.
 878
 879
 880 ``DELETE``
 881 ~~~~~~~~~~
 882
 883 Delete a tag.
 884
 885 In order to delete a set of tags, the DELETE request should be addressed
 886 to URI like::
 887
 888     /tags?tag=[tag]&tag=[tag]
 889
 890 It supports the ``dry-run`` argument.
 891
 892
 893 ``/2/jobs``
 894 +++++++++++
 895
 896 The ``/2/jobs`` resource.
 897
 898 It supports the following commands: ``GET``.
 899
 900 ``GET``
 901 ~~~~~~~
 902
 903 Returns a dictionary of jobs.
 904
 905 Returns: a dictionary with jobs id and uri.
 906
 907 ``/2/jobs/[job_id]``
 908 ++++++++++++++++++++
 909
 910
 911 Individual job URI.
 912
 913 It supports the following commands: ``GET``, ``DELETE``.
 914
 915 ``GET``
 916 ~~~~~~~
 917
 918 Returns a job status.
 919
 920 Returns: a dictionary with job parameters.
 921
 922 The result includes:
 923
 924 - id: job ID as a number
 925 - status: current job status as a string
 926 - ops: involved OpCodes as a list of dictionaries for each opcodes in
 927   the job
 928 - opstatus: OpCodes status as a list
 929 - opresult: OpCodes results as a list
 930
 931 For a successful opcode, the ``opresult`` field corresponding to it will
 932 contain the raw result from its :term:`LogicalUnit`. In case an opcode
 933 has failed, its element in the opresult list will be a list of two
 934 elements:
 935
 936 - first element the error type (the Ganeti internal error name)
 937 - second element a list of either one or two elements:
 938
 939   - the first element is the textual error description
 940   - the second element, if any, will hold an error classification
 941
 942 The error classification is most useful for the ``OpPrereqError``
 943 error type - these errors happen before the OpCode has started
 944 executing, so it's possible to retry the OpCode without side
 945 effects. But whether it make sense to retry depends on the error
 946 classification:
 947
 948 ``resolver_error``
 949   Resolver errors. This usually means that a name doesn't exist in DNS,
 950   so if it's a case of slow DNS propagation the operation can be retried
 951   later.
 952
 953 ``insufficient_resources``
 954   Not enough resources (iallocator failure, disk space, memory,
 955   etc.). If the resources on the cluster increase, the operation might
 956   succeed.
 957
 958 ``wrong_input``
 959   Wrong arguments (at syntax level). The operation will not ever be
 960   accepted unless the arguments change.
 961
 962 ``wrong_state``
 963   Wrong entity state. For example, live migration has been requested for
 964   a down instance, or instance creation on an offline node. The
 965   operation can be retried once the resource has changed state.
 966
 967 ``unknown_entity``
 968   Entity not found. For example, information has been requested for an
 969   unknown instance.
 970
 971 ``already_exists``
 972   Entity already exists. For example, instance creation has been
 973   requested for an already-existing instance.
 974
 975 ``resource_not_unique``
 976   Resource not unique (e.g. MAC or IP duplication).
 977
 978 ``internal_error``
 979   Internal cluster error. For example, a node is unreachable but not set
 980   offline, or the ganeti node daemons are not working, etc. A
 981   ``gnt-cluster verify`` should be run.
 982
 983 ``environment_error``
 984   Environment error (e.g. node disk error). A ``gnt-cluster verify``
 985   should be run.
 986
 987 Note that in the above list, by entity we refer to a node or instance,
 988 while by a resource we refer to an instance's disk, or NIC, etc.
 989
 990
 991 ``DELETE``
 992 ~~~~~~~~~~
 993
 994 Cancel a not-yet-started job.
 995
 996
 997 ``/2/jobs/[job_id]/wait``
 998 +++++++++++++++++++++++++
 999
1000 ``GET``
1001 ~~~~~~~
1002
1003 Waits for changes on a job. Takes the following body parameters in a
1004 dict:
1005
1006 ``fields``
1007   The job fields on which to watch for changes.
1008
1009 ``previous_job_info``
1010   Previously received field values or None if not yet available.
1011
1012 ``previous_log_serial``
1013   Highest log serial number received so far or None if not yet
1014   available.
1015
1016 Returns None if no changes have been detected and a dict with two keys,
1017 ``job_info`` and ``log_entries`` otherwise.
1018
1019
1020 ``/2/nodes``
1021 ++++++++++++
1022
1023 Nodes resource.
1024
1025 It supports the following commands: ``GET``.
1026
1027 ``GET``
1028 ~~~~~~~
1029
1030 Returns a list of all nodes.
1031
1032 Example::
1033
1034     [
1035       {
1036         "id": "node1.example.com",
1037         "uri": "\/nodes\/node1.example.com"
1038       },
1039       {
1040         "id": "node2.example.com",
1041         "uri": "\/nodes\/node2.example.com"
1042       }
1043     ]
1044
1045 If the optional 'bulk' argument is provided and set to 'true' value (i.e
1046 '?bulk=1'), the output contains detailed information about nodes as a
1047 list.
1048
1049 Example::
1050
1051     [
1052       {
1053         "pinst_cnt": 1,
1054         "mfree": 31280,
1055         "mtotal": 32763,
1056         "name": "www.example.com",
1057         "tags": [],
1058         "mnode": 512,
1059         "dtotal": 5246208,
1060         "sinst_cnt": 2,
1061         "dfree": 5171712,
1062         "offline": false
1063       },
1064       ...
1065     ]
1066
1067 ``/2/nodes/[node_name]``
1068 +++++++++++++++++++++++++++++++++
1069
1070 Returns information about a node.
1071
1072 It supports the following commands: ``GET``.
1073
1074 ``/2/nodes/[node_name]/evacuate``
1075 +++++++++++++++++++++++++++++++++
1076
1077 Evacuates all secondary instances off a node.
1078
1079 It supports the following commands: ``POST``.
1080
1081 ``POST``
1082 ~~~~~~~~
1083
1084 To evacuate a node, either one of the ``iallocator`` or ``remote_node``
1085 parameters must be passed::
1086
1087     evacuate?iallocator=[iallocator]
1088     evacuate?remote_node=[nodeX.example.com]
1089
1090 The result value will be a list, each element being a triple of the job
1091 id (for this specific evacuation), the instance which is being evacuated
1092 by this job, and the node to which it is being relocated. In case the
1093 node is already empty, the result will be an empty list (without any
1094 jobs being submitted).
1095
1096 And additional parameter ``early_release`` signifies whether to try to
1097 parallelize the evacuations, at the risk of increasing I/O contention
1098 and increasing the chances of data loss, if the primary node of any of
1099 the instances being evacuated is not fully healthy.
1100
1101 If the dry-run parameter was specified, then the evacuation jobs were
1102 not actually submitted, and the job IDs will be null.
1103
1104
1105 ``/2/nodes/[node_name]/migrate``
1106 +++++++++++++++++++++++++++++++++
1107
1108 Migrates all primary instances from a node.
1109
1110 It supports the following commands: ``POST``.
1111
1112 ``POST``
1113 ~~~~~~~~
1114
1115 If no mode is explicitly specified, each instances' hypervisor default
1116 migration mode will be used. Query parameters:
1117
1118 ``live`` (bool)
1119   If set, use live migration if available.
1120 ``mode`` (string)
1121   Sets migration mode, ``live`` for live migration and ``non-live`` for
1122   non-live migration. Supported by Ganeti 2.2 and above.
1123
1124
1125 ``/2/nodes/[node_name]/role``
1126 +++++++++++++++++++++++++++++
1127
1128 Manages node role.
1129
1130 It supports the following commands: ``GET``, ``PUT``.
1131
1132 The role is always one of the following:
1133
1134   - drained
1135   - master
1136   - master-candidate
1137   - offline
1138   - regular
1139
1140 ``GET``
1141 ~~~~~~~
1142
1143 Returns the current node role.
1144
1145 Example::
1146
1147     "master-candidate"
1148
1149 ``PUT``
1150 ~~~~~~~
1151
1152 Change the node role.
1153
1154 The request is a string which should be PUT to this URI. The result will
1155 be a job id.
1156
1157 It supports the bool ``force`` argument.
1158
1159 ``/2/nodes/[node_name]/storage``
1160 ++++++++++++++++++++++++++++++++
1161
1162 Manages storage units on the node.
1163
1164 ``GET``
1165 ~~~~~~~
1166
1167 Requests a list of storage units on a node. Requires the parameters
1168 ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
1169 ``output_fields``. The result will be a job id, using which the result
1170 can be retrieved.
1171
1172 ``/2/nodes/[node_name]/storage/modify``
1173 +++++++++++++++++++++++++++++++++++++++
1174
1175 Modifies storage units on the node.
1176
1177 ``PUT``
1178 ~~~~~~~
1179
1180 Modifies parameters of storage units on the node. Requires the
1181 parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
1182 and ``name`` (name of the storage unit).  Parameters can be passed
1183 additionally. Currently only ``allocatable`` (bool) is supported. The
1184 result will be a job id.
1185
1186 ``/2/nodes/[node_name]/storage/repair``
1187 +++++++++++++++++++++++++++++++++++++++
1188
1189 Repairs a storage unit on the node.
1190
1191 ``PUT``
1192 ~~~~~~~
1193
1194 Repairs a storage unit on the node. Requires the parameters
1195 ``storage_type`` (currently only ``lvm-vg`` can be repaired) and
1196 ``name`` (name of the storage unit). The result will be a job id.
1197
1198 ``/2/nodes/[node_name]/tags``
1199 +++++++++++++++++++++++++++++
1200
1201 Manages per-node tags.
1202
1203 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1204
1205 ``GET``
1206 ~~~~~~~
1207
1208 Returns a list of tags.
1209
1210 Example::
1211
1212     ["tag1", "tag2", "tag3"]
1213
1214 ``PUT``
1215 ~~~~~~~
1216
1217 Add a set of tags.
1218
1219 The request as a list of strings should be PUT to this URI. The result
1220 will be a job id.
1221
1222 It supports the ``dry-run`` argument.
1223
1224 ``DELETE``
1225 ~~~~~~~~~~
1226
1227 Deletes tags.
1228
1229 In order to delete a set of tags, the DELETE request should be addressed
1230 to URI like::
1231
1232     /tags?tag=[tag]&tag=[tag]
1233
1234 It supports the ``dry-run`` argument.
1235
1236
1237 ``/2/os``
1238 +++++++++
1239
1240 OS resource.
1241
1242 It supports the following commands: ``GET``.
1243
1244 ``GET``
1245 ~~~~~~~
1246
1247 Return a list of all OSes.
1248
1249 Can return error 500 in case of a problem. Since this is a costly
1250 operation for Ganeti 2.0, it is not recommended to execute it too often.
1251
1252 Example::
1253
1254     ["debian-etch"]
1255
1256 ``/2/tags``
1257 +++++++++++
1258
1259 Manages cluster tags.
1260
1261 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1262
1263 ``GET``
1264 ~~~~~~~
1265
1266 Returns the cluster tags.
1267
1268 Example::
1269
1270     ["tag1", "tag2", "tag3"]
1271
1272 ``PUT``
1273 ~~~~~~~
1274
1275 Adds a set of tags.
1276
1277 The request as a list of strings should be PUT to this URI. The result
1278 will be a job id.
1279
1280 It supports the ``dry-run`` argument.
1281
1282
1283 ``DELETE``
1284 ~~~~~~~~~~
1285
1286 Deletes tags.
1287
1288 In order to delete a set of tags, the DELETE request should be addressed
1289 to URI like::
1290
1291     /tags?tag=[tag]&tag=[tag]
1292
1293 It supports the ``dry-run`` argument.
1294
1295
1296 ``/version``
1297 ++++++++++++
1298
1299 The version resource.
1300
1301 This resource should be used to determine the remote API version and to
1302 adapt clients accordingly.
1303
1304 It supports the following commands: ``GET``.
1305
1306 ``GET``
1307 ~~~~~~~
1308
1309 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1310 returns ``2``.
1311
1312 .. vim: set textwidth=72 :
1313 .. Local Variables:
1314 .. mode: rst
1315 .. fill-column: 72
1316 .. End: