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
  • Michael Hanselmann's avatar
    ganeti-rapi: Watch directory, not file for user file changes · 073c31a5
    Michael Hanselmann authored 
    
We noticed several issues when just watching the file, among them race
conditions upon replacing the file using rename(2) (the new watcher
would be created too soon). By just watching the directory for events on
the rapi_users file, this can be avoided.

A nice side-effect is that now the users file is also reloaded if it
didn't exist upon ganeti-rapi's start (see the documentation update).

Since ganeti-rapi now becomes active for virtually every change in the
configuration directory (…/lib/ganeti), moving the rapi_users file to a
separate directory will be considered. It doesn't have to happen in or
before this patch, though.

Signed-off-by: default avatarMichael Hanselmann <hansmi@google.com>
Reviewed-by: default avatarIustin Pop <iustin@google.com>
    073c31a5
rapi.rst 27.38 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. Changes to the file will be read automatically.

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 RFC 2617 ("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 RFC 2617 is supported.

A note on JSON as used by RAPI

JSON as used by Ganeti RAPI does not conform to the specification in RFC 4627. Section 2 defines a JSON text to be either an object ({"key": "value", …}) or an array ([1, 2, 3, …]). In violation of this RAPI uses plain strings ("master-candidate", "1234") for some requests or responses. Changing this now would likely break existing clients and cause a lot of trouble.

Unlike Python's JSON encoder and decoder, other programming languages or libraries may only provide a strict implementation, not allowing plain values. For those, responses can usually be wrapped in an array whose first element is then used, e.g. the response "1234" becomes ["1234"]. This works equally well for more complex values. Example in Ruby:

require "json"

# Insert code to get response here
response = "\"1234\""

decoded = JSON.parse("[#{response}]").first

Short of modifying the encoder to allow encoding to a less strict format, requests will have to be formatted by hand. Newer RAPI requests already use a dictionary as their input data and shouldn't cause any problems.

PUT or POST?

According to RFC 2616 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