code.grnet.gr Git - ganeti-local/blob - 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