rapi.rst 11.4 KB
Newer Older
1 2 3
Ganeti remote API
=================

Iustin Pop's avatar
Iustin Pop committed
4
Documents Ganeti version |version|
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

.. contents::

Introduction
------------

Ganeti supports a remote API for enable external tools to easily
retrieve information about a cluster's state. The remote API daemon,
*ganeti-rapi*, is automatically started on the master node. By default
it runs on TCP port 5080, but this can be changed either in
``.../constants.py`` or via the command line parameter *-p*. SSL mode,
which is used by default, can also be disabled by passing command line
parameters.

Protocol
--------

The protocol used is JSON_ over HTTP designed after the REST_
principle.

.. _JSON: http://www.json.org/
.. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
Generic parameters
------------------

A few parameter mean the same thing across all resources which implement it.

``bulk``
++++++++

Bulk-mode means that for the resources which usually return just a
list of child resources (e.g. ``/2/instances`` which returns just
instance names), the output will instead contain detailed data for all
these subresources. This is more efficient than query-ing the
sub-resources themselves.

``dry-run``
+++++++++++

The optional *dry-run* argument, if provided and set to a positive
integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
should not be executed, only the pre-execution checks will be done.

This is useful in trying to determine (without guarantees though, as
in the meantime the cluster state could have changed) if the operation
is likely to succeed or at least start executing.

53 54 55 56 57 58
``force``
+++++++++++

Force operation to continue even if it will cause the cluster to become
inconsistent (e.g. because there are not enough master candidates).

59 60 61 62 63 64 65 66 67
Usage examples
--------------

You can access the API using your favorite programming language as
long as it supports network connections.

Shell
+++++

Iustin Pop's avatar
Iustin Pop committed
68 69
.. highlight:: sh

70 71
Using wget::

Iustin Pop's avatar
Iustin Pop committed
72
   wget -q -O - https://CLUSTERNAME:5080/2/info
73 74 75 76 77 78 79 80 81

or curl::

  curl https://CLUSTERNAME:5080/2/info


Python
++++++

Iustin Pop's avatar
Iustin Pop committed
82
.. highlight: python
83 84

  import urllib2
Tim Boring's avatar
Tim Boring committed
85
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
86 87 88 89 90 91
  print f.read()


JavaScript
++++++++++

92 93 94 95
.. warning:: While it's possible to use JavaScript, it poses several
  potential problems, including browser blocking request due to
  non-standard ports or different domain names. Fetching the data on
  the webserver is easier.
96

Iustin Pop's avatar
Iustin Pop committed
97 98
.. highlight:: javascript

99 100
::

Tim Boring's avatar
Tim Boring committed
101
  var url = 'https://CLUSTERNAME:5080/2/info';
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
  var info;
  var xmlreq = new XMLHttpRequest();
  xmlreq.onreadystatechange = function () {
    if (xmlreq.readyState != 4) return;
    if (xmlreq.status == 200) {
      info = eval("(" + xmlreq.responseText + ")");
      alert(info);
    } else {
      alert('Error fetching cluster info');
    }
    xmlreq = null;
  };
  xmlreq.open('GET', url, true);
  xmlreq.send(null);

Resources
---------

Iustin Pop's avatar
Iustin Pop committed
120
.. highlight:: javascript
121

Iustin Pop's avatar
Iustin Pop committed
122 123
``/``
+++++
124

Iustin Pop's avatar
Iustin Pop committed
125
The root resource.
126

Iustin Pop's avatar
Iustin Pop committed
127
It supports the following commands: ``GET``.
128

Iustin Pop's avatar
Iustin Pop committed
129 130
``GET``
~~~~~~~
131

Iustin Pop's avatar
Iustin Pop committed
132
Shows the list of mapped resources.
133

Iustin Pop's avatar
Iustin Pop committed
134
Returns: a dictionary with 'name' and 'uri' keys for each of them.
135

Iustin Pop's avatar
Iustin Pop committed
136 137
``/2``
++++++
138

Iustin Pop's avatar
Iustin Pop committed
139
The ``/2`` resource, the root of the version 2 API.
140

