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
  57    and 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 HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
  74 header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
  75 (HTTP/1.1), section 7.2.1).
  76
  77
  78 A note on JSON as used by RAPI
  79 ++++++++++++++++++++++++++++++
  80
  81 JSON_ as used by Ganeti RAPI does not conform to the specification in
  82 :rfc:`4627`. Section 2 defines a JSON text to be either an object
  83 (``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
  84 of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
  85 some requests or responses. Changing this now would likely break
  86 existing clients and cause a lot of trouble.
  87
  88 .. highlight:: ruby
  89
  90 Unlike Python's `JSON encoder and decoder
  91 <http://docs.python.org/library/json.html>`_, other programming
  92 languages or libraries may only provide a strict implementation, not
  93 allowing plain values. For those, responses can usually be wrapped in an
  94 array whose first element is then used, e.g. the response ``"1234"``
  95 becomes ``["1234"]``. This works equally well for more complex values.
  96 Example in Ruby::
  97
  98   require "json"
  99
 100   # Insert code to get response here
 101   response = "\"1234\""
 102
 103   decoded = JSON.parse("[#{response}]").first
 104
 105 Short of modifying the encoder to allow encoding to a less strict
 106 format, requests will have to be formatted by hand. Newer RAPI requests
 107 already use a dictionary as their input data and shouldn't cause any
 108 problems.
 109
 110
 111 PUT or POST?
 112 ------------
 113
 114 According to :rfc:`2616` the main difference between PUT and POST is
 115 that POST can create new resources but PUT can only create the resource
 116 the URI was pointing to on the PUT request.
 117
 118 Unfortunately, due to historic reasons, the Ganeti RAPI library is not
 119 consistent with this usage, so just use the methods as documented below
 120 for each resource.
 121
 122 For more details have a look in the source code at
 123 ``lib/rapi/rlib2.py``.
 124
 125
 126 Generic parameter types
 127 -----------------------
 128
 129 A few generic refered parameter types and the values they allow.
 130
 131 ``bool``
 132 ++++++++
 133
 134 A boolean option will accept ``1`` or ``0`` as numbers but not
 135 i.e. ``True`` or ``False``.
 136
 137 Generic parameters
 138 ------------------
 139
 140 A few parameter mean the same thing across all resources which implement
 141 it.
 142
 143 ``bulk``
 144 ++++++++
 145
 146 Bulk-mode means that for the resources which usually return just a list
 147 of child resources (e.g. ``/2/instances`` which returns just instance
 148 names), the output will instead contain detailed data for all these
 149 subresources. This is more efficient than query-ing the sub-resources
 150 themselves.
 151
 152 ``dry-run``
 153 +++++++++++
 154
 155 The boolean *dry-run* argument, if provided and set, signals to Ganeti
 156 that the job should not be executed, only the pre-execution checks will
 157 be done.
 158
 159 This is useful in trying to determine (without guarantees though, as in
 160 the meantime the cluster state could have changed) if the operation is
 161 likely to succeed or at least start executing.
 162
 163 ``force``
 164 +++++++++++
 165
 166 Force operation to continue even if it will cause the cluster to become
 167 inconsistent (e.g. because there are not enough master candidates).
 168
 169 Usage examples
 170 --------------
 171
 172 You can access the API using your favorite programming language as long
 173 as it supports network connections.
 174
 175 Ganeti RAPI client
 176 ++++++++++++++++++
 177
 178 Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.
 179
 180 Shell
 181 +++++
 182
 183 .. highlight:: sh
 184
 185 Using wget::
 186
 187    wget -q -O - https://CLUSTERNAME:5080/2/info
 188
 189 or curl::
 190
 191   curl https://CLUSTERNAME:5080/2/info
 192
 193
 194 Python
 195 ++++++
 196
 197 .. highlight:: python
 198
 199 ::
 200
 201   import urllib2
 202   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
 203   print f.read()
 204
 205
 206 JavaScript
 207 ++++++++++
 208
 209 .. warning:: While it's possible to use JavaScript, it poses several
 210    potential problems, including browser blocking request due to
 211    non-standard ports or different domain names. Fetching the data on
 212    the webserver is easier.
 213
 214 .. highlight:: javascript
 215
 216 ::
 217
 218   var url = 'https://CLUSTERNAME:5080/2/info';
 219   var info;
 220   var xmlreq = new XMLHttpRequest();
 221   xmlreq.onreadystatechange = function () {
 222     if (xmlreq.readyState != 4) return;
 223     if (xmlreq.status == 200) {
 224       info = eval("(" + xmlreq.responseText + ")");
 225       alert(info);
 226     } else {
 227       alert('Error fetching cluster info');
 228     }
 229     xmlreq = null;
 230   };
 231   xmlreq.open('GET', url, true);
 232   xmlreq.send(null);
 233
 234 Resources
 235 ---------
 236
 237 .. highlight:: javascript
 238
 239 ``/``
 240 +++++
 241
 242 The root resource. Has no function, but for legacy reasons the ``GET``
 243 method is supported.
 244
 245 ``/2``
 246 ++++++
 247
 248 Has no function, but for legacy reasons the ``GET`` method is supported.
 249
 250 ``/2/info``
 251 +++++++++++
 252
 253 Cluster information resource.
 254
 255 It supports the following commands: ``GET``.
 256
 257 ``GET``
 258 ~~~~~~~
 259
 260 Returns cluster information.
 261
 262 Example::
 263
 264   {
 265     "config_version": 2000000,
 266     "name": "cluster",
 267     "software_version": "2.0.0~beta2",
 268     "os_api_version": 10,
 269     "export_version": 0,
 270     "candidate_pool_size": 10,
 271     "enabled_hypervisors": [
 272       "fake"
 273     ],
 274     "hvparams": {
 275       "fake": {}
 276      },
 277     "default_hypervisor": "fake",
 278     "master": "node1.example.com",
 279     "architecture": [
 280       "64bit",
 281       "x86_64"
 282     ],
 283     "protocol_version": 20,
 284     "beparams": {
 285       "default": {
 286         "auto_balance": true,
 287         "vcpus": 1,
 288         "memory": 128
 289        }
 290       }
 291     }
 292
 293
 294 ``/2/redistribute-config``
 295 ++++++++++++++++++++++++++
 296
 297 Redistribute configuration to all nodes.
 298
 299 It supports the following commands: ``PUT``.
 300
 301 ``PUT``
 302 ~~~~~~~
 303
 304 Redistribute configuration to all nodes. The result will be a job id.
 305
 306
 307 ``/2/features``
 308 +++++++++++++++
 309
 310 ``GET``
 311 ~~~~~~~
 312
 313 Returns a list of features supported by the RAPI server. Available
 314 features:
 315
 316 .. pyassert::
 317
 318   rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
 319                              rlib2._INST_REINSTALL_REQV1,
 320                              rlib2._NODE_MIGRATE_REQV1,
 321                              rlib2._NODE_EVAC_RES1])
 322
 323 :pyeval:`rlib2._INST_CREATE_REQV1`
 324   Instance creation request data version 1 supported.
 325 :pyeval:`rlib2._INST_REINSTALL_REQV1`
 326   Instance reinstall supports body parameters.
 327 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
 328   Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
 329   request body parameters.
 330 :pyeval:`rlib2._NODE_EVAC_RES1`
 331   Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
 332   a new-style result (see resource description)
 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 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`
 382
 383 Example::
 384
 385     [
 386       {
 387         "name": "group1",
 388         "node_cnt": 2,
 389         "node_list": [
 390           "node1.example.com",
 391           "node2.example.com"
 392         ],
 393         "uuid": "0d7d407c-262e-49af-881a-6a430034bf43"
 394       },
 395       {
 396         "name": "group2",
 397         "node_cnt": 1,
 398         "node_list": [
 399           "node3.example.com"
 400         ],
 401         "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c"
 402       }
 403     ]
 404
 405 ``POST``
 406 ~~~~~~~~
 407
 408 Creates a node group.
 409
 410 If the optional bool *dry-run* argument is provided, the job will not be
 411 actually executed, only the pre-execution checks will be done.
 412
 413 Returns: a job ID that can be used later for polling.
 414
 415 Body parameters:
 416
 417 .. opcode_params:: OP_GROUP_ADD
 418
 419 Earlier versions used a parameter named ``name`` which, while still
 420 supported, has been renamed to ``group_name``.
 421
 422
 423 ``/2/groups/[group_name]``
 424 ++++++++++++++++++++++++++
 425
 426 Returns information about a node group.
 427
 428 It supports the following commands: ``GET``, ``DELETE``.
 429
 430 ``GET``
 431 ~~~~~~~
 432
 433 Returns information about a node group, similar to the bulk output from
 434 the node group list.
 435
 436 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`
 437
 438 ``DELETE``
 439 ~~~~~~~~~~
 440
 441 Deletes a node group.
 442
 443 It supports the ``dry-run`` argument.
 444
 445
 446 ``/2/groups/[group_name]/modify``
 447 +++++++++++++++++++++++++++++++++
 448
 449 Modifies the parameters of a node group.
 450
 451 Supports the following commands: ``PUT``.
 452
 453 ``PUT``
 454 ~~~~~~~
 455
 456 Returns a job ID.
 457
 458 Body parameters:
 459
 460 .. opcode_params:: OP_GROUP_SET_PARAMS
 461    :exclude: group_name
 462
 463 Job result:
 464
 465 .. opcode_result:: OP_GROUP_SET_PARAMS
 466
 467
 468 ``/2/groups/[group_name]/rename``
 469 +++++++++++++++++++++++++++++++++
 470
 471 Renames a node group.
 472
 473 Supports the following commands: ``PUT``.
 474
 475 ``PUT``
 476 ~~~~~~~
 477
 478 Returns a job ID.
 479
 480 Body parameters:
 481
 482 .. opcode_params:: OP_GROUP_RENAME
 483    :exclude: group_name
 484
 485 Job result:
 486
 487 .. opcode_result:: OP_GROUP_RENAME
 488
 489
 490 ``/2/groups/[group_name]/assign-nodes``
 491 +++++++++++++++++++++++++++++++++++++++
 492
 493 Assigns nodes to a group.
 494
 495 Supports the following commands: ``PUT``.
 496
 497 ``PUT``
 498 ~~~~~~~
 499
 500 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
 501
 502 Body parameters:
 503
 504 .. opcode_params:: OP_GROUP_ASSIGN_NODES
 505    :exclude: group_name, force, dry_run
 506
 507
 508 ``/2/groups/[group_name]/tags``
 509 +++++++++++++++++++++++++++++++
 510
 511 Manages per-nodegroup tags.
 512
 513 Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 514
 515 ``GET``
 516 ~~~~~~~
 517
 518 Returns a list of tags.
 519
 520 Example::
 521
 522     ["tag1", "tag2", "tag3"]
 523
 524 ``PUT``
 525 ~~~~~~~
 526
 527 Add a set of tags.
 528
 529 The request as a list of strings should be ``PUT`` to this URI. The
 530 result will be a job id.
 531
 532 It supports the ``dry-run`` argument.
 533
 534
 535 ``DELETE``
 536 ~~~~~~~~~~
 537
 538 Delete a tag.
 539
 540 In order to delete a set of tags, the DELETE request should be addressed
 541 to URI like::
 542
 543     /tags?tag=[tag]&tag=[tag]
 544
 545 It supports the ``dry-run`` argument.
 546
 547
 548 ``/2/instances``
 549 ++++++++++++++++
 550
 551 The instances resource.
 552
 553 It supports the following commands: ``GET``, ``POST``.
 554
 555 ``GET``
 556 ~~~~~~~
 557
 558 Returns a list of all available instances.
 559
 560 Example::
 561
 562     [
 563       {
 564         "name": "web.example.com",
 565         "uri": "\/instances\/web.example.com"
 566       },
 567       {
 568         "name": "mail.example.com",
 569         "uri": "\/instances\/mail.example.com"
 570       }
 571     ]
 572
 573 If the optional bool *bulk* argument is provided and set to a true value
 574 (i.e ``?bulk=1``), the output contains detailed information about
 575 instances as a list.
 576
 577 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
 578
 579 Example::
 580
 581     [
 582       {
 583          "status": "running",
 584          "disk_usage": 20480,
 585          "nic.bridges": [
 586            "xen-br0"
 587           ],
 588          "name": "web.example.com",
 589          "tags": ["tag1", "tag2"],
 590          "beparams": {
 591            "vcpus": 2,
 592            "memory": 512
 593          },
 594          "disk.sizes": [
 595              20480
 596          ],
 597          "pnode": "node1.example.com",
 598          "nic.macs": ["01:23:45:67:89:01"],
 599          "snodes": ["node2.example.com"],
 600          "disk_template": "drbd",
 601          "admin_state": true,
 602          "os": "debian-etch",
 603          "oper_state": true
 604       },
 605       ...
 606     ]
 607
 608
 609 ``POST``
 610 ~~~~~~~~
 611
 612 Creates an instance.
 613
 614 If the optional bool *dry-run* argument is provided, the job will not be
 615 actually executed, only the pre-execution checks will be done. Query-ing
 616 the job result will return, in both dry-run and normal case, the list of
 617 nodes selected for the instance.
 618
 619 Returns: a job ID that can be used later for polling.
 620
 621 Body parameters:
 622
 623 ``__version__`` (int, required)
 624   Must be ``1`` (older Ganeti versions used a different format for
 625   instance creation requests, version ``0``, but that format is no
 626   longer supported)
 627
 628 .. opcode_params:: OP_INSTANCE_CREATE
 629
 630 Earlier versions used parameters named ``name`` and ``os``. These have
 631 been replaced by ``instance_name`` and ``os_type`` to match the
 632 underlying opcode. The old names can still be used.
 633
 634 Job result:
 635
 636 .. opcode_result:: OP_INSTANCE_CREATE
 637
 638
 639 ``/2/instances/[instance_name]``
 640 ++++++++++++++++++++++++++++++++
 641
 642 Instance-specific resource.
 643
 644 It supports the following commands: ``GET``, ``DELETE``.
 645
 646 ``GET``
 647 ~~~~~~~
 648
 649 Returns information about an instance, similar to the bulk output from
 650 the instance list.
 651
 652 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
 653
 654 ``DELETE``
 655 ~~~~~~~~~~
 656
 657 Deletes an instance.
 658
 659 It supports the ``dry-run`` argument.
 660
 661
 662 ``/2/instances/[instance_name]/info``
 663 +++++++++++++++++++++++++++++++++++++++
 664
 665 It supports the following commands: ``GET``.
 666
 667 ``GET``
 668 ~~~~~~~
 669
 670 Requests detailed information about the instance. An optional parameter,
 671 ``static`` (bool), can be set to return only static information from the
 672 configuration without querying the instance's nodes. The result will be
 673 a job id.
 674
 675
 676 ``/2/instances/[instance_name]/reboot``
 677 +++++++++++++++++++++++++++++++++++++++
 678
 679 Reboots URI for an instance.
 680
 681 It supports the following commands: ``POST``.
 682
 683 ``POST``
 684 ~~~~~~~~
 685
 686 Reboots the instance.
 687
 688 The URI takes optional ``type=soft|hard|full`` and
 689 ``ignore_secondaries=0|1`` parameters.
 690
 691 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
 692 without terminating the hypervisor. ``hard`` means full shutdown
 693 (including terminating the hypervisor process) and startup again.
 694 ``full`` is like ``hard`` but also recreates the configuration from
 695 ground up as if you would have done a ``gnt-instance shutdown`` and
 696 ``gnt-instance start`` on it.
 697
 698 ``ignore_secondaries`` is a bool argument indicating if we start the
 699 instance even if secondary disks are failing.
 700
 701 It supports the ``dry-run`` argument.
 702
 703
 704 ``/2/instances/[instance_name]/shutdown``
 705 +++++++++++++++++++++++++++++++++++++++++
 706
 707 Instance shutdown URI.
 708
 709 It supports the following commands: ``PUT``.
 710
 711 ``PUT``
 712 ~~~~~~~
 713
 714 Shutdowns an instance.
 715
 716 It supports the ``dry-run`` argument.
 717
 718 .. opcode_params:: OP_INSTANCE_SHUTDOWN
 719    :exclude: instance_name, dry_run
 720
 721
 722 ``/2/instances/[instance_name]/startup``
 723 ++++++++++++++++++++++++++++++++++++++++
 724
 725 Instance startup URI.
 726
 727 It supports the following commands: ``PUT``.
 728
 729 ``PUT``
 730 ~~~~~~~
 731
 732 Startup an instance.
 733
 734 The URI takes an optional ``force=1|0`` parameter to start the
 735 instance even if secondary disks are failing.
 736
 737 It supports the ``dry-run`` argument.
 738
 739 ``/2/instances/[instance_name]/reinstall``
 740 ++++++++++++++++++++++++++++++++++++++++++++++
 741
 742 Installs the operating system again.
 743
 744 It supports the following commands: ``POST``.
 745
 746 ``POST``
 747 ~~~~~~~~
 748
 749 Returns a job ID.
 750
 751 Body parameters:
 752
 753 ``os`` (string, required)
 754   Instance operating system.
 755 ``start`` (bool, defaults to true)
 756   Whether to start instance after reinstallation.
 757 ``osparams`` (dict)
 758   Dictionary with (temporary) OS parameters.
 759
 760 For backwards compatbility, this resource also takes the query
 761 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
 762 clients should use the body parameters.
 763
 764
 765 ``/2/instances/[instance_name]/replace-disks``
 766 ++++++++++++++++++++++++++++++++++++++++++++++
 767
 768 Replaces disks on an instance.
 769
 770 It supports the following commands: ``POST``.
 771
 772 ``POST``
 773 ~~~~~~~~
 774
 775 Returns a job ID.
 776
 777 Body parameters:
 778
 779 .. opcode_params:: OP_INSTANCE_REPLACE_DISKS
 780    :exclude: instance_name
 781
 782 Ganeti 2.4 and below used query parameters. Those are deprecated and
 783 should no longer be used.
 784
 785
 786 ``/2/instances/[instance_name]/activate-disks``
 787 +++++++++++++++++++++++++++++++++++++++++++++++
 788
 789 Activate disks on an instance.
 790
 791 It supports the following commands: ``PUT``.
 792
 793 ``PUT``
 794 ~~~~~~~
 795
 796 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 797 size (useful for forcing activation when recorded size is wrong).
 798
 799
 800 ``/2/instances/[instance_name]/deactivate-disks``
 801 +++++++++++++++++++++++++++++++++++++++++++++++++
 802
 803 Deactivate disks on an instance.
 804
 805 It supports the following commands: ``PUT``.
 806
 807 ``PUT``
 808 ~~~~~~~
 809
 810 Takes no parameters.
 811
 812
 813 ``/2/instances/[instance_name]/recreate-disks``
 814 +++++++++++++++++++++++++++++++++++++++++++++++++
 815
 816 Recreate disks of an instance. Supports the following commands:
 817 ``POST``.
 818
 819 ``POST``
 820 ~~~~~~~~
 821
 822 Returns a job ID.
 823
 824 Body parameters:
 825
 826 .. opcode_params:: OP_INSTANCE_RECREATE_DISKS
 827    :exclude: instance_name
 828
 829
 830 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
 831 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 832
 833 Grows one disk of an instance.
 834
 835 Supports the following commands: ``POST``.
 836
 837 ``POST``
 838 ~~~~~~~~
 839
 840 Returns a job ID.
 841
 842 Body parameters:
 843
 844 .. opcode_params:: OP_INSTANCE_GROW_DISK
 845    :exclude: instance_name, disk
 846
 847
 848 ``/2/instances/[instance_name]/prepare-export``
 849 +++++++++++++++++++++++++++++++++++++++++++++++++
 850
 851 Prepares an export of an instance.
 852
 853 It supports the following commands: ``PUT``.
 854
 855 ``PUT``
 856 ~~~~~~~
 857
 858 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 859
 860
 861 ``/2/instances/[instance_name]/export``
 862 +++++++++++++++++++++++++++++++++++++++++++++++++
 863
 864 Exports an instance.
 865
 866 It supports the following commands: ``PUT``.
 867
 868 ``PUT``
 869 ~~~~~~~
 870
 871 Returns a job ID.
 872
 873 Body parameters:
 874
 875 .. opcode_params:: OP_BACKUP_EXPORT
 876    :exclude: instance_name
 877    :alias: target_node=destination
 878
 879
 880 ``/2/instances/[instance_name]/migrate``
 881 ++++++++++++++++++++++++++++++++++++++++
 882
 883 Migrates an instance.
 884
 885 Supports the following commands: ``PUT``.
 886
 887 ``PUT``
 888 ~~~~~~~
 889
 890 Returns a job ID.
 891
 892 Body parameters:
 893
 894 .. opcode_params:: OP_INSTANCE_MIGRATE
 895    :exclude: instance_name, live
 896
 897
 898 ``/2/instances/[instance_name]/failover``
 899 +++++++++++++++++++++++++++++++++++++++++
 900
 901 Does a failover of an instance.
 902
 903 Supports the following commands: ``PUT``.
 904
 905 ``PUT``
 906 ~~~~~~~
 907
 908 Returns a job ID.
 909
 910 Body parameters:
 911
 912 .. opcode_params:: OP_INSTANCE_FAILOVER
 913    :exclude: instance_name
 914
 915
 916 ``/2/instances/[instance_name]/rename``
 917 ++++++++++++++++++++++++++++++++++++++++
 918
 919 Renames an instance.
 920
 921 Supports the following commands: ``PUT``.
 922
 923 ``PUT``
 924 ~~~~~~~
 925
 926 Returns a job ID.
 927
 928 Body parameters:
 929
 930 .. opcode_params:: OP_INSTANCE_RENAME
 931    :exclude: instance_name
 932
 933 Job result:
 934
 935 .. opcode_result:: OP_INSTANCE_RENAME
 936
 937
 938 ``/2/instances/[instance_name]/modify``
 939 ++++++++++++++++++++++++++++++++++++++++
 940
 941 Modifies an instance.
 942
 943 Supports the following commands: ``PUT``.
 944
 945 ``PUT``
 946 ~~~~~~~
 947
 948 Returns a job ID.
 949
 950 Body parameters:
 951
 952 .. opcode_params:: OP_INSTANCE_SET_PARAMS
 953    :exclude: instance_name
 954
 955 Job result:
 956
 957 .. opcode_result:: OP_INSTANCE_SET_PARAMS
 958
 959
 960 ``/2/instances/[instance_name]/console``
 961 ++++++++++++++++++++++++++++++++++++++++
 962
 963 Request information for connecting to instance's console.
 964
 965 Supports the following commands: ``GET``.
 966
 967 ``GET``
 968 ~~~~~~~
 969
 970 Returns a dictionary containing information about the instance's
 971 console. Contained keys:
 972
 973 .. pyassert::
 974
 975    constants.CONS_ALL == frozenset([
 976      constants.CONS_MESSAGE,
 977      constants.CONS_SSH,
 978      constants.CONS_VNC,
 979      constants.CONS_SPICE,
 980      ])
 981
 982 ``instance``
 983   Instance name.
 984 ``kind``
 985   Console type, one of :pyeval:`constants.CONS_SSH`,
 986   :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
 987   or :pyeval:`constants.CONS_MESSAGE`.
 988 ``message``
 989   Message to display (:pyeval:`constants.CONS_MESSAGE` type only).
 990 ``host``
 991   Host to connect to (:pyeval:`constants.CONS_SSH`,
 992   :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only).
 993 ``port``
 994   TCP port to connect to (:pyeval:`constants.CONS_VNC` or
 995   :pyeval:`constants.CONS_SPICE` only).
 996 ``user``
 997   Username to use (:pyeval:`constants.CONS_SSH` only).
 998 ``command``
 999   Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
