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.

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/2/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/2/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]/reinstall

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

Implements an instance reinstall.

It supports the following commands: POST.

POST

Reinstall an instance.

The URI takes os=name and nostartup=[0|1] optional
parameters. By default, the instance will be started
automatically.

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