Iustin Pop's avatar
Iustin Pop committed
141
It supports the following commands: ``GET``.
142

Iustin Pop's avatar
Iustin Pop committed
143 144
``GET``
~~~~~~~
145

Iustin Pop's avatar
Iustin Pop committed
146
Show the list of mapped resources.
147

Iustin Pop's avatar
Iustin Pop committed
148
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
149

Iustin Pop's avatar
Iustin Pop committed
150 151
``/2/info``
+++++++++++
152

Iustin Pop's avatar
Iustin Pop committed
153
Cluster information resource.
154

Iustin Pop's avatar
Iustin Pop committed
155
It supports the following commands: ``GET``.
156

Iustin Pop's avatar
Iustin Pop committed
157 158
``GET``
~~~~~~~
159

Iustin Pop's avatar
Iustin Pop committed
160
Returns cluster information.
161

Iustin Pop's avatar
Iustin Pop committed
162
Example::
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192

  {
    "config_version": 2000000,
    "name": "cluster",
    "software_version": "2.0.0~beta2",
    "os_api_version": 10,
    "export_version": 0,
    "candidate_pool_size": 10,
    "enabled_hypervisors": [
      "fake"
    ],
    "hvparams": {
      "fake": {}
     },
    "default_hypervisor": "fake",
    "master": "node1.example.com",
    "architecture": [
      "64bit",
      "x86_64"
    ],
    "protocol_version": 20,
    "beparams": {
      "default": {
        "auto_balance": true,
        "vcpus": 1,
        "memory": 128
       }
      }
    }

Iustin Pop's avatar
Iustin Pop committed
193 194
``/2/instances``
++++++++++++++++
195

Iustin Pop's avatar
Iustin Pop committed
196
The instances resource.
197

Iustin Pop's avatar
Iustin Pop committed
198
It supports the following commands: ``GET``, ``POST``.
199

Iustin Pop's avatar
Iustin Pop committed
200 201
``GET``
~~~~~~~
202

Iustin Pop's avatar
Iustin Pop committed
203
Returns a list of all available instances.
204

Iustin Pop's avatar
Iustin Pop committed
205
Example::
206 207 208 209 210 211 212 213 214 215 216 217

    [
      {
        "name": "web.example.com",
        "uri": "\/instances\/web.example.com"
      },
      {
        "name": "mail.example.com",
        "uri": "\/instances\/mail.example.com"
      }
    ]

Iustin Pop's avatar
Iustin Pop committed
218 219 220
If the optional *bulk* argument is provided and set to a true value
(i.e ``?bulk=1``), the output contains detailed information about
instances as a list.
221

Iustin Pop's avatar
Iustin Pop committed
222
Example::
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

    [
      {
         "status": "running",
         "disk_usage": 20480,
         "nic.bridges": [
           "xen-br0"
          ],
         "name": "web.example.com",
         "tags": ["tag1", "tag2"],
         "beparams": {
           "vcpus": 2,
           "memory": 512
         },
         "disk.sizes": [
             20480
         ],
         "pnode": "node1.example.com",
         "nic.macs": ["01:23:45:67:89:01"],
         "snodes": ["node2.example.com"],
         "disk_template": "drbd",
         "admin_state": true,
         "os": "debian-etch",
         "oper_state": true
      },
      ...
    ]


Iustin Pop's avatar
Iustin Pop committed
252 253
``POST``
~~~~~~~~
254

Iustin Pop's avatar
Iustin Pop committed
255
Creates an instance.
256

257 258 259 260 261 262
If the optional *dry-run* argument is provided and set to a positive
integer valu (e.g. ``?dry-run=1``), the job will not be actually
executed, only the pre-execution checks will be done. Query-ing the
job result will return, in both dry-run and normal case, the list of
nodes selected for the instance.

Iustin Pop's avatar
Iustin Pop committed
263
Returns: a job ID that can be used later for polling.
264

Iustin Pop's avatar
Iustin Pop committed
265 266
``/2/instances/[instance_name]``
++++++++++++++++++++++++++++++++
267

Iustin Pop's avatar
Iustin Pop committed
268
Instance-specific resource.
269

