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