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