X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/e987f166f35084ff9eaa4cb9ee791ed0c9cea101..995736c6ba6bfc22891ce281eac23fda2bfa66c9:/doc/rapi.rst diff --git a/doc/rapi.rst b/doc/rapi.rst index 2ab5afc..c80a309 100644 --- a/doc/rapi.rst +++ b/doc/rapi.rst @@ -53,8 +53,8 @@ Example:: .. [#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 @@ -239,30 +239,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`` +++++++++++ @@ -395,6 +378,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:: [ @@ -448,6 +433,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`` ~~~~~~~~~~ @@ -473,6 +460,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`` +++++++++++++++++++++++++++++++++ @@ -491,6 +482,10 @@ Body parameters: .. opcode_params:: OP_GROUP_RENAME :exclude: group_name +Job result: + +.. opcode_result:: OP_GROUP_RENAME + ``/2/groups/[group_name]/assign-nodes`` +++++++++++++++++++++++++++++++++++++++ @@ -579,6 +574,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 instances as a list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))` + Example:: [ @@ -634,6 +631,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]`` ++++++++++++++++++++++++++++++++ @@ -648,6 +649,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`` ~~~~~~~~~~ @@ -769,16 +772,15 @@ 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: -Either ``remote_node`` or ``iallocator`` needs to be defined when using -``mode=replace_new_secondary``. +.. opcode_params:: OP_INSTANCE_REPLACE_DISKS + :exclude: instance_name -``mode`` is a mandatory parameter. ``replace_auto`` tries to determine -the broken disk(s) on its own and replacing it. +Ganeti 2.4 and below used query parameters. Those are deprecated and +should no longer be used. ``/2/instances/[instance_name]/activate-disks`` @@ -808,6 +810,23 @@ It supports the following commands: ``PUT``. Takes no parameters. +``/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 + + ``/2/instances/[instance_name]/disk/[disk_index]/grow`` +++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -911,6 +930,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_RENAME :exclude: instance_name +Job result: + +.. opcode_result:: OP_INSTANCE_RENAME + ``/2/instances/[instance_name]/modify`` ++++++++++++++++++++++++++++++++++++++++ @@ -929,6 +952,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_SET_PARAMS :exclude: instance_name +Job result: + +.. opcode_result:: OP_INSTANCE_SET_PARAMS + ``/2/instances/[instance_name]/console`` ++++++++++++++++++++++++++++++++++++++++ @@ -943,22 +970,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. ``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`` @@ -1019,6 +1059,10 @@ 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]`` ++++++++++++++++++++ @@ -1030,9 +1074,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: @@ -1164,9 +1207,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:: @@ -1193,6 +1238,19 @@ 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. + + ``/2/nodes/[node_name]/evacuate`` +++++++++++++++++++++++++++++++++ @@ -1215,6 +1273,10 @@ 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. +Job result: + +.. opcode_result:: OP_NODE_EVACUATE + ``/2/nodes/[node_name]/migrate`` +++++++++++++++++++++++++++++++++ @@ -1236,6 +1298,10 @@ 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`` +++++++++++++++++++++++++++++ @@ -1274,6 +1340,28 @@ be a job id. It supports the bool ``force`` argument. + +``/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`` ++++++++++++++++++++++++++++++++