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