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