rapi.rst 8.91 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 28 29 30 31 32 33 34 35 36

.. 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

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
37 38
.. highlight:: sh

39 40
Using wget::

Iustin Pop's avatar
Iustin Pop committed
41
   wget -q -O - https://CLUSTERNAME:5080/2/info
42 43 44 45 46 47 48 49 50

or curl::

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


Python
++++++

Iustin Pop's avatar
Iustin Pop committed
51
.. highlight: python
52 53

  import urllib2
Tim Boring's avatar
Tim Boring committed
54
  f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
55 56 57 58 59 60 61 62 63 64 65
  print f.read()


JavaScript
++++++++++

.. 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.

Iustin Pop's avatar
Iustin Pop committed
66 67
.. highlight:: javascript

68 69
::

Tim Boring's avatar
Tim Boring committed
70
  var url = 'https://CLUSTERNAME:5080/2/info';
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
  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
89
.. highlight:: javascript
90

Iustin Pop's avatar
Iustin Pop committed
91 92
``/``
+++++
93

Iustin Pop's avatar
Iustin Pop committed
94
The root resource.
95

Iustin Pop's avatar
Iustin Pop committed
96
It supports the following commands: ``GET``.
97

Iustin Pop's avatar
Iustin Pop committed
98 99
``GET``
~~~~~~~
100

Iustin Pop's avatar
Iustin Pop committed
101
Shows the list of mapped resources.
102

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

Iustin Pop's avatar
Iustin Pop committed
105 106
``/2``
++++++
107

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

Iustin Pop's avatar
Iustin Pop committed
110
It supports the following commands: ``GET``.
111

Iustin Pop's avatar
Iustin Pop committed
112 113
``GET``
~~~~~~~
114

Iustin Pop's avatar
Iustin Pop committed
115
Show the list of mapped resources.
116

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

Iustin Pop's avatar
Iustin Pop committed
119 120
``/2/info``
+++++++++++
121

Iustin Pop's avatar
Iustin Pop committed
122
Cluster information resource.
123

Iustin Pop's avatar
Iustin Pop committed
124
It supports the following commands: ``GET``.
125

Iustin Pop's avatar
Iustin Pop committed
126 127
``GET``
~~~~~~~
128

Iustin Pop's avatar
Iustin Pop committed
129
Returns cluster information.
130

