Commit a72b3711 authored by Oleksiy Mishchenko's avatar Oleksiy Mishchenko
Browse files

RAPI Desing Doc

Reviewed-by: iustinp
parent ec5c88dc
......@@ -112,7 +112,8 @@ docrst = \
doc/design-2.0-index.rst \
doc/design-2.0-job-queue.rst \
doc/design-2.0-locking.rst \
doc/design-2.0-master-daemon.rst
doc/design-2.0-master-daemon.rst \
doc/design-2.0-rapi-changes.rst
doc_DATA = \
$(patsubst %.rst,%.html,$(docrst)) \
......
Ganeti Remote API
=================
.. contents::
Objective
---------
The Ganeti RAPI provides limited remote control over Ganeti-cluster for
third-party applications, exposing internal Ganeti functionality via RESTful
API.
Goals
~~~~~
- Provide functionality for remote cluster management.
- Expose current cluster state
- Must be extensible and revolvable in design
- Restrict access
Requirements
~~~~~~~~~~~~
- Authentication
- Encryption
- Language independent
- Reliable and easy to use
Background
----------
A growing amount of installations can shortly put ganeti based infrastructure
on manageable edge. Therefore the is strong need to centralize clusters
management, provide information for the "best placement" and cluster
rebalancing decisions.
The first Ganeti RAPI was designed and deployed with the Ganeti 1.2.5 release.
That version provide Read-Only access to a cluster state. Fully functional
read-write API demand significant internal changes which are in a pipeline for
Ganeti 2.0 release.
Overview
--------
We decided to go with implementing the Ganeti RAPI in a RESTful way, which is
aligned with key features we looking. It is simple, stateless, scalable and
extensible paradigm of API implementation. As transport it uses HTTP over SSL,
and we are implementing it in JSON encoding, but in a way it possible to extend
and provide any other one.
Design
-------
The Ganeti API implemented as independent daemon, running on the same node
with the same permission level as Ganeti master daemon. Communication done
through unix socket protocol provided by Ganeti luxi library.
In order to keep communication asynchronous RAPI process two types of client
requests:
- queries: sever able to answer immediately
- jobs: some time needed.
In the query case requested data send back to client in http body. Typical
examples of queries would be list of nodes, instances, cluster info, etc.
Dealing with jobs client instead of waiting until job completes receive a job
id, the identifier which allows to query the job progress in the job queue.
(See job queue design doc for details)
Internally, each exported object has an version identifier, which is used as a
state stamp in the http header E-Tag field for request/response to avoid a race
condition.
Resource representation
~~~~~~~~~~~~~~~~~~~~~~~
The key difference of REST approach from others API is instead having one URI
for all our requests, REST demand separate service by resources with unique
URI. Each of them should have limited amount of stateless and standard HTTP
methods: GET, POST, DELETE, PUT.
For example in Ganeti case we can have a set of URI:
- /{clustername}/instances
- /{clustername}/instances/{instancename}
- /{clustername}/instances/{instancename}/tag
- /{clustername}/tag
A GET request to /{clustername}/instances will return list of instances, a POST
to /{clustername}/instances should create new instance, a DELETE
/{clustername}/instances/{instancename} should delete instance, a GET
/{clustername}/tag get cluster tag
Each resource URI has a version prefix. The complete list of resources id TBD.
Internal encoding might be JSON, XML, or any other. The JSON encoding fits
nicely in Ganeti RAPI needs. Specific representation client can request with
Accept field in the HTTP header.
The REST uses standard HTTP as application protocol (not just as a transport)
for resources access. Set of possible result codes is a subset of standard HTTP
results. The stateless provide additional reliability and transparency to
operations.
Security
~~~~~~~~
With the write functionality security becomes much bigger an issue. The Ganeti
RAPI uses basic HTTP authentication on top of SSL connection to grant access to
an exported resource. The password stores locally in Apache-style .htpasswd
file. Only one level of privileges is supported.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment