-------------------
``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.
+``/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
.. [#pwhash] Using the MD5 hash of username, realm and password is
- described in RFC2617_ ("HTTP Authentication"), sections 3.2.2.2 and
+ 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.
--------
The protocol used is JSON_ over HTTP designed after the REST_ principle.
-HTTP Basic authentication as per RFC2617_ is supported.
+HTTP Basic authentication as per :rfc:`2617` is supported.
.. _JSON: http://www.json.org/
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
-.. _RFC2617: http://tools.ietf.org/rfc/rfc2617.txt
A note on JSON as used by RAPI
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.
+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
``instance-create-reqv1``
Instance creation request data version 1 supported.
+``instance-reinstall-reqv1``
+ Instance reinstall supports body parameters.
+
+
+``/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:
+
+``name`` (string, required)
+ Node 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:
+
+``alloc_policy`` (string)
+ If present, the new allocation policy for the node group.
+
+
+``/2/groups/[group_name]/rename``
++++++++++++++++++++++++++++++++++
+
+Renames a node group.
+
+Supports the following commands: ``PUT``.
+
+``PUT``
+~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+``new_name`` (string, required)
+ New node group name.
``/2/instances``
will fail.
``force_variant`` (bool)
Whether to force an unknown variant.
+``no_install`` (bool)
+ Do not install the OS (will enable no-start)
``pnode`` (string)
Primary node.
``snode`` (string)
``POST``
~~~~~~~~
-Takes the parameters ``os`` (OS template name) and ``nostartup`` (bool).
+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``
``POST``
~~~~~~~~
-No parameters are required, but the bool parameter ``live`` can be set
-to use live migration (if available).
+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``
+++++++++++++++++++++++++++++
projects / ganeti-local / blobdiff