Iustin Pop's avatar
Iustin Pop committed
131
Example::
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161

  {
    "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
162 163
``/2/instances``
++++++++++++++++
164

Iustin Pop's avatar
Iustin Pop committed
165
The instances resource.
166

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

Iustin Pop's avatar
Iustin Pop committed
169 170
``GET``
~~~~~~~
171

Iustin Pop's avatar
Iustin Pop committed
172
Returns a list of all available instances.
173 174


Iustin Pop's avatar
Iustin Pop committed
175
Example::
176 177 178 179 180 181 182 183 184 185 186 187

    [
      {
        "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
188 189 190
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.
191

Iustin Pop's avatar
Iustin Pop committed
192
Example::
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221

    [
      {
         "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
222 223
``POST``
~~~~~~~~
224

Iustin Pop's avatar
Iustin Pop committed
225
Creates an instance.
226

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

Iustin Pop's avatar
Iustin Pop committed
229 230
``/2/instances/[instance_name]``
++++++++++++++++++++++++++++++++
231

Iustin Pop's avatar
Iustin Pop committed
232
Instance-specific resource.
233

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

Iustin Pop's avatar
Iustin Pop committed
236 237
``GET``
~~~~~~~
238

Iustin Pop's avatar
Iustin Pop committed
239 240
Returns information about an instance, similar to the bulk output from
the instance list.
241

Iustin Pop's avatar
Iustin Pop committed
242 243
``DELETE``
~~~~~~~~~~
244

Iustin Pop's avatar
Iustin Pop committed
245
Deletes an instance.
246 247


Iustin Pop's avatar
Iustin Pop committed
248 249
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
250

Iustin Pop's avatar
Iustin Pop committed
251
Reboots URI for an instance.
252

Iustin Pop's avatar
Iustin Pop committed
253
It supports the following commands: ``POST``.
254

Iustin Pop's avatar
Iustin Pop committed
255 256
``POST``
~~~~~~~~
257

Iustin Pop's avatar
Iustin Pop committed
258
Reboots the instance.
259

Iustin Pop's avatar
Iustin Pop committed
260 261
The URI takes optional ``type=hard|soft|full`` and
``ignore_secondaries=False|True`` parameters.
262

Iustin Pop's avatar
Iustin Pop committed
263 264
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
265

Iustin Pop's avatar
Iustin Pop committed
266
Instance shutdown URI.
267

Iustin Pop's avatar
Iustin Pop committed
268
It supports the following commands: ``PUT``.
269

Iustin Pop's avatar
Iustin Pop committed
270 271
``PUT``
~~~~~~~
272

Iustin Pop's avatar
Iustin Pop committed
273
Shutdowns an instance.
274 275


Iustin Pop's avatar
Iustin Pop committed
276 277
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
278

Iustin Pop's avatar
Iustin Pop committed
279
Instance startup URI.
280

Iustin Pop's avatar
Iustin Pop committed
281
It supports the following commands: ``PUT``.
282

Iustin Pop's avatar
Iustin Pop committed
283 284
``PUT``
~~~~~~~
285

Iustin Pop's avatar
Iustin Pop committed
286
Startup an instance.
287

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

Iustin Pop's avatar
Iustin Pop committed
291 292
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
293

Iustin Pop's avatar
Iustin Pop committed
294
Manages per-instance tags.
295

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

Iustin Pop's avatar
Iustin Pop committed
298 299
``GET``
~~~~~~~
300

Iustin Pop's avatar
Iustin Pop committed
301
Returns a list of tags.
302

Iustin Pop's avatar
Iustin Pop committed
303
Example::
304

Iustin Pop's avatar
Iustin Pop committed
305
    ["tag1", "tag2", "tag3"]
306

Iustin Pop's avatar
Iustin Pop committed
307 308
``PUT``
~~~~~~~
309

Iustin Pop's avatar
Iustin Pop committed
310
Add a set of tags.
311

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

Iustin Pop's avatar
Iustin Pop committed
315 316
``DELETE``
~~~~~~~~~~
317

Iustin Pop's avatar
Iustin Pop committed
318
Delete a tag.
319

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

Iustin Pop's avatar
Iustin Pop committed
323
    /tags?tag=[tag]&tag=[tag]
324

Iustin Pop's avatar
Iustin Pop committed
325 326
``/2/jobs``
+++++++++++
327

Iustin Pop's avatar
Iustin Pop committed
328
The ``/2/jobs`` resource.
329

Iustin Pop's avatar
Iustin Pop committed
330
It supports the following commands: ``GET``.
331

Iustin Pop's avatar
Iustin Pop committed
332 333
``GET``
~~~~~~~
334

Iustin Pop's avatar
Iustin Pop committed
335
Returns a dictionary of jobs.
336

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

Iustin Pop's avatar
Iustin Pop committed
339 340
``/2/jobs/[job_id]``
++++++++++++++++++++
341 342


Iustin Pop's avatar
Iustin Pop committed
343
Individual job URI.
344

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

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

Iustin Pop's avatar
Iustin Pop committed
350
Returns a job status.
351

Iustin Pop's avatar
Iustin Pop committed
352
Returns: a dictionary with job parameters.
353

Iustin Pop's avatar
Iustin Pop committed
354
The result includes:
355

Iustin Pop's avatar
Iustin Pop committed
356 357 358 359 360 361
- 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
362

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

Iustin Pop's avatar
Iustin Pop committed
366
Cancel a not-yet-started job.
367

Iustin Pop's avatar
Iustin Pop committed
368 369
``/2/nodes``
++++++++++++
370

Iustin Pop's avatar
Iustin Pop committed
371
Nodes resource.
372

Iustin Pop's avatar
Iustin Pop committed
373
It supports the following commands: ``GET``.
374

Iustin Pop's avatar
Iustin Pop committed
375 376
``GET``
~~~~~~~
377

Iustin Pop's avatar
Iustin Pop committed
378
Returns a list of all nodes.
379

Iustin Pop's avatar
Iustin Pop committed
380
Example::
381 382 383 384 385 386 387 388 389 390 391 392

    [
      {
        "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
393 394 395
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.
396

Iustin Pop's avatar
Iustin Pop committed
397
Example::
398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414

    [
      {
        "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
415 416
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
417

Iustin Pop's avatar
Iustin Pop committed
418
Manages per-node tags.
419

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

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

Iustin Pop's avatar
Iustin Pop committed
425
Returns a list of tags.
426

Iustin Pop's avatar
Iustin Pop committed
427
Example::
428

Iustin Pop's avatar
Iustin Pop committed
429
    ["tag1", "tag2", "tag3"]
430

Iustin Pop's avatar
Iustin Pop committed
431 432
``PUT``
~~~~~~~
433

Iustin Pop's avatar
Iustin Pop committed
434
Add a set of tags.
435

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

Iustin Pop's avatar
Iustin Pop committed
439 440
``DELETE``
~~~~~~~~~~
441

Iustin Pop's avatar
Iustin Pop committed
442
Deletes tags.
443

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

Iustin Pop's avatar
Iustin Pop committed
447
    /tags?tag=[tag]&tag=[tag]
448

Iustin Pop's avatar
Iustin Pop committed
449 450
``/2/os``
+++++++++
451

Iustin Pop's avatar
Iustin Pop committed
452
OS resource.
453

Iustin Pop's avatar
Iustin Pop committed
454
It supports the following commands: ``GET``.
455

Iustin Pop's avatar
Iustin Pop committed
456 457
``GET``
~~~~~~~
458

Iustin Pop's avatar
Iustin Pop committed
459
Return a list of all OSes.
460

Iustin Pop's avatar
Iustin Pop committed
461 462 463
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.
464

Iustin Pop's avatar
Iustin Pop committed
465
Example::
466

Iustin Pop's avatar
Iustin Pop committed
467
    ["debian-etch"]
468

Iustin Pop's avatar
Iustin Pop committed
469 470
``/2/tags``
+++++++++++
471

Iustin Pop's avatar
Iustin Pop committed
472
Manages cluster tags.
473

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

Iustin Pop's avatar
Iustin Pop committed
476 477
``GET``
~~~~~~~
478

Iustin Pop's avatar
Iustin Pop committed
479
Returns the cluster tags.
480

Iustin Pop's avatar
Iustin Pop committed
481
Example::
482

Iustin Pop's avatar
Iustin Pop committed
483
    ["tag1", "tag2", "tag3"]
484

Iustin Pop's avatar
Iustin Pop committed
485 486
``PUT``
~~~~~~~
487

Iustin Pop's avatar
Iustin Pop committed
488
Adds a set of tags.
489

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

Iustin Pop's avatar
Iustin Pop committed
493 494
``DELETE``
~~~~~~~~~~
495

Iustin Pop's avatar
Iustin Pop committed
496
Deletes tags.
497

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

Iustin Pop's avatar
Iustin Pop committed
501
    /tags?tag=[tag]&tag=[tag]
502

Iustin Pop's avatar
Iustin Pop committed
503 504
``/version``
++++++++++++
505

Iustin Pop's avatar
Iustin Pop committed
506
The version resource.
507

Iustin Pop's avatar
Iustin Pop committed
508 509
This resource should be used to determine the remote API version and
to adapt clients accordingly.
510

Iustin Pop's avatar
Iustin Pop committed
511
It supports the following commands: ``GET``.
512

Iustin Pop's avatar
Iustin Pop committed
513 514
``GET``
~~~~~~~
515

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