root / doc / design-2.0-rapi-changes.rst @ c2b05d85
History | View | Annotate | Download (3.8 kB)
1 | a72b3711 | Oleksiy Mishchenko | Ganeti Remote API |
---|---|---|---|
2 | a72b3711 | Oleksiy Mishchenko | ================= |
3 | a72b3711 | Oleksiy Mishchenko | |
4 | a72b3711 | Oleksiy Mishchenko | .. contents:: |
5 | a72b3711 | Oleksiy Mishchenko | |
6 | a72b3711 | Oleksiy Mishchenko | Objective |
7 | a72b3711 | Oleksiy Mishchenko | --------- |
8 | a72b3711 | Oleksiy Mishchenko | The Ganeti RAPI provides limited remote control over Ganeti-cluster for |
9 | a72b3711 | Oleksiy Mishchenko | third-party applications, exposing internal Ganeti functionality via RESTful |
10 | a72b3711 | Oleksiy Mishchenko | API. |
11 | a72b3711 | Oleksiy Mishchenko | |
12 | a72b3711 | Oleksiy Mishchenko | |
13 | a72b3711 | Oleksiy Mishchenko | Goals |
14 | a72b3711 | Oleksiy Mishchenko | ~~~~~ |
15 | a72b3711 | Oleksiy Mishchenko | |
16 | a72b3711 | Oleksiy Mishchenko | - Provide functionality for remote cluster management. |
17 | a72b3711 | Oleksiy Mishchenko | |
18 | a72b3711 | Oleksiy Mishchenko | - Expose current cluster state |
19 | a72b3711 | Oleksiy Mishchenko | |
20 | a72b3711 | Oleksiy Mishchenko | - Must be extensible and revolvable in design |
21 | a72b3711 | Oleksiy Mishchenko | |
22 | a72b3711 | Oleksiy Mishchenko | - Restrict access |
23 | a72b3711 | Oleksiy Mishchenko | |
24 | a72b3711 | Oleksiy Mishchenko | |
25 | a72b3711 | Oleksiy Mishchenko | Requirements |
26 | a72b3711 | Oleksiy Mishchenko | ~~~~~~~~~~~~ |
27 | a72b3711 | Oleksiy Mishchenko | |
28 | a72b3711 | Oleksiy Mishchenko | - Authentication |
29 | a72b3711 | Oleksiy Mishchenko | |
30 | a72b3711 | Oleksiy Mishchenko | - Encryption |
31 | a72b3711 | Oleksiy Mishchenko | |
32 | a72b3711 | Oleksiy Mishchenko | - Language independent |
33 | a72b3711 | Oleksiy Mishchenko | |
34 | a72b3711 | Oleksiy Mishchenko | - Reliable and easy to use |
35 | a72b3711 | Oleksiy Mishchenko | |
36 | a72b3711 | Oleksiy Mishchenko | |
37 | a72b3711 | Oleksiy Mishchenko | Background |
38 | a72b3711 | Oleksiy Mishchenko | ---------- |
39 | a72b3711 | Oleksiy Mishchenko | |
40 | a72b3711 | Oleksiy Mishchenko | A growing amount of installations can shortly put ganeti based infrastructure |
41 | a72b3711 | Oleksiy Mishchenko | on manageable edge. Therefore the is strong need to centralize clusters |
42 | a72b3711 | Oleksiy Mishchenko | management, provide information for the "best placement" and cluster |
43 | a72b3711 | Oleksiy Mishchenko | rebalancing decisions. |
44 | a72b3711 | Oleksiy Mishchenko | |
45 | a72b3711 | Oleksiy Mishchenko | The first Ganeti RAPI was designed and deployed with the Ganeti 1.2.5 release. |
46 | a72b3711 | Oleksiy Mishchenko | That version provide Read-Only access to a cluster state. Fully functional |
47 | a72b3711 | Oleksiy Mishchenko | read-write API demand significant internal changes which are in a pipeline for |
48 | a72b3711 | Oleksiy Mishchenko | Ganeti 2.0 release. |
49 | a72b3711 | Oleksiy Mishchenko | |
50 | a72b3711 | Oleksiy Mishchenko | Overview |
51 | a72b3711 | Oleksiy Mishchenko | -------- |
52 | a72b3711 | Oleksiy Mishchenko | |
53 | a72b3711 | Oleksiy Mishchenko | We decided to go with implementing the Ganeti RAPI in a RESTful way, which is |
54 | a72b3711 | Oleksiy Mishchenko | aligned with key features we looking. It is simple, stateless, scalable and |
55 | a72b3711 | Oleksiy Mishchenko | extensible paradigm of API implementation. As transport it uses HTTP over SSL, |
56 | a72b3711 | Oleksiy Mishchenko | and we are implementing it in JSON encoding, but in a way it possible to extend |
57 | a72b3711 | Oleksiy Mishchenko | and provide any other one. |
58 | a72b3711 | Oleksiy Mishchenko | |
59 | a72b3711 | Oleksiy Mishchenko | Design |
60 | a72b3711 | Oleksiy Mishchenko | ------- |
61 | a72b3711 | Oleksiy Mishchenko | |
62 | a72b3711 | Oleksiy Mishchenko | The Ganeti API implemented as independent daemon, running on the same node |
63 | a72b3711 | Oleksiy Mishchenko | with the same permission level as Ganeti master daemon. Communication done |
64 | a72b3711 | Oleksiy Mishchenko | through unix socket protocol provided by Ganeti luxi library. |
65 | a72b3711 | Oleksiy Mishchenko | In order to keep communication asynchronous RAPI process two types of client |
66 | a72b3711 | Oleksiy Mishchenko | requests: |
67 | a72b3711 | Oleksiy Mishchenko | |
68 | a72b3711 | Oleksiy Mishchenko | - queries: sever able to answer immediately |
69 | a72b3711 | Oleksiy Mishchenko | - jobs: some time needed. |
70 | a72b3711 | Oleksiy Mishchenko | |
71 | a72b3711 | Oleksiy Mishchenko | In the query case requested data send back to client in http body. Typical |
72 | a72b3711 | Oleksiy Mishchenko | examples of queries would be list of nodes, instances, cluster info, etc. |
73 | a72b3711 | Oleksiy Mishchenko | Dealing with jobs client instead of waiting until job completes receive a job |
74 | a72b3711 | Oleksiy Mishchenko | id, the identifier which allows to query the job progress in the job queue. |
75 | a72b3711 | Oleksiy Mishchenko | (See job queue design doc for details) |
76 | a72b3711 | Oleksiy Mishchenko | |
77 | a72b3711 | Oleksiy Mishchenko | Internally, each exported object has an version identifier, which is used as a |
78 | a72b3711 | Oleksiy Mishchenko | state stamp in the http header E-Tag field for request/response to avoid a race |
79 | a72b3711 | Oleksiy Mishchenko | condition. |
80 | a72b3711 | Oleksiy Mishchenko | |
81 | a72b3711 | Oleksiy Mishchenko | |
82 | a72b3711 | Oleksiy Mishchenko | Resource representation |
83 | a72b3711 | Oleksiy Mishchenko | ~~~~~~~~~~~~~~~~~~~~~~~ |
84 | a72b3711 | Oleksiy Mishchenko | The key difference of REST approach from others API is instead having one URI |
85 | a72b3711 | Oleksiy Mishchenko | for all our requests, REST demand separate service by resources with unique |
86 | a72b3711 | Oleksiy Mishchenko | URI. Each of them should have limited amount of stateless and standard HTTP |
87 | a72b3711 | Oleksiy Mishchenko | methods: GET, POST, DELETE, PUT. |
88 | a72b3711 | Oleksiy Mishchenko | |
89 | a72b3711 | Oleksiy Mishchenko | For example in Ganeti case we can have a set of URI: |
90 | a72b3711 | Oleksiy Mishchenko | - /{clustername}/instances |
91 | a72b3711 | Oleksiy Mishchenko | - /{clustername}/instances/{instancename} |
92 | a72b3711 | Oleksiy Mishchenko | - /{clustername}/instances/{instancename}/tag |
93 | a72b3711 | Oleksiy Mishchenko | - /{clustername}/tag |
94 | a72b3711 | Oleksiy Mishchenko | |
95 | a72b3711 | Oleksiy Mishchenko | A GET request to /{clustername}/instances will return list of instances, a POST |
96 | a72b3711 | Oleksiy Mishchenko | to /{clustername}/instances should create new instance, a DELETE |
97 | a72b3711 | Oleksiy Mishchenko | /{clustername}/instances/{instancename} should delete instance, a GET |
98 | a72b3711 | Oleksiy Mishchenko | /{clustername}/tag get cluster tag |
99 | a72b3711 | Oleksiy Mishchenko | |
100 | a72b3711 | Oleksiy Mishchenko | Each resource URI has a version prefix. The complete list of resources id TBD. |
101 | a72b3711 | Oleksiy Mishchenko | |
102 | a72b3711 | Oleksiy Mishchenko | Internal encoding might be JSON, XML, or any other. The JSON encoding fits |
103 | a72b3711 | Oleksiy Mishchenko | nicely in Ganeti RAPI needs. Specific representation client can request with |
104 | a72b3711 | Oleksiy Mishchenko | Accept field in the HTTP header. |
105 | a72b3711 | Oleksiy Mishchenko | |
106 | a72b3711 | Oleksiy Mishchenko | The REST uses standard HTTP as application protocol (not just as a transport) |
107 | a72b3711 | Oleksiy Mishchenko | for resources access. Set of possible result codes is a subset of standard HTTP |
108 | a72b3711 | Oleksiy Mishchenko | results. The stateless provide additional reliability and transparency to |
109 | a72b3711 | Oleksiy Mishchenko | operations. |
110 | a72b3711 | Oleksiy Mishchenko | |
111 | a72b3711 | Oleksiy Mishchenko | |
112 | a72b3711 | Oleksiy Mishchenko | Security |
113 | a72b3711 | Oleksiy Mishchenko | ~~~~~~~~ |
114 | a72b3711 | Oleksiy Mishchenko | With the write functionality security becomes much bigger an issue. The Ganeti |
115 | a72b3711 | Oleksiy Mishchenko | RAPI uses basic HTTP authentication on top of SSL connection to grant access to |
116 | a72b3711 | Oleksiy Mishchenko | an exported resource. The password stores locally in Apache-style .htpasswd |
117 | a72b3711 | Oleksiy Mishchenko | file. Only one level of privileges is supported. |