rapi.rst 10.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 59 60 61
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
62 63
.. highlight:: sh

64 65
Using wget::

Iustin Pop's avatar
Iustin Pop committed
66
   wget -q -O - https://CLUSTERNAME:5080/2/info
67 68 69 70 71 72 73 74 75

or curl::

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


Python
++++++

Iustin Pop's avatar
Iustin Pop committed
76
.. highlight: python
77 78

  import urllib2
Tim Boring's avatar
Tim Boring committed
79
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
80 81 82 83 84 85
  print f.read()


JavaScript
++++++++++

86 87 88 89
.. 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.
90

Iustin Pop's avatar
Iustin Pop committed
91 92
.. highlight:: javascript

93 94
::

Tim Boring's avatar
Tim Boring committed
95
  var url = 'https://CLUSTERNAME:5080/2/info';
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
  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
114
.. highlight:: javascript
115

Iustin Pop's avatar
Iustin Pop committed
116 117
``/``
+++++
118

Iustin Pop's avatar
Iustin Pop committed
119
The root resource.
120

Iustin Pop's avatar
Iustin Pop committed
121
It supports the following commands: ``GET``.
122

Iustin Pop's avatar
Iustin Pop committed
123 124
``GET``
~~~~~~~
125

Iustin Pop's avatar
Iustin Pop committed
126
Shows the list of mapped resources.
127

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

Iustin Pop's avatar
Iustin Pop committed
130 131
``/2``
++++++
132

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

Iustin Pop's avatar
Iustin Pop committed
135
It supports the following commands: ``GET``.
136

Iustin Pop's avatar
Iustin Pop committed
137 138
``GET``
~~~~~~~
139

Iustin Pop's avatar
Iustin Pop committed
140
Show the list of mapped resources.
141

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

Iustin Pop's avatar
Iustin Pop committed
144 145
``/2/info``
+++++++++++
146

Iustin Pop's avatar
Iustin Pop committed
147
Cluster information resource.
148

Iustin Pop's avatar
Iustin Pop committed
149
It supports the following commands: ``GET``.
150

Iustin Pop's avatar
Iustin Pop committed
151 152
``GET``
~~~~~~~
153

Iustin Pop's avatar
Iustin Pop committed
154
Returns cluster information.
155

