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
  57    and 3.3. The reason for using it over another algorithm is forward
  58    compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
  59    authentication in the future, the same hash could be used.
  60    In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
  61    API``, can only be changed by modifying the source code.
  62
  63
  64 Protocol
  65 --------
  66
  67 The protocol used is JSON_ over HTTP designed after the REST_ principle.
  68 HTTP Basic authentication as per :rfc:`2617` is supported.
  69
  70 .. _JSON: http://www.json.org/
  71 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
  72
  73 HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
  74 header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
  75 (HTTP/1.1), section 7.2.1).
  76
  77
  78 A note on JSON as used by RAPI
  79 ++++++++++++++++++++++++++++++
  80
  81 JSON_ as used by Ganeti RAPI does not conform to the specification in
  82 :rfc:`4627`. Section 2 defines a JSON text to be either an object
  83 (``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
  84 of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
  85 some requests or responses. Changing this now would likely break
  86 existing clients and cause a lot of trouble.
  87
  88 .. highlight:: ruby
  89
  90 Unlike Python's `JSON encoder and decoder
  91 <http://docs.python.org/library/json.html>`_, other programming
  92 languages or libraries may only provide a strict implementation, not
  93 allowing plain values. For those, responses can usually be wrapped in an
  94 array whose first element is then used, e.g. the response ``"1234"``
  95 becomes ``["1234"]``. This works equally well for more complex values.
  96 Example in Ruby::
  97
  98   require "json"
  99
 100   # Insert code to get response here
 101   response = "\"1234\""
 102
 103   decoded = JSON.parse("[#{response}]").first
 104
 105 Short of modifying the encoder to allow encoding to a less strict
 106 format, requests will have to be formatted by hand. Newer RAPI requests
 107 already use a dictionary as their input data and shouldn't cause any
 108 problems.
 109
 110
 111 PUT or POST?
 112 ------------
 113
 114 According to :rfc:`2616` the main difference between PUT and POST is
 115 that POST can create new resources but PUT can only create the resource
 116 the URI was pointing to on the PUT request.
 117
 118 Unfortunately, due to historic reasons, the Ganeti RAPI library is not
 119 consistent with this usage, so just use the methods as documented below
 120 for each resource.
 121
 122 For more details have a look in the source code at
 123 ``lib/rapi/rlib2.py``.
 124
 125
 126 Generic parameter types
 127 -----------------------
 128
 129 A few generic refered parameter types and the values they allow.
 130
 131 ``bool``
 132 ++++++++
 133
 134 A boolean option will accept ``1`` or ``0`` as numbers but not
 135 i.e. ``True`` or ``False``.
 136
 137 Generic parameters
 138 ------------------
 139
 140 A few parameter mean the same thing across all resources which implement
 141 it.
 142
 143 ``bulk``
 144 ++++++++
 145
 146 Bulk-mode means that for the resources which usually return just a list
 147 of child resources (e.g. ``/2/instances`` which returns just instance
 148 names), the output will instead contain detailed data for all these
 149 subresources. This is more efficient than query-ing the sub-resources
 150 themselves.
 151
 152 ``dry-run``
 153 +++++++++++
 154
 155 The boolean *dry-run* argument, if provided and set, signals to Ganeti
 156 that the job should not be executed, only the pre-execution checks will
 157 be done.
 158
 159 This is useful in trying to determine (without guarantees though, as in
 160 the meantime the cluster state could have changed) if the operation is
 161 likely to succeed or at least start executing.
 162
 163 ``force``
 164 +++++++++++
 165
 166 Force operation to continue even if it will cause the cluster to become
 167 inconsistent (e.g. because there are not enough master candidates).
 168
 169 Parameter details
 170 -----------------
 171
 172 Some parameters are not straight forward, so we describe them in details
 173 here.
 174
 175 .. _rapi-ipolicy:
 176
 177 ``ipolicy``
 178 +++++++++++
 179
 180 The instance policy specification is a dict with the following fields:
 181
 182 .. pyassert::
 183
 184   constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN,
 185                                      constants.ISPECS_MAX,
 186                                      constants.ISPECS_STD,
 187                                      constants.IPOLICY_DTS,
 188                                      constants.IPOLICY_VCPU_RATIO,
 189                                      constants.IPOLICY_SPINDLE_RATIO])
 190
 191
 192 .. pyassert::
 193
 194   (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
 195    set([constants.ISPEC_MEM_SIZE,
 196         constants.ISPEC_DISK_SIZE,
 197         constants.ISPEC_DISK_COUNT,
 198         constants.ISPEC_CPU_COUNT,
 199         constants.ISPEC_NIC_COUNT,
 200         constants.ISPEC_SPINDLE_USE]))
 201
 202 .. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
 203 .. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
 204 .. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
 205
 206
 207 |ispec-min|, |ispec-max|, |ispec-std|
 208   A sub- `dict` with the following fields, which sets the limit and standard
 209   values of the instances:
 210
 211   :pyeval:`constants.ISPEC_MEM_SIZE`
 212     The size in MiB of the memory used
 213   :pyeval:`constants.ISPEC_DISK_SIZE`
 214     The size in MiB of the disk used
 215   :pyeval:`constants.ISPEC_DISK_COUNT`
 216     The numbers of disks used
 217   :pyeval:`constants.ISPEC_CPU_COUNT`
 218     The numbers of cpus used
 219   :pyeval:`constants.ISPEC_NIC_COUNT`
 220     The numbers of nics used
 221   :pyeval:`constants.ISPEC_SPINDLE_USE`
 222     The numbers of virtual disk spindles used by this instance. They are
 223     not real in the sense of actual HDD spindles, but useful for
 224     accounting the spindle usage on the residing node
 225 :pyeval:`constants.IPOLICY_DTS`
 226   A `list` of disk templates allowed for instances using this policy
 227 :pyeval:`constants.IPOLICY_VCPU_RATIO`
 228   Maximum ratio of virtual to physical CPUs (`float`)
 229 :pyeval:`constants.IPOLICY_SPINDLE_RATIO`
 230   Maximum ratio of instances to their node's ``spindle_count`` (`float`)
 231
 232 Usage examples
 233 --------------
 234
 235 You can access the API using your favorite programming language as long
 236 as it supports network connections.
 237
 238 Ganeti RAPI client
 239 ++++++++++++++++++
 240
 241 Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.
 242
 243 Shell
 244 +++++
 245
 246 .. highlight:: sh
 247
 248 Using wget::
 249
 250    wget -q -O - https://CLUSTERNAME:5080/2/info
 251
 252 or curl::
 253
 254   curl https://CLUSTERNAME:5080/2/info
 255
 256
 257 Python
 258 ++++++
 259
 260 .. highlight:: python
 261
 262 ::
 263
 264   import urllib2
 265   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
 266   print f.read()
 267
 268
 269 JavaScript
 270 ++++++++++
 271
 272 .. warning:: While it's possible to use JavaScript, it poses several
 273    potential problems, including browser blocking request due to
 274    non-standard ports or different domain names. Fetching the data on
 275    the webserver is easier.
 276
 277 .. highlight:: javascript
 278
 279 ::
 280
 281   var url = 'https://CLUSTERNAME:5080/2/info';
 282   var info;
 283   var xmlreq = new XMLHttpRequest();
 284   xmlreq.onreadystatechange = function () {
 285     if (xmlreq.readyState != 4) return;
 286     if (xmlreq.status == 200) {
 287       info = eval("(" + xmlreq.responseText + ")");
 288       alert(info);
 289     } else {
 290       alert('Error fetching cluster info');
 291     }
 292     xmlreq = null;
 293   };
 294   xmlreq.open('GET', url, true);
 295   xmlreq.send(null);
 296
 297 Resources
 298 ---------
 299
 300 .. highlight:: javascript
 301
 302 ``/``
 303 +++++
 304
 305 The root resource. Has no function, but for legacy reasons the ``GET``
 306 method is supported.
 307
 308 ``/2``
 309 ++++++
 310
 311 Has no function, but for legacy reasons the ``GET`` method is supported.
 312
 313 ``/2/info``
 314 +++++++++++
 315
 316 Cluster information resource.
 317
 318 It supports the following commands: ``GET``.
 319
 320 ``GET``
 321 ~~~~~~~
 322
 323 Returns cluster information.
 324
 325 Example::
 326
 327   {
 328     "config_version": 2000000,
 329     "name": "cluster",
 330     "software_version": "2.0.0~beta2",
 331     "os_api_version": 10,
 332     "export_version": 0,
 333     "candidate_pool_size": 10,
 334     "enabled_hypervisors": [
 335       "fake"
 336     ],
 337     "hvparams": {
 338       "fake": {}
 339      },
 340     "default_hypervisor": "fake",
 341     "master": "node1.example.com",
 342     "architecture": [
 343       "64bit",
 344       "x86_64"
 345     ],
 346     "protocol_version": 20,
 347     "beparams": {
 348       "default": {
 349         "auto_balance": true,
 350         "vcpus": 1,
 351         "memory": 128
 352        }
 353       }
 354     }
 355
 356
 357 ``/2/redistribute-config``
 358 ++++++++++++++++++++++++++
 359
 360 Redistribute configuration to all nodes.
 361
 362 It supports the following commands: ``PUT``.
 363
 364 ``PUT``
 365 ~~~~~~~
 366
 367 Redistribute configuration to all nodes. The result will be a job id.
 368
 369 Job result:
 370
 371 .. opcode_result:: OP_CLUSTER_REDIST_CONF
 372
 373
 374 ``/2/features``
 375 +++++++++++++++
 376
 377 ``GET``
 378 ~~~~~~~
 379
 380 Returns a list of features supported by the RAPI server. Available
 381 features:
 382
 383 .. pyassert::
 384
 385   rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
 386                              rlib2._INST_REINSTALL_REQV1,
 387                              rlib2._NODE_MIGRATE_REQV1,
 388                              rlib2._NODE_EVAC_RES1])
 389
 390 :pyeval:`rlib2._INST_CREATE_REQV1`
 391   Instance creation request data version 1 supported
 392 :pyeval:`rlib2._INST_REINSTALL_REQV1`
 393   Instance reinstall supports body parameters
 394 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
 395   Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
 396   request body parameters
 397 :pyeval:`rlib2._NODE_EVAC_RES1`
 398   Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
 399   a new-style result (see resource description)
 400
 401
 402 ``/2/modify``
 403 ++++++++++++++++++++++++++++++++++++++++
 404
 405 Modifies cluster parameters.
 406
 407 Supports the following commands: ``PUT``.
 408
 409 ``PUT``
 410 ~~~~~~~
 411
 412 Returns a job ID.
 413
 414 Body parameters:
 415
 416 .. opcode_params:: OP_CLUSTER_SET_PARAMS
 417
 418 Job result:
 419
 420 .. opcode_result:: OP_CLUSTER_SET_PARAMS
 421
 422
 423 ``/2/groups``
 424 +++++++++++++
 425
 426 The groups resource.
 427
 428 It supports the following commands: ``GET``, ``POST``.
 429
 430 ``GET``
 431 ~~~~~~~
 432
 433 Returns a list of all existing node groups.
 434
 435 Example::
 436
 437     [
 438       {
 439         "name": "group1",
 440         "uri": "\/2\/groups\/group1"
 441       },
 442       {
 443         "name": "group2",
 444         "uri": "\/2\/groups\/group2"
 445       }
 446     ]
 447
 448 If the optional bool *bulk* argument is provided and set to a true value
 449 (i.e ``?bulk=1``), the output contains detailed information about node
 450 groups as a list.
 451
 452 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
 453
 454 Example::
 455
 456     [
 457       {
 458         "name": "group1",
 459         "node_cnt": 2,
 460         "node_list": [
 461           "node1.example.com",
 462           "node2.example.com"
 463         ],
 464         "uuid": "0d7d407c-262e-49af-881a-6a430034bf43"
 465       },
 466       {
 467         "name": "group2",
 468         "node_cnt": 1,
 469         "node_list": [
 470           "node3.example.com"
 471         ],
 472         "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c"
 473       }
 474     ]
 475
 476 ``POST``
 477 ~~~~~~~~
 478
 479 Creates a node group.
 480
 481 If the optional bool *dry-run* argument is provided, the job will not be
 482 actually executed, only the pre-execution checks will be done.
 483
 484 Returns: a job ID that can be used later for polling.
 485
 486 Body parameters:
 487
 488 .. opcode_params:: OP_GROUP_ADD
 489
 490 Earlier versions used a parameter named ``name`` which, while still
 491 supported, has been renamed to ``group_name``.
 492
 493 Job result:
 494
 495 .. opcode_result:: OP_GROUP_ADD
 496
 497
 498 ``/2/groups/[group_name]``
 499 ++++++++++++++++++++++++++
 500
 501 Returns information about a node group.
 502
 503 It supports the following commands: ``GET``, ``DELETE``.
 504
 505 ``GET``
 506 ~~~~~~~
 507
 508 Returns information about a node group, similar to the bulk output from
 509 the node group list.
 510
 511 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
 512
 513 ``DELETE``
 514 ~~~~~~~~~~
 515
 516 Deletes a node group.
 517
 518 It supports the ``dry-run`` argument.
 519
 520 Job result:
 521
 522 .. opcode_result:: OP_GROUP_REMOVE
 523
 524
 525 ``/2/groups/[group_name]/modify``
 526 +++++++++++++++++++++++++++++++++
 527
 528 Modifies the parameters of a node group.
 529
 530 Supports the following commands: ``PUT``.
 531
 532 ``PUT``
 533 ~~~~~~~
 534
 535 Returns a job ID.
 536
 537 Body parameters:
 538
 539 .. opcode_params:: OP_GROUP_SET_PARAMS
 540    :exclude: group_name
 541
 542 Job result:
 543
 544 .. opcode_result:: OP_GROUP_SET_PARAMS
 545
 546
 547 ``/2/groups/[group_name]/rename``
 548 +++++++++++++++++++++++++++++++++
 549
 550 Renames a node group.
 551
 552 Supports the following commands: ``PUT``.
 553
 554 ``PUT``
 555 ~~~~~~~
 556
 557 Returns a job ID.
 558
 559 Body parameters:
 560
 561 .. opcode_params:: OP_GROUP_RENAME
 562    :exclude: group_name
 563
 564 Job result:
 565
 566 .. opcode_result:: OP_GROUP_RENAME
 567
 568
 569 ``/2/groups/[group_name]/assign-nodes``
 570 +++++++++++++++++++++++++++++++++++++++
 571
 572 Assigns nodes to a group.
 573
 574 Supports the following commands: ``PUT``.
 575
 576 ``PUT``
 577 ~~~~~~~
 578
 579 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
 580
 581 Body parameters:
 582
 583 .. opcode_params:: OP_GROUP_ASSIGN_NODES
 584    :exclude: group_name, force, dry_run
 585
 586 Job result:
 587
 588 .. opcode_result:: OP_GROUP_ASSIGN_NODES
 589
 590
 591 ``/2/groups/[group_name]/tags``
 592 +++++++++++++++++++++++++++++++
 593
 594 Manages per-nodegroup tags.
 595
 596 Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 597
 598 ``GET``
 599 ~~~~~~~
 600
 601 Returns a list of tags.
 602
 603 Example::
 604
 605     ["tag1", "tag2", "tag3"]
 606
 607 ``PUT``
 608 ~~~~~~~
 609
 610 Add a set of tags.
 611
 612 The request as a list of strings should be ``PUT`` to this URI. The
 613 result will be a job id.
 614
 615 It supports the ``dry-run`` argument.
 616
 617
 618 ``DELETE``
 619 ~~~~~~~~~~
 620
 621 Delete a tag.
 622
 623 In order to delete a set of tags, the DELETE request should be addressed
 624 to URI like::
 625
 626     /tags?tag=[tag]&tag=[tag]
 627
 628 It supports the ``dry-run`` argument.
 629
 630
 631 ``/2/instances-multi-alloc``
 632 ++++++++++++++++++++++++++++
 633
 634 Tries to allocate multiple instances.
 635
 636 It supports the following commands: ``POST``
 637
 638 ``POST``
 639 ~~~~~~~~
 640
 641 The parameters:
 642
 643 .. opcode_params:: OP_INSTANCE_MULTI_ALLOC
 644
 645 Job result:
 646
 647 .. opcode_result:: OP_INSTANCE_MULTI_ALLOC
 648
 649
 650 ``/2/instances``
 651 ++++++++++++++++
 652
 653 The instances resource.
 654
 655 It supports the following commands: ``GET``, ``POST``.
 656
 657 ``GET``
 658 ~~~~~~~
 659
 660 Returns a list of all available instances.
 661
 662 Example::
 663
 664     [
 665       {
 666         "name": "web.example.com",
 667         "uri": "\/instances\/web.example.com"
 668       },
 669       {
 670         "name": "mail.example.com",
 671         "uri": "\/instances\/mail.example.com"
 672       }
 673     ]
 674
 675 If the optional bool *bulk* argument is provided and set to a true value
 676 (i.e ``?bulk=1``), the output contains detailed information about
 677 instances as a list.
 678
 679 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
 680
 681 Example::
 682
 683     [
 684       {
 685          "status": "running",
 686          "disk_usage": 20480,
 687          "nic.bridges": [
 688            "xen-br0"
 689           ],
 690          "name": "web.example.com",
 691          "tags": ["tag1", "tag2"],
 692          "beparams": {
 693            "vcpus": 2,
 694            "memory": 512
 695          },
 696          "disk.sizes": [
 697              20480
 698          ],
 699          "pnode": "node1.example.com",
 700          "nic.macs": ["01:23:45:67:89:01"],
 701          "snodes": ["node2.example.com"],
 702          "disk_template": "drbd",
 703          "admin_state": true,
 704          "os": "debian-etch",
 705          "oper_state": true
 706       },
 707       ...
 708     ]
 709
 710
 711 ``POST``
 712 ~~~~~~~~
 713
 714 Creates an instance.
 715
 716 If the optional bool *dry-run* argument is provided, the job will not be
 717 actually executed, only the pre-execution checks will be done. Query-ing
 718 the job result will return, in both dry-run and normal case, the list of
 719 nodes selected for the instance.
 720
 721 Returns: a job ID that can be used later for polling.
 722
 723 Body parameters:
 724
 725 ``__version__`` (int, required)
 726   Must be ``1`` (older Ganeti versions used a different format for
 727   instance creation requests, version ``0``, but that format is no
 728   longer supported)
 729
 730 .. opcode_params:: OP_INSTANCE_CREATE
 731
 732 Earlier versions used parameters named ``name`` and ``os``. These have
 733 been replaced by ``instance_name`` and ``os_type`` to match the
 734 underlying opcode. The old names can still be used.
 735
 736 Job result:
 737
 738 .. opcode_result:: OP_INSTANCE_CREATE
 739
 740
 741 ``/2/instances/[instance_name]``
 742 ++++++++++++++++++++++++++++++++
 743
 744 Instance-specific resource.
 745
 746 It supports the following commands: ``GET``, ``DELETE``.
 747
 748 ``GET``
 749 ~~~~~~~
 750
 751 Returns information about an instance, similar to the bulk output from
 752 the instance list.
 753
 754 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
 755
 756 ``DELETE``
 757 ~~~~~~~~~~
 758
 759 Deletes an instance.
 760
 761 It supports the ``dry-run`` argument.
 762
 763 Job result:
 764
 765 .. opcode_result:: OP_INSTANCE_REMOVE
 766
 767
 768 ``/2/instances/[instance_name]/info``
 769 +++++++++++++++++++++++++++++++++++++++
 770
 771 It supports the following commands: ``GET``.
 772
 773 ``GET``
 774 ~~~~~~~
 775
 776 Requests detailed information about the instance. An optional parameter,
 777 ``static`` (bool), can be set to return only static information from the
 778 configuration without querying the instance's nodes. The result will be
 779 a job id.
 780
 781 Job result:
 782
 783 .. opcode_result:: OP_INSTANCE_QUERY_DATA
 784
 785
 786 ``/2/instances/[instance_name]/reboot``
 787 +++++++++++++++++++++++++++++++++++++++
 788
 789 Reboots URI for an instance.
 790
 791 It supports the following commands: ``POST``.
 792
 793 ``POST``
 794 ~~~~~~~~
 795
 796 Reboots the instance.
 797
 798 The URI takes optional ``type=soft|hard|full`` and
 799 ``ignore_secondaries=0|1`` parameters.
 800
 801 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
 802 without terminating the hypervisor. ``hard`` means full shutdown
 803 (including terminating the hypervisor process) and startup again.
 804 ``full`` is like ``hard`` but also recreates the configuration from
 805 ground up as if you would have done a ``gnt-instance shutdown`` and
 806 ``gnt-instance start`` on it.
 807
 808 ``ignore_secondaries`` is a bool argument indicating if we start the
 809 instance even if secondary disks are failing.
 810
 811 It supports the ``dry-run`` argument.
 812
 813 Job result:
 814
 815 .. opcode_result:: OP_INSTANCE_REBOOT
 816
 817
 818 ``/2/instances/[instance_name]/shutdown``
 819 +++++++++++++++++++++++++++++++++++++++++
 820
 821 Instance shutdown URI.
 822
 823 It supports the following commands: ``PUT``.
 824
 825 ``PUT``
 826 ~~~~~~~
 827
 828 Shutdowns an instance.
 829
 830 It supports the ``dry-run`` argument.
 831
 832 .. opcode_params:: OP_INSTANCE_SHUTDOWN
 833    :exclude: instance_name, dry_run
 834
 835 Job result:
 836
 837 .. opcode_result:: OP_INSTANCE_SHUTDOWN
 838
 839
 840 ``/2/instances/[instance_name]/startup``
 841 ++++++++++++++++++++++++++++++++++++++++
 842
 843 Instance startup URI.
 844
 845 It supports the following commands: ``PUT``.
 846
 847 ``PUT``
 848 ~~~~~~~
 849
 850 Startup an instance.
 851
 852 The URI takes an optional ``force=1|0`` parameter to start the
 853 instance even if secondary disks are failing.
 854
 855 It supports the ``dry-run`` argument.
 856
 857 Job result:
 858
 859 .. opcode_result:: OP_INSTANCE_STARTUP
 860
 861
 862 ``/2/instances/[instance_name]/reinstall``
 863 ++++++++++++++++++++++++++++++++++++++++++++++
 864
 865 Installs the operating system again.
 866
 867 It supports the following commands: ``POST``.
 868
 869 ``POST``
 870 ~~~~~~~~
 871
 872 Returns a job ID.
 873
 874 Body parameters:
 875
 876 ``os`` (string, required)
 877   Instance operating system.
 878 ``start`` (bool, defaults to true)
 879   Whether to start instance after reinstallation.
 880 ``osparams`` (dict)
 881   Dictionary with (temporary) OS parameters.
 882
 883 For backwards compatbility, this resource also takes the query
 884 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
 885 clients should use the body parameters.
 886
 887
 888 ``/2/instances/[instance_name]/replace-disks``
 889 ++++++++++++++++++++++++++++++++++++++++++++++
 890
 891 Replaces disks on an instance.
 892
 893 It supports the following commands: ``POST``.
 894
 895 ``POST``
 896 ~~~~~~~~
 897
 898 Returns a job ID.
 899
 900 Body parameters:
 901
 902 .. opcode_params:: OP_INSTANCE_REPLACE_DISKS
 903    :exclude: instance_name
 904
 905 Ganeti 2.4 and below used query parameters. Those are deprecated and
 906 should no longer be used.
 907
 908 Job result:
 909
 910 .. opcode_result:: OP_INSTANCE_REPLACE_DISKS
 911
 912
 913 ``/2/instances/[instance_name]/activate-disks``
 914 +++++++++++++++++++++++++++++++++++++++++++++++
 915
 916 Activate disks on an instance.
 917
 918 It supports the following commands: ``PUT``.
 919
 920 ``PUT``
 921 ~~~~~~~
 922
 923 Takes the bool parameter ``ignore_size``. When set ignore the recorded
 924 size (useful for forcing activation when recorded size is wrong).
 925
 926 Job result:
 927
 928 .. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
 929
 930
 931 ``/2/instances/[instance_name]/deactivate-disks``
 932 +++++++++++++++++++++++++++++++++++++++++++++++++
 933
 934 Deactivate disks on an instance.
 935
 936 It supports the following commands: ``PUT``.
 937
 938 ``PUT``
 939 ~~~~~~~
 940
 941 Takes no parameters.
 942
 943 Job result:
 944
 945 .. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS
 946
 947
 948 ``/2/instances/[instance_name]/recreate-disks``
 949 +++++++++++++++++++++++++++++++++++++++++++++++++
 950
 951 Recreate disks of an instance. Supports the following commands:
 952 ``POST``.
 953
 954 ``POST``
 955 ~~~~~~~~
 956
 957 Returns a job ID.
 958
 959 Body parameters:
 960
 961 .. opcode_params:: OP_INSTANCE_RECREATE_DISKS
 962    :exclude: instance_name
 963
 964 Job result:
 965
 966 .. opcode_result:: OP_INSTANCE_RECREATE_DISKS
 967
 968
 969 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
 970 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 971
 972 Grows one disk of an instance.
 973
 974 Supports the following commands: ``POST``.
 975
 976 ``POST``
 977 ~~~~~~~~
 978
 979 Returns a job ID.
 980
 981 Body parameters:
 982
 983 .. opcode_params:: OP_INSTANCE_GROW_DISK
 984    :exclude: instance_name, disk
 985
 986 Job result:
 987
 988 .. opcode_result:: OP_INSTANCE_GROW_DISK
 989
 990
 991 ``/2/instances/[instance_name]/prepare-export``
 992 +++++++++++++++++++++++++++++++++++++++++++++++++
 993
 994 Prepares an export of an instance.
 995
 996 It supports the following commands: ``PUT``.
 997
 998 ``PUT``
 999 ~~~~~~~