Iustin Pop's avatar
Iustin Pop committed
270
It supports the following commands: ``GET``, ``DELETE``.
271

Iustin Pop's avatar
Iustin Pop committed
272 273
``GET``
~~~~~~~
274

Iustin Pop's avatar
Iustin Pop committed
275 276
Returns information about an instance, similar to the bulk output from
the instance list.
277

Iustin Pop's avatar
Iustin Pop committed
278 279
``DELETE``
~~~~~~~~~~
280

Iustin Pop's avatar
Iustin Pop committed
281
Deletes an instance.
282

283 284
It supports the ``dry-run`` argument.

285

Iustin Pop's avatar
Iustin Pop committed
286 287
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
288

Iustin Pop's avatar
Iustin Pop committed
289
Reboots URI for an instance.
290

Iustin Pop's avatar
Iustin Pop committed
291
It supports the following commands: ``POST``.
292

Iustin Pop's avatar
Iustin Pop committed
293 294
``POST``
~~~~~~~~
295

Iustin Pop's avatar
Iustin Pop committed
296
Reboots the instance.
297

Iustin Pop's avatar
Iustin Pop committed
298 299
The URI takes optional ``type=hard|soft|full`` and
``ignore_secondaries=False|True`` parameters.
300

301 302 303
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
304 305
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
306

Iustin Pop's avatar
Iustin Pop committed
307
Instance shutdown URI.
308

Iustin Pop's avatar
Iustin Pop committed
309
It supports the following commands: ``PUT``.
310

Iustin Pop's avatar
Iustin Pop committed
311 312
``PUT``
~~~~~~~
313

Iustin Pop's avatar
Iustin Pop committed
314
Shutdowns an instance.
315

316 317
It supports the ``dry-run`` argument.

318

Iustin Pop's avatar
Iustin Pop committed
319 320
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
321

Iustin Pop's avatar
Iustin Pop committed
322
Instance startup URI.
323

Iustin Pop's avatar
Iustin Pop committed
324
It supports the following commands: ``PUT``.
325

Iustin Pop's avatar
Iustin Pop committed
326 327
``PUT``
~~~~~~~
328

Iustin Pop's avatar
Iustin Pop committed
329
Startup an instance.
330

Iustin Pop's avatar
Iustin Pop committed
331 332
The URI takes an optional ``force=False|True`` parameter to start the
instance if even if secondary disks are failing.
333

334 335 336
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
337 338
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
339

Iustin Pop's avatar
Iustin Pop committed
340
Manages per-instance tags.
341

Iustin Pop's avatar
Iustin Pop committed
342
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
343

Iustin Pop's avatar
Iustin Pop committed
344 345
``GET``
~~~~~~~
346

Iustin Pop's avatar
Iustin Pop committed
347
Returns a list of tags.
348

Iustin Pop's avatar
Iustin Pop committed
349
Example::
350

Iustin Pop's avatar
Iustin Pop committed
351
    ["tag1", "tag2", "tag3"]
352

Iustin Pop's avatar
Iustin Pop committed
353 354
``PUT``
~~~~~~~
355

Iustin Pop's avatar
Iustin Pop committed
356
Add a set of tags.
357

Iustin Pop's avatar
Iustin Pop committed
358 359
The request as a list of strings should be ``PUT`` to this URI. The
result willl be a job id.
360

361 362 363
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
364 365
``DELETE``
~~~~~~~~~~
366

Iustin Pop's avatar
Iustin Pop committed
367
Delete a tag.
368

Iustin Pop's avatar
Iustin Pop committed
369 370
In order to delete a set of tags, the DELETE request should be
addressed to URI like::
371

Iustin Pop's avatar
Iustin Pop committed
372
    /tags?tag=[tag]&tag=[tag]
373

374 375 376
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
377 378
``/2/jobs``
+++++++++++
379

Iustin Pop's avatar
Iustin Pop committed
380
The ``/2/jobs`` resource.
381

Iustin Pop's avatar
Iustin Pop committed
382
It supports the following commands: ``GET``.
383