Iustin Pop's avatar
Iustin Pop committed
156
Example::
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

  {
    "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
187 188
``/2/instances``
++++++++++++++++
189

Iustin Pop's avatar
Iustin Pop committed
190
The instances resource.
191

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

Iustin Pop's avatar
Iustin Pop committed
194 195
``GET``
~~~~~~~
196

Iustin Pop's avatar
Iustin Pop committed
197
Returns a list of all available instances.
198

Iustin Pop's avatar
Iustin Pop committed
199
Example::
200 201 202 203 204 205 206 207 208 209 210 211

    [
      {
        "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
212 213 214
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.
215

Iustin Pop's avatar
Iustin Pop committed
216
Example::
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245

    [
      {
         "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
246 247
``POST``
~~~~~~~~
248

Iustin Pop's avatar
Iustin Pop committed
249
Creates an instance.
250

251 252 253 254 255 256
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
257
Returns: a job ID that can be used later for polling.
258

Iustin Pop's avatar
Iustin Pop committed
259 260
``/2/instances/[instance_name]``
++++++++++++++++++++++++++++++++
261

Iustin Pop's avatar
Iustin Pop committed
262
Instance-specific resource.
263

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

Iustin Pop's avatar
Iustin Pop committed
266 267
``GET``
~~~~~~~
268

Iustin Pop's avatar
Iustin Pop committed
269 270
Returns information about an instance, similar to the bulk output from
the instance list.
271

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

Iustin Pop's avatar
Iustin Pop committed
275
Deletes an instance.
276

277 278
It supports the ``dry-run`` argument.

279

Iustin Pop's avatar
Iustin Pop committed
280 281
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
282

Iustin Pop's avatar
Iustin Pop committed
283
Reboots URI for an instance.
284

Iustin Pop's avatar
Iustin Pop committed
285
It supports the following commands: ``POST``.
286

Iustin Pop's avatar
Iustin Pop committed
287 288
``POST``
~~~~~~~~
289

Iustin Pop's avatar
Iustin Pop committed
290
Reboots the instance.
291

Iustin Pop's avatar
Iustin Pop committed
292 293
The URI takes optional ``type=hard|soft|full`` and
``ignore_secondaries=False|True`` parameters.
294

295 296 297
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
298 299
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
300

Iustin Pop's avatar
Iustin Pop committed
301
Instance shutdown URI.
302

Iustin Pop's avatar
Iustin Pop committed
303
It supports the following commands: ``PUT``.
304

Iustin Pop's avatar
Iustin Pop committed
305 306
``PUT``
~~~~~~~
307

Iustin Pop's avatar
Iustin Pop committed
308
Shutdowns an instance.
309

310 311
It supports the ``dry-run`` argument.

312

Iustin Pop's avatar
Iustin Pop committed
313 314
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
315

Iustin Pop's avatar
Iustin Pop committed
316
Instance startup URI.
317

Iustin Pop's avatar
Iustin Pop committed
318
It supports the following commands: ``PUT``.
319

Iustin Pop's avatar
Iustin Pop committed
320 321
``PUT``
~~~~~~~
322

Iustin Pop's avatar
Iustin Pop committed
323
Startup an instance.
324

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

328 329 330
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
331 332
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
333

Iustin Pop's avatar
Iustin Pop committed
334
Manages per-instance tags.
335

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

Iustin Pop's avatar
Iustin Pop committed
338 339
``GET``
~~~~~~~
340

Iustin Pop's avatar
Iustin Pop committed
341
Returns a list of tags.
342

Iustin Pop's avatar
Iustin Pop committed
343
Example::
344

Iustin Pop's avatar
Iustin Pop committed
345
    ["tag1", "tag2", "tag3"]
346

Iustin Pop's avatar
Iustin Pop committed
347 348
``PUT``
~~~~~~~
349

Iustin Pop's avatar
Iustin Pop committed
350
Add a set of tags.
351

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

355 356 357
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
358 359
``DELETE``
~~~~~~~~~~
360

Iustin Pop's avatar
Iustin Pop committed
361
Delete a tag.
362

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

Iustin Pop's avatar
Iustin Pop committed
366
    /tags?tag=[tag]&tag=[tag]
367

368 369 370
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
371 372
``/2/jobs``
+++++++++++
373

Iustin Pop's avatar
Iustin Pop committed
374
The ``/2/jobs`` resource.
375

Iustin Pop's avatar
Iustin Pop committed
376
It supports the following commands: ``GET``.
377

Iustin Pop's avatar
Iustin Pop committed
378 379
``GET``
~~~~~~~
380

Iustin Pop's avatar
Iustin Pop committed
381
Returns a dictionary of jobs.
382

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

Iustin Pop's avatar
Iustin Pop committed
385 386
``/2/jobs/[job_id]``
++++++++++++++++++++
387 388


Iustin Pop's avatar
Iustin Pop committed
389
Individual job URI.
390

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

Iustin Pop's avatar
Iustin Pop committed
393 394
``GET``
~~~~~~~
395

Iustin Pop's avatar
Iustin Pop committed
396
Returns a job status.
397

Iustin Pop's avatar
Iustin Pop committed
398
Returns: a dictionary with job parameters.
399

Iustin Pop's avatar
Iustin Pop committed
400
The result includes:
401

Iustin Pop's avatar
Iustin Pop committed
402 403 404 405 406 407
- 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
408

Iustin Pop's avatar
Iustin Pop committed
409 410
``DELETE``
~~~~~~~~~~
411

Iustin Pop's avatar
Iustin Pop committed
412
Cancel a not-yet-started job.
413

Iustin Pop's avatar
Iustin Pop committed
414 415
``/2/nodes``
++++++++++++
416

Iustin Pop's avatar
Iustin Pop committed
417
Nodes resource.
418

Iustin Pop's avatar
Iustin Pop committed
419
It supports the following commands: ``GET``.
420

Iustin Pop's avatar
Iustin Pop committed
421 422
``GET``
~~~~~~~
423

Iustin Pop's avatar
Iustin Pop committed
424
Returns a list of all nodes.
425

Iustin Pop's avatar
Iustin Pop committed
426
Example::
427 428 429 430 431 432 433 434 435 436 437 438

    [
      {
        "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
439 440 441
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.
442

Iustin Pop's avatar
Iustin Pop committed
443
Example::
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460

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

Iustin Pop's avatar
Iustin Pop committed
461 462
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
463

Iustin Pop's avatar
Iustin Pop committed
464
Manages per-node tags.
465

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

Iustin Pop's avatar
Iustin Pop committed
468 469
``GET``
~~~~~~~
470

Iustin Pop's avatar
Iustin Pop committed
471
Returns a list of tags.
472

Iustin Pop's avatar
Iustin Pop committed
473
Example::
474

Iustin Pop's avatar
Iustin Pop committed
475
    ["tag1", "tag2", "tag3"]
476

Iustin Pop's avatar
Iustin Pop committed
477 478
``PUT``
~~~~~~~
479

Iustin Pop's avatar
Iustin Pop committed
480
Add a set of tags.
481

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

485 486
It supports the ``dry-run`` argument.

Iustin Pop's avatar
Iustin Pop committed
487 488
``DELETE``
~~~~~~~~~~
489

Iustin Pop's avatar
Iustin Pop committed
490
Deletes tags.
491

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

Iustin Pop's avatar
Iustin Pop committed
495
    /tags?tag=[tag]&tag=[tag]
496

497 498 499
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
500 501
``/2/os``
+++++++++
502

Iustin Pop's avatar
Iustin Pop committed
503
OS resource.
504

Iustin Pop's avatar
Iustin Pop committed
505
It supports the following commands: ``GET``.
506

Iustin Pop's avatar
Iustin Pop committed
507 508
``GET``
~~~~~~~
509

Iustin Pop's avatar
Iustin Pop committed
510
Return a list of all OSes.
511

Iustin Pop's avatar
Iustin Pop committed
512 513 514
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.
515

Iustin Pop's avatar
Iustin Pop committed
516
Example::
517

Iustin Pop's avatar
Iustin Pop committed
518
    ["debian-etch"]
519

Iustin Pop's avatar
Iustin Pop committed
520 521
``/2/tags``
+++++++++++
522

Iustin Pop's avatar
Iustin Pop committed
523
Manages cluster tags.
524

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

Iustin Pop's avatar
Iustin Pop committed
527 528
``GET``
~~~~~~~
529

Iustin Pop's avatar
Iustin Pop committed
530
Returns the cluster tags.
531

Iustin Pop's avatar
Iustin Pop committed
532
Example::
533

Iustin Pop's avatar
Iustin Pop committed
534
    ["tag1", "tag2", "tag3"]
535

Iustin Pop's avatar
Iustin Pop committed
536 537
``PUT``
~~~~~~~
538

Iustin Pop's avatar
Iustin Pop committed
539
Adds a set of tags.
540

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

544 545 546
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
547 548
``DELETE``
~~~~~~~~~~
549

Iustin Pop's avatar
Iustin Pop committed
550
Deletes tags.
551

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

Iustin Pop's avatar
Iustin Pop committed
555
    /tags?tag=[tag]&tag=[tag]
556

557 558 559
It supports the ``dry-run`` argument.


Iustin Pop's avatar
Iustin Pop committed
560 561
``/version``
++++++++++++
562

Iustin Pop's avatar
Iustin Pop committed
563
The version resource.
564

Iustin Pop's avatar
Iustin Pop committed
565 566
This resource should be used to determine the remote API version and
to adapt clients accordingly.
567

Iustin Pop's avatar
Iustin Pop committed
568
It supports the following commands: ``GET``.
569

Iustin Pop's avatar
Iustin Pop committed
570 571
``GET``
~~~~~~~
572

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