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