Iustin Pop's avatar
Iustin Pop committed
384 385
``GET``
~~~~~~~
386

Iustin Pop's avatar
Iustin Pop committed
387
Returns a dictionary of jobs.
388

Iustin Pop's avatar
Iustin Pop committed
389
Returns: a dictionary with jobs id and uri.
390

Iustin Pop's avatar
Iustin Pop committed
391 392
``/2/jobs/[job_id]``
++++++++++++++++++++
393 394


Iustin Pop's avatar
Iustin Pop committed
395
Individual job URI.
396

Iustin Pop's avatar
Iustin Pop committed
397
It supports the following commands: ``GET``, ``DELETE``.
398

Iustin Pop's avatar
Iustin Pop committed
399 400
``GET``
~~~~~~~
401

Iustin Pop's avatar
Iustin Pop committed
402
Returns a job status.
403

Iustin Pop's avatar
Iustin Pop committed
404
Returns: a dictionary with job parameters.
405

Iustin Pop's avatar
Iustin Pop committed
406
The result includes:
407

Iustin Pop's avatar
Iustin Pop committed
408 409 410 411 412 413
- id: job ID as a number
- status: current job status as a string
- ops: involved OpCodes as a list of dictionaries for each
  opcodes in the job
- opstatus: OpCodes status as a list
- opresult: OpCodes results as a list of lists
414

Iustin Pop's avatar
Iustin Pop committed
415 416
``DELETE``
~~~~~~~~~~
417

Iustin Pop's avatar
Iustin Pop committed
418
Cancel a not-yet-started job.
419

Iustin Pop's avatar
Iustin Pop committed
420 421
``/2/nodes``
++++++++++++
422

Iustin Pop's avatar
Iustin Pop committed
423
Nodes resource.
424

Iustin Pop's avatar
Iustin Pop committed
425
It supports the following commands: ``GET``.
426

Iustin Pop's avatar
Iustin Pop committed
427 428
``GET``
~~~~~~~
429

Iustin Pop's avatar
Iustin Pop committed
430
Returns a list of all nodes.
431

Iustin Pop's avatar
Iustin Pop committed
432
Example::
433 434 435 436 437 438 439 440 441 442 443 444

    [
      {
        "id": "node1.example.com",
        "uri": "\/instances\/node1.example.com"
      },
      {
        "id": "node2.example.com",
        "uri": "\/instances\/node2.example.com"
      }
    ]

Iustin Pop's avatar
Iustin Pop committed
445 446 447
If the optional 'bulk' argument is provided and set to 'true' value
(i.e '?bulk=1'), the output contains detailed information about nodes
as a list.
448

Iustin Pop's avatar
Iustin Pop committed
449
Example::
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466

    [
      {
        "pinst_cnt": 1,
        "mfree": 31280,
        "mtotal": 32763,
        "name": "www.example.com",
        "tags": [],
        "mnode": 512,
        "dtotal": 5246208,
        "sinst_cnt": 2,
        "dfree": 5171712,
        "offline": false
      },
      ...
    ]

467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482
``/2/nodes/[node_name]/evacuate``
+++++++++++++++++++++++++++++++++

Evacuates all secondary instances off a node.

It supports the following commands: ``POST``.

``POST``
~~~~~~~~

To evacuate a node, either one of the ``iallocator`` or ``remote_node``
parameters must be passed:

    evacuate?iallocator=[iallocator]
    evacuate?remote_node=[nodeX.example.com]

483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516
``/2/nodes/[node_name]/role``
+++++++++++++++++++++++++++++

Manages node role.

It supports the following commands: ``GET``, ``PUT``.

The role is always one of the following:

  - drained
  - master
  - master-candidate
  - offline
  - regular

``GET``
~~~~~~~

Returns the current node role.

Example::

    "master-candidate"

``PUT``
~~~~~~~

Change the node role.

The request is a string which should be PUT to this URI. The result will be a
job id.

It supports the ``force`` argument.

Iustin Pop's avatar
Iustin Pop committed
517 518
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
519

Iustin Pop's avatar
Iustin Pop committed
520
Manages per-node tags.
521

Iustin Pop's avatar
Iustin Pop committed
522
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
523

Iustin Pop's avatar
Iustin Pop committed
524 525
``GET``
~~~~~~~
526

Iustin Pop's avatar
Iustin Pop committed
527
Returns a list of tags.
528

Iustin Pop's avatar
Iustin Pop committed
529
Example::
530

Iustin Pop's avatar
Iustin Pop committed
531
    ["tag1", "tag2", "tag3"]
532

Iustin Pop's avatar
Iustin Pop committed
533 534
``PUT``
~~~~~~~
535

Iustin Pop's avatar
Iustin Pop committed
536
Add a set of tags.
537

Iustin Pop's avatar
Iustin Pop committed
538 539
The request as a list of strings should be PUT to this URI. The result
will be a job id.
540

541 542
It supports the ``dry-run`` argument.

Iustin Pop's avatar
Iustin Pop committed
543 544
``DELETE``
~~~~~~~~~~
545

Iustin Pop's avatar
Iustin Pop committed
546
Deletes tags.
547

Iustin Pop's avatar
Iustin Pop committed
548 549
In order to delete a set of tags, the DELETE request should be
addressed to URI like::
550

Iustin Pop's avatar
Iustin Pop committed
551
    /tags?tag=[tag]&tag=[tag]
552

553 554 555
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
556 557
``/2/os``
+++++++++
558

Iustin Pop's avatar
Iustin Pop committed
559
OS resource.
560

Iustin Pop's avatar
Iustin Pop committed
561
It supports the following commands: ``GET``.
562

Iustin Pop's avatar
Iustin Pop committed
563 564
``GET``
~~~~~~~
565

Iustin Pop's avatar
Iustin Pop committed
566
Return a list of all OSes.
567

Iustin Pop's avatar
Iustin Pop committed
568 569 570
Can return error 500 in case of a problem. Since this is a costly
operation for Ganeti 2.0, it is not recommended to execute it too
often.
571

Iustin Pop's avatar
Iustin Pop committed
572
Example::
573

Iustin Pop's avatar
Iustin Pop committed
574
    ["debian-etch"]
575

Iustin Pop's avatar
Iustin Pop committed
576 577
``/2/tags``
+++++++++++
578

Iustin Pop's avatar
Iustin Pop committed
579
Manages cluster tags.
580

Iustin Pop's avatar
Iustin Pop committed
581
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
582

Iustin Pop's avatar
Iustin Pop committed
583 584
``GET``
~~~~~~~
585

Iustin Pop's avatar
Iustin Pop committed
586
Returns the cluster tags.
587

Iustin Pop's avatar
Iustin Pop committed
588
Example::
589

Iustin Pop's avatar
Iustin Pop committed
590
    ["tag1", "tag2", "tag3"]
591

Iustin Pop's avatar
Iustin Pop committed
592 593
``PUT``
~~~~~~~
594

Iustin Pop's avatar
Iustin Pop committed
595
Adds a set of tags.
596

Iustin Pop's avatar
Iustin Pop committed
597 598
The request as a list of strings should be PUT to this URI. The result
will be a job id.
599

600 601 602
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
603 604
``DELETE``
~~~~~~~~~~
605

Iustin Pop's avatar
Iustin Pop committed
606
Deletes tags.
607

Iustin Pop's avatar
Iustin Pop committed
608 609
In order to delete a set of tags, the DELETE request should be
addressed to URI like::
610

Iustin Pop's avatar
Iustin Pop committed
611
    /tags?tag=[tag]&tag=[tag]
612

613 614 615
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
616 617
``/version``
++++++++++++
618

Iustin Pop's avatar
Iustin Pop committed
619
The version resource.
620

Iustin Pop's avatar
Iustin Pop committed
621 622
This resource should be used to determine the remote API version and
to adapt clients accordingly.
623

Iustin Pop's avatar
Iustin Pop committed
624
It supports the following commands: ``GET``.
625

Iustin Pop's avatar
Iustin Pop committed
626 627
``GET``
~~~~~~~
628

Iustin Pop's avatar
Iustin Pop committed
629 630
Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti
2.0 returns ``2``.