Synnefo » snf-ganeti » ganeti-local

Ganeti remote API

=================

Documents Ganeti version 2.0

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

+++++

Using wget::

  wget -q -O - https://CLUSTERNAME:5080/2/info

or curl::

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

Python

++++++

::

  import urllib2

  f = urllib2.urlopen('https://CLUSTERNAME:5080/info')

  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.

::

  var url = 'https://CLUSTERNAME:5080/info';

  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

---------

/

+

::

  / resource.

It supports the following commands: GET.

GET

~~~

::

  Show the list of mapped resources.

  Returns: a dictionary with 'name' and 'uri' keys for each of them.

/2

++

::

  /2 resource, the root of the version 2 API.

It supports the following commands: GET.

GET

~~~

::

  Show the list of mapped resources.

  Returns: a dictionary with 'name' and 'uri' keys for each of them.

/2/info

+++++++

::

  Cluster info.

It supports the following commands: GET.

GET

~~~

::

  Returns cluster information.

  Example::

  {

    "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

       }

      }

    }

/2/instances

++++++++++++

::

  /2/instances resource.

It supports the following commands: GET, POST.

GET

~~~

::

  Returns a list of all available instances.

  Example::

    [

      {

        "name": "web.example.com",

        "uri": "\/instances\/web.example.com"

      },

      {

        "name": "mail.example.com",

        "uri": "\/instances\/mail.example.com"

      }

    ]

  If the optional 'bulk' argument is provided and set to 'true'

  value (i.e '?bulk=1'), the output contains detailed

  information about instances as a list.

  Example::

    [

      {

         "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

      },

      ...

    ]

  Returns: a dictionary with 'name' and 'uri' keys for each of them.

POST

~~~~

::

  Create an instance.

  Returns: a job id

/2/instances/[instance_name]

++++++++++++++++++++++++++++

::

  /2/instances/[instance_name] resources.

It supports the following commands: GET, DELETE.

GET

~~~

::

  Send information about an instance.

DELETE

~~~~~~

::

  Delete an instance.

/2/instances/[instance_name]/reboot

+++++++++++++++++++++++++++++++++++

::

  /2/instances/[instance_name]/reboot resource.

  Implements an instance reboot.

It supports the following commands: POST.

POST

~~~~

::

  Reboot an instance.

  The URI takes type=[hard|soft|full] and

  ignore_secondaries=[False|True] parameters.

/2/instances/[instance_name]/shutdown

+++++++++++++++++++++++++++++++++++++

::

  /2/instances/[instance_name]/shutdown resource.

  Implements an instance shutdown.

It supports the following commands: PUT.

PUT

~~~

::

  Shutdown an instance.

/2/instances/[instance_name]/startup

++++++++++++++++++++++++++++++++++++

::

  /2/instances/[instance_name]/startup resource.

  Implements an instance startup.

It supports the following commands: PUT.

PUT

~~~

::

  Startup an instance.

  The URI takes force=[False|True] parameter to start the instance

  if even if secondary disks are failing.

/2/instances/[instance_name]/tags

+++++++++++++++++++++++++++++++++

::

  /2/instances/[instance_name]/tags resource.

  Manages per-instance tags.

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

GET

~~~

::

  Returns a list of tags.

  Example: ["tag1", "tag2", "tag3"]

PUT

~~~

::

  Add a set of tags.

  The request as a list of strings should be PUT to this URI. And

  you'll have back a job id.

DELETE

~~~~~~

::

  Delete a tag.

  In order to delete a set of tags, the DELETE

  request should be addressed to URI like:

  /tags?tag=[tag]&tag=[tag]

/2/jobs

+++++++

::

  /2/jobs resource.

It supports the following commands: GET.

GET

~~~

::

  Returns a dictionary of jobs.

  Returns: a dictionary with jobs id and uri.

/2/jobs/[job_id]

++++++++++++++++

::

  /2/jobs/[job_id] resource.

It supports the following commands: GET, DELETE.

GET

~~~

::

  Returns a job status.

  Returns: a dictionary with job parameters.

      The result includes:

          - 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

DELETE

~~~~~~

::

  Cancel not-yet-started job.

/2/nodes

++++++++

::

  /2/nodes resource.

It supports the following commands: GET.

GET

~~~

::

  Returns a list of all nodes.

  Example::

    [

      {

        "id": "node1.example.com",

        "uri": "\/instances\/node1.example.com"

      },

      {

        "id": "node2.example.com",

        "uri": "\/instances\/node2.example.com"

      }

    ]

  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.

  Example::

    [

      {

        "pinst_cnt": 1,

        "mfree": 31280,

        "mtotal": 32763,

        "name": "www.example.com",

        "tags": [],

        "mnode": 512,

        "dtotal": 5246208,

        "sinst_cnt": 2,

        "dfree": 5171712,

        "offline": false

      },

      ...

    ]

  Returns: a dictionary with 'name' and 'uri' keys for each of them

/2/nodes/[node_name]/tags

+++++++++++++++++++++++++

::

  /2/nodes/[node_name]/tags resource.

  Manages per-node tags.

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

GET

~~~

::

  Returns a list of tags.

  Example: ["tag1", "tag2", "tag3"]

PUT

~~~

::

  Add a set of tags.

  The request as a list of strings should be PUT to this URI. And

  you'll have back a job id.

DELETE

~~~~~~

::

  Delete a tag.

  In order to delete a set of tags, the DELETE

  request should be addressed to URI like:

  /tags?tag=[tag]&tag=[tag]

/2/os

+++++

::

  /2/os resource.

It supports the following commands: GET.

GET

~~~

::

  Return a list of all OSes.

  Can return error 500 in case of a problem.

  Example: ["debian-etch"]

/2/tags

+++++++

::

  /2/instances/tags resource.

  Manages cluster tags.

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

GET

~~~

::

  Returns a list of tags.

  Example: ["tag1", "tag2", "tag3"]

PUT

~~~

::

  Add a set of tags.

  The request as a list of strings should be PUT to this URI. And

  you'll have back a job id.

DELETE

~~~~~~

::

  Delete a tag.

  In order to delete a set of tags, the DELETE

  request should be addressed to URI like:

  /tags?tag=[tag]&tag=[tag]

/nodes/[node_name]

++++++++++++++++++

::

  /2/nodes/[node_name] resources.

It supports the following commands: GET.

GET

~~~

::

  Send information about a node.

/version

++++++++

::

  /version resource.

  This resource should be used to determine the remote API version and

  to adapt clients accordingly.

It supports the following commands: GET.

GET

~~~

::

  Returns the remote API version.