Skip to content
Snippets Groups Projects
Select Git revision
  • debian-jessie-2.10-bpo2
  • debian-2.10-bpo2
  • stable-2.10-bpo2
  • master default
  • stable-2.10-grnet-rebased
  • stable-2.10-bpo
  • stable-2.8-grnet
  • debian-2.6
  • stable-2.6-ippool-hotplug-esi-nolvm-netxen
  • stable-2.6-debian
  • grnet-2.4-ippool-devel
  • v2.12.5
  • v2.13.2
  • v2.14.1
  • v2.13.1
  • v2.15.0rc1
  • v2.14.0
  • v2.14.0rc2
  • v2.12.4
  • v2.15.0beta1
  • v2.14.0rc1
  • v2.12.3
  • v2.13.0
  • v2.11.7
  • v2.14.0beta2
  • v2.13.0rc1
  • v2.12.2
  • debian/2.10.7.1+grnet1+bpo2+rmext-1
  • v2.14.0beta1
  • v2.12.1
  • v2.13.0beta1
31 results
Blame History Permalink
rapi.rst 24.34 KiB

Ganeti remote API

Documents Ganeti version |version|

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.

Users and passwords

ganeti-rapi reads users and passwords from a file (usually /var/lib/ganeti/rapi_users) on startup. After modifying the password file, ganeti-rapi must be restarted.

Each line consists of two or three fields separated by whitespace. The first two fields are for username and password. The third field is optional and can be used to specify per-user options. Currently, write is the only option supported and enables the user to execute operations modifying the cluster. Lines starting with the hash sign (#) are treated as comments.

Passwords can either be written in clear text or as a hash. Clear text passwords may not start with an opening brace ({) or they must be prefixed with {cleartext}. To use the hashed form, get the MD5 hash of the string $username:Ganeti Remote API:$password (e.g. echo -n 'jack:Ganeti Remote API:abc123' | openssl md5) [1] and prefix it with {ha1}. Using the scheme prefix for all passwords is recommended. Scheme prefixes are not case sensitive.

Example:

# Give Jack and Fred read-only access
jack abc123
fred {cleartext}foo555

# Give write access to an imaginary instance creation script
autocreator xyz789 write

# Hashed password for Jessica
jessica {HA1}7046452df2cbb530877058712cf17bd4 write
[1] Using the MD5 hash of username, realm and password is described in RFC2617 ("HTTP Authentication"), sections 3.2.2.2 and 3.3. The reason for using it over another algorithm is forward compatibility. If ganeti-rapi were to implement HTTP Digest authentication in the future, the same hash could be used. In the current version ganeti-rapi's realm, Ganeti Remote API, can only be changed by modifying the source code.

Protocol

The protocol used is JSON over HTTP designed after the REST principle. HTTP Basic authentication as per RFC2617 is supported.

PUT or POST?

According to RFC2616 the main difference between PUT and POST is that POST can create new resources but PUT can only create the resource the URI was pointing to on the PUT request.

Unfortunately, due to historic reasons, the Ganeti RAPI library is not consistent with this usage, so just use the methods as documented below for each resource.

For more details have a look in the source code at lib/rapi/rlib2.py.

Generic parameter types

A few generic refered parameter types and the values they allow.

bool

A boolean option will accept 1 or 0 as numbers but not i.e. True or False.

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 boolean dry-run argument, if provided and set, 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.

force

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

Usage examples

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

Ganeti RAPI client

Ganeti includes a standalone RAPI client, lib/rapi/client.py.

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

/

The root resource.

It supports the following commands: GET.

GET

Shows the list of mapped resources.

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

/2

The /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 information resource.

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/redistribute-config

Redistribute configuration to all nodes.

It supports the following commands: PUT.

PUT

Redistribute configuration to all nodes. The result will be a job id.

/2/features

GET

Returns a list of features supported by the RAPI server. Available features:

instance-create-reqv1
Instance creation request data version 1 supported.