code.grnet.gr Git - ganeti-local/blob - doc/rapi.rst

   1 Ganeti remote API
   2 =================
   3
   4 Documents Ganeti version |version|
   5
   6 .. contents::
   7
   8 Introduction
   9 ------------
  10
  11 Ganeti supports a remote API for enable external tools to easily
  12 retrieve information about a cluster's state. The remote API daemon,
  13 *ganeti-rapi*, is automatically started on the master node. By default
  14 it runs on TCP port 5080, but this can be changed either in
  15 ``.../constants.py`` or via the command line parameter *-p*. SSL mode,
  16 which is used by default, can also be disabled by passing command line
  17 parameters.
  18
  19 Protocol
  20 --------
  21
  22 The protocol used is JSON_ over HTTP designed after the REST_
  23 principle.
  24
  25 .. _JSON: http://www.json.org/
  26 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
  27
  28 Usage examples
  29 --------------
  30
  31 You can access the API using your favorite programming language as
  32 long as it supports network connections.
  33
  34 Shell
  35 +++++
  36
  37 .. highlight:: sh
  38
  39 Using wget::
  40
  41    wget -q -O - https://CLUSTERNAME:5080/2/info
  42
  43 or curl::
  44
  45   curl https://CLUSTERNAME:5080/2/info
  46
  47
  48 Python
  49 ++++++
  50
  51 .. highlight: python
  52
  53   import urllib2
  54   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
  55   print f.read()
  56
  57
  58 JavaScript
  59 ++++++++++
  60
  61 .. warning:: While it's possible to use JavaScript, it poses several potential
  62   problems, including browser blocking request due to
  63   non-standard ports or different domain names. Fetching the data
  64   on the webserver is easier.
  65
  66 .. highlight:: javascript
  67
  68 ::
  69
  70   var url = 'https://CLUSTERNAME:5080/2/info';
  71   var info;
  72   var xmlreq = new XMLHttpRequest();
  73   xmlreq.onreadystatechange = function () {
  74     if (xmlreq.readyState != 4) return;
  75     if (xmlreq.status == 200) {
  76       info = eval("(" + xmlreq.responseText + ")");
  77       alert(info);
  78     } else {
  79       alert('Error fetching cluster info');
  80     }
  81     xmlreq = null;
  82   };
  83   xmlreq.open('GET', url, true);
  84   xmlreq.send(null);
  85
  86 Resources
  87 ---------
  88
  89 .. highlight:: javascript
  90
  91 ``/``
  92 +++++
  93
  94 The root resource.
  95
  96 It supports the following commands: ``GET``.
  97
  98 ``GET``
  99 ~~~~~~~
 100
 101 Shows the list of mapped resources.
 102
 103 Returns: a dictionary with 'name' and 'uri' keys for each of them.
 104
 105 ``/2``
 106 ++++++
 107
 108 The ``/2`` resource, the root of the version 2 API.
 109
 110 It supports the following commands: ``GET``.
 111
 112 ``GET``
 113 ~~~~~~~
 114
 115 Show the list of mapped resources.
 116
 117 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
 118
 119 ``/2/info``
 120 +++++++++++
 121
 122 Cluster information resource.
 123
 124 It supports the following commands: ``GET``.
 125
 126 ``GET``
 127 ~~~~~~~
 128
 129 Returns cluster information.
 130
 131 Example::
 132
 133   {
 134     "config_version": 2000000,
 135     "name": "cluster",
 136     "software_version": "2.0.0~beta2",
 137     "os_api_version": 10,
 138     "export_version": 0,
 139     "candidate_pool_size": 10,
 140     "enabled_hypervisors": [
 141       "fake"
 142     ],
 143     "hvparams": {
 144       "fake": {}
 145      },
 146     "default_hypervisor": "fake",
 147     "master": "node1.example.com",
 148     "architecture": [
 149       "64bit",
 150       "x86_64"
 151     ],
 152     "protocol_version": 20,
 153     "beparams": {
 154       "default": {
 155         "auto_balance": true,
 156         "vcpus": 1,
 157         "memory": 128
 158        }
 159       }
 160     }
 161
 162 ``/2/instances``
 163 ++++++++++++++++
 164
 165 The instances resource.
 166
 167 It supports the following commands: ``GET``, ``POST``.
 168
 169 ``GET``
 170 ~~~~~~~
 171
 172 Returns a list of all available instances.
 173
 174
 175 Example::
 176
 177     [
 178       {
 179         "name": "web.example.com",
 180         "uri": "\/instances\/web.example.com"
 181       },
 182       {
 183         "name": "mail.example.com",
 184         "uri": "\/instances\/mail.example.com"
 185       }
 186     ]
 187
 188 If the optional *bulk* argument is provided and set to a true value
 189 (i.e ``?bulk=1``), the output contains detailed information about
 190 instances as a list.
 191
 192 Example::
 193
 194     [
 195       {
 196          "status": "running",
 197          "disk_usage": 20480,
 198          "nic.bridges": [
 199            "xen-br0"
 200           ],
 201          "name": "web.example.com",
 202          "tags": ["tag1", "tag2"],
 203          "beparams": {
 204            "vcpus": 2,
 205            "memory": 512
 206          },
 207          "disk.sizes": [
 208              20480
 209          ],
 210          "pnode": "node1.example.com",
 211          "nic.macs": ["01:23:45:67:89:01"],
 212          "snodes": ["node2.example.com"],
 213          "disk_template": "drbd",
 214          "admin_state": true,
 215          "os": "debian-etch",
 216          "oper_state": true
 217       },
 218       ...
 219     ]
 220
 221
 222 ``POST``
 223 ~~~~~~~~
 224
 225 Creates an instance.
 226
 227 Returns: a job ID that can be used later for polling.
 228
 229 ``/2/instances/[instance_name]``
 230 ++++++++++++++++++++++++++++++++
 231
 232 Instance-specific resource.
 233
 234 It supports the following commands: ``GET``, ``DELETE``.
 235
 236 ``GET``
 237 ~~~~~~~
 238
 239 Returns information about an instance, similar to the bulk output from
 240 the instance list.
 241
 242 ``DELETE``
 243 ~~~~~~~~~~
 244
 245 Deletes an instance.
 246
 247
 248 ``/2/instances/[instance_name]/reboot``
 249 +++++++++++++++++++++++++++++++++++++++
 250
 251 Reboots URI for an instance.
 252
 253 It supports the following commands: ``POST``.
 254
 255 ``POST``
 256 ~~~~~~~~
 257
 258 Reboots the instance.
 259
 260 The URI takes optional ``type=hard|soft|full`` and
 261 ``ignore_secondaries=False|True`` parameters.
 262
 263 ``/2/instances/[instance_name]/shutdown``
 264 +++++++++++++++++++++++++++++++++++++++++
 265
 266 Instance shutdown URI.
 267
 268 It supports the following commands: ``PUT``.
 269
 270 ``PUT``
 271 ~~~~~~~
 272
 273 Shutdowns an instance.
 274
 275
 276 ``/2/instances/[instance_name]/startup``
 277 ++++++++++++++++++++++++++++++++++++++++
 278
 279 Instance startup URI.
 280
 281 It supports the following commands: ``PUT``.
 282
 283 ``PUT``
 284 ~~~~~~~
 285
 286 Startup an instance.
 287
 288 The URI takes an optional ``force=False|True`` parameter to start the
 289 instance if even if secondary disks are failing.
 290
 291 ``/2/instances/[instance_name]/tags``
 292 +++++++++++++++++++++++++++++++++++++
 293
 294 Manages per-instance tags.
 295
 296 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 297
 298 ``GET``
 299 ~~~~~~~
 300
 301 Returns a list of tags.
 302
 303 Example::
 304
 305     ["tag1", "tag2", "tag3"]
 306
 307 ``PUT``
 308 ~~~~~~~
 309
 310 Add a set of tags.
 311
 312 The request as a list of strings should be ``PUT`` to this URI. The
 313 result willl be a job id.
 314
 315 ``DELETE``
 316 ~~~~~~~~~~
 317
 318 Delete a tag.
 319
 320 In order to delete a set of tags, the DELETE request should be
 321 addressed to URI like::
 322
 323     /tags?tag=[tag]&tag=[tag]
 324
 325 ``/2/jobs``
 326 +++++++++++
 327
 328 The ``/2/jobs`` resource.
 329
 330 It supports the following commands: ``GET``.
 331
 332 ``GET``
 333 ~~~~~~~
 334
 335 Returns a dictionary of jobs.
 336
 337 Returns: a dictionary with jobs id and uri.
 338
 339 ``/2/jobs/[job_id]``
 340 ++++++++++++++++++++
 341
 342
 343 Individual job URI.
 344
 345 It supports the following commands: ``GET``, ``DELETE``.
 346
 347 ``GET``
 348 ~~~~~~~
 349
 350 Returns a job status.
 351
 352 Returns: a dictionary with job parameters.
 353
 354 The result includes:
 355
 356 - id: job ID as a number
 357 - status: current job status as a string
 358 - ops: involved OpCodes as a list of dictionaries for each
 359   opcodes in the job
 360 - opstatus: OpCodes status as a list
 361 - opresult: OpCodes results as a list of lists
 362
 363 ``DELETE``
 364 ~~~~~~~~~~
 365
 366 Cancel a not-yet-started job.
 367
 368 ``/2/nodes``
 369 ++++++++++++
 370
 371 Nodes resource.
 372
 373 It supports the following commands: ``GET``.
 374
 375 ``GET``
 376 ~~~~~~~
 377
 378 Returns a list of all nodes.
 379
 380 Example::
 381
 382     [
 383       {
 384         "id": "node1.example.com",
 385         "uri": "\/instances\/node1.example.com"
 386       },
 387       {
 388         "id": "node2.example.com",
 389         "uri": "\/instances\/node2.example.com"
 390       }
 391     ]
 392
 393 If the optional 'bulk' argument is provided and set to 'true' value
 394 (i.e '?bulk=1'), the output contains detailed information about nodes
 395 as a list.
 396
 397 Example::
 398
 399     [
 400       {
 401         "pinst_cnt": 1,
 402         "mfree": 31280,
 403         "mtotal": 32763,
 404         "name": "www.example.com",
 405         "tags": [],
 406         "mnode": 512,
 407         "dtotal": 5246208,
 408         "sinst_cnt": 2,
 409         "dfree": 5171712,
 410         "offline": false
 411       },
 412       ...
 413     ]
 414
 415 ``/2/nodes/[node_name]/tags``
 416 +++++++++++++++++++++++++++++
 417
 418 Manages per-node tags.
 419
 420 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 421
 422 ``GET``
 423 ~~~~~~~
 424
 425 Returns a list of tags.
 426
 427 Example::
 428
 429     ["tag1", "tag2", "tag3"]
 430
 431 ``PUT``
 432 ~~~~~~~
 433
 434 Add a set of tags.
 435
 436 The request as a list of strings should be PUT to this URI. The result
 437 will be a job id.
 438
 439 ``DELETE``
 440 ~~~~~~~~~~
 441
 442 Deletes tags.
 443
 444 In order to delete a set of tags, the DELETE request should be
 445 addressed to URI like::
 446
 447     /tags?tag=[tag]&tag=[tag]
 448
 449 ``/2/os``
 450 +++++++++
 451
 452 OS resource.
 453
 454 It supports the following commands: ``GET``.
 455
 456 ``GET``
 457 ~~~~~~~
 458
 459 Return a list of all OSes.
 460
 461 Can return error 500 in case of a problem. Since this is a costly
 462 operation for Ganeti 2.0, it is not recommended to execute it too
 463 often.
 464
 465 Example::
 466
 467     ["debian-etch"]
 468
 469 ``/2/tags``
 470 +++++++++++
 471
 472 Manages cluster tags.
 473
 474 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 475
 476 ``GET``
 477 ~~~~~~~
 478
 479 Returns the cluster tags.
 480
 481 Example::
 482
 483     ["tag1", "tag2", "tag3"]
 484
 485 ``PUT``
 486 ~~~~~~~
 487
 488 Adds a set of tags.
 489
 490 The request as a list of strings should be PUT to this URI. The result
 491 will be a job id.
 492
 493 ``DELETE``
 494 ~~~~~~~~~~
 495
 496 Deletes tags.
 497
 498 In order to delete a set of tags, the DELETE request should be
 499 addressed to URI like::
 500
 501     /tags?tag=[tag]&tag=[tag]
 502
 503 ``/version``
 504 ++++++++++++
 505
 506 The version resource.
 507
 508 This resource should be used to determine the remote API version and
 509 to adapt clients accordingly.
 510
 511 It supports the following commands: ``GET``.
 512
 513 ``GET``
 514 ~~~~~~~
 515
 516 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
 517 2.0 returns ``2``.