root / doc / client-api.txt @ c2c2a903
History | View | Annotate | Download (4.5 kB)
1 | e2618bc7 | Iustin Pop | Notes about the client api |
---|---|---|---|
2 | e2618bc7 | Iustin Pop | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3 | e2618bc7 | Iustin Pop | |
4 | e2618bc7 | Iustin Pop | Starting with Ganeti 1.3, the individual commands (gnt-...) do not |
5 | e2618bc7 | Iustin Pop | execute code directly, but instead via a master daemon. The |
6 | e2618bc7 | Iustin Pop | communication between these commands and the daemon will be language |
7 | e2618bc7 | Iustin Pop | agnostic, and we will be providing a python library implementing all |
8 | e2618bc7 | Iustin Pop | operations. |
9 | e2618bc7 | Iustin Pop | |
10 | e2618bc7 | Iustin Pop | TODO: add tags support, add gnt-instance info implementation, document |
11 | e2618bc7 | Iustin Pop | all results from query and all opcode fields |
12 | e2618bc7 | Iustin Pop | |
13 | e2618bc7 | Iustin Pop | Protocol |
14 | e2618bc7 | Iustin Pop | ======== |
15 | e2618bc7 | Iustin Pop | |
16 | e2618bc7 | Iustin Pop | The protocol for communication will consist of passing JSON-encoded |
17 | e2618bc7 | Iustin Pop | messages over a UNIX socket. The protocol will be send message, receive |
18 | e2618bc7 | Iustin Pop | message, send message, ..., etc. Each message (either request or |
19 | e2618bc7 | Iustin Pop | response) will end (after the JSON message) with a ``ETX`` character |
20 | e2618bc7 | Iustin Pop | (ascii decimal 3), which is not a valid character in JSON messages and |
21 | e2618bc7 | Iustin Pop | thus can serve as a message delimiter. Quoting from the |
22 | e2618bc7 | Iustin Pop | http://www.json.org grammar:: |
23 | e2618bc7 | Iustin Pop | |
24 | e2618bc7 | Iustin Pop | char: any unicode character except " or \ or control character |
25 | e2618bc7 | Iustin Pop | |
26 | e2618bc7 | Iustin Pop | There are three request types than can be done: |
27 | e2618bc7 | Iustin Pop | |
28 | e2618bc7 | Iustin Pop | - submit job; a job is a sequence of opcodes that modify the cluster |
29 | e2618bc7 | Iustin Pop | - abort a job; in some circumstances, a job can be aborted; the exact |
30 | e2618bc7 | Iustin Pop | conditions depend on the master daemon implementation and clients |
31 | e2618bc7 | Iustin Pop | should not rely on being able to abort jobs |
32 | e2618bc7 | Iustin Pop | - query objects; this is a generic form of query that works for all |
33 | e2618bc7 | Iustin Pop | object types |
34 | e2618bc7 | Iustin Pop | |
35 | e2618bc7 | Iustin Pop | All requests will be encoded as a JSON object, having three fields: |
36 | e2618bc7 | Iustin Pop | |
37 | e2618bc7 | Iustin Pop | - ``request``: string, one of ``submit``, ``abort``, ``query`` |
38 | e2618bc7 | Iustin Pop | - ``data``: the payload of the request, variable type based on request |
39 | e2618bc7 | Iustin Pop | - ``version``: the protocol version spoken by the client; we are |
40 | e2618bc7 | Iustin Pop | describing here the version 0 |
41 | e2618bc7 | Iustin Pop | |
42 | e2618bc7 | Iustin Pop | The response to any request will be a JSON object, with two fields: |
43 | e2618bc7 | Iustin Pop | |
44 | e2618bc7 | Iustin Pop | - ``success``: either ``true`` or ``false`` denoting whether the |
45 | e2618bc7 | Iustin Pop | request was successful or not |
46 | e2618bc7 | Iustin Pop | - ``result``: the result of the request (depends on request type) if |
47 | e2618bc7 | Iustin Pop | successful, otherwise the error message (describing the failure) |
48 | e2618bc7 | Iustin Pop | |
49 | e2618bc7 | Iustin Pop | The server has no defined upper-limit on the time it will take to |
50 | e2618bc7 | Iustin Pop | respond to a request, so the clients should implement their own timeout |
51 | e2618bc7 | Iustin Pop | handling. Note though that most requests should be answered quickly, if |
52 | e2618bc7 | Iustin Pop | the cluster is in a normal state. |
53 | e2618bc7 | Iustin Pop | |
54 | e2618bc7 | Iustin Pop | Submit |
55 | e2618bc7 | Iustin Pop | ------ |
56 | e2618bc7 | Iustin Pop | |
57 | e2618bc7 | Iustin Pop | The submit ``data`` field will be a JSON object - a (partial) Job |
58 | e2618bc7 | Iustin Pop | description. It will have the following fields: |
59 | e2618bc7 | Iustin Pop | |
60 | e2618bc7 | Iustin Pop | - ``opcode_list``: a list of opcode objects, see below |
61 | e2618bc7 | Iustin Pop | |
62 | e2618bc7 | Iustin Pop | The opcode objects supported will mostly be the ones supported by the |
63 | e2618bc7 | Iustin Pop | internal Ganeti implementation; currently there is no well-defined |
64 | e2618bc7 | Iustin Pop | definition of them (work in progress). |
65 | e2618bc7 | Iustin Pop | |
66 | e2618bc7 | Iustin Pop | Each opcode will be represented in the message list as an object: |
67 | e2618bc7 | Iustin Pop | |
68 | e2618bc7 | Iustin Pop | - ``OP_ID``: an opcode id; this will be equivalent to the ``OP_ID`` |
69 | e2618bc7 | Iustin Pop | class attribute on opcodes (in lib/opcodes.py) |
70 | e2618bc7 | Iustin Pop | - other fields: as needed by the opcode in question |
71 | e2618bc7 | Iustin Pop | |
72 | e2618bc7 | Iustin Pop | Small example, request:: |
73 | e2618bc7 | Iustin Pop | |
74 | e2618bc7 | Iustin Pop | { |
75 | e2618bc7 | Iustin Pop | "opcode_list": [ |
76 | e2618bc7 | Iustin Pop | { |
77 | e2618bc7 | Iustin Pop | "instance_name": "instance1.example.com", |
78 | e2618bc7 | Iustin Pop | "OP_ID": "OP_INSTANCE_SHUTDOWN" |
79 | e2618bc7 | Iustin Pop | } |
80 | e2618bc7 | Iustin Pop | ] |
81 | e2618bc7 | Iustin Pop | } |
82 | e2618bc7 | Iustin Pop | |
83 | e2618bc7 | Iustin Pop | And response:: |
84 | e2618bc7 | Iustin Pop | |
85 | e2618bc7 | Iustin Pop | { |
86 | e2618bc7 | Iustin Pop | "result": "1104", |
87 | e2618bc7 | Iustin Pop | "success": true |
88 | e2618bc7 | Iustin Pop | } |
89 | e2618bc7 | Iustin Pop | |
90 | e2618bc7 | Iustin Pop | The result of the submit request will be if successful, a single JSON |
91 | e2618bc7 | Iustin Pop | value denoting the job ID. While the job ID might be (or look like) an |
92 | e2618bc7 | Iustin Pop | integer, the clients should not depend on this and treat this ID as an |
93 | e2618bc7 | Iustin Pop | opaque identifier. |
94 | e2618bc7 | Iustin Pop | |
95 | e2618bc7 | Iustin Pop | Abort |
96 | e2618bc7 | Iustin Pop | ----- |
97 | e2618bc7 | Iustin Pop | |
98 | e2618bc7 | Iustin Pop | The abort request data will be a single job ID (as returned by submit or |
99 | e2618bc7 | Iustin Pop | query jobs). The result will hold no data (i.e. it will be a JSON |
100 | e2618bc7 | Iustin Pop | ``null`` value), if successful, and will be the error message if it |
101 | e2618bc7 | Iustin Pop | fails. |
102 | e2618bc7 | Iustin Pop | |
103 | e2618bc7 | Iustin Pop | Query |
104 | e2618bc7 | Iustin Pop | ----- |
105 | e2618bc7 | Iustin Pop | |
106 | e2618bc7 | Iustin Pop | The ``data`` argument to the query request is a JSON object containing: |
107 | e2618bc7 | Iustin Pop | |
108 | e2618bc7 | Iustin Pop | - ``object``: the object type to be queried |
109 | e2618bc7 | Iustin Pop | - ``names``: if querying a list of objects, this can restrict the |
110 | e2618bc7 | Iustin Pop | query to a subset of the entire list |
111 | e2618bc7 | Iustin Pop | - ``fields``: the list of informations that we are interested in |
112 | e2618bc7 | Iustin Pop | |
113 | e2618bc7 | Iustin Pop | The valid values for the ``object`` field is: |
114 | e2618bc7 | Iustin Pop | |
115 | e2618bc7 | Iustin Pop | - ``cluster`` |
116 | e2618bc7 | Iustin Pop | - ``node`` |
117 | e2618bc7 | Iustin Pop | - ``instance`` |
118 | e2618bc7 | Iustin Pop | |
119 | e2618bc7 | Iustin Pop | For the ``cluster`` object, the ``names`` parameter is unused and must |
120 | e2618bc7 | Iustin Pop | be null. |
121 | e2618bc7 | Iustin Pop | |
122 | e2618bc7 | Iustin Pop | The result value will be a list of lists: each row in the top-level list |
123 | e2618bc7 | Iustin Pop | will hold the result for a single object, and each row in the per-object |
124 | e2618bc7 | Iustin Pop | results will hold a result field, in the same order as the ``fields`` |
125 | e2618bc7 | Iustin Pop | value. |
126 | e2618bc7 | Iustin Pop | |
127 | e2618bc7 | Iustin Pop | Small example, request:: |
128 | e2618bc7 | Iustin Pop | |
129 | e2618bc7 | Iustin Pop | { |
130 | e2618bc7 | Iustin Pop | "data": { |
131 | e2618bc7 | Iustin Pop | "fields": [ |
132 | e2618bc7 | Iustin Pop | "name", |
133 | e2618bc7 | Iustin Pop | "admin_memory" |
134 | e2618bc7 | Iustin Pop | ], |
135 | e2618bc7 | Iustin Pop | "object": "instance" |
136 | e2618bc7 | Iustin Pop | }, |
137 | e2618bc7 | Iustin Pop | "request": "query" |
138 | e2618bc7 | Iustin Pop | } |
139 | e2618bc7 | Iustin Pop | |
140 | e2618bc7 | Iustin Pop | And response:: |
141 | e2618bc7 | Iustin Pop | |
142 | e2618bc7 | Iustin Pop | { |
143 | e2618bc7 | Iustin Pop | "result": [ |
144 | e2618bc7 | Iustin Pop | [ |
145 | e2618bc7 | Iustin Pop | "instance1.example.com", |
146 | e2618bc7 | Iustin Pop | "128" |
147 | e2618bc7 | Iustin Pop | ], |
148 | e2618bc7 | Iustin Pop | [ |
149 | e2618bc7 | Iustin Pop | "instance2.example.com", |
150 | e2618bc7 | Iustin Pop | "4096" |
151 | e2618bc7 | Iustin Pop | ] |
152 | e2618bc7 | Iustin Pop | ], |
153 | e2618bc7 | Iustin Pop | "success": true |
154 | e2618bc7 | Iustin Pop | } |