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