1000 ``display``
1001   VNC display number (:pyeval:`constants.CONS_VNC` only).
1002
1003
1004 ``/2/instances/[instance_name]/tags``
1005 +++++++++++++++++++++++++++++++++++++
1006
1007 Manages per-instance tags.
1008
1009 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1010
1011 ``GET``
1012 ~~~~~~~
1013
1014 Returns a list of tags.
1015
1016 Example::
1017
1018     ["tag1", "tag2", "tag3"]
1019
1020 ``PUT``
1021 ~~~~~~~
1022
1023 Add a set of tags.
1024
1025 The request as a list of strings should be ``PUT`` to this URI. The
1026 result will be a job id.
1027
1028 It supports the ``dry-run`` argument.
1029
1030
1031 ``DELETE``
1032 ~~~~~~~~~~
1033
1034 Delete a tag.
1035
1036 In order to delete a set of tags, the DELETE request should be addressed
1037 to URI like::
1038
1039     /tags?tag=[tag]&tag=[tag]
1040
1041 It supports the ``dry-run`` argument.
1042
1043
1044 ``/2/jobs``
1045 +++++++++++
1046
1047 The ``/2/jobs`` resource.
1048
1049 It supports the following commands: ``GET``.
1050
1051 ``GET``
1052 ~~~~~~~
1053
1054 Returns a dictionary of jobs.
1055
1056 Returns: a dictionary with jobs id and uri.
1057
1058 If the optional bool *bulk* argument is provided and set to a true value
1059 (i.e. ``?bulk=1``), the output contains detailed information about jobs
1060 as a list.
1061
1062 Returned fields for bulk requests (unlike other bulk requests, these
1063 fields are not the same as for per-job requests):
1064 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`
1065
1066 ``/2/jobs/[job_id]``
1067 ++++++++++++++++++++
1068
1069
1070 Individual job URI.
1071
1072 It supports the following commands: ``GET``, ``DELETE``.
1073
1074 ``GET``
1075 ~~~~~~~
1076
1077 Returns a dictionary with job parameters, containing the fields
1078 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.
1079
1080 The result includes:
1081
1082 - id: job ID as a number
1083 - status: current job status as a string
1084 - ops: involved OpCodes as a list of dictionaries for each opcodes in
1085   the job
1086 - opstatus: OpCodes status as a list
1087 - opresult: OpCodes results as a list
1088
1089 For a successful opcode, the ``opresult`` field corresponding to it will
1090 contain the raw result from its :term:`LogicalUnit`. In case an opcode
1091 has failed, its element in the opresult list will be a list of two
1092 elements:
1093
1094 - first element the error type (the Ganeti internal error name)
1095 - second element a list of either one or two elements:
1096
1097   - the first element is the textual error description
1098   - the second element, if any, will hold an error classification
1099
1100 The error classification is most useful for the ``OpPrereqError``
1101 error type - these errors happen before the OpCode has started
1102 executing, so it's possible to retry the OpCode without side
1103 effects. But whether it make sense to retry depends on the error
1104 classification:
1105
1106 .. pyassert::
1107
1108    errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
1109      errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
1110      errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
1111      errors.ECODE_ENVIRON])
1112
1113 :pyeval:`errors.ECODE_RESOLVER`
1114   Resolver errors. This usually means that a name doesn't exist in DNS,
1115   so if it's a case of slow DNS propagation the operation can be retried
1116   later.
1117
1118 :pyeval:`errors.ECODE_NORES`
1119   Not enough resources (iallocator failure, disk space, memory,
1120   etc.). If the resources on the cluster increase, the operation might
1121   succeed.
1122
1123 :pyeval:`errors.ECODE_INVAL`
1124   Wrong arguments (at syntax level). The operation will not ever be
1125   accepted unless the arguments change.
1126
1127 :pyeval:`errors.ECODE_STATE`
1128   Wrong entity state. For example, live migration has been requested for
1129   a down instance, or instance creation on an offline node. The
1130   operation can be retried once the resource has changed state.
1131
1132 :pyeval:`errors.ECODE_NOENT`
1133   Entity not found. For example, information has been requested for an
1134   unknown instance.
1135
1136 :pyeval:`errors.ECODE_EXISTS`
1137   Entity already exists. For example, instance creation has been
1138   requested for an already-existing instance.
1139
1140 :pyeval:`errors.ECODE_NOTUNIQUE`
1141   Resource not unique (e.g. MAC or IP duplication).
1142
1143 :pyeval:`errors.ECODE_FAULT`
1144   Internal cluster error. For example, a node is unreachable but not set
1145   offline, or the ganeti node daemons are not working, etc. A
1146   ``gnt-cluster verify`` should be run.
1147
1148 :pyeval:`errors.ECODE_ENVIRON`
1149   Environment error (e.g. node disk error). A ``gnt-cluster verify``
1150   should be run.
1151
1152 Note that in the above list, by entity we refer to a node or instance,
1153 while by a resource we refer to an instance's disk, or NIC, etc.
1154
1155
1156 ``DELETE``
1157 ~~~~~~~~~~
1158
1159 Cancel a not-yet-started job.
1160
1161
1162 ``/2/jobs/[job_id]/wait``
1163 +++++++++++++++++++++++++
1164
1165 ``GET``
1166 ~~~~~~~
1167
1168 Waits for changes on a job. Takes the following body parameters in a
1169 dict:
1170
1171 ``fields``
1172   The job fields on which to watch for changes.
1173
1174 ``previous_job_info``
1175   Previously received field values or None if not yet available.
1176
1177 ``previous_log_serial``
1178   Highest log serial number received so far or None if not yet
1179   available.
1180
1181 Returns None if no changes have been detected and a dict with two keys,
1182 ``job_info`` and ``log_entries`` otherwise.
1183
1184
1185 ``/2/nodes``
1186 ++++++++++++
1187
1188 Nodes resource.
1189
1190 It supports the following commands: ``GET``.
1191
1192 ``GET``
1193 ~~~~~~~
1194
1195 Returns a list of all nodes.
1196
1197 Example::
1198
1199     [
1200       {
1201         "id": "node1.example.com",
1202         "uri": "\/nodes\/node1.example.com"
1203       },
1204       {
1205         "id": "node2.example.com",
1206         "uri": "\/nodes\/node2.example.com"
1207       }
1208     ]
1209
1210 If the optional bool *bulk* argument is provided and set to a true value
1211 (i.e ``?bulk=1``), the output contains detailed information about nodes
1212 as a list.
1213
1214 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
1215
1216 Example::
1217
1218     [
1219       {
1220         "pinst_cnt": 1,
1221         "mfree": 31280,
1222         "mtotal": 32763,
1223         "name": "www.example.com",
1224         "tags": [],
1225         "mnode": 512,
1226         "dtotal": 5246208,
1227         "sinst_cnt": 2,
1228         "dfree": 5171712,
1229         "offline": false
1230       },
1231       ...
1232     ]
1233
1234 ``/2/nodes/[node_name]``
1235 +++++++++++++++++++++++++++++++++
1236
1237 Returns information about a node.
1238
1239 It supports the following commands: ``GET``.
1240
1241 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
1242
1243 ``/2/nodes/[node_name]/powercycle``
1244 +++++++++++++++++++++++++++++++++++
1245
1246 Powercycles a node. Supports the following commands: ``POST``.
1247
1248 ``POST``
1249 ~~~~~~~~
1250
1251 Returns a job ID.
1252
1253
1254 ``/2/nodes/[node_name]/evacuate``
1255 +++++++++++++++++++++++++++++++++
1256
1257 Evacuates instances off a node.
1258
1259 It supports the following commands: ``POST``.
1260
1261 ``POST``
1262 ~~~~~~~~
1263
1264 Returns a job ID. The result of the job will contain the IDs of the
1265 individual jobs submitted to evacuate the node.
1266
1267 Body parameters:
1268
1269 .. opcode_params:: OP_NODE_EVACUATE
1270    :exclude: nodes
1271
1272 Up to and including Ganeti 2.4 query arguments were used. Those are no
1273 longer supported. The new request can be detected by the presence of the
1274 :pyeval:`rlib2._NODE_EVAC_RES1` feature string.
1275
1276 Job result:
1277
1278 .. opcode_result:: OP_NODE_EVACUATE
1279
1280
1281 ``/2/nodes/[node_name]/migrate``
1282 +++++++++++++++++++++++++++++++++
1283
1284 Migrates all primary instances from a node.
1285
1286 It supports the following commands: ``POST``.
1287
1288 ``POST``
1289 ~~~~~~~~
1290
1291 If no mode is explicitly specified, each instances' hypervisor default
1292 migration mode will be used. Body parameters:
1293
1294 .. opcode_params:: OP_NODE_MIGRATE
1295    :exclude: node_name
1296
1297 The query arguments used up to and including Ganeti 2.4 are deprecated
1298 and should no longer be used. The new request format can be detected by
1299 the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
1300
1301 Job result:
1302
1303 .. opcode_result:: OP_NODE_MIGRATE
1304
1305
1306 ``/2/nodes/[node_name]/role``
1307 +++++++++++++++++++++++++++++
1308
1309 Manages node role.
1310
1311 It supports the following commands: ``GET``, ``PUT``.
1312
1313 The role is always one of the following:
1314
1315   - drained
1316   - master-candidate
1317   - offline
1318   - regular
1319
1320 Note that the 'master' role is a special, and currently it can't be
1321 modified via RAPI, only via the command line (``gnt-cluster
1322 master-failover``).
1323
1324 ``GET``
1325 ~~~~~~~
1326
1327 Returns the current node role.
1328
1329 Example::
1330
1331     "master-candidate"
1332
1333 ``PUT``
1334 ~~~~~~~
1335
1336 Change the node role.
1337
1338 The request is a string which should be PUT to this URI. The result will
1339 be a job id.
1340
1341 It supports the bool ``force`` argument.
1342
1343
1344 ``/2/nodes/[node_name]/modify``
1345 +++++++++++++++++++++++++++++++
1346
1347 Modifies the parameters of a node. Supports the following commands:
1348 ``POST``.
1349
1350 ``POST``
1351 ~~~~~~~~
1352
1353 Returns a job ID.
1354
1355 Body parameters:
1356
1357 .. opcode_params:: OP_NODE_SET_PARAMS
1358    :exclude: node_name
1359
1360 Job result:
1361
1362 .. opcode_result:: OP_NODE_SET_PARAMS
1363
1364
1365 ``/2/nodes/[node_name]/storage``
1366 ++++++++++++++++++++++++++++++++
1367
1368 Manages storage units on the node.
1369
1370 ``GET``
1371 ~~~~~~~
1372
1373 .. pyassert::
1374
1375    constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
1376                                          constants.ST_LVM_PV,
1377                                          constants.ST_LVM_VG])
1378
1379 Requests a list of storage units on a node. Requires the parameters
1380 ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1381 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
1382 ``output_fields``. The result will be a job id, using which the result
1383 can be retrieved.
1384
1385 ``/2/nodes/[node_name]/storage/modify``
1386 +++++++++++++++++++++++++++++++++++++++
1387
1388 Modifies storage units on the node.
1389
1390 ``PUT``
1391 ~~~~~~~
1392
1393 Modifies parameters of storage units on the node. Requires the
1394 parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1395 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
1396 and ``name`` (name of the storage unit).  Parameters can be passed
1397 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
1398 is supported. The result will be a job id.
1399
1400 ``/2/nodes/[node_name]/storage/repair``
1401 +++++++++++++++++++++++++++++++++++++++
1402
1403 Repairs a storage unit on the node.
1404
1405 ``PUT``
1406 ~~~~~~~
1407
1408 .. pyassert::
1409
1410    constants.VALID_STORAGE_OPERATIONS == {
1411     constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
1412     }
1413
1414 Repairs a storage unit on the node. Requires the parameters
1415 ``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
1416 repaired) and ``name`` (name of the storage unit). The result will be a
1417 job id.
1418
1419 ``/2/nodes/[node_name]/tags``
1420 +++++++++++++++++++++++++++++
1421
1422 Manages per-node tags.
1423
1424 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1425
1426 ``GET``
1427 ~~~~~~~
1428
1429 Returns a list of tags.
1430
1431 Example::
1432
1433     ["tag1", "tag2", "tag3"]
1434
1435 ``PUT``
1436 ~~~~~~~
1437
1438 Add a set of tags.
1439
1440 The request as a list of strings should be PUT to this URI. The result
1441 will be a job id.
1442
1443 It supports the ``dry-run`` argument.
1444
1445 ``DELETE``
1446 ~~~~~~~~~~
1447
1448 Deletes tags.
1449
1450 In order to delete a set of tags, the DELETE request should be addressed
1451 to URI like::
1452
1453     /tags?tag=[tag]&tag=[tag]
1454
1455 It supports the ``dry-run`` argument.
1456
1457
1458 ``/2/query/[resource]``
1459 +++++++++++++++++++++++
1460
1461 Requests resource information. Available fields can be found in man
1462 pages and using ``/2/query/[resource]/fields``. The resource is one of
1463 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
1464 design document <design-query2>` for more details.
1465
1466 Supports the following commands: ``GET``, ``PUT``.
1467
1468 ``GET``
1469 ~~~~~~~
1470
1471 Returns list of included fields and actual data. Takes a query parameter
1472 named "fields", containing a comma-separated list of field names. Does
1473 not support filtering.
1474
1475 ``PUT``
1476 ~~~~~~~
1477
1478 Returns list of included fields and actual data. The list of requested
1479 fields can either be given as the query parameter "fields" or as a body
1480 parameter with the same name. The optional body parameter "filter" can
1481 be given and must be either ``null`` or a list containing filter
1482 operators.
1483
1484
1485 ``/2/query/[resource]/fields``
1486 ++++++++++++++++++++++++++++++
1487
1488 Request list of available fields for a resource. The resource is one of
1489 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
1490 :doc:`query2 design document <design-query2>` for more details.
1491
1492 Supports the following commands: ``GET``.
1493
1494 ``GET``
1495 ~~~~~~~
1496
1497 Returns a list of field descriptions for available fields. Takes an
1498 optional query parameter named "fields", containing a comma-separated
1499 list of field names.
1500
1501
1502 ``/2/os``
1503 +++++++++
1504
1505 OS resource.
1506
1507 It supports the following commands: ``GET``.
1508
1509 ``GET``
1510 ~~~~~~~
1511
1512 Return a list of all OSes.
1513
1514 Can return error 500 in case of a problem. Since this is a costly
1515 operation for Ganeti 2.0, it is not recommended to execute it too often.
1516
1517 Example::
1518
1519     ["debian-etch"]
1520
1521 ``/2/tags``
1522 +++++++++++
1523
1524 Manages cluster tags.
1525
1526 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1527
1528 ``GET``
1529 ~~~~~~~
1530
1531 Returns the cluster tags.
1532
1533 Example::
1534
1535     ["tag1", "tag2", "tag3"]
1536
1537 ``PUT``
1538 ~~~~~~~
1539
1540 Adds a set of tags.
1541
1542 The request as a list of strings should be PUT to this URI. The result
1543 will be a job id.
1544
1545 It supports the ``dry-run`` argument.
1546
1547
1548 ``DELETE``
1549 ~~~~~~~~~~
1550
1551 Deletes tags.
1552
1553 In order to delete a set of tags, the DELETE request should be addressed
1554 to URI like::
1555
1556     /tags?tag=[tag]&tag=[tag]
1557
1558 It supports the ``dry-run`` argument.
1559
1560
1561 ``/version``
1562 ++++++++++++
1563
1564 The version resource.
1565
1566 This resource should be used to determine the remote API version and to
1567 adapt clients accordingly.
1568
1569 It supports the following commands: ``GET``.
1570
1571 ``GET``
1572 ~~~~~~~
1573
1574 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1575 returns ``2``.
1576
1577 .. vim: set textwidth=72 :
1578 .. Local Variables:
1579 .. mode: rst
1580 .. fill-column: 72
1581 .. End: