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