X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/c1be3f59a5bfcfcf35c0817f0535870adb5ec774..c8fcde472922e4ee664d904e0bf1a583f1d5040d:/doc/rapi.rst diff --git a/doc/rapi.rst b/doc/rapi.rst index be57b01..8138637 100644 --- a/doc/rapi.rst +++ b/doc/rapi.rst @@ -1,7 +1,7 @@ Ganeti remote API ================= -Documents Ganeti version 2.0 +Documents Ganeti version |version| .. contents:: @@ -34,9 +34,11 @@ long as it supports network connections. Shell +++++ +.. highlight:: sh + Using wget:: - wget -q -O - https://CLUSTERNAME:5080/2/info + wget -q -O - https://CLUSTERNAME:5080/2/info or curl:: @@ -46,7 +48,7 @@ or curl:: Python ++++++ -:: +.. highlight: python import urllib2 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info') @@ -61,6 +63,8 @@ JavaScript non-standard ports or different domain names. Fetching the data on the webserver is easier. +.. highlight:: javascript + :: var url = 'https://CLUSTERNAME:5080/2/info'; @@ -82,59 +86,49 @@ JavaScript Resources --------- -/ -+ - -:: - - / resource. - -It supports the following commands: GET. +.. highlight:: javascript -GET -~~~ +``/`` ++++++ -:: +The root resource. - Show the list of mapped resources. +It supports the following commands: ``GET``. - Returns: a dictionary with 'name' and 'uri' keys for each of them. +``GET`` +~~~~~~~ -/2 -++ +Shows the list of mapped resources. -:: +Returns: a dictionary with 'name' and 'uri' keys for each of them. - /2 resource, the root of the version 2 API. +``/2`` +++++++ -It supports the following commands: GET. +The ``/2`` resource, the root of the version 2 API. -GET -~~~ +It supports the following commands: ``GET``. -:: +``GET`` +~~~~~~~ - Show the list of mapped resources. +Show the list of mapped resources. - Returns: a dictionary with 'name' and 'uri' keys for each of them. +Returns: a dictionary with ``name`` and ``uri`` keys for each of them. -/2/info -+++++++ +``/2/info`` ++++++++++++ -:: +Cluster information resource. - Cluster info. +It supports the following commands: ``GET``. -It supports the following commands: GET. +``GET`` +~~~~~~~ -GET -~~~ +Returns cluster information. -:: - - Returns cluster information. - - Example:: +Example:: { "config_version": 2000000, @@ -165,24 +159,20 @@ GET } } -/2/instances -++++++++++++ - -:: +``/2/instances`` +++++++++++++++++ - /2/instances resource. +The instances resource. -It supports the following commands: GET, POST. +It supports the following commands: ``GET``, ``POST``. -GET -~~~ +``GET`` +~~~~~~~ -:: +Returns a list of all available instances. - Returns a list of all available instances. - - Example:: +Example:: [ { @@ -195,11 +185,11 @@ GET } ] - If the optional 'bulk' argument is provided and set to 'true' - value (i.e '?bulk=1'), the output contains detailed - information about instances as a list. +If the optional *bulk* argument is provided and set to a true value +(i.e ``?bulk=1``), the output contains detailed information about +instances as a list. - Example:: +Example:: [ { @@ -228,216 +218,166 @@ GET ... ] - Returns: a dictionary with 'name' and 'uri' keys for each of them. - -POST -~~~~ - -:: - - Create an instance. - - Returns: a job id - -/2/instances/[instance_name] -++++++++++++++++++++++++++++ - -:: - - /2/instances/[instance_name] resources. - -It supports the following commands: GET, DELETE. - -GET -~~~ - -:: - - Send information about an instance. - - - -DELETE -~~~~~~ - -:: - - Delete an instance. - - - -/2/instances/[instance_name]/reboot -+++++++++++++++++++++++++++++++++++ - -:: - - /2/instances/[instance_name]/reboot resource. - - Implements an instance reboot. - -It supports the following commands: POST. - -POST -~~~~ - -:: - - Reboot an instance. - The URI takes type=[hard|soft|full] and - ignore_secondaries=[False|True] parameters. +``POST`` +~~~~~~~~ -/2/instances/[instance_name]/shutdown -+++++++++++++++++++++++++++++++++++++ +Creates an instance. -:: +Returns: a job ID that can be used later for polling. - /2/instances/[instance_name]/shutdown resource. +``/2/instances/[instance_name]`` +++++++++++++++++++++++++++++++++ - Implements an instance shutdown. +Instance-specific resource. -It supports the following commands: PUT. +It supports the following commands: ``GET``, ``DELETE``. -PUT -~~~ +``GET`` +~~~~~~~ -:: +Returns information about an instance, similar to the bulk output from +the instance list. - Shutdown an instance. +``DELETE`` +~~~~~~~~~~ +Deletes an instance. -/2/instances/[instance_name]/startup -++++++++++++++++++++++++++++++++++++ +``/2/instances/[instance_name]/reboot`` ++++++++++++++++++++++++++++++++++++++++ -:: +Reboots URI for an instance. - /2/instances/[instance_name]/startup resource. +It supports the following commands: ``POST``. - Implements an instance startup. +``POST`` +~~~~~~~~ -It supports the following commands: PUT. +Reboots the instance. -PUT -~~~ +The URI takes optional ``type=hard|soft|full`` and +``ignore_secondaries=False|True`` parameters. -:: +``/2/instances/[instance_name]/shutdown`` ++++++++++++++++++++++++++++++++++++++++++ - Startup an instance. +Instance shutdown URI. - The URI takes force=[False|True] parameter to start the instance - if even if secondary disks are failing. +It supports the following commands: ``PUT``. -/2/instances/[instance_name]/tags -+++++++++++++++++++++++++++++++++ +``PUT`` +~~~~~~~ -:: +Shutdowns an instance. - /2/instances/[instance_name]/tags resource. - Manages per-instance tags. +``/2/instances/[instance_name]/startup`` +++++++++++++++++++++++++++++++++++++++++ -It supports the following commands: GET, PUT, DELETE. +Instance startup URI. -GET -~~~ +It supports the following commands: ``PUT``. -:: +``PUT`` +~~~~~~~ - Returns a list of tags. +Startup an instance. - Example: ["tag1", "tag2", "tag3"] +The URI takes an optional ``force=False|True`` parameter to start the +instance if even if secondary disks are failing. -PUT -~~~ +``/2/instances/[instance_name]/tags`` ++++++++++++++++++++++++++++++++++++++ -:: +Manages per-instance tags. - Add a set of tags. +It supports the following commands: ``GET``, ``PUT``, ``DELETE``. - The request as a list of strings should be PUT to this URI. And - you'll have back a job id. +``GET`` +~~~~~~~ -DELETE -~~~~~~ +Returns a list of tags. -:: +Example:: - Delete a tag. + ["tag1", "tag2", "tag3"] - In order to delete a set of tags, the DELETE - request should be addressed to URI like: - /tags?tag=[tag]&tag=[tag] +``PUT`` +~~~~~~~ -/2/jobs -+++++++ +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. - /2/jobs resource. +``DELETE`` +~~~~~~~~~~ -It supports the following commands: GET. +Delete a tag. -GET -~~~ +In order to delete a set of tags, the DELETE request should be +addressed to URI like:: -:: + /tags?tag=[tag]&tag=[tag] - Returns a dictionary of jobs. +``/2/jobs`` ++++++++++++ - Returns: a dictionary with jobs id and uri. +The ``/2/jobs`` resource. -/2/jobs/[job_id] -++++++++++++++++ +It supports the following commands: ``GET``. -:: +``GET`` +~~~~~~~ - /2/jobs/[job_id] resource. +Returns a dictionary of jobs. -It supports the following commands: GET, DELETE. +Returns: a dictionary with jobs id and uri. -GET -~~~ +``/2/jobs/[job_id]`` +++++++++++++++++++++ -:: - Returns a job status. +Individual job URI. - Returns: a dictionary with job parameters. - 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 - - opstatus: OpCodes status as a list - - opresult: OpCodes results as a list of lists +It supports the following commands: ``GET``, ``DELETE``. -DELETE -~~~~~~ +``GET`` +~~~~~~~ -:: +Returns a job status. - Cancel not-yet-started job. +Returns: a dictionary with job parameters. +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 +- opstatus: OpCodes status as a list +- opresult: OpCodes results as a list of lists -/2/nodes -++++++++ +``DELETE`` +~~~~~~~~~~ -:: +Cancel a not-yet-started job. - /2/nodes resource. +``/2/nodes`` +++++++++++++ -It supports the following commands: GET. +Nodes resource. -GET -~~~ +It supports the following commands: ``GET``. -:: +``GET`` +~~~~~~~ - Returns a list of all nodes. +Returns a list of all nodes. - Example:: +Example:: [ { @@ -450,11 +390,11 @@ GET } ] - 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:: +Example:: [ { @@ -472,143 +412,106 @@ GET ... ] - Returns: a dictionary with 'name' and 'uri' keys for each of them - -/2/nodes/[node_name]/tags -+++++++++++++++++++++++++ - -:: - - /2/nodes/[node_name]/tags resource. - - Manages per-node tags. - -It supports the following commands: GET, PUT, DELETE. - -GET -~~~ - -:: - - Returns a list of tags. +``/2/nodes/[node_name]/tags`` ++++++++++++++++++++++++++++++ - Example: ["tag1", "tag2", "tag3"] +Manages per-node tags. -PUT -~~~ +It supports the following commands: ``GET``, ``PUT``, ``DELETE``. -:: +``GET`` +~~~~~~~ - Add a set of tags. +Returns a list of tags. - The request as a list of strings should be PUT to this URI. And - you'll have back a job id. +Example:: -DELETE -~~~~~~ + ["tag1", "tag2", "tag3"] -:: +``PUT`` +~~~~~~~ - 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] - -/2/os -+++++ +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. - /2/os resource. +``DELETE`` +~~~~~~~~~~ -It supports the following commands: GET. +Deletes tags. -GET -~~~ +In order to delete a set of tags, the DELETE request should be +addressed to URI like:: -:: + /tags?tag=[tag]&tag=[tag] - Return a list of all OSes. +``/2/os`` ++++++++++ - Can return error 500 in case of a problem. +OS resource. - Example: ["debian-etch"] +It supports the following commands: ``GET``. -/2/tags -+++++++ +``GET`` +~~~~~~~ -:: +Return a list of all OSes. - /2/instances/tags resource. +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. - Manages cluster tags. +Example:: -It supports the following commands: GET, PUT, DELETE. + ["debian-etch"] -GET -~~~ +``/2/tags`` ++++++++++++ -:: +Manages cluster tags. - Returns a list of tags. +It supports the following commands: ``GET``, ``PUT``, ``DELETE``. - Example: ["tag1", "tag2", "tag3"] +``GET`` +~~~~~~~ -PUT -~~~ +Returns the cluster tags. -:: +Example:: - Add a set of tags. + ["tag1", "tag2", "tag3"] - The request as a list of strings should be PUT to this URI. And - you'll have back a job id. +``PUT`` +~~~~~~~ -DELETE -~~~~~~ +Adds a set of tags. -:: +The request as a list of strings should be PUT to this URI. The result +will be a job id. - Delete a tag. +``DELETE`` +~~~~~~~~~~ - In order to delete a set of tags, the DELETE - request should be addressed to URI like: - /tags?tag=[tag]&tag=[tag] +Deletes tags. -/nodes/[node_name] -++++++++++++++++++ +In order to delete a set of tags, the DELETE request should be +addressed to URI like:: -:: + /tags?tag=[tag]&tag=[tag] - /2/nodes/[node_name] resources. - -It supports the following commands: GET. - -GET -~~~ - -:: - - Send information about a node. - - - -/version -++++++++ - -:: - - /version resource. +``/version`` +++++++++++++ - This resource should be used to determine the remote API version and - to adapt clients accordingly. +The version resource. -It supports the following commands: GET. +This resource should be used to determine the remote API version and +to adapt clients accordingly. -GET -~~~ +It supports the following commands: ``GET``. -:: +``GET`` +~~~~~~~ - Returns the remote API version. +Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti +2.0 returns ``2``.