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