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.
 243
 244 It supports the following commands: ``GET``.
 245
 246 ``GET``
 247 ~~~~~~~
 248
 249 Shows the list of mapped resources.
 250
 251 Returns: a dictionary with 'name' and 'uri' keys for each of them.
 252
 253 ``/2``
 254 ++++++
 255
 256 The ``/2`` resource, the root of the version 2 API.
 257
 258 It supports the following commands: ``GET``.
 259
 260 ``GET``
 261 ~~~~~~~
 262
 263 Show the list of mapped resources.
 264
 265 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
 266
 267 ``/2/info``
 268 +++++++++++
 269
 270 Cluster information resource.
 271
 272 It supports the following commands: ``GET``.
 273
 274 ``GET``
 275 ~~~~~~~
 276
 277 Returns cluster information.
 278
 279 Example::
 280
 281   {
 282     "config_version": 2000000,
 283     "name": "cluster",
 284     "software_version": "2.0.0~beta2",
 285     "os_api_version": 10,
 286     "export_version": 0,
 287     "candidate_pool_size": 10,
 288     "enabled_hypervisors": [
 289       "fake"
 290     ],
 291     "hvparams": {
 292       "fake": {}
 293      },
 294     "default_hypervisor": "fake",
 295     "master": "node1.example.com",
 296     "architecture": [
 297       "64bit",
 298       "x86_64"
 299     ],
 300     "protocol_version": 20,
 301     "beparams": {
 302       "default": {
 303         "auto_balance": true,
 304         "vcpus": 1,
 305         "memory": 128
 306        }
 307       }
 308     }
 309
 310
 311 ``/2/redistribute-config``
 312 ++++++++++++++++++++++++++
 313
 314 Redistribute configuration to all nodes.
 315
 316 It supports the following commands: ``PUT``.
 317
 318 ``PUT``
 319 ~~~~~~~
 320
 321 Redistribute configuration to all nodes. The result will be a job id.
 322
 323
 324 ``/2/features``
 325 +++++++++++++++
 326
 327 ``GET``
 328 ~~~~~~~
 329
 330 Returns a list of features supported by the RAPI server. Available
 331 features:
 332
 333 .. pyassert::
 334
 335   rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
 336                              rlib2._INST_REINSTALL_REQV1,
 337                              rlib2._NODE_MIGRATE_REQV1,
 338                              rlib2._NODE_EVAC_RES1])
 339
 340 :pyeval:`rlib2._INST_CREATE_REQV1`
 341   Instance creation request data version 1 supported.
 342 :pyeval:`rlib2._INST_REINSTALL_REQV1`
 343   Instance reinstall supports body parameters.
 344 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
 345   Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
 346   request body parameters.
 347 :pyeval:`rlib2._NODE_EVAC_RES1`
 348   Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
 349   a new-style result (see resource description)
 350
 351
 352 ``/2/modify``
 353 ++++++++++++++++++++++++++++++++++++++++
 354
 355 Modifies cluster parameters.
 356
 357 Supports the following commands: ``PUT``.
 358
 359 ``PUT``
 360 ~~~~~~~
 361
 362 Returns a job ID.
 363
 364 Body parameters:
 365
 366 .. opcode_params:: OP_CLUSTER_SET_PARAMS
 367
 368
 369 ``/2/groups``
 370 +++++++++++++
 371
 372 The groups resource.
 373
 374 It supports the following commands: ``GET``, ``POST``.
 375
 376 ``GET``
 377 ~~~~~~~
 378
 379 Returns a list of all existing node groups.
 380
 381 Example::
 382
 383     [
 384       {
 385         "name": "group1",
 386         "uri": "\/2\/groups\/group1"
 387       },
 388       {
 389         "name": "group2",
 390         "uri": "\/2\/groups\/group2"
 391       }
 392     ]
 393
 394 If the optional bool *bulk* argument is provided and set to a true value
 395 (i.e ``?bulk=1``), the output contains detailed information about node
 396 groups as a list.
 397
 398 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`
 399
 400 Example::
 401
 402     [
 403       {
 404         "name": "group1",
 405         "node_cnt": 2,
 406         "node_list": [
 407           "node1.example.com",
 408           "node2.example.com"
 409         ],
 410         "uuid": "0d7d407c-262e-49af-881a-6a430034bf43"
 411       },
 412       {
 413         "name": "group2",
 414         "node_cnt": 1,
 415         "node_list": [
 416           "node3.example.com"
 417         ],
 418         "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c"
 419       }
 420     ]
 421
 422 ``POST``
 423 ~~~~~~~~
 424
 425 Creates a node group.
 426
 427 If the optional bool *dry-run* argument is provided, the job will not be
 428 actually executed, only the pre-execution checks will be done.
 429
 430 Returns: a job ID that can be used later for polling.
 431
 432 Body parameters:
 433
 434 .. opcode_params:: OP_GROUP_ADD
 435
 436 Earlier versions used a parameter named ``name`` which, while still
 437 supported, has been renamed to ``group_name``.
 438
 439
 440 ``/2/groups/[group_name]``
 441 ++++++++++++++++++++++++++
 442
 443 Returns information about a node group.
 444
 445 It supports the following commands: ``GET``, ``DELETE``.
 446
 447 ``GET``
 448 ~~~~~~~
 449
 450 Returns information about a node group, similar to the bulk output from
 451 the node group list.
 452
 453 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`
 454
 455 ``DELETE``
 456 ~~~~~~~~~~
 457
 458 Deletes a node group.
 459
 460 It supports the ``dry-run`` argument.
 461
 462
 463 ``/2/groups/[group_name]/modify``
 464 +++++++++++++++++++++++++++++++++
 465
 466 Modifies the parameters of a node group.
 467
 468 Supports the following commands: ``PUT``.
 469
 470 ``PUT``
 471 ~~~~~~~
 472
 473 Returns a job ID.
 474
 475 Body parameters:
 476
 477 .. opcode_params:: OP_GROUP_SET_PARAMS
 478    :exclude: group_name
 479
 480 Job result:
 481
 482 .. opcode_result:: OP_GROUP_SET_PARAMS
 483
 484
 485 ``/2/groups/[group_name]/rename``
 486 +++++++++++++++++++++++++++++++++
 487
 488 Renames a node group.
 489
 490 Supports the following commands: ``PUT``.
 491
 492 ``PUT``
 493 ~~~~~~~
 494
 495 Returns a job ID.
 496
 497 Body parameters:
 498
 499 .. opcode_params:: OP_GROUP_RENAME
 500    :exclude: group_name
 501
 502 Job result:
 503
 504 .. opcode_result:: OP_GROUP_RENAME
 505
 506
 507 ``/2/groups/[group_name]/assign-nodes``
 508 +++++++++++++++++++++++++++++++++++++++
 509
 510 Assigns nodes to a group.
 511
 512 Supports the following commands: ``PUT``.
 513
 514 ``PUT``
 515 ~~~~~~~
 516
 517 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
 518
 519 Body parameters:
 520
 521 .. opcode_params:: OP_GROUP_ASSIGN_NODES
 522    :exclude: group_name, force, dry_run
 523
 524
 525 ``/2/groups/[group_name]/tags``
 526 +++++++++++++++++++++++++++++++
 527
 528 Manages per-nodegroup tags.
 529
 530 Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 531
 532 ``GET``
 533 ~~~~~~~
 534
 535 Returns a list of tags.
 536
 537 Example::
 538
 539     ["tag1", "tag2", "tag3"]
 540
 541 ``PUT``
 542 ~~~~~~~
 543
 544 Add a set of tags.
 545
 546 The request as a list of strings should be ``PUT`` to this URI. The
 547 result will be a job id.
 548
 549 It supports the ``dry-run`` argument.
 550
 551
 552 ``DELETE``
 553 ~~~~~~~~~~
 554
 555 Delete a tag.
 556
 557 In order to delete a set of tags, the DELETE request should be addressed
 558 to URI like::
 559
 560     /tags?tag=[tag]&tag=[tag]
 561
 562 It supports the ``dry-run`` argument.
 563
 564
 565 ``/2/instances``
 566 ++++++++++++++++
 567
 568 The instances resource.
 569
 570 It supports the following commands: ``GET``, ``POST``.
 571
 572 ``GET``
 573 ~~~~~~~
 574
 575 Returns a list of all available instances.
 576
 577 Example::
 578
 579     [
 580       {
 581         "name": "web.example.com",
 582         "uri": "\/instances\/web.example.com"
 583       },
 584       {
 585         "name": "mail.example.com",
 586         "uri": "\/instances\/mail.example.com"
 587       }
 588     ]
 589
 590 If the optional bool *bulk* argument is provided and set to a true value
 591 (i.e ``?bulk=1``), the output contains detailed information about
 592 instances as a list.
 593
 594 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
 595
 596 Example::
 597
 598     [
 599       {
 600          "status": "running",
 601          "disk_usage": 20480,
 602          "nic.bridges": [
 603            "xen-br0"
 604           ],
 605          "name": "web.example.com",
 606          "tags": ["tag1", "tag2"],
 607          "beparams": {
 608            "vcpus": 2,
 609            "memory": 512
 610          },
 611          "disk.sizes": [
 612              20480
 613          ],
 614          "pnode": "node1.example.com",
 615          "nic.macs": ["01:23:45:67:89:01"],
 616          "snodes": ["node2.example.com"],
 617          "disk_template": "drbd",
 618          "admin_state": true,
 619          "os": "debian-etch",
 620          "oper_state": true
 621       },
 622       ...
 623     ]
 624
 625
 626 ``POST``
 627 ~~~~~~~~
 628
 629 Creates an instance.
 630
 631 If the optional bool *dry-run* argument is provided, the job will not be
 632 actually executed, only the pre-execution checks will be done. Query-ing
 633 the job result will return, in both dry-run and normal case, the list of
 634 nodes selected for the instance.
 635
 636 Returns: a job ID that can be used later for polling.
 637
 638 Body parameters:
 639
 640 ``__version__`` (int, required)
 641   Must be ``1`` (older Ganeti versions used a different format for
 642   instance creation requests, version ``0``, but that format is no
 643   longer supported)
 644
 645 .. opcode_params:: OP_INSTANCE_CREATE
 646
 647 Earlier versions used parameters named ``name`` and ``os``. These have
 648 been replaced by ``instance_name`` and ``os_type`` to match the
 649 underlying opcode. The old names can still be used.
 650
 651 Job result:
 652
 653 .. opcode_result:: OP_INSTANCE_CREATE
 654
 655
 656 ``/2/instances/[instance_name]``
 657 ++++++++++++++++++++++++++++++++
 658
 659 Instance-specific resource.
 660
 661 It supports the following commands: ``GET``, ``DELETE``.
 662
 663 ``GET``
 664 ~~~~~~~
 665
 666 Returns information about an instance, similar to the bulk output from
 667 the instance list.
 668
 669 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
 670
 671 ``DELETE``
 672 ~~~~~~~~~~
 673
 674 Deletes an instance.
 675
 676 It supports the ``dry-run`` argument.
 677
 678
 679 ``/2/instances/[instance_name]/info``
 680 +++++++++++++++++++++++++++++++++++++++
 681
 682 It supports the following commands: ``GET``.
 683
 684 ``GET``
 685 ~~~~~~~
 686
 687 Requests detailed information about the instance. An optional parameter,
 688 ``static`` (bool), can be set to return only static information from the
 689 configuration without querying the instance's nodes. The result will be
 690 a job id.
 691
 692
 693 ``/2/instances/[instance_name]/reboot``
 694 +++++++++++++++++++++++++++++++++++++++
 695
 696 Reboots URI for an instance.
 697
 698 It supports the following commands: ``POST``.
 699
 700 ``POST``
 701 ~~~~~~~~
 702
 703 Reboots the instance.
 704
 705 The URI takes optional ``type=soft|hard|full`` and
 706 ``ignore_secondaries=0|1`` parameters.
 707
 708 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
 709 without terminating the hypervisor. ``hard`` means full shutdown
 710 (including terminating the hypervisor process) and startup again.
 711 ``full`` is like ``hard`` but also recreates the configuration from
 712 ground up as if you would have done a ``gnt-instance shutdown`` and
 713 ``gnt-instance start`` on it.
 714
 715 ``ignore_secondaries`` is a bool argument indicating if we start the
 716 instance even if secondary disks are failing.
 717
 718 It supports the ``dry-run`` argument.
 719
 720
 721 ``/2/instances/[instance_name]/shutdown``
 722 +++++++++++++++++++++++++++++++++++++++++
 723
 724 Instance shutdown URI.
 725
 726 It supports the following commands: ``PUT``.
 727
 728 ``PUT``
 729 ~~~~~~~
 730
 731 Shutdowns an instance.
 732
 733 It supports the ``dry-run`` argument.
 734
 735 .. opcode_params:: OP_INSTANCE_SHUTDOWN
 736    :exclude: instance_name, dry_run
 737
 738
 739 ``/2/instances/[instance_name]/startup``
 740 ++++++++++++++++++++++++++++++++++++++++
 741
 742 Instance startup URI.
 743
 744 It supports the following commands: ``PUT``.
 745
 746 ``PUT``
 747 ~~~~~~~
 748
 749 Startup an instance.
 750
 751 The URI takes an optional ``force=1|0`` parameter to start the
 752 instance even if secondary disks are failing.
 753
 754 It supports the ``dry-run`` argument.
 755
 756 ``/2/instances/[instance_name]/reinstall``
 757 ++++++++++++++++++++++++++++++++++++++++++++++
 758
 759 Installs the operating system again.
 760
 761 It supports the following commands: ``POST``.
 762
 763 ``POST``
 764 ~~~~~~~~
 765
 766 Returns a job ID.
 767
 768 Body parameters:
 769
 770 ``os`` (string, required)
 771   Instance operating system.
 772 ``start`` (bool, defaults to true)
 773   Whether to start instance after reinstallation.
 774 ``osparams`` (dict)
 775   Dictionary with (temporary) OS parameters.
 776
 777 For backwards compatbility, this resource also takes the query
 778 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
 779 clients should use the body parameters.
 780
 781
 782 ``/2/instances/[instance_name]/replace-disks``
 783 ++++++++++++++++++++++++++++++++++++++++++++++
 784
 785 Replaces disks on an instance.
 786
 787 It supports the following commands: ``POST``.
 788
 789 ``POST``
 790 ~~~~~~~~
 791
 792 Takes the parameters ``mode`` (one of ``replace_on_primary``,
 793 ``replace_on_secondary``, ``replace_new_secondary`` or
 794 ``replace_auto``), ``disks`` (comma separated list of disk indexes),
 795 ``remote_node`` and ``iallocator``.
 796
 797 Either ``remote_node`` or ``iallocator`` needs to be defined when using
 798 ``mode=replace_new_secondary``.
 799
 800 ``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
 801 the broken disk(s) on its own and replacing it.
 802
 803
 804 ``/2/instances/[instance_name]/activate-disks``
 805 +++++++++++++++++++++++++++++++++++++++++++++++
 806
 807 Activate disks on an instance.
 808
 809 It supports the following commands: ``PUT``.
 810
 811 ``PUT``
 812 ~~~~~~~
 813
 814 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 815 size (useful for forcing activation when recorded size is wrong).
 816
 817
 818 ``/2/instances/[instance_name]/deactivate-disks``
 819 +++++++++++++++++++++++++++++++++++++++++++++++++
 820
 821 Deactivate disks on an instance.
 822
 823 It supports the following commands: ``PUT``.
 824
 825 ``PUT``
 826 ~~~~~~~
 827
 828 Takes no parameters.
 829
 830
 831 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
 832 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 833
 834 Grows one disk of an instance.
 835
 836 Supports the following commands: ``POST``.
 837
 838 ``POST``
 839 ~~~~~~~~
 840
 841 Returns a job ID.
 842
 843 Body parameters:
 844
 845 .. opcode_params:: OP_INSTANCE_GROW_DISK
 846    :exclude: instance_name, disk
 847
 848
 849 ``/2/instances/[instance_name]/prepare-export``
 850 +++++++++++++++++++++++++++++++++++++++++++++++++
 851
 852 Prepares an export of an instance.
 853
 854 It supports the following commands: ``PUT``.
 855
 856 ``PUT``
 857 ~~~~~~~
 858
 859 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
 860
 861
 862 ``/2/instances/[instance_name]/export``
 863 +++++++++++++++++++++++++++++++++++++++++++++++++
 864
 865 Exports an instance.
 866
 867 It supports the following commands: ``PUT``.
 868
 869 ``PUT``
 870 ~~~~~~~
 871
 872 Returns a job ID.
 873
 874 Body parameters:
 875
 876 .. opcode_params:: OP_BACKUP_EXPORT
 877    :exclude: instance_name
 878    :alias: target_node=destination
 879
 880
 881 ``/2/instances/[instance_name]/migrate``
 882 ++++++++++++++++++++++++++++++++++++++++
 883
 884 Migrates an instance.
 885
 886 Supports the following commands: ``PUT``.
 887
 888 ``PUT``
 889 ~~~~~~~
 890
 891 Returns a job ID.
 892
 893 Body parameters:
 894
 895 .. opcode_params:: OP_INSTANCE_MIGRATE
 896    :exclude: instance_name, live
 897
 898
 899 ``/2/instances/[instance_name]/failover``
 900 +++++++++++++++++++++++++++++++++++++++++
 901
 902 Does a failover of an instance.
 903
 904 Supports the following commands: ``PUT``.
 905
 906 ``PUT``
 907 ~~~~~~~
 908
 909 Returns a job ID.
 910
 911 Body parameters:
 912
 913 .. opcode_params:: OP_INSTANCE_FAILOVER
 914    :exclude: instance_name
 915
 916
 917 ``/2/instances/[instance_name]/rename``
 918 ++++++++++++++++++++++++++++++++++++++++
 919
 920 Renames an instance.
 921
 922 Supports the following commands: ``PUT``.
 923
 924 ``PUT``
 925 ~~~~~~~
 926
 927 Returns a job ID.
 928
 929 Body parameters:
 930
 931 .. opcode_params:: OP_INSTANCE_RENAME
 932    :exclude: instance_name
 933
 934 Job result:
 935
 936 .. opcode_result:: OP_INSTANCE_RENAME
 937
 938
 939 ``/2/instances/[instance_name]/modify``
 940 ++++++++++++++++++++++++++++++++++++++++
 941
 942 Modifies an instance.
 943
 944 Supports the following commands: ``PUT``.
 945
 946 ``PUT``
 947 ~~~~~~~
 948
 949 Returns a job ID.
 950
 951 Body parameters:
 952
 953 .. opcode_params:: OP_INSTANCE_SET_PARAMS
 954    :exclude: instance_name
 955
 956 Job result:
 957
 958 .. opcode_result:: OP_INSTANCE_SET_PARAMS
 959
 960
 961 ``/2/instances/[instance_name]/console``
 962 ++++++++++++++++++++++++++++++++++++++++
 963
 964 Request information for connecting to instance's console.
 965
 966 Supports the following commands: ``GET``.
 967
 968 ``GET``
 969 ~~~~~~~
 970
 971 Returns a dictionary containing information about the instance's
 972 console. Contained keys:
 973
 974 .. pyassert::
 975
 976    constants.CONS_ALL == frozenset([
 977      constants.CONS_MESSAGE,
 978      constants.CONS_SSH,
 979      constants.CONS_VNC,
 980      ])
 981
 982 ``instance``
 983   Instance name.
 984 ``kind``
 985   Console type, one of :pyeval:`constants.CONS_SSH`,
 986   :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_MESSAGE`.
 987 ``message``
 988   Message to display (:pyeval:`constants.CONS_MESSAGE` type only).
 989 ``host``
 990   Host to connect to (:pyeval:`constants.CONS_SSH` and
 991   :pyeval:`constants.CONS_VNC` only).
 992 ``port``
 993   TCP port to connect to (:pyeval:`constants.CONS_VNC` only).
 994 ``user``
 995   Username to use (:pyeval:`constants.CONS_SSH` only).
 996 ``command``
 997   Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
 998 ``display``
 999   VNC display number (:pyeval:`constants.CONS_VNC` only).
1000
1001
1002 ``/2/instances/[instance_name]/tags``
1003 +++++++++++++++++++++++++++++++++++++
1004
1005 Manages per-instance tags.
1006
1007 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1008
1009 ``GET``
1010 ~~~~~~~
1011
1012 Returns a list of tags.
1013
1014 Example::
1015
1016     ["tag1", "tag2", "tag3"]
1017
1018 ``PUT``
1019 ~~~~~~~
1020
1021 Add a set of tags.
1022
1023 The request as a list of strings should be ``PUT`` to this URI. The
1024 result will be a job id.
1025
1026 It supports the ``dry-run`` argument.
1027
1028
1029 ``DELETE``
1030 ~~~~~~~~~~
1031
1032 Delete a tag.
1033
1034 In order to delete a set of tags, the DELETE request should be addressed
1035 to URI like::
1036
1037     /tags?tag=[tag]&tag=[tag]
1038
1039 It supports the ``dry-run`` argument.
1040
1041
1042 ``/2/jobs``
1043 +++++++++++
1044
1045 The ``/2/jobs`` resource.
1046
1047 It supports the following commands: ``GET``.
1048
1049 ``GET``
1050 ~~~~~~~
1051
1052 Returns a dictionary of jobs.
1053
1054 Returns: a dictionary with jobs id and uri.
1055
1056 If the optional bool *bulk* argument is provided and set to a true value
1057 (i.e. ``?bulk=1``), the output contains detailed information about jobs
1058 as a list.
1059
1060 Returned fields for bulk requests (unlike other bulk requests, these
1061 fields are not the same as for per-job requests):
1062 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`
1063
1064 ``/2/jobs/[job_id]``
1065 ++++++++++++++++++++
1066
1067
1068 Individual job URI.
1069
1070 It supports the following commands: ``GET``, ``DELETE``.
1071
1072 ``GET``
1073 ~~~~~~~
1074
1075 Returns a dictionary with job parameters, containing the fields
1076 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.
1077
1078 The result includes:
1079
1080 - id: job ID as a number
1081 - status: current job status as a string
1082 - ops: involved OpCodes as a list of dictionaries for each opcodes in
1083   the job
1084 - opstatus: OpCodes status as a list
1085 - opresult: OpCodes results as a list
1086
1087 For a successful opcode, the ``opresult`` field corresponding to it will
1088 contain the raw result from its :term:`LogicalUnit`. In case an opcode
1089 has failed, its element in the opresult list will be a list of two
1090 elements:
1091
1092 - first element the error type (the Ganeti internal error name)
1093 - second element a list of either one or two elements:
1094
1095   - the first element is the textual error description
1096   - the second element, if any, will hold an error classification
1097
1098 The error classification is most useful for the ``OpPrereqError``
1099 error type - these errors happen before the OpCode has started
1100 executing, so it's possible to retry the OpCode without side
1101 effects. But whether it make sense to retry depends on the error
1102 classification:
1103
1104 .. pyassert::
1105
1106    errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
1107      errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
1108      errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
1109      errors.ECODE_ENVIRON])
1110
1111 :pyeval:`errors.ECODE_RESOLVER`
1112   Resolver errors. This usually means that a name doesn't exist in DNS,
1113   so if it's a case of slow DNS propagation the operation can be retried
1114   later.
1115
1116 :pyeval:`errors.ECODE_NORES`
1117   Not enough resources (iallocator failure, disk space, memory,
1118   etc.). If the resources on the cluster increase, the operation might
1119   succeed.
1120
1121 :pyeval:`errors.ECODE_INVAL`
1122   Wrong arguments (at syntax level). The operation will not ever be
1123   accepted unless the arguments change.
1124
1125 :pyeval:`errors.ECODE_STATE`
1126   Wrong entity state. For example, live migration has been requested for
1127   a down instance, or instance creation on an offline node. The
1128   operation can be retried once the resource has changed state.
1129
1130 :pyeval:`errors.ECODE_NOENT`
1131   Entity not found. For example, information has been requested for an
1132   unknown instance.
1133
1134 :pyeval:`errors.ECODE_EXISTS`
1135   Entity already exists. For example, instance creation has been
1136   requested for an already-existing instance.
1137
1138 :pyeval:`errors.ECODE_NOTUNIQUE`
1139   Resource not unique (e.g. MAC or IP duplication).
1140
1141 :pyeval:`errors.ECODE_FAULT`
1142   Internal cluster error. For example, a node is unreachable but not set
1143   offline, or the ganeti node daemons are not working, etc. A
1144   ``gnt-cluster verify`` should be run.
1145
1146 :pyeval:`errors.ECODE_ENVIRON`
1147   Environment error (e.g. node disk error). A ``gnt-cluster verify``
1148   should be run.
1149
1150 Note that in the above list, by entity we refer to a node or instance,
1151 while by a resource we refer to an instance's disk, or NIC, etc.
1152
1153
1154 ``DELETE``
1155 ~~~~~~~~~~
1156
1157 Cancel a not-yet-started job.
1158
1159
1160 ``/2/jobs/[job_id]/wait``
1161 +++++++++++++++++++++++++
1162
1163 ``GET``
1164 ~~~~~~~
1165
1166 Waits for changes on a job. Takes the following body parameters in a
1167 dict:
1168
1169 ``fields``
1170   The job fields on which to watch for changes.
1171
1172 ``previous_job_info``
1173   Previously received field values or None if not yet available.
1174
1175 ``previous_log_serial``
1176   Highest log serial number received so far or None if not yet
1177   available.
1178
1179 Returns None if no changes have been detected and a dict with two keys,
1180 ``job_info`` and ``log_entries`` otherwise.
1181
1182
1183 ``/2/nodes``
1184 ++++++++++++
1185
1186 Nodes resource.
1187
1188 It supports the following commands: ``GET``.
1189
1190 ``GET``
1191 ~~~~~~~
1192
1193 Returns a list of all nodes.
1194
1195 Example::
1196
1197     [
1198       {
1199         "id": "node1.example.com",
1200         "uri": "\/nodes\/node1.example.com"
1201       },
1202       {
1203         "id": "node2.example.com",
1204         "uri": "\/nodes\/node2.example.com"
1205       }
1206     ]
1207
1208 If the optional bool *bulk* argument is provided and set to a true value
1209 (i.e ``?bulk=1``), the output contains detailed information about nodes
1210 as a list.
1211
1212 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
1213
1214 Example::
1215
1216     [
1217       {
1218         "pinst_cnt": 1,
1219         "mfree": 31280,
1220         "mtotal": 32763,
1221         "name": "www.example.com",
1222         "tags": [],
1223         "mnode": 512,
1224         "dtotal": 5246208,
1225         "sinst_cnt": 2,
1226         "dfree": 5171712,
1227         "offline": false
1228       },
1229       ...
1230     ]
1231
1232 ``/2/nodes/[node_name]``
1233 +++++++++++++++++++++++++++++++++
1234
1235 Returns information about a node.
1236
1237 It supports the following commands: ``GET``.
1238
1239 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
1240
1241 ``/2/nodes/[node_name]/evacuate``
1242 +++++++++++++++++++++++++++++++++
1243
1244 Evacuates instances off a node.
1245
1246 It supports the following commands: ``POST``.
1247
1248 ``POST``
1249 ~~~~~~~~
1250
1251 Returns a job ID. The result of the job will contain the IDs of the
1252 individual jobs submitted to evacuate the node.
1253
1254 Body parameters:
1255
1256 .. opcode_params:: OP_NODE_EVACUATE
1257    :exclude: nodes
1258
1259 Up to and including Ganeti 2.4 query arguments were used. Those are no
1260 longer supported. The new request can be detected by the presence of the
1261 :pyeval:`rlib2._NODE_EVAC_RES1` feature string.
1262
1263 Job result:
1264
1265 .. opcode_result:: OP_NODE_EVACUATE
1266
1267
1268 ``/2/nodes/[node_name]/migrate``
1269 +++++++++++++++++++++++++++++++++
1270
1271 Migrates all primary instances from a node.
1272
1273 It supports the following commands: ``POST``.
1274
1275 ``POST``
1276 ~~~~~~~~
1277
1278 If no mode is explicitly specified, each instances' hypervisor default
1279 migration mode will be used. Body parameters:
1280
1281 .. opcode_params:: OP_NODE_MIGRATE
1282    :exclude: node_name
1283
1284 The query arguments used up to and including Ganeti 2.4 are deprecated
1285 and should no longer be used. The new request format can be detected by
1286 the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
1287
1288
1289 ``/2/nodes/[node_name]/role``
1290 +++++++++++++++++++++++++++++
1291
1292 Manages node role.
1293
1294 It supports the following commands: ``GET``, ``PUT``.
1295
1296 The role is always one of the following:
1297
1298   - drained
1299   - master-candidate
1300   - offline
1301   - regular
1302
1303 Note that the 'master' role is a special, and currently it can't be
1304 modified via RAPI, only via the command line (``gnt-cluster
1305 master-failover``).
1306
1307 ``GET``
1308 ~~~~~~~
1309
1310 Returns the current node role.
1311
1312 Example::
1313
1314     "master-candidate"
1315
1316 ``PUT``
1317 ~~~~~~~
1318
1319 Change the node role.
1320
1321 The request is a string which should be PUT to this URI. The result will
1322 be a job id.
1323
1324 It supports the bool ``force`` argument.
1325
1326 ``/2/nodes/[node_name]/storage``
1327 ++++++++++++++++++++++++++++++++
1328
1329 Manages storage units on the node.
1330
1331 ``GET``
1332 ~~~~~~~
1333
1334 .. pyassert::
1335
1336    constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
1337                                          constants.ST_LVM_PV,
1338                                          constants.ST_LVM_VG])
1339
1340 Requests a list of storage units on a node. Requires the parameters
1341 ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1342 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
1343 ``output_fields``. The result will be a job id, using which the result
1344 can be retrieved.
1345
1346 ``/2/nodes/[node_name]/storage/modify``
1347 +++++++++++++++++++++++++++++++++++++++
1348
1349 Modifies storage units on the node.
1350
1351 ``PUT``
1352 ~~~~~~~
1353
1354 Modifies parameters of storage units on the node. Requires the
1355 parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1356 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
1357 and ``name`` (name of the storage unit).  Parameters can be passed
1358 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
1359 is supported. The result will be a job id.
1360
1361 ``/2/nodes/[node_name]/storage/repair``
1362 +++++++++++++++++++++++++++++++++++++++
1363
1364 Repairs a storage unit on the node.
1365
1366 ``PUT``
1367 ~~~~~~~
1368
1369 .. pyassert::
1370
1371    constants.VALID_STORAGE_OPERATIONS == {
1372     constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
1373     }
1374
1375 Repairs a storage unit on the node. Requires the parameters
1376 ``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
1377 repaired) and ``name`` (name of the storage unit). The result will be a
1378 job id.
1379
1380 ``/2/nodes/[node_name]/tags``
1381 +++++++++++++++++++++++++++++
1382
1383 Manages per-node tags.
1384
1385 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1386
1387 ``GET``
1388 ~~~~~~~
1389
1390 Returns a list of tags.
1391
1392 Example::
1393
1394     ["tag1", "tag2", "tag3"]
1395
1396 ``PUT``
1397 ~~~~~~~
1398
1399 Add a set of tags.
1400
1401 The request as a list of strings should be PUT to this URI. The result
1402 will be a job id.
1403
1404 It supports the ``dry-run`` argument.
1405
1406 ``DELETE``
1407 ~~~~~~~~~~
1408
1409 Deletes tags.
1410
1411 In order to delete a set of tags, the DELETE request should be addressed
1412 to URI like::
1413
1414     /tags?tag=[tag]&tag=[tag]
1415
1416 It supports the ``dry-run`` argument.
1417
1418
1419 ``/2/query/[resource]``
1420 +++++++++++++++++++++++
1421
1422 Requests resource information. Available fields can be found in man
1423 pages and using ``/2/query/[resource]/fields``. The resource is one of
1424 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
1425 design document <design-query2>` for more details.
1426
1427 Supports the following commands: ``GET``, ``PUT``.
1428
1429 ``GET``
1430 ~~~~~~~
1431
1432 Returns list of included fields and actual data. Takes a query parameter
1433 named "fields", containing a comma-separated list of field names. Does
1434 not support filtering.
1435
1436 ``PUT``
1437 ~~~~~~~
1438
1439 Returns list of included fields and actual data. The list of requested
1440 fields can either be given as the query parameter "fields" or as a body
1441 parameter with the same name. The optional body parameter "filter" can
1442 be given and must be either ``null`` or a list containing filter
1443 operators.
1444
1445
1446 ``/2/query/[resource]/fields``
1447 ++++++++++++++++++++++++++++++
1448
1449 Request list of available fields for a resource. The resource is one of
1450 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
1451 :doc:`query2 design document <design-query2>` for more details.
1452
1453 Supports the following commands: ``GET``.
1454
1455 ``GET``
1456 ~~~~~~~
1457
1458 Returns a list of field descriptions for available fields. Takes an
1459 optional query parameter named "fields", containing a comma-separated
1460 list of field names.
1461
1462
1463 ``/2/os``
1464 +++++++++
1465
1466 OS resource.
1467
1468 It supports the following commands: ``GET``.
1469
1470 ``GET``
1471 ~~~~~~~
1472
1473 Return a list of all OSes.
1474
1475 Can return error 500 in case of a problem. Since this is a costly
1476 operation for Ganeti 2.0, it is not recommended to execute it too often.
1477
1478 Example::
1479
1480     ["debian-etch"]
1481
1482 ``/2/tags``
1483 +++++++++++
1484
1485 Manages cluster tags.
1486
1487 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1488
1489 ``GET``
1490 ~~~~~~~
1491
1492 Returns the cluster tags.
1493
1494 Example::
1495
1496     ["tag1", "tag2", "tag3"]
1497
1498 ``PUT``
1499 ~~~~~~~
1500
1501 Adds a set of tags.
1502
1503 The request as a list of strings should be PUT to this URI. The result
1504 will be a job id.
1505
1506 It supports the ``dry-run`` argument.
1507
1508
1509 ``DELETE``
1510 ~~~~~~~~~~
1511
1512 Deletes tags.
1513
1514 In order to delete a set of tags, the DELETE request should be addressed
1515 to URI like::
1516
1517     /tags?tag=[tag]&tag=[tag]
1518
1519 It supports the ``dry-run`` argument.
1520
1521
1522 ``/version``
1523 ++++++++++++
1524
1525 The version resource.
1526
1527 This resource should be used to determine the remote API version and to
1528 adapt clients accordingly.
1529
1530 It supports the following commands: ``GET``.
1531
1532 ``GET``
1533 ~~~~~~~
1534
1535 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1536 returns ``2``.
1537
1538 .. vim: set textwidth=72 :
1539 .. Local Variables:
1540 .. mode: rst
1541 .. fill-column: 72
1542 .. End: