Revision e2618bc7

b/doc/client-api.txt
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

  

Also available in: Unified diff