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 Generic parameters
  29 ------------------
  30
  31 A few parameter mean the same thing across all resources which implement it.
  32
  33 ``bulk``
  34 ++++++++
  35
  36 Bulk-mode means that for the resources which usually return just a
  37 list of child resources (e.g. ``/2/instances`` which returns just
  38 instance names), the output will instead contain detailed data for all
  39 these subresources. This is more efficient than query-ing the
  40 sub-resources themselves.
  41
  42 ``dry-run``
  43 +++++++++++
  44
  45 The optional *dry-run* argument, if provided and set to a positive
  46 integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
  47 should not be executed, only the pre-execution checks will be done.
  48
  49 This is useful in trying to determine (without guarantees though, as
  50 in the meantime the cluster state could have changed) if the operation
  51 is likely to succeed or at least start executing.
  52
  53 ``force``
  54 +++++++++++
  55
  56 Force operation to continue even if it will cause the cluster to become
  57 inconsistent (e.g. because there are not enough master candidates).
  58
  59 Usage examples
  60 --------------
  61
  62 You can access the API using your favorite programming language as
  63 long as it supports network connections.
  64
  65 Shell
  66 +++++
  67
  68 .. highlight:: sh
  69
  70 Using wget::
  71
  72    wget -q -O - https://CLUSTERNAME:5080/2/info
  73
  74 or curl::
  75
  76   curl https://CLUSTERNAME:5080/2/info
  77
  78
  79 Python
  80 ++++++
  81
  82 .. highlight: python
  83
  84   import urllib2
  85   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
  86   print f.read()
  87
  88
  89 JavaScript
  90 ++++++++++
  91
  92 .. warning:: While it's possible to use JavaScript, it poses several
  93   potential problems, including browser blocking request due to
  94   non-standard ports or different domain names. Fetching the data on
  95   the webserver is easier.
  96
  97 .. highlight:: javascript
  98
  99 ::
 100
 101   var url = 'https://CLUSTERNAME:5080/2/info';
 102   var info;
 103   var xmlreq = new XMLHttpRequest();
 104   xmlreq.onreadystatechange = function () {
 105     if (xmlreq.readyState != 4) return;
 106     if (xmlreq.status == 200) {
 107       info = eval("(" + xmlreq.responseText + ")");
 108       alert(info);
 109     } else {
 110       alert('Error fetching cluster info');
 111     }
 112     xmlreq = null;
 113   };
 114   xmlreq.open('GET', url, true);
 115   xmlreq.send(null);
 116
 117 Resources
 118 ---------
 119
 120 .. highlight:: javascript
 121
 122 ``/``
 123 +++++
 124
 125 The root resource.
 126
 127 It supports the following commands: ``GET``.
 128
 129 ``GET``
 130 ~~~~~~~
 131
 132 Shows the list of mapped resources.
 133
 134 Returns: a dictionary with 'name' and 'uri' keys for each of them.
 135
 136 ``/2``
 137 ++++++
 138
 139 The ``/2`` resource, the root of the version 2 API.
 140
 141 It supports the following commands: ``GET``.
 142
 143 ``GET``
 144 ~~~~~~~
 145
 146 Show the list of mapped resources.
 147
 148 Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
 149
 150 ``/2/info``
 151 +++++++++++
 152
 153 Cluster information resource.
 154
 155 It supports the following commands: ``GET``.
 156
 157 ``GET``
 158 ~~~~~~~
 159
 160 Returns cluster information.
 161
 162 Example::
 163
 164   {
 165     "config_version": 2000000,
 166     "name": "cluster",
 167     "software_version": "2.0.0~beta2",
 168     "os_api_version": 10,
 169     "export_version": 0,
 170     "candidate_pool_size": 10,
 171     "enabled_hypervisors": [
 172       "fake"
 173     ],
 174     "hvparams": {
 175       "fake": {}
 176      },
 177     "default_hypervisor": "fake",
 178     "master": "node1.example.com",
 179     "architecture": [
 180       "64bit",
 181       "x86_64"
 182     ],
 183     "protocol_version": 20,
 184     "beparams": {
 185       "default": {
 186         "auto_balance": true,
 187         "vcpus": 1,
 188         "memory": 128
 189        }
 190       }
 191     }
 192
 193 ``/2/instances``
 194 ++++++++++++++++
 195
 196 The instances resource.
 197
 198 It supports the following commands: ``GET``, ``POST``.
 199
 200 ``GET``
 201 ~~~~~~~
 202
 203 Returns a list of all available instances.
 204
 205 Example::
 206
 207     [
 208       {
 209         "name": "web.example.com",
 210         "uri": "\/instances\/web.example.com"
 211       },
 212       {
 213         "name": "mail.example.com",
 214         "uri": "\/instances\/mail.example.com"
 215       }
 216     ]
 217
 218 If the optional *bulk* argument is provided and set to a true value
 219 (i.e ``?bulk=1``), the output contains detailed information about
 220 instances as a list.
 221
 222 Example::
 223
 224     [
 225       {
 226          "status": "running",
 227          "disk_usage": 20480,
 228          "nic.bridges": [
 229            "xen-br0"
 230           ],
 231          "name": "web.example.com",
 232          "tags": ["tag1", "tag2"],
 233          "beparams": {
 234            "vcpus": 2,
 235            "memory": 512
 236          },
 237          "disk.sizes": [
 238              20480
 239          ],
 240          "pnode": "node1.example.com",
 241          "nic.macs": ["01:23:45:67:89:01"],
 242          "snodes": ["node2.example.com"],
 243          "disk_template": "drbd",
 244          "admin_state": true,
 245          "os": "debian-etch",
 246          "oper_state": true
 247       },
 248       ...
 249     ]
 250
 251
 252 ``POST``
 253 ~~~~~~~~
 254
 255 Creates an instance.
 256
 257 If the optional *dry-run* argument is provided and set to a positive
 258 integer valu (e.g. ``?dry-run=1``), the job will not be actually
 259 executed, only the pre-execution checks will be done. Query-ing the
 260 job result will return, in both dry-run and normal case, the list of
 261 nodes selected for the instance.
 262
 263 Returns: a job ID that can be used later for polling.
 264
 265 ``/2/instances/[instance_name]``
 266 ++++++++++++++++++++++++++++++++
 267
 268 Instance-specific resource.
 269
 270 It supports the following commands: ``GET``, ``DELETE``.
 271
 272 ``GET``
 273 ~~~~~~~
 274
 275 Returns information about an instance, similar to the bulk output from
 276 the instance list.
 277
 278 ``DELETE``
 279 ~~~~~~~~~~
 280
 281 Deletes an instance.
 282
 283 It supports the ``dry-run`` argument.
 284
 285
 286 ``/2/instances/[instance_name]/reboot``
 287 +++++++++++++++++++++++++++++++++++++++
 288
 289 Reboots URI for an instance.
 290
 291 It supports the following commands: ``POST``.
 292
 293 ``POST``
 294 ~~~~~~~~
 295
 296 Reboots the instance.
 297
 298 The URI takes optional ``type=hard|soft|full`` and
 299 ``ignore_secondaries=False|True`` parameters.
 300
 301 It supports the ``dry-run`` argument.
 302
 303
 304 ``/2/instances/[instance_name]/shutdown``
 305 +++++++++++++++++++++++++++++++++++++++++
 306
 307 Instance shutdown URI.
 308
 309 It supports the following commands: ``PUT``.
 310
 311 ``PUT``
 312 ~~~~~~~
 313
 314 Shutdowns an instance.
 315
 316 It supports the ``dry-run`` argument.
 317
 318
 319 ``/2/instances/[instance_name]/startup``
 320 ++++++++++++++++++++++++++++++++++++++++
 321
 322 Instance startup URI.
 323
 324 It supports the following commands: ``PUT``.
 325
 326 ``PUT``
 327 ~~~~~~~
 328
 329 Startup an instance.
 330
 331 The URI takes an optional ``force=False|True`` parameter to start the
 332 instance if even if secondary disks are failing.
 333
 334 It supports the ``dry-run`` argument.
 335
 336
 337 ``/2/instances/[instance_name]/tags``
 338 +++++++++++++++++++++++++++++++++++++
 339
 340 Manages per-instance tags.
 341
 342 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 343
 344 ``GET``
 345 ~~~~~~~
 346
 347 Returns a list of tags.
 348
 349 Example::
 350
 351     ["tag1", "tag2", "tag3"]
 352
 353 ``PUT``
 354 ~~~~~~~
 355
 356 Add a set of tags.
 357
 358 The request as a list of strings should be ``PUT`` to this URI. The
 359 result willl be a job id.
 360
 361 It supports the ``dry-run`` argument.
 362
 363
 364 ``DELETE``
 365 ~~~~~~~~~~
 366
 367 Delete a tag.
 368
 369 In order to delete a set of tags, the DELETE request should be
 370 addressed to URI like::
 371
 372     /tags?tag=[tag]&tag=[tag]
 373
 374 It supports the ``dry-run`` argument.
 375
 376
 377 ``/2/jobs``
 378 +++++++++++
 379
 380 The ``/2/jobs`` resource.
 381
 382 It supports the following commands: ``GET``.
 383
 384 ``GET``
 385 ~~~~~~~
 386
 387 Returns a dictionary of jobs.
 388
 389 Returns: a dictionary with jobs id and uri.
 390
 391 ``/2/jobs/[job_id]``
 392 ++++++++++++++++++++
 393
 394
 395 Individual job URI.
 396
 397 It supports the following commands: ``GET``, ``DELETE``.
 398
 399 ``GET``
 400 ~~~~~~~
 401
 402 Returns a job status.
 403
 404 Returns: a dictionary with job parameters.
 405
 406 The result includes:
 407
 408 - id: job ID as a number
 409 - status: current job status as a string
 410 - ops: involved OpCodes as a list of dictionaries for each
 411   opcodes in the job
 412 - opstatus: OpCodes status as a list
 413 - opresult: OpCodes results as a list of lists
 414
 415 ``DELETE``
 416 ~~~~~~~~~~
 417
 418 Cancel a not-yet-started job.
 419
 420 ``/2/nodes``
 421 ++++++++++++
 422
 423 Nodes resource.
 424
 425 It supports the following commands: ``GET``.
 426
 427 ``GET``
 428 ~~~~~~~
 429
 430 Returns a list of all nodes.
 431
 432 Example::
 433
 434     [
 435       {
 436         "id": "node1.example.com",
 437         "uri": "\/instances\/node1.example.com"
 438       },
 439       {
 440         "id": "node2.example.com",
 441         "uri": "\/instances\/node2.example.com"
 442       }
 443     ]
 444
 445 If the optional 'bulk' argument is provided and set to 'true' value
 446 (i.e '?bulk=1'), the output contains detailed information about nodes
 447 as a list.
 448
 449 Example::
 450
 451     [
 452       {
 453         "pinst_cnt": 1,
 454         "mfree": 31280,
 455         "mtotal": 32763,
 456         "name": "www.example.com",
 457         "tags": [],
 458         "mnode": 512,
 459         "dtotal": 5246208,
 460         "sinst_cnt": 2,
 461         "dfree": 5171712,
 462         "offline": false
 463       },
 464       ...
 465     ]
 466
 467 ``/2/nodes/[node_name]/evacuate``
 468 +++++++++++++++++++++++++++++++++
 469
 470 Evacuates all secondary instances off a node.
 471
 472 It supports the following commands: ``POST``.
 473
 474 ``POST``
 475 ~~~~~~~~
 476
 477 To evacuate a node, either one of the ``iallocator`` or ``remote_node``
 478 parameters must be passed:
 479
 480     evacuate?iallocator=[iallocator]
 481     evacuate?remote_node=[nodeX.example.com]
 482
 483 ``/2/nodes/[node_name]/migrate``
 484 +++++++++++++++++++++++++++++++++
 485
 486 Migrates all primary instances from a node.
 487
 488 It supports the following commands: ``POST``.
 489
 490 ``POST``
 491 ~~~~~~~~
 492
 493 No parameters are required, but ``live`` can be set to a boolean value.
 494
 495     migrate?live=[0|1]
 496
 497 ``/2/nodes/[node_name]/role``
 498 +++++++++++++++++++++++++++++
 499
 500 Manages node role.
 501
 502 It supports the following commands: ``GET``, ``PUT``.
 503
 504 The role is always one of the following:
 505
 506   - drained
 507   - master
 508   - master-candidate
 509   - offline
 510   - regular
 511
 512 ``GET``
 513 ~~~~~~~
 514
 515 Returns the current node role.
 516
 517 Example::
 518
 519     "master-candidate"
 520
 521 ``PUT``
 522 ~~~~~~~
 523
 524 Change the node role.
 525
 526 The request is a string which should be PUT to this URI. The result will be a
 527 job id.
 528
 529 It supports the ``force`` argument.
 530
 531 ``/2/nodes/[node_name]/storage``
 532 ++++++++++++++++++++++++++++++++
 533
 534 Manages storage units on the node.
 535
 536 ``GET``
 537 ~~~~~~~
 538
 539 Requests a list of storage units on a node. Requires the parameters
 540 ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
 541 ``output_fields``. The result will be a job id, using which the result can be
 542 retrieved.
 543
 544 ``/2/nodes/[node_name]/tags``
 545 +++++++++++++++++++++++++++++
 546
 547 Manages per-node tags.
 548
 549 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 550
 551 ``GET``
 552 ~~~~~~~
 553
 554 Returns a list of tags.
 555
 556 Example::
 557
 558     ["tag1", "tag2", "tag3"]
 559
 560 ``PUT``
 561 ~~~~~~~
 562
 563 Add a set of tags.
 564
 565 The request as a list of strings should be PUT to this URI. The result
 566 will be a job id.
 567
 568 It supports the ``dry-run`` argument.
 569
 570 ``DELETE``
 571 ~~~~~~~~~~
 572
 573 Deletes tags.
 574
 575 In order to delete a set of tags, the DELETE request should be
 576 addressed to URI like::
 577
 578     /tags?tag=[tag]&tag=[tag]
 579
 580 It supports the ``dry-run`` argument.
 581
 582
 583 ``/2/os``
 584 +++++++++
 585
 586 OS resource.
 587
 588 It supports the following commands: ``GET``.
 589
 590 ``GET``
 591 ~~~~~~~
 592
 593 Return a list of all OSes.
 594
 595 Can return error 500 in case of a problem. Since this is a costly
 596 operation for Ganeti 2.0, it is not recommended to execute it too
 597 often.
 598
 599 Example::
 600
 601     ["debian-etch"]
 602
 603 ``/2/tags``
 604 +++++++++++
 605
 606 Manages cluster tags.
 607
 608 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
 609
 610 ``GET``
 611 ~~~~~~~
 612
 613 Returns the cluster tags.
 614
 615 Example::
 616
 617     ["tag1", "tag2", "tag3"]
 618
 619 ``PUT``
 620 ~~~~~~~
 621
 622 Adds a set of tags.
 623
 624 The request as a list of strings should be PUT to this URI. The result
 625 will be a job id.
 626
 627 It supports the ``dry-run`` argument.
 628
 629
 630 ``DELETE``
 631 ~~~~~~~~~~
 632
 633 Deletes tags.
 634
 635 In order to delete a set of tags, the DELETE request should be
 636 addressed to URI like::
 637
 638     /tags?tag=[tag]&tag=[tag]
 639
 640 It supports the ``dry-run`` argument.
 641
 642
 643 ``/version``
 644 ++++++++++++
 645
 646 The version resource.
 647
 648 This resource should be used to determine the remote API version and
 649 to adapt clients accordingly.
 650
 651 It supports the following commands: ``GET``.
 652
 653 ``GET``
 654 ~~~~~~~
 655
 656 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
 657 2.0 returns ``2``.