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