1000
1001 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
1002
1003 Job result:
1004
1005 .. opcode_result:: OP_BACKUP_PREPARE
1006
1007
1008 ``/2/instances/[instance_name]/export``
1009 +++++++++++++++++++++++++++++++++++++++++++++++++
1010
1011 Exports an instance.
1012
1013 It supports the following commands: ``PUT``.
1014
1015 ``PUT``
1016 ~~~~~~~
1017
1018 Returns a job ID.
1019
1020 Body parameters:
1021
1022 .. opcode_params:: OP_BACKUP_EXPORT
1023    :exclude: instance_name
1024    :alias: target_node=destination
1025
1026 Job result:
1027
1028 .. opcode_result:: OP_BACKUP_EXPORT
1029
1030
1031 ``/2/instances/[instance_name]/migrate``
1032 ++++++++++++++++++++++++++++++++++++++++
1033
1034 Migrates an instance.
1035
1036 Supports the following commands: ``PUT``.
1037
1038 ``PUT``
1039 ~~~~~~~
1040
1041 Returns a job ID.
1042
1043 Body parameters:
1044
1045 .. opcode_params:: OP_INSTANCE_MIGRATE
1046    :exclude: instance_name, live
1047
1048 Job result:
1049
1050 .. opcode_result:: OP_INSTANCE_MIGRATE
1051
1052
1053 ``/2/instances/[instance_name]/failover``
1054 +++++++++++++++++++++++++++++++++++++++++
1055
1056 Does a failover of an instance.
1057
1058 Supports the following commands: ``PUT``.
1059
1060 ``PUT``
1061 ~~~~~~~
1062
1063 Returns a job ID.
1064
1065 Body parameters:
1066
1067 .. opcode_params:: OP_INSTANCE_FAILOVER
1068    :exclude: instance_name
1069
1070 Job result:
1071
1072 .. opcode_result:: OP_INSTANCE_FAILOVER
1073
1074
1075 ``/2/instances/[instance_name]/rename``
1076 ++++++++++++++++++++++++++++++++++++++++
1077
1078 Renames an instance.
1079
1080 Supports the following commands: ``PUT``.
1081
1082 ``PUT``
1083 ~~~~~~~
1084
1085 Returns a job ID.
1086
1087 Body parameters:
1088
1089 .. opcode_params:: OP_INSTANCE_RENAME
1090    :exclude: instance_name
1091
1092 Job result:
1093
1094 .. opcode_result:: OP_INSTANCE_RENAME
1095
1096
1097 ``/2/instances/[instance_name]/modify``
1098 ++++++++++++++++++++++++++++++++++++++++
1099
1100 Modifies an instance.
1101
1102 Supports the following commands: ``PUT``.
1103
1104 ``PUT``
1105 ~~~~~~~
1106
1107 Returns a job ID.
1108
1109 Body parameters:
1110
1111 .. opcode_params:: OP_INSTANCE_SET_PARAMS
1112    :exclude: instance_name
1113
1114 Job result:
1115
1116 .. opcode_result:: OP_INSTANCE_SET_PARAMS
1117
1118
1119 ``/2/instances/[instance_name]/console``
1120 ++++++++++++++++++++++++++++++++++++++++
1121
1122 Request information for connecting to instance's console.
1123
1124 Supports the following commands: ``GET``.
1125
1126 ``GET``
1127 ~~~~~~~
1128
1129 Returns a dictionary containing information about the instance's
1130 console. Contained keys:
1131
1132 .. pyassert::
1133
1134    constants.CONS_ALL == frozenset([
1135      constants.CONS_MESSAGE,
1136      constants.CONS_SSH,
1137      constants.CONS_VNC,
1138      constants.CONS_SPICE,
1139      ])
1140
1141 ``instance``
1142   Instance name
1143 ``kind``
1144   Console type, one of :pyeval:`constants.CONS_SSH`,
1145   :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
1146   or :pyeval:`constants.CONS_MESSAGE`
1147 ``message``
1148   Message to display (:pyeval:`constants.CONS_MESSAGE` type only)
1149 ``host``
1150   Host to connect to (:pyeval:`constants.CONS_SSH`,
1151   :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
1152 ``port``
1153   TCP port to connect to (:pyeval:`constants.CONS_VNC` or
1154   :pyeval:`constants.CONS_SPICE` only)
1155 ``user``
1156   Username to use (:pyeval:`constants.CONS_SSH` only)
1157 ``command``
1158   Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
1159 ``display``
1160   VNC display number (:pyeval:`constants.CONS_VNC` only)
1161
1162
1163 ``/2/instances/[instance_name]/tags``
1164 +++++++++++++++++++++++++++++++++++++
1165
1166 Manages per-instance tags.
1167
1168 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1169
1170 ``GET``
1171 ~~~~~~~
1172
1173 Returns a list of tags.
1174
1175 Example::
1176
1177     ["tag1", "tag2", "tag3"]
1178
1179 ``PUT``
1180 ~~~~~~~
1181
1182 Add a set of tags.
1183
1184 The request as a list of strings should be ``PUT`` to this URI. The
1185 result will be a job id.
1186
1187 It supports the ``dry-run`` argument.
1188
1189
1190 ``DELETE``
1191 ~~~~~~~~~~
1192
1193 Delete a tag.
1194
1195 In order to delete a set of tags, the DELETE request should be addressed
1196 to URI like::
1197
1198     /tags?tag=[tag]&tag=[tag]
1199
1200 It supports the ``dry-run`` argument.
1201
1202
1203 ``/2/jobs``
1204 +++++++++++
1205
1206 The ``/2/jobs`` resource.
1207
1208 It supports the following commands: ``GET``.
1209
1210 ``GET``
1211 ~~~~~~~
1212
1213 Returns a dictionary of jobs.
1214
1215 Returns: a dictionary with jobs id and uri.
1216
1217 If the optional bool *bulk* argument is provided and set to a true value
1218 (i.e. ``?bulk=1``), the output contains detailed information about jobs
1219 as a list.
1220
1221 Returned fields for bulk requests (unlike other bulk requests, these
1222 fields are not the same as for per-job requests):
1223 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`.
1224
1225 ``/2/jobs/[job_id]``
1226 ++++++++++++++++++++
1227
1228
1229 Individual job URI.
1230
1231 It supports the following commands: ``GET``, ``DELETE``.
1232
1233 ``GET``
1234 ~~~~~~~
1235
1236 Returns a dictionary with job parameters, containing the fields
1237 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.
1238
1239 The result includes:
1240
1241 - id: job ID as a number
1242 - status: current job status as a string
1243 - ops: involved OpCodes as a list of dictionaries for each opcodes in
1244   the job
1245 - opstatus: OpCodes status as a list
1246 - opresult: OpCodes results as a list
1247
1248 For a successful opcode, the ``opresult`` field corresponding to it will
1249 contain the raw result from its :term:`LogicalUnit`. In case an opcode
1250 has failed, its element in the opresult list will be a list of two
1251 elements:
1252
1253 - first element the error type (the Ganeti internal error name)
1254 - second element a list of either one or two elements:
1255
1256   - the first element is the textual error description
1257   - the second element, if any, will hold an error classification
1258
1259 The error classification is most useful for the ``OpPrereqError``
1260 error type - these errors happen before the OpCode has started
1261 executing, so it's possible to retry the OpCode without side
1262 effects. But whether it make sense to retry depends on the error
1263 classification:
1264
1265 .. pyassert::
1266
1267    errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
1268      errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
1269      errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
1270      errors.ECODE_ENVIRON])
1271
1272 :pyeval:`errors.ECODE_RESOLVER`
1273   Resolver errors. This usually means that a name doesn't exist in DNS,
1274   so if it's a case of slow DNS propagation the operation can be retried
1275   later.
1276
1277 :pyeval:`errors.ECODE_NORES`
1278   Not enough resources (iallocator failure, disk space, memory,
1279   etc.). If the resources on the cluster increase, the operation might
1280   succeed.
1281
1282 :pyeval:`errors.ECODE_INVAL`
1283   Wrong arguments (at syntax level). The operation will not ever be
1284   accepted unless the arguments change.
1285
1286 :pyeval:`errors.ECODE_STATE`
1287   Wrong entity state. For example, live migration has been requested for
1288   a down instance, or instance creation on an offline node. The
1289   operation can be retried once the resource has changed state.
1290
1291 :pyeval:`errors.ECODE_NOENT`
1292   Entity not found. For example, information has been requested for an
1293   unknown instance.
1294
1295 :pyeval:`errors.ECODE_EXISTS`
1296   Entity already exists. For example, instance creation has been
1297   requested for an already-existing instance.
1298
1299 :pyeval:`errors.ECODE_NOTUNIQUE`
1300   Resource not unique (e.g. MAC or IP duplication).
1301
1302 :pyeval:`errors.ECODE_FAULT`
1303   Internal cluster error. For example, a node is unreachable but not set
1304   offline, or the ganeti node daemons are not working, etc. A
1305   ``gnt-cluster verify`` should be run.
1306
1307 :pyeval:`errors.ECODE_ENVIRON`
1308   Environment error (e.g. node disk error). A ``gnt-cluster verify``
1309   should be run.
1310
1311 Note that in the above list, by entity we refer to a node or instance,
1312 while by a resource we refer to an instance's disk, or NIC, etc.
1313
1314
1315 ``DELETE``
1316 ~~~~~~~~~~
1317
1318 Cancel a not-yet-started job.
1319
1320
1321 ``/2/jobs/[job_id]/wait``
1322 +++++++++++++++++++++++++
1323
1324 ``GET``
1325 ~~~~~~~
1326
1327 Waits for changes on a job. Takes the following body parameters in a
1328 dict:
1329
1330 ``fields``
1331   The job fields on which to watch for changes
1332
1333 ``previous_job_info``
1334   Previously received field values or None if not yet available
1335
1336 ``previous_log_serial``
1337   Highest log serial number received so far or None if not yet
1338   available
1339
1340 Returns None if no changes have been detected and a dict with two keys,
1341 ``job_info`` and ``log_entries`` otherwise.
1342
1343
1344 ``/2/nodes``
1345 ++++++++++++
1346
1347 Nodes resource.
1348
1349 It supports the following commands: ``GET``.
1350
1351 ``GET``
1352 ~~~~~~~
1353
1354 Returns a list of all nodes.
1355
1356 Example::
1357
1358     [
1359       {
1360         "id": "node1.example.com",
1361         "uri": "\/nodes\/node1.example.com"
1362       },
1363       {
1364         "id": "node2.example.com",
1365         "uri": "\/nodes\/node2.example.com"
1366       }
1367     ]
1368
1369 If the optional bool *bulk* argument is provided and set to a true value
1370 (i.e ``?bulk=1``), the output contains detailed information about nodes
1371 as a list.
1372
1373 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1374
1375 Example::
1376
1377     [
1378       {
1379         "pinst_cnt": 1,
1380         "mfree": 31280,
1381         "mtotal": 32763,
1382         "name": "www.example.com",
1383         "tags": [],
1384         "mnode": 512,
1385         "dtotal": 5246208,
1386         "sinst_cnt": 2,
1387         "dfree": 5171712,
1388         "offline": false
1389       },
1390       ...
1391     ]
1392
1393 ``/2/nodes/[node_name]``
1394 +++++++++++++++++++++++++++++++++
1395
1396 Returns information about a node.
1397
1398 It supports the following commands: ``GET``.
1399
1400 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1401
1402 ``/2/nodes/[node_name]/powercycle``
1403 +++++++++++++++++++++++++++++++++++
1404
1405 Powercycles a node. Supports the following commands: ``POST``.
1406
1407 ``POST``
1408 ~~~~~~~~
1409
1410 Returns a job ID.
1411
1412 Job result:
1413
1414 .. opcode_result:: OP_NODE_POWERCYCLE
1415
1416
1417 ``/2/nodes/[node_name]/evacuate``
1418 +++++++++++++++++++++++++++++++++
1419
1420 Evacuates instances off a node.
1421
1422 It supports the following commands: ``POST``.
1423
1424 ``POST``
1425 ~~~~~~~~
1426
1427 Returns a job ID. The result of the job will contain the IDs of the
1428 individual jobs submitted to evacuate the node.
1429
1430 Body parameters:
1431
1432 .. opcode_params:: OP_NODE_EVACUATE
1433    :exclude: nodes
1434
1435 Up to and including Ganeti 2.4 query arguments were used. Those are no
1436 longer supported. The new request can be detected by the presence of the
1437 :pyeval:`rlib2._NODE_EVAC_RES1` feature string.
1438
1439 Job result:
1440
1441 .. opcode_result:: OP_NODE_EVACUATE
1442
1443
1444 ``/2/nodes/[node_name]/migrate``
1445 +++++++++++++++++++++++++++++++++
1446
1447 Migrates all primary instances from a node.
1448
1449 It supports the following commands: ``POST``.
1450
1451 ``POST``
1452 ~~~~~~~~
1453
1454 If no mode is explicitly specified, each instances' hypervisor default
1455 migration mode will be used. Body parameters:
1456
1457 .. opcode_params:: OP_NODE_MIGRATE
1458    :exclude: node_name
1459
1460 The query arguments used up to and including Ganeti 2.4 are deprecated
1461 and should no longer be used. The new request format can be detected by
1462 the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
1463
1464 Job result:
1465
1466 .. opcode_result:: OP_NODE_MIGRATE
1467
1468
1469 ``/2/nodes/[node_name]/role``
1470 +++++++++++++++++++++++++++++
1471
1472 Manages node role.
1473
1474 It supports the following commands: ``GET``, ``PUT``.
1475
1476 The role is always one of the following:
1477
1478   - drained
1479   - master-candidate
1480   - offline
1481   - regular
1482
1483 Note that the 'master' role is a special, and currently it can't be
1484 modified via RAPI, only via the command line (``gnt-cluster
1485 master-failover``).
1486
1487 ``GET``
1488 ~~~~~~~
1489
1490 Returns the current node role.
1491
1492 Example::
1493
1494     "master-candidate"
1495
1496 ``PUT``
1497 ~~~~~~~
1498
1499 Change the node role.
1500
1501 The request is a string which should be PUT to this URI. The result will
1502 be a job id.
1503
1504 It supports the bool ``force`` argument.
1505
1506 Job result:
1507
1508 .. opcode_result:: OP_NODE_SET_PARAMS
1509
1510
1511 ``/2/nodes/[node_name]/modify``
1512 +++++++++++++++++++++++++++++++
1513
1514 Modifies the parameters of a node. Supports the following commands:
1515 ``POST``.
1516
1517 ``POST``
1518 ~~~~~~~~
1519
1520 Returns a job ID.
1521
1522 Body parameters:
1523
1524 .. opcode_params:: OP_NODE_SET_PARAMS
1525    :exclude: node_name
1526
1527 Job result:
1528
1529 .. opcode_result:: OP_NODE_SET_PARAMS
1530
1531
1532 ``/2/nodes/[node_name]/storage``
1533 ++++++++++++++++++++++++++++++++
1534
1535 Manages storage units on the node.
1536
1537 ``GET``
1538 ~~~~~~~
1539
1540 .. pyassert::
1541
1542    constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
1543                                          constants.ST_LVM_PV,
1544                                          constants.ST_LVM_VG])
1545
1546 Requests a list of storage units on a node. Requires the parameters
1547 ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1548 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
1549 ``output_fields``. The result will be a job id, using which the result
1550 can be retrieved.
1551
1552 ``/2/nodes/[node_name]/storage/modify``
1553 +++++++++++++++++++++++++++++++++++++++
1554
1555 Modifies storage units on the node.
1556
1557 ``PUT``
1558 ~~~~~~~
1559
1560 Modifies parameters of storage units on the node. Requires the
1561 parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1562 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
1563 and ``name`` (name of the storage unit).  Parameters can be passed
1564 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
1565 is supported. The result will be a job id.
1566
1567 Job result:
1568
1569 .. opcode_result:: OP_NODE_MODIFY_STORAGE
1570
1571
1572 ``/2/nodes/[node_name]/storage/repair``
1573 +++++++++++++++++++++++++++++++++++++++
1574
1575 Repairs a storage unit on the node.
1576
1577 ``PUT``
1578 ~~~~~~~
1579
1580 .. pyassert::
1581
1582    constants.VALID_STORAGE_OPERATIONS == {
1583     constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
1584     }
1585
1586 Repairs a storage unit on the node. Requires the parameters
1587 ``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
1588 repaired) and ``name`` (name of the storage unit). The result will be a
1589 job id.
1590
1591 Job result:
1592
1593 .. opcode_result:: OP_REPAIR_NODE_STORAGE
1594
1595
1596 ``/2/nodes/[node_name]/tags``
1597 +++++++++++++++++++++++++++++
1598
1599 Manages per-node tags.
1600
1601 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1602
1603 ``GET``
1604 ~~~~~~~
1605
1606 Returns a list of tags.
1607
1608 Example::
1609
1610     ["tag1", "tag2", "tag3"]
1611
1612 ``PUT``
1613 ~~~~~~~
1614
1615 Add a set of tags.
1616
1617 The request as a list of strings should be PUT to this URI. The result
1618 will be a job id.
1619
1620 It supports the ``dry-run`` argument.
1621
1622 ``DELETE``
1623 ~~~~~~~~~~
1624
1625 Deletes tags.
1626
1627 In order to delete a set of tags, the DELETE request should be addressed
1628 to URI like::
1629
1630     /tags?tag=[tag]&tag=[tag]
1631
1632 It supports the ``dry-run`` argument.
1633
1634
1635 ``/2/query/[resource]``
1636 +++++++++++++++++++++++
1637
1638 Requests resource information. Available fields can be found in man
1639 pages and using ``/2/query/[resource]/fields``. The resource is one of
1640 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
1641 design document <design-query2>` for more details.
1642
1643 Supports the following commands: ``GET``, ``PUT``.
1644
1645 ``GET``
1646 ~~~~~~~
1647
1648 Returns list of included fields and actual data. Takes a query parameter
1649 named "fields", containing a comma-separated list of field names. Does
1650 not support filtering.
1651
1652 ``PUT``
1653 ~~~~~~~
1654
1655 Returns list of included fields and actual data. The list of requested
1656 fields can either be given as the query parameter "fields" or as a body
1657 parameter with the same name. The optional body parameter "filter" can
1658 be given and must be either ``null`` or a list containing filter
1659 operators.
1660
1661
1662 ``/2/query/[resource]/fields``
1663 ++++++++++++++++++++++++++++++
1664
1665 Request list of available fields for a resource. The resource is one of
1666 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
1667 :doc:`query2 design document <design-query2>` for more details.
1668
1669 Supports the following commands: ``GET``.
1670
1671 ``GET``
1672 ~~~~~~~
1673
1674 Returns a list of field descriptions for available fields. Takes an
1675 optional query parameter named "fields", containing a comma-separated
1676 list of field names.
1677
1678
1679 ``/2/os``
1680 +++++++++
1681
1682 OS resource.
1683
1684 It supports the following commands: ``GET``.
1685
1686 ``GET``
1687 ~~~~~~~
1688
1689 Return a list of all OSes.
1690
1691 Can return error 500 in case of a problem. Since this is a costly
1692 operation for Ganeti 2.0, it is not recommended to execute it too often.
1693
1694 Example::
1695
1696     ["debian-etch"]
1697
1698 ``/2/tags``
1699 +++++++++++
1700
1701 Manages cluster tags.
1702
1703 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1704
1705 ``GET``
1706 ~~~~~~~
1707
1708 Returns the cluster tags.
1709
1710 Example::
1711
1712     ["tag1", "tag2", "tag3"]
1713
1714 ``PUT``
1715 ~~~~~~~
1716
1717 Adds a set of tags.
1718
1719 The request as a list of strings should be PUT to this URI. The result
1720 will be a job id.
1721
1722 It supports the ``dry-run`` argument.
1723
1724
1725 ``DELETE``
1726 ~~~~~~~~~~
1727
1728 Deletes tags.
1729
1730 In order to delete a set of tags, the DELETE request should be addressed
1731 to URI like::
1732
1733     /tags?tag=[tag]&tag=[tag]
1734
1735 It supports the ``dry-run`` argument.
1736
1737
1738 ``/version``
1739 ++++++++++++
1740
1741 The version resource.
1742
1743 This resource should be used to determine the remote API version and to
1744 adapt clients accordingly.
1745
1746 It supports the following commands: ``GET``.
1747
1748 ``GET``
1749 ~~~~~~~
1750
1751 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
1752 returns ``2``.
1753
1754 .. vim: set textwidth=72 :
1755 .. Local Variables:
1756 .. mode: rst
1757 .. fill-column: 72
1758 .. End: