X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/7a95a954decb4c038ed8af4949fac9268bacfc33..7738342cc66200d0ed0f4b658f960a63a4da8a34:/doc/rapi.rst?ds=sidebyside diff --git a/doc/rapi.rst b/doc/rapi.rst index 09fab7a..337f36d 100644 --- a/doc/rapi.rst +++ b/doc/rapi.rst @@ -16,39 +16,145 @@ 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. + +Users and passwords +------------------- + +``ganeti-rapi`` reads users and passwords from a file (usually +``/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. + +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 +prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash +of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n +'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix +it with ``{ha1}``. Using the scheme prefix for all passwords is +recommended. Scheme prefixes are not case sensitive. + +Example:: + + # Give Jack and Fred read-only access + jack abc123 + fred {cleartext}foo555 + + # Give write access to an imaginary instance creation script + autocreator xyz789 write + + # Hashed password for Jessica + jessica {HA1}7046452df2cbb530877058712cf17bd4 write + + +.. [#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 + 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 + API``, can only be changed by modifying the source code. + + Protocol -------- -The protocol used is JSON_ over HTTP designed after the REST_ -principle. +The protocol used is JSON_ over HTTP designed after the REST_ principle. +HTTP Basic authentication as per :rfc:`2617` is supported. .. _JSON: http://www.json.org/ .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer + +A note on JSON as used by RAPI +++++++++++++++++++++++++++++++ + +JSON_ as used by Ganeti RAPI does not conform to the specification in +:rfc:`4627`. Section 2 defines a JSON text to be either an object +(``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation +of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for +some requests or responses. Changing this now would likely break +existing clients and cause a lot of trouble. + +.. highlight:: ruby + +Unlike Python's `JSON encoder and decoder +`_, other programming +languages or libraries may only provide a strict implementation, not +allowing plain values. For those, responses can usually be wrapped in an +array whose first element is then used, e.g. the response ``"1234"`` +becomes ``["1234"]``. This works equally well for more complex values. +Example in Ruby:: + + require "json" + + # Insert code to get response here + response = "\"1234\"" + + decoded = JSON.parse("[#{response}]").first + +Short of modifying the encoder to allow encoding to a less strict +format, requests will have to be formatted by hand. Newer RAPI requests +already use a dictionary as their input data and shouldn't cause any +problems. + + +PUT or POST? +------------ + +According to :rfc:`2616` the main difference between PUT and POST is +that POST can create new resources but PUT can only create the resource +the URI was pointing to on the PUT request. + +Unfortunately, due to historic reasons, the Ganeti RAPI library is not +consistent with this usage, so just use the methods as documented below +for each resource. + +For more details have a look in the source code at +``lib/rapi/rlib2.py``. + + +Generic parameter types +----------------------- + +A few generic refered parameter types and the values they allow. + +``bool`` +++++++++ + +A boolean option will accept ``1`` or ``0`` as numbers but not +i.e. ``True`` or ``False``. + Generic parameters ------------------ -A few parameter mean the same thing across all resources which implement it. +A few parameter mean the same thing across all resources which implement +it. ``bulk`` ++++++++ -Bulk-mode means that for the resources which usually return just a -list of child resources (e.g. ``/2/instances`` which returns just -instance names), the output will instead contain detailed data for all -these subresources. This is more efficient than query-ing the -sub-resources themselves. +Bulk-mode means that for the resources which usually return just a list +of child resources (e.g. ``/2/instances`` which returns just instance +names), the output will instead contain detailed data for all these +subresources. This is more efficient than query-ing the sub-resources +themselves. ``dry-run`` +++++++++++ -The optional *dry-run* argument, if provided and set to a positive -integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job -should not be executed, only the pre-execution checks will be done. +The boolean *dry-run* argument, if provided and set, signals to Ganeti +that the job should not be executed, only the pre-execution checks will +be done. -This is useful in trying to determine (without guarantees though, as -in the meantime the cluster state could have changed) if the operation -is likely to succeed or at least start executing. +This is useful in trying to determine (without guarantees though, as in +the meantime the cluster state could have changed) if the operation is +likely to succeed or at least start executing. ``force`` +++++++++++ @@ -59,8 +165,13 @@ inconsistent (e.g. because there are not enough master candidates). Usage examples -------------- -You can access the API using your favorite programming language as -long as it supports network connections. +You can access the API using your favorite programming language as long +as it supports network connections. + +Ganeti RAPI client +++++++++++++++++++ + +Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``. Shell +++++ @@ -79,7 +190,9 @@ or curl:: Python ++++++ -.. highlight: python +.. highlight:: python + +:: import urllib2 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info') @@ -90,9 +203,9 @@ JavaScript ++++++++++ .. warning:: While it's possible to use JavaScript, it poses several - potential problems, including browser blocking request due to - non-standard ports or different domain names. Fetching the data on - the webserver is easier. + potential problems, including browser blocking request due to + non-standard ports or different domain names. Fetching the data on + the webserver is easier. .. highlight:: javascript @@ -190,6 +303,196 @@ Example:: } } + +``/2/redistribute-config`` +++++++++++++++++++++++++++ + +Redistribute configuration to all nodes. + +It supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Redistribute configuration to all nodes. The result will be a job id. + + +``/2/features`` ++++++++++++++++ + +``GET`` +~~~~~~~ + +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. + + +``/2/modify`` +++++++++++++++++++++++++++++++++++++++++ + +Modifies cluster parameters. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_CLUSTER_SET_PARAMS + + +``/2/groups`` ++++++++++++++ + +The groups resource. + +It supports the following commands: ``GET``, ``POST``. + +``GET`` +~~~~~~~ + +Returns a list of all existing node groups. + +Example:: + + [ + { + "name": "group1", + "uri": "\/2\/groups\/group1" + }, + { + "name": "group2", + "uri": "\/2\/groups\/group2" + } + ] + +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. + +Example:: + + [ + { + "name": "group1", + "node_cnt": 2, + "node_list": [ + "node1.example.com", + "node2.example.com" + ], + "uuid": "0d7d407c-262e-49af-881a-6a430034bf43" + }, + { + "name": "group2", + "node_cnt": 1, + "node_list": [ + "node3.example.com" + ], + "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c" + } + ] + +``POST`` +~~~~~~~~ + +Creates a node group. + +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_GROUP_ADD + +Earlier versions used a parameter named ``name`` which, while still +supported, has been renamed to ``group_name``. + + +``/2/groups/[group_name]`` +++++++++++++++++++++++++++ + +Returns information about a node group. + +It supports the following commands: ``GET``, ``DELETE``. + +``GET`` +~~~~~~~ + +Returns information about a node group, similar to the bulk output from +the node group list. + +``DELETE`` +~~~~~~~~~~ + +Deletes a node group. + +It supports the ``dry-run`` argument. + + +``/2/groups/[group_name]/modify`` ++++++++++++++++++++++++++++++++++ + +Modifies the parameters of a node group. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_GROUP_SET_PARAMS + :exclude: group_name + + +``/2/groups/[group_name]/rename`` ++++++++++++++++++++++++++++++++++ + +Renames a node group. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_GROUP_RENAME + :exclude: group_name + + +``/2/groups/[group_name]/assign-nodes`` ++++++++++++++++++++++++++++++++++++++++ + +Assigns nodes to a group. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. It supports the ``dry-run`` and ``force`` arguments. + +Body parameters: + +.. opcode_params:: OP_GROUP_ASSIGN_NODES + :exclude: group_name, force, dry_run + + ``/2/instances`` ++++++++++++++++ @@ -215,7 +518,7 @@ Example:: } ] -If the optional *bulk* argument is provided and set to a true value +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. @@ -254,14 +557,27 @@ Example:: Creates an instance. -If the optional *dry-run* argument is provided and set to a positive -integer valu (e.g. ``?dry-run=1``), the job will not be actually -executed, only the pre-execution checks will be done. Query-ing the -job result will return, in both dry-run and normal case, the list of +If the optional bool *dry-run* argument is provided, the job will not be +actually executed, only the pre-execution checks will be done. Query-ing +the job result will return, in both dry-run and normal case, the list of nodes selected for the instance. Returns: a job ID that can be used later for polling. +Body parameters: + +``__version__`` (int, required) + Must be ``1`` (older Ganeti versions used a different format for + instance creation requests, version ``0``, but that format is not + documented and should no longer be used). + +.. opcode_params:: OP_INSTANCE_CREATE + +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. + + ``/2/instances/[instance_name]`` ++++++++++++++++++++++++++++++++ @@ -283,6 +599,20 @@ Deletes an instance. It supports the ``dry-run`` argument. +``/2/instances/[instance_name]/info`` ++++++++++++++++++++++++++++++++++++++++ + +It supports the following commands: ``GET``. + +``GET`` +~~~~~~~ + +Requests detailed information about the instance. An optional parameter, +``static`` (bool), can be set to return only static information from the +configuration without querying the instance's nodes. The result will be +a job id. + + ``/2/instances/[instance_name]/reboot`` +++++++++++++++++++++++++++++++++++++++ @@ -295,8 +625,18 @@ It supports the following commands: ``POST``. Reboots the instance. -The URI takes optional ``type=hard|soft|full`` and -``ignore_secondaries=False|True`` parameters. +The URI takes optional ``type=soft|hard|full`` and +``ignore_secondaries=0|1`` parameters. + +``type`` defines the reboot type. ``soft`` is just a normal reboot, +without terminating the hypervisor. ``hard`` means full shutdown +(including terminating the hypervisor process) and startup again. +``full`` is like ``hard`` but also recreates the configuration from +ground up as if you would have done a ``gnt-instance shutdown`` and +``gnt-instance start`` on it. + +``ignore_secondaries`` is a bool argument indicating if we start the +instance even if secondary disks are failing. It supports the ``dry-run`` argument. @@ -328,11 +668,220 @@ It supports the following commands: ``PUT``. Startup an instance. -The URI takes an optional ``force=False|True`` parameter to start the -instance if even if secondary disks are failing. +The URI takes an optional ``force=1|0`` parameter to start the +instance even if secondary disks are failing. It supports the ``dry-run`` argument. +``/2/instances/[instance_name]/reinstall`` +++++++++++++++++++++++++++++++++++++++++++++++ + +Installs the operating system again. + +It supports the following commands: ``POST``. + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +``os`` (string, required) + Instance operating system. +``start`` (bool, defaults to true) + Whether to start instance after reinstallation. +``osparams`` (dict) + Dictionary with (temporary) OS parameters. + +For backwards compatbility, this resource also takes the query +parameters ``os`` (OS template name) and ``nostartup`` (bool). New +clients should use the body parameters. + + +``/2/instances/[instance_name]/replace-disks`` +++++++++++++++++++++++++++++++++++++++++++++++ + +Replaces disks on an instance. + +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``. + +Either ``remote_node`` or ``iallocator`` needs to be defined when using +``mode=replace_new_secondary``. + +``mode`` is a mandatory parameter. ``replace_auto`` tries to determine +the broken disk(s) on its own and replacing it. + + +``/2/instances/[instance_name]/activate-disks`` ++++++++++++++++++++++++++++++++++++++++++++++++ + +Activate disks on an instance. + +It supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Takes the bool parameter ``ignore_size``. When set ignore the recorded +size (useful for forcing activation when recorded size is wrong). + + +``/2/instances/[instance_name]/deactivate-disks`` ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Deactivate disks on an instance. + +It supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Takes no parameters. + + +``/2/instances/[instance_name]/disk/[disk_index]/grow`` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Grows one disk of an instance. + +Supports the following commands: ``POST``. + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_GROW_DISK + :exclude: instance_name, disk + + +``/2/instances/[instance_name]/prepare-export`` ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Prepares an export of an instance. + +It supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Takes one parameter, ``mode``, for the export mode. Returns a job ID. + + +``/2/instances/[instance_name]/export`` ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Exports an instance. + +It supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_BACKUP_EXPORT + :exclude: instance_name + :alias: target_node=destination + + +``/2/instances/[instance_name]/migrate`` +++++++++++++++++++++++++++++++++++++++++ + +Migrates an instance. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_MIGRATE + :exclude: instance_name, live + + +``/2/instances/[instance_name]/rename`` +++++++++++++++++++++++++++++++++++++++++ + +Renames an instance. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_RENAME + :exclude: instance_name + + +``/2/instances/[instance_name]/modify`` +++++++++++++++++++++++++++++++++++++++++ + +Modifies an instance. + +Supports the following commands: ``PUT``. + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_SET_PARAMS + :exclude: instance_name + + +``/2/instances/[instance_name]/console`` +++++++++++++++++++++++++++++++++++++++++ + +Request information for connecting to instance's console. + +Supports the following commands: ``GET``. + +``GET`` +~~~~~~~ + +Returns a dictionary containing information about the instance's +console. Contained keys: + +``instance`` + Instance name. +``kind`` + Console type, one of ``ssh``, ``vnc`` or ``msg``. +``message`` + Message to display (``msg`` type only). +``host`` + Host to connect to (``ssh`` and ``vnc`` only). +``port`` + TCP port to connect to (``vnc`` only). +``user`` + Username to use (``ssh`` only). +``command`` + Command to execute on machine (``ssh`` only) +``display`` + VNC display number (``vnc`` only). + ``/2/instances/[instance_name]/tags`` +++++++++++++++++++++++++++++++++++++ @@ -356,7 +905,7 @@ Example:: Add a set of tags. The request as a list of strings should be ``PUT`` to this URI. The -result willl be a job id. +result will be a job id. It supports the ``dry-run`` argument. @@ -366,8 +915,8 @@ It supports the ``dry-run`` argument. Delete a tag. -In order to delete a set of tags, the DELETE request should be -addressed to URI like:: +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: /tags?tag=[tag]&tag=[tag] @@ -407,16 +956,107 @@ The result includes: - id: job ID as a number - status: current job status as a string -- ops: involved OpCodes as a list of dictionaries for each - opcodes in the job +- ops: involved OpCodes as a list of dictionaries for each opcodes in + the job - opstatus: OpCodes status as a list -- opresult: OpCodes results as a list of lists +- opresult: OpCodes results as a list + +For a successful opcode, the ``opresult`` field corresponding to it will +contain the raw result from its :term:`LogicalUnit`. In case an opcode +has failed, its element in the opresult list will be a list of two +elements: + +- first element the error type (the Ganeti internal error name) +- second element a list of either one or two elements: + + - the first element is the textual error description + - the second element, if any, will hold an error classification + +The error classification is most useful for the ``OpPrereqError`` +error type - these errors happen before the OpCode has started +executing, so it's possible to retry the OpCode without side +effects. But whether it make sense to retry depends on the error +classification: + +.. pyassert:: + + 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]) + +:pyeval:`errors.ECODE_RESOLVER` + Resolver errors. This usually means that a name doesn't exist in DNS, + so if it's a case of slow DNS propagation the operation can be retried + later. + +:pyeval:`errors.ECODE_NORES` + Not enough resources (iallocator failure, disk space, memory, + etc.). If the resources on the cluster increase, the operation might + succeed. + +:pyeval:`errors.ECODE_INVAL` + Wrong arguments (at syntax level). The operation will not ever be + accepted unless the arguments change. + +:pyeval:`errors.ECODE_STATE` + Wrong entity state. For example, live migration has been requested for + a down instance, or instance creation on an offline node. The + operation can be retried once the resource has changed state. + +:pyeval:`errors.ECODE_NOENT` + Entity not found. For example, information has been requested for an + unknown instance. + +:pyeval:`errors.ECODE_EXISTS` + Entity already exists. For example, instance creation has been + requested for an already-existing instance. + +:pyeval:`errors.ECODE_NOTUNIQUE` + Resource not unique (e.g. MAC or IP duplication). + +:pyeval:`errors.ECODE_FAULT` + Internal cluster error. For example, a node is unreachable but not set + offline, or the ganeti node daemons are not working, etc. A + ``gnt-cluster verify`` should be run. + +:pyeval:`errors.ECODE_ENVIRON` + Environment error (e.g. node disk error). A ``gnt-cluster verify`` + should be run. + +Note that in the above list, by entity we refer to a node or instance, +while by a resource we refer to an instance's disk, or NIC, etc. + ``DELETE`` ~~~~~~~~~~ Cancel a not-yet-started job. + +``/2/jobs/[job_id]/wait`` ++++++++++++++++++++++++++ + +``GET`` +~~~~~~~ + +Waits for changes on a job. Takes the following body parameters in a +dict: + +``fields`` + The job fields on which to watch for changes. + +``previous_job_info`` + 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. + +Returns None if no changes have been detected and a dict with two keys, +``job_info`` and ``log_entries`` otherwise. + + ``/2/nodes`` ++++++++++++ @@ -434,17 +1074,17 @@ Example:: [ { "id": "node1.example.com", - "uri": "\/instances\/node1.example.com" + "uri": "\/nodes\/node1.example.com" }, { "id": "node2.example.com", - "uri": "\/instances\/node2.example.com" + "uri": "\/nodes\/node2.example.com" } ] -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 'bulk' argument is provided and set to 'true' value (i.e +'?bulk=1'), the output contains detailed information about nodes as a +list. Example:: @@ -464,6 +1104,13 @@ Example:: ... ] +``/2/nodes/[node_name]`` ++++++++++++++++++++++++++++++++++ + +Returns information about a node. + +It supports the following commands: ``GET``. + ``/2/nodes/[node_name]/evacuate`` +++++++++++++++++++++++++++++++++ @@ -475,11 +1122,26 @@ It supports the following commands: ``POST``. ~~~~~~~~ To evacuate a node, either one of the ``iallocator`` or ``remote_node`` -parameters must be passed: +parameters must be passed:: evacuate?iallocator=[iallocator] evacuate?remote_node=[nodeX.example.com] +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). + +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. + +If the dry-run parameter was specified, then the evacuation jobs were +not actually submitted, and the job IDs will be null. + + ``/2/nodes/[node_name]/migrate`` +++++++++++++++++++++++++++++++++ @@ -490,9 +1152,15 @@ It supports the following commands: ``POST``. ``POST`` ~~~~~~~~ -No parameters are required, but ``live`` can be set to a boolean value. +If no mode is explicitly specified, each instances' hypervisor default +migration mode will be used. Query parameters: + +``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. - migrate?live=[0|1] ``/2/nodes/[node_name]/role`` +++++++++++++++++++++++++++++ @@ -523,10 +1191,10 @@ Example:: Change the node role. -The request is a string which should be PUT to this URI. The result will be a -job id. +The request is a string which should be PUT to this URI. The result will +be a job id. -It supports the ``force`` argument. +It supports the bool ``force`` argument. ``/2/nodes/[node_name]/storage`` ++++++++++++++++++++++++++++++++ @@ -536,10 +1204,51 @@ Manages storage units on the node. ``GET`` ~~~~~~~ +.. pyassert:: + + constants.VALID_STORAGE_TYPES == set([constants.ST_FILE, + constants.ST_LVM_PV, + constants.ST_LVM_VG]) + Requests a list of storage units on a node. Requires the parameters -``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and -``output_fields``. The result will be a job id, using which the result can be -retrieved. +``storage_type`` (one of :pyeval:`constants.ST_FILE`, +:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and +``output_fields``. The result will be a job id, using which the result +can be retrieved. + +``/2/nodes/[node_name]/storage/modify`` ++++++++++++++++++++++++++++++++++++++++ + +Modifies storage units on the node. + +``PUT`` +~~~~~~~ + +Modifies parameters of storage units on the node. Requires the +parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`, +:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) +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. + +``/2/nodes/[node_name]/storage/repair`` ++++++++++++++++++++++++++++++++++++++++ + +Repairs a storage unit on the node. + +``PUT`` +~~~~~~~ + +.. pyassert:: + + constants.VALID_STORAGE_OPERATIONS == { + constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]), + } + +Repairs a storage unit on the node. Requires the parameters +``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be +repaired) and ``name`` (name of the storage unit). The result will be a +job id. ``/2/nodes/[node_name]/tags`` +++++++++++++++++++++++++++++ @@ -572,8 +1281,8 @@ It supports the ``dry-run`` argument. Deletes tags. -In order to delete a set of tags, the DELETE request should be -addressed to URI like:: +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: /tags?tag=[tag]&tag=[tag] @@ -593,8 +1302,7 @@ It supports the following commands: ``GET``. Return a list of all OSes. Can return error 500 in case of a problem. Since this is a costly -operation for Ganeti 2.0, it is not recommended to execute it too -often. +operation for Ganeti 2.0, it is not recommended to execute it too often. Example:: @@ -632,8 +1340,8 @@ It supports the ``dry-run`` argument. Deletes tags. -In order to delete a set of tags, the DELETE request should be -addressed to URI like:: +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: /tags?tag=[tag]&tag=[tag] @@ -645,13 +1353,19 @@ It supports the ``dry-run`` argument. The version resource. -This resource should be used to determine the remote API version and -to adapt clients accordingly. +This resource should be used to determine the remote API version and to +adapt clients accordingly. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ -Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti -2.0 returns ``2``. +Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0 +returns ``2``. + +.. vim: set textwidth=72 : +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: