X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/af7b66896dd0fd02748f78071ecd9d166393513d..99c7cd5be025e86745aa46003ca0962609e0b4e2:/doc/rapi.rst diff --git a/doc/rapi.rst b/doc/rapi.rst index d278b29..37dbebd 100644 --- a/doc/rapi.rst +++ b/doc/rapi.rst @@ -16,6 +16,7 @@ it runs on TCP port 5080, but this can be changed either in which is used by default, can also be disabled by passing command line parameters. +.. _rapi-users: Users and passwords ------------------- @@ -24,12 +25,24 @@ Users and passwords ``/var/lib/ganeti/rapi/users``) on startup. Changes to the file will be read automatically. -Each line consists of two or three fields separated by whitespace. The -first two fields are for username and password. The third field is -optional and can be used to specify per-user options. Currently, -``write`` is the only option supported and enables the user to execute -operations modifying the cluster. Lines starting with the hash sign -(``#``) are treated as comments. +Lines starting with the hash sign (``#``) are treated as comments. Each +line consists of two or three fields separated by whitespace. The first +two fields are for username and password. The third field is optional +and can be used to specify per-user options (separated by comma without +spaces). Available options: + +.. pyassert:: + + rapi.RAPI_ACCESS_ALL == set([ + rapi.RAPI_ACCESS_WRITE, + rapi.RAPI_ACCESS_READ, + ]) + +:pyeval:`rapi.RAPI_ACCESS_WRITE` + Enables the user to execute operations modifying the cluster. Implies + :pyeval:`rapi.RAPI_ACCESS_READ` access. +:pyeval:`rapi.RAPI_ACCESS_READ` + Allow access to operations querying for information. Passwords can either be written in clear text or as a hash. Clear text passwords may not start with an opening brace (``{``) or they must be @@ -51,10 +64,23 @@ Example:: # Hashed password for Jessica jessica {HA1}7046452df2cbb530877058712cf17bd4 write + # Monitoring can query for values + monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read + + # A user who can read and write (the former is implied by granting + # write access) + superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read,write + +When using the RAPI, username and password can be sent to the server +by using the standard HTTP basic access authentication. This means that +for accessing the protected URL ``https://cluster.example.com/resource``, +the address ``https://username:password@cluster.example.com/resource`` should +be used instead. Alternatively, the appropriate parameter of your HTTP client +(such as ``-u`` for ``curl``) can be used. .. [#pwhash] Using the MD5 hash of username, realm and password is - described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 and - 3.3. The reason for using it over another algorithm is forward + described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 + and 3.3. The reason for using it over another algorithm is forward compatibility. If ``ganeti-rapi`` were to implement HTTP Digest authentication in the future, the same hash could be used. In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote @@ -166,6 +192,69 @@ likely to succeed or at least start executing. Force operation to continue even if it will cause the cluster to become inconsistent (e.g. because there are not enough master candidates). +Parameter details +----------------- + +Some parameters are not straight forward, so we describe them in details +here. + +.. _rapi-ipolicy: + +``ipolicy`` ++++++++++++ + +The instance policy specification is a dict with the following fields: + +.. pyassert:: + + constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN, + constants.ISPECS_MAX, + constants.ISPECS_STD, + constants.IPOLICY_DTS, + constants.IPOLICY_VCPU_RATIO, + constants.IPOLICY_SPINDLE_RATIO]) + + +.. pyassert:: + + (set(constants.ISPECS_PARAMETER_TYPES.keys()) == + set([constants.ISPEC_MEM_SIZE, + constants.ISPEC_DISK_SIZE, + constants.ISPEC_DISK_COUNT, + constants.ISPEC_CPU_COUNT, + constants.ISPEC_NIC_COUNT, + constants.ISPEC_SPINDLE_USE])) + +.. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN` +.. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX` +.. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD` + + +|ispec-min|, |ispec-max|, |ispec-std| + A sub- `dict` with the following fields, which sets the limit and standard + values of the instances: + + :pyeval:`constants.ISPEC_MEM_SIZE` + The size in MiB of the memory used + :pyeval:`constants.ISPEC_DISK_SIZE` + The size in MiB of the disk used + :pyeval:`constants.ISPEC_DISK_COUNT` + The numbers of disks used + :pyeval:`constants.ISPEC_CPU_COUNT` + The numbers of cpus used + :pyeval:`constants.ISPEC_NIC_COUNT` + The numbers of nics used + :pyeval:`constants.ISPEC_SPINDLE_USE` + The numbers of virtual disk spindles used by this instance. They are + not real in the sense of actual HDD spindles, but useful for + accounting the spindle usage on the residing node +:pyeval:`constants.IPOLICY_DTS` + A `list` of disk templates allowed for instances using this policy +:pyeval:`constants.IPOLICY_VCPU_RATIO` + Maximum ratio of virtual to physical CPUs (`float`) +:pyeval:`constants.IPOLICY_SPINDLE_RATIO` + Maximum ratio of instances to their node's ``spindle_count`` (`float`) + Usage examples -------------- @@ -180,16 +269,21 @@ Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``. Shell +++++ -.. highlight:: sh +.. highlight:: shell-example -Using wget:: +Using ``wget``:: - wget -q -O - https://CLUSTERNAME:5080/2/info + $ wget -q -O - https://%CLUSTERNAME%:5080/2/info -or curl:: +or ``curl``:: - curl https://CLUSTERNAME:5080/2/info + $ curl https://%CLUSTERNAME%:5080/2/info +Note: with ``curl``, the request method (GET, POST, PUT) can be specified +using the ``-X`` command line option, and the username/password can be +specified with the ``-u`` option. In case of POST requests with a body, the +Content-Type can be set to JSON (as per the Protocol_ section) using the +parameter ``-H "Content-Type: application/json"``. Python ++++++ @@ -239,30 +333,13 @@ Resources ``/`` +++++ -The root resource. - -It supports the following commands: ``GET``. - -``GET`` -~~~~~~~ - -Shows the list of mapped resources. - -Returns: a dictionary with 'name' and 'uri' keys for each of them. +The root resource. Has no function, but for legacy reasons the ``GET`` +method is supported. ``/2`` ++++++ -The ``/2`` resource, the root of the version 2 API. - -It supports the following commands: ``GET``. - -``GET`` -~~~~~~~ - -Show the list of mapped resources. - -Returns: a dictionary with ``name`` and ``uri`` keys for each of them. +Has no function, but for legacy reasons the ``GET`` method is supported. ``/2/info`` +++++++++++ @@ -304,8 +381,9 @@ Example:: "vcpus": 1, "memory": 128 } - } - } + }, + … + } ``/2/redistribute-config`` @@ -320,6 +398,10 @@ It supports the following commands: ``PUT``. Redistribute configuration to all nodes. The result will be a job id. +Job result: + +.. opcode_result:: OP_CLUSTER_REDIST_CONF + ``/2/features`` +++++++++++++++ @@ -330,10 +412,23 @@ Redistribute configuration to all nodes. The result will be a job id. Returns a list of features supported by the RAPI server. Available features: -``instance-create-reqv1`` - Instance creation request data version 1 supported. -``instance-reinstall-reqv1`` - Instance reinstall supports body parameters. +.. pyassert:: + + rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1, + rlib2._INST_REINSTALL_REQV1, + rlib2._NODE_MIGRATE_REQV1, + rlib2._NODE_EVAC_RES1]) + +:pyeval:`rlib2._INST_CREATE_REQV1` + Instance creation request data version 1 supported +:pyeval:`rlib2._INST_REINSTALL_REQV1` + Instance reinstall supports body parameters +:pyeval:`rlib2._NODE_MIGRATE_REQV1` + Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports + request body parameters +:pyeval:`rlib2._NODE_EVAC_RES1` + Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns + a new-style result (see resource description) ``/2/modify`` @@ -352,6 +447,10 @@ Body parameters: .. opcode_params:: OP_CLUSTER_SET_PARAMS +Job result: + +.. opcode_result:: OP_CLUSTER_SET_PARAMS + ``/2/groups`` +++++++++++++ @@ -382,6 +481,8 @@ If the optional bool *bulk* argument is provided and set to a true value (i.e ``?bulk=1``), the output contains detailed information about node groups as a list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`. + Example:: [ @@ -392,7 +493,8 @@ Example:: "node1.example.com", "node2.example.com" ], - "uuid": "0d7d407c-262e-49af-881a-6a430034bf43" + "uuid": "0d7d407c-262e-49af-881a-6a430034bf43", + … }, { "name": "group2", @@ -400,8 +502,10 @@ Example:: "node_list": [ "node3.example.com" ], - "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c" - } + "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c", + … + }, + … ] ``POST`` @@ -421,6 +525,10 @@ Body parameters: Earlier versions used a parameter named ``name`` which, while still supported, has been renamed to ``group_name``. +Job result: + +.. opcode_result:: OP_GROUP_ADD + ``/2/groups/[group_name]`` ++++++++++++++++++++++++++ @@ -435,6 +543,8 @@ It supports the following commands: ``GET``, ``DELETE``. Returns information about a node group, similar to the bulk output from the node group list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`. + ``DELETE`` ~~~~~~~~~~ @@ -442,6 +552,10 @@ Deletes a node group. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_GROUP_REMOVE + ``/2/groups/[group_name]/modify`` +++++++++++++++++++++++++++++++++ @@ -460,6 +574,10 @@ Body parameters: .. opcode_params:: OP_GROUP_SET_PARAMS :exclude: group_name +Job result: + +.. opcode_result:: OP_GROUP_SET_PARAMS + ``/2/groups/[group_name]/rename`` +++++++++++++++++++++++++++++++++ @@ -478,6 +596,10 @@ Body parameters: .. opcode_params:: OP_GROUP_RENAME :exclude: group_name +Job result: + +.. opcode_result:: OP_GROUP_RENAME + ``/2/groups/[group_name]/assign-nodes`` +++++++++++++++++++++++++++++++++++++++ @@ -496,6 +618,271 @@ Body parameters: .. opcode_params:: OP_GROUP_ASSIGN_NODES :exclude: group_name, force, dry_run +Job result: + +.. opcode_result:: OP_GROUP_ASSIGN_NODES + + +``/2/groups/[group_name]/tags`` ++++++++++++++++++++++++++++++++ + +Manages per-nodegroup tags. + +Supports the following commands: ``GET``, ``PUT``, ``DELETE``. + +``GET`` +~~~~~~~ + +Returns a list of tags. + +Example:: + + ["tag1", "tag2", "tag3"] + +``PUT`` +~~~~~~~ + +Add a set of tags. + +The request as a list of strings should be ``PUT`` to this URI. The +result will be a job id. + +It supports the ``dry-run`` argument. + + +``DELETE`` +~~~~~~~~~~ + +Delete a tag. + +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: + + /tags?tag=[tag]&tag=[tag] + +It supports the ``dry-run`` argument. + + +``/2/networks`` ++++++++++++++++ + +The networks resource. + +It supports the following commands: ``GET``, ``POST``. + +``GET`` +~~~~~~~ + +Returns a list of all existing networks. + +Example:: + + [ + { + "name": "network1", + "uri": "\/2\/networks\/network1" + }, + { + "name": "network2", + "uri": "\/2\/networks\/network2" + } + ] + +If the optional bool *bulk* argument is provided and set to a true value +(i.e ``?bulk=1``), the output contains detailed information about networks +as a list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`. + +Example:: + + [ + { + 'external_reservations': '10.0.0.0, 10.0.0.1, 10.0.0.15', + 'free_count': 13, + 'gateway': '10.0.0.1', + 'gateway6': None, + 'group_list': ['default(bridged, prv0)'], + 'inst_list': [], + 'mac_prefix': None, + 'map': 'XX.............X', + 'name': 'nat', + 'network': '10.0.0.0/28', + 'network6': None, + 'reserved_count': 3, + 'tags': ['nfdhcpd'], + … + }, + … + ] + +``POST`` +~~~~~~~~ + +Creates a network. + +If the optional bool *dry-run* argument is provided, the job will not be +actually executed, only the pre-execution checks will be done. + +Returns: a job ID that can be used later for polling. + +Body parameters: + +.. opcode_params:: OP_NETWORK_ADD + +Job result: + +.. opcode_result:: OP_NETWORK_ADD + + +``/2/networks/[network_name]`` +++++++++++++++++++++++++++++++ + +Returns information about a network. + +It supports the following commands: ``GET``, ``DELETE``. + +``GET`` +~~~~~~~ + +Returns information about a network, similar to the bulk output from +the network list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`. + +``DELETE`` +~~~~~~~~~~ + +Deletes a network. + +It supports the ``dry-run`` argument. + +Job result: + +.. opcode_result:: OP_NETWORK_REMOVE + + +``/2/networks/[network_name]/modify`` ++++++++++++++++++++++++++++++++++++++ + +Modifies the parameters of a network. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_NETWORK_SET_PARAMS + +Job result: + +.. opcode_result:: OP_NETWORK_SET_PARAMS + + +``/2/networks/[network_name]/connect`` +++++++++++++++++++++++++++++++++++++++ + +Connects a network to a nodegroup. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. It supports the ``dry-run`` arguments. + +Body parameters: + +.. opcode_params:: OP_NETWORK_CONNECT + +Job result: + +.. opcode_result:: OP_NETWORK_CONNECT + + +``/2/networks/[network_name]/disconnect`` ++++++++++++++++++++++++++++++++++++++++++ + +Disonnects a network from a nodegroup. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. It supports the ``dry-run`` arguments. + +Body parameters: + +.. opcode_params:: OP_NETWORK_DISCONNECT + +Job result: + +.. opcode_result:: OP_NETWORK_DISCONNECT + + +``/2/networks/[network_name]/tags`` ++++++++++++++++++++++++++++++++++++ + +Manages per-network tags. + +Supports the following commands: ``GET``, ``PUT``, ``DELETE``. + +``GET`` +~~~~~~~ + +Returns a list of tags. + +Example:: + + ["tag1", "tag2", "tag3"] + +``PUT`` +~~~~~~~ + +Add a set of tags. + +The request as a list of strings should be ``PUT`` to this URI. The +result will be a job id. + +It supports the ``dry-run`` argument. + + +``DELETE`` +~~~~~~~~~~ + +Delete a tag. + +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: + + /tags?tag=[tag]&tag=[tag] + +It supports the ``dry-run`` argument. + + +``/2/instances-multi-alloc`` +++++++++++++++++++++++++++++ + +Tries to allocate multiple instances. + +It supports the following commands: ``POST`` + +``POST`` +~~~~~~~~ + +The parameters: + +.. opcode_params:: OP_INSTANCE_MULTI_ALLOC + +Job result: + +.. opcode_result:: OP_INSTANCE_MULTI_ALLOC + ``/2/instances`` ++++++++++++++++ @@ -526,33 +913,36 @@ If the optional bool *bulk* argument is provided and set to a true value (i.e ``?bulk=1``), the output contains detailed information about instances as a list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`. + Example:: [ { - "status": "running", - "disk_usage": 20480, - "nic.bridges": [ - "xen-br0" - ], - "name": "web.example.com", - "tags": ["tag1", "tag2"], - "beparams": { - "vcpus": 2, - "memory": 512 - }, - "disk.sizes": [ - 20480 - ], - "pnode": "node1.example.com", - "nic.macs": ["01:23:45:67:89:01"], - "snodes": ["node2.example.com"], - "disk_template": "drbd", - "admin_state": true, - "os": "debian-etch", - "oper_state": true + "status": "running", + "disk_usage": 20480, + "nic.bridges": [ + "xen-br0" + ], + "name": "web.example.com", + "tags": ["tag1", "tag2"], + "beparams": { + "vcpus": 2, + "memory": 512 + }, + "disk.sizes": [ + 20480 + ], + "pnode": "node1.example.com", + "nic.macs": ["01:23:45:67:89:01"], + "snodes": ["node2.example.com"], + "disk_template": "drbd", + "admin_state": true, + "os": "debian-etch", + "oper_state": true, + … }, - ... + … ] @@ -581,6 +971,10 @@ Earlier versions used parameters named ``name`` and ``os``. These have been replaced by ``instance_name`` and ``os_type`` to match the underlying opcode. The old names can still be used. +Job result: + +.. opcode_result:: OP_INSTANCE_CREATE + ``/2/instances/[instance_name]`` ++++++++++++++++++++++++++++++++ @@ -595,6 +989,8 @@ It supports the following commands: ``GET``, ``DELETE``. Returns information about an instance, similar to the bulk output from the instance list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`. + ``DELETE`` ~~~~~~~~~~ @@ -602,6 +998,10 @@ Deletes an instance. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_INSTANCE_REMOVE + ``/2/instances/[instance_name]/info`` +++++++++++++++++++++++++++++++++++++++ @@ -616,6 +1016,10 @@ Requests detailed information about the instance. An optional parameter, configuration without querying the instance's nodes. The result will be a job id. +Job result: + +.. opcode_result:: OP_INSTANCE_QUERY_DATA + ``/2/instances/[instance_name]/reboot`` +++++++++++++++++++++++++++++++++++++++ @@ -644,6 +1048,10 @@ instance even if secondary disks are failing. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_INSTANCE_REBOOT + ``/2/instances/[instance_name]/shutdown`` +++++++++++++++++++++++++++++++++++++++++ @@ -662,6 +1070,10 @@ It supports the ``dry-run`` argument. .. opcode_params:: OP_INSTANCE_SHUTDOWN :exclude: instance_name, dry_run +Job result: + +.. opcode_result:: OP_INSTANCE_SHUTDOWN + ``/2/instances/[instance_name]/startup`` ++++++++++++++++++++++++++++++++++++++++ @@ -680,6 +1092,11 @@ instance even if secondary disks are failing. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_INSTANCE_STARTUP + + ``/2/instances/[instance_name]/reinstall`` ++++++++++++++++++++++++++++++++++++++++++++++ @@ -716,16 +1133,19 @@ It supports the following commands: ``POST``. ``POST`` ~~~~~~~~ -Takes the parameters ``mode`` (one of ``replace_on_primary``, -``replace_on_secondary``, ``replace_new_secondary`` or -``replace_auto``), ``disks`` (comma separated list of disk indexes), -``remote_node`` and ``iallocator``. +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_REPLACE_DISKS + :exclude: instance_name + +Ganeti 2.4 and below used query parameters. Those are deprecated and +should no longer be used. -Either ``remote_node`` or ``iallocator`` needs to be defined when using -``mode=replace_new_secondary``. +Job result: -``mode`` is a mandatory parameter. ``replace_auto`` tries to determine -the broken disk(s) on its own and replacing it. +.. opcode_result:: OP_INSTANCE_REPLACE_DISKS ``/2/instances/[instance_name]/activate-disks`` @@ -741,6 +1161,10 @@ It supports the following commands: ``PUT``. Takes the bool parameter ``ignore_size``. When set ignore the recorded size (useful for forcing activation when recorded size is wrong). +Job result: + +.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS + ``/2/instances/[instance_name]/deactivate-disks`` +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -754,6 +1178,31 @@ It supports the following commands: ``PUT``. Takes no parameters. +Job result: + +.. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS + + +``/2/instances/[instance_name]/recreate-disks`` ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Recreate disks of an instance. Supports the following commands: +``POST``. + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_RECREATE_DISKS + :exclude: instance_name + +Job result: + +.. opcode_result:: OP_INSTANCE_RECREATE_DISKS + ``/2/instances/[instance_name]/disk/[disk_index]/grow`` +++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -772,6 +1221,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_GROW_DISK :exclude: instance_name, disk +Job result: + +.. opcode_result:: OP_INSTANCE_GROW_DISK + ``/2/instances/[instance_name]/prepare-export`` +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -785,6 +1238,10 @@ It supports the following commands: ``PUT``. Takes one parameter, ``mode``, for the export mode. Returns a job ID. +Job result: + +.. opcode_result:: OP_BACKUP_PREPARE + ``/2/instances/[instance_name]/export`` +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -804,6 +1261,10 @@ Body parameters: :exclude: instance_name :alias: target_node=destination +Job result: + +.. opcode_result:: OP_BACKUP_EXPORT + ``/2/instances/[instance_name]/migrate`` ++++++++++++++++++++++++++++++++++++++++ @@ -822,6 +1283,32 @@ Body parameters: .. opcode_params:: OP_INSTANCE_MIGRATE :exclude: instance_name, live +Job result: + +.. opcode_result:: OP_INSTANCE_MIGRATE + + +``/2/instances/[instance_name]/failover`` ++++++++++++++++++++++++++++++++++++++++++ + +Does a failover of an instance. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_FAILOVER + :exclude: instance_name + +Job result: + +.. opcode_result:: OP_INSTANCE_FAILOVER + ``/2/instances/[instance_name]/rename`` ++++++++++++++++++++++++++++++++++++++++ @@ -840,6 +1327,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_RENAME :exclude: instance_name +Job result: + +.. opcode_result:: OP_INSTANCE_RENAME + ``/2/instances/[instance_name]/modify`` ++++++++++++++++++++++++++++++++++++++++ @@ -858,13 +1349,25 @@ Body parameters: .. opcode_params:: OP_INSTANCE_SET_PARAMS :exclude: instance_name +Job result: + +.. opcode_result:: OP_INSTANCE_SET_PARAMS + ``/2/instances/[instance_name]/console`` ++++++++++++++++++++++++++++++++++++++++ Request information for connecting to instance's console. -Supports the following commands: ``GET``. +.. pyassert:: + + not (hasattr(rlib2.R_2_instances_name_console, "PUT") or + hasattr(rlib2.R_2_instances_name_console, "POST") or + hasattr(rlib2.R_2_instances_name_console, "DELETE")) + +Supports the following commands: ``GET``. Requires authentication with +one of the following options: +:pyeval:`utils.CommaJoin(rlib2.R_2_instances_name_console.GET_ACCESS)`. ``GET`` ~~~~~~~ @@ -872,22 +1375,35 @@ Supports the following commands: ``GET``. Returns a dictionary containing information about the instance's console. Contained keys: +.. pyassert:: + + constants.CONS_ALL == frozenset([ + constants.CONS_MESSAGE, + constants.CONS_SSH, + constants.CONS_VNC, + constants.CONS_SPICE, + ]) + ``instance`` - Instance name. + Instance name ``kind`` - Console type, one of ``ssh``, ``vnc`` or ``msg``. + Console type, one of :pyeval:`constants.CONS_SSH`, + :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE` + or :pyeval:`constants.CONS_MESSAGE` ``message`` - Message to display (``msg`` type only). + Message to display (:pyeval:`constants.CONS_MESSAGE` type only) ``host`` - Host to connect to (``ssh`` and ``vnc`` only). + Host to connect to (:pyeval:`constants.CONS_SSH`, + :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only) ``port`` - TCP port to connect to (``vnc`` only). + TCP port to connect to (:pyeval:`constants.CONS_VNC` or + :pyeval:`constants.CONS_SPICE` only) ``user`` - Username to use (``ssh`` only). + Username to use (:pyeval:`constants.CONS_SSH` only) ``command`` - Command to execute on machine (``ssh`` only) + Command to execute on machine (:pyeval:`constants.CONS_SSH` only) ``display`` - VNC display number (``vnc`` only). + VNC display number (:pyeval:`constants.CONS_VNC` only) ``/2/instances/[instance_name]/tags`` @@ -944,6 +1460,14 @@ Returns a dictionary of jobs. Returns: a dictionary with jobs id and uri. +If the optional bool *bulk* argument is provided and set to a true value +(i.e. ``?bulk=1``), the output contains detailed information about jobs +as a list. + +Returned fields for bulk requests (unlike other bulk requests, these +fields are not the same as for per-job requests): +:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`. + ``/2/jobs/[job_id]`` ++++++++++++++++++++ @@ -955,9 +1479,8 @@ It supports the following commands: ``GET``, ``DELETE``. ``GET`` ~~~~~~~ -Returns a job status. - -Returns: a dictionary with job parameters. +Returns a dictionary with job parameters, containing the fields +:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`. The result includes: @@ -990,7 +1513,7 @@ classification: errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES, errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT, errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT, - errors.ECODE_ENVIRON]) + errors.ECODE_ENVIRON, errors.ECODE_TEMP_NORES]) :pyeval:`errors.ECODE_RESOLVER` Resolver errors. This usually means that a name doesn't exist in DNS, @@ -1002,6 +1525,10 @@ classification: etc.). If the resources on the cluster increase, the operation might succeed. +:pyeval:`errors.ECODE_TEMP_NORES` + Simliar to :pyeval:`errors.ECODE_NORES`, but indicating the operation + should be attempted again after some time. + :pyeval:`errors.ECODE_INVAL` Wrong arguments (at syntax level). The operation will not ever be accepted unless the arguments change. @@ -1051,14 +1578,14 @@ Waits for changes on a job. Takes the following body parameters in a dict: ``fields`` - The job fields on which to watch for changes. + The job fields on which to watch for changes ``previous_job_info`` - Previously received field values or None if not yet available. + Previously received field values or None if not yet available ``previous_log_serial`` Highest log serial number received so far or None if not yet - available. + available Returns None if no changes have been detected and a dict with two keys, ``job_info`` and ``log_entries`` otherwise. @@ -1089,9 +1616,11 @@ Example:: } ] -If the optional 'bulk' argument is provided and set to 'true' value (i.e -'?bulk=1'), the output contains detailed information about nodes as a -list. +If the optional bool *bulk* argument is provided and set to a true value +(i.e ``?bulk=1``), the output contains detailed information about nodes +as a list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`. Example:: @@ -1106,9 +1635,10 @@ Example:: "dtotal": 5246208, "sinst_cnt": 2, "dfree": 5171712, - "offline": false + "offline": false, + … }, - ... + … ] ``/2/nodes/[node_name]`` @@ -1118,35 +1648,48 @@ Returns information about a node. It supports the following commands: ``GET``. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`. + +``/2/nodes/[node_name]/powercycle`` ++++++++++++++++++++++++++++++++++++ + +Powercycles a node. Supports the following commands: ``POST``. + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Job result: + +.. opcode_result:: OP_NODE_POWERCYCLE + + ``/2/nodes/[node_name]/evacuate`` +++++++++++++++++++++++++++++++++ -Evacuates all secondary instances off a node. +Evacuates instances off a node. It supports the following commands: ``POST``. ``POST`` ~~~~~~~~ -To evacuate a node, either one of the ``iallocator`` or ``remote_node`` -parameters must be passed:: +Returns a job ID. The result of the job will contain the IDs of the +individual jobs submitted to evacuate the node. - evacuate?iallocator=[iallocator] - evacuate?remote_node=[nodeX.example.com] +Body parameters: + +.. opcode_params:: OP_NODE_EVACUATE + :exclude: nodes -The result value will be a list, each element being a triple of the job -id (for this specific evacuation), the instance which is being evacuated -by this job, and the node to which it is being relocated. In case the -node is already empty, the result will be an empty list (without any -jobs being submitted). +Up to and including Ganeti 2.4 query arguments were used. Those are no +longer supported. The new request can be detected by the presence of the +:pyeval:`rlib2._NODE_EVAC_RES1` feature string. -And additional parameter ``early_release`` signifies whether to try to -parallelize the evacuations, at the risk of increasing I/O contention -and increasing the chances of data loss, if the primary node of any of -the instances being evacuated is not fully healthy. +Job result: -If the dry-run parameter was specified, then the evacuation jobs were -not actually submitted, and the job IDs will be null. +.. opcode_result:: OP_NODE_EVACUATE ``/2/nodes/[node_name]/migrate`` @@ -1160,13 +1703,18 @@ It supports the following commands: ``POST``. ~~~~~~~~ If no mode is explicitly specified, each instances' hypervisor default -migration mode will be used. Query parameters: +migration mode will be used. Body parameters: + +.. opcode_params:: OP_NODE_MIGRATE + :exclude: node_name -``live`` (bool) - If set, use live migration if available. -``mode`` (string) - Sets migration mode, ``live`` for live migration and ``non-live`` for - non-live migration. Supported by Ganeti 2.2 and above. +The query arguments used up to and including Ganeti 2.4 are deprecated +and should no longer be used. The new request format can be detected by +the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string. + +Job result: + +.. opcode_result:: OP_NODE_MIGRATE ``/2/nodes/[node_name]/role`` @@ -1179,11 +1727,14 @@ It supports the following commands: ``GET``, ``PUT``. The role is always one of the following: - drained - - master - master-candidate - offline - regular +Note that the 'master' role is a special, and currently it can't be +modified via RAPI, only via the command line (``gnt-cluster +master-failover``). + ``GET`` ~~~~~~~ @@ -1203,6 +1754,32 @@ be a job id. It supports the bool ``force`` argument. +Job result: + +.. opcode_result:: OP_NODE_SET_PARAMS + + +``/2/nodes/[node_name]/modify`` ++++++++++++++++++++++++++++++++ + +Modifies the parameters of a node. Supports the following commands: +``POST``. + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_NODE_SET_PARAMS + :exclude: node_name + +Job result: + +.. opcode_result:: OP_NODE_SET_PARAMS + + ``/2/nodes/[node_name]/storage`` ++++++++++++++++++++++++++++++++ @@ -1238,6 +1815,11 @@ and ``name`` (name of the storage unit). Parameters can be passed additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool) is supported. The result will be a job id. +Job result: + +.. opcode_result:: OP_NODE_MODIFY_STORAGE + + ``/2/nodes/[node_name]/storage/repair`` +++++++++++++++++++++++++++++++++++++++ @@ -1257,6 +1839,11 @@ Repairs a storage unit on the node. Requires the parameters repaired) and ``name`` (name of the storage unit). The result will be a job id. +Job result: + +.. opcode_result:: OP_REPAIR_NODE_STORAGE + + ``/2/nodes/[node_name]/tags`` +++++++++++++++++++++++++++++ @@ -1304,7 +1891,15 @@ pages and using ``/2/query/[resource]/fields``. The resource is one of :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2 design document ` for more details. -Supports the following commands: ``GET``, ``PUT``. +.. pyassert:: + + (rlib2.R_2_query.GET_ACCESS == rlib2.R_2_query.PUT_ACCESS and + not (hasattr(rlib2.R_2_query, "POST") or + hasattr(rlib2.R_2_query, "DELETE"))) + +Supports the following commands: ``GET``, ``PUT``. Requires +authentication with one of the following options: +:pyeval:`utils.CommaJoin(rlib2.R_2_query.GET_ACCESS)`. ``GET`` ~~~~~~~