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