Ganeti remote API
=================
-Documents Ganeti version 2.0
+Documents Ganeti version |version|
.. contents::
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. After modifying the password
+file, ``ganeti-rapi`` must be restarted.
+
+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 RFC2617_ ("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 RFC2617_ is supported.
.. _JSON: http://www.json.org/
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
+.. _RFC2617: http://tools.ietf.org/rfc/rfc2617.txt
+
+
+PUT or POST?
+------------
+
+According to RFC2616 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.
+
+``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.
+
+``dry-run``
++++++++++++
+
+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.
+
+``force``
++++++++++++
+
+Force operation to continue even if it will cause the cluster to become
+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.
Shell
+++++
+.. highlight:: sh
+
Using wget::
- wget -q -O - https://CLUSTERNAME:5080/2/info
+ wget -q -O - https://CLUSTERNAME:5080/2/info
or curl::
Python
++++++
+.. highlight:: python
+
::
import urllib2
- f = urllib2.urlopen('https://CLUSTERNAME:5080/info')
+ f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
print f.read()
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.
+.. 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.
+
+.. highlight:: javascript
::
- var url = 'https://CLUSTERNAME:5080/info';
+ var url = 'https://CLUSTERNAME:5080/2/info';
var info;
var xmlreq = new XMLHttpRequest();
xmlreq.onreadystatechange = function () {
Resources
---------
-.. include:: rapi-resources.gen
+.. highlight:: javascript
+
+``/``
++++++
+
+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.
+
+``/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.
+
+``/2/info``
++++++++++++
+
+Cluster information resource.
+
+It supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns cluster information.
+
+Example::
+
+ {
+ "config_version": 2000000,
+ "name": "cluster",
+ "software_version": "2.0.0~beta2",
+ "os_api_version": 10,
+ "export_version": 0,
+ "candidate_pool_size": 10,
+ "enabled_hypervisors": [
+ "fake"
+ ],
+ "hvparams": {
+ "fake": {}
+ },
+ "default_hypervisor": "fake",
+ "master": "node1.example.com",
+ "architecture": [
+ "64bit",
+ "x86_64"
+ ],
+ "protocol_version": 20,
+ "beparams": {
+ "default": {
+ "auto_balance": true,
+ "vcpus": 1,
+ "memory": 128
+ }
+ }
+ }
+
+
+``/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/instances``
+++++++++++++++++
+
+The instances resource.
+
+It supports the following commands: ``GET``, ``POST``.
+
+``GET``
+~~~~~~~
+
+Returns a list of all available instances.
+
+Example::
+
+ [
+ {
+ "name": "web.example.com",
+ "uri": "\/instances\/web.example.com"
+ },
+ {
+ "name": "mail.example.com",
+ "uri": "\/instances\/mail.example.com"
+ }
+ ]
+
+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.
+
+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
+ },
+ ...
+ ]
+
+
+``POST``
+~~~~~~~~
+
+Creates an instance.
+
+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.
+
+``/2/instances/[instance_name]``
+++++++++++++++++++++++++++++++++
+
+Instance-specific resource.
+
+It supports the following commands: ``GET``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns information about an instance, similar to the bulk output from
+the instance list.
+
+``DELETE``
+~~~~~~~~~~
+
+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``
++++++++++++++++++++++++++++++++++++++++
+
+Reboots URI for an instance.
+
+It supports the following commands: ``POST``.
+
+``POST``
+~~~~~~~~
+
+Reboots the instance.
+
+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.
+
+
+``/2/instances/[instance_name]/shutdown``
++++++++++++++++++++++++++++++++++++++++++
+
+Instance shutdown URI.
+
+It supports the following commands: ``PUT``.
+
+``PUT``
+~~~~~~~
+
+Shutdowns an instance.
+
+It supports the ``dry-run`` argument.
+
+
+``/2/instances/[instance_name]/startup``
+++++++++++++++++++++++++++++++++++++++++
+
+Instance startup URI.
+
+It supports the following commands: ``PUT``.
+
+``PUT``
+~~~~~~~
+
+Startup an instance.
+
+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``
+~~~~~~~~
+
+Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
+
+
+``/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]/tags``
++++++++++++++++++++++++++++++++++++++
+
+Manages per-instance tags.
+
+It 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/jobs``
++++++++++++
+
+The ``/2/jobs`` resource.
+
+It supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns a dictionary of jobs.
+
+Returns: a dictionary with jobs id and uri.
+
+``/2/jobs/[job_id]``
+++++++++++++++++++++
+
+
+Individual job URI.
+
+It supports the following commands: ``GET``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns a job status.
+
+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
+
+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:
+
+``resolver_error``
+ 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.
+
+``insufficient_resources``
+ Not enough resources (iallocator failure, disk space, memory,
+ etc.). If the resources on the cluster increase, the operation might
+ succeed.
+
+``wrong_input``
+ Wrong arguments (at syntax level). The operation will not ever be
+ accepted unless the arguments change.
+
+``wrong_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.
+
+``unknown_entity``
+ Entity not found. For example, information has been requested for an
+ unknown instance.
+
+``already_exists``
+ Entity already exists. For example, instance creation has been
+ requested for an already-existing instance.
+
+``resource_not_unique``
+ Resource not unique (e.g. MAC or IP duplication).
+
+``internal_error``
+ 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.
+
+``environment_error``
+ 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/nodes``
+++++++++++++
+
+Nodes resource.
+
+It supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns a list of all nodes.
+
+Example::
+
+ [
+ {
+ "id": "node1.example.com",
+ "uri": "\/nodes\/node1.example.com"
+ },
+ {
+ "id": "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.
+
+Example::
+
+ [
+ {
+ "pinst_cnt": 1,
+ "mfree": 31280,
+ "mtotal": 32763,
+ "name": "www.example.com",
+ "tags": [],
+ "mnode": 512,
+ "dtotal": 5246208,
+ "sinst_cnt": 2,
+ "dfree": 5171712,
+ "offline": false
+ },
+ ...
+ ]
+
+``/2/nodes/[node_name]``
++++++++++++++++++++++++++++++++++
+
+Returns information about a node.
+
+It supports the following commands: ``GET``.
+
+``/2/nodes/[node_name]/evacuate``
++++++++++++++++++++++++++++++++++
+
+Evacuates all secondary 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::
+
+ evacuate?iallocator=[iallocator]
+ evacuate?remote_node=[nodeX.example.com]
+
+``/2/nodes/[node_name]/migrate``
++++++++++++++++++++++++++++++++++
+
+Migrates all primary instances from a node.
+
+It supports the following commands: ``POST``.
+
+``POST``
+~~~~~~~~
+
+No parameters are required, but the bool parameter ``live`` can be set
+to use live migration (if available).
+
+ migrate?live=[0|1]
+
+``/2/nodes/[node_name]/role``
++++++++++++++++++++++++++++++
+
+Manages node role.
+
+It supports the following commands: ``GET``, ``PUT``.
+
+The role is always one of the following:
+
+ - drained
+ - master
+ - master-candidate
+ - offline
+ - regular
+
+``GET``
+~~~~~~~
+
+Returns the current node role.
+
+Example::
+
+ "master-candidate"
+
+``PUT``
+~~~~~~~
+
+Change the node role.
+
+The request is a string which should be PUT to this URI. The result will
+be a job id.
+
+It supports the bool ``force`` argument.
+
+``/2/nodes/[node_name]/storage``
+++++++++++++++++++++++++++++++++
+
+Manages storage units on the node.
+
+``GET``
+~~~~~~~
+
+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.
+
+``/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 ``file``, ``lvm-pv`` or ``lvm-vg``)
+and ``name`` (name of the storage unit). Parameters can be passed
+additionally. Currently only ``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``
+~~~~~~~
+
+Repairs a storage unit on the node. Requires the parameters
+``storage_type`` (currently only ``lvm-vg`` can be repaired) and
+``name`` (name of the storage unit). The result will be a job id.
+
+``/2/nodes/[node_name]/tags``
++++++++++++++++++++++++++++++
+
+Manages per-node tags.
+
+It 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``
+~~~~~~~~~~
+
+Deletes tags.
+
+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/os``
++++++++++
+
+OS resource.
+
+It supports the following commands: ``GET``.
+
+``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.
+
+Example::
+
+ ["debian-etch"]
+
+``/2/tags``
++++++++++++
+
+Manages cluster tags.
+
+It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns the cluster tags.
+
+Example::
+
+ ["tag1", "tag2", "tag3"]
+
+``PUT``
+~~~~~~~
+
+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.
+
+It supports the ``dry-run`` argument.
+
+
+``DELETE``
+~~~~~~~~~~
+
+Deletes tags.
+
+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.
+
+
+``/version``
+++++++++++++
+
+The version resource.
+
+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``.
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End:
projects / ganeti-local / blobdiff