-
René Nussbaumer authored
Also fixed a typo I noticed. Signed-off-by:
René Nussbaumer <rn@google.com> Reviewed-by:
Iustin Pop <iustin@google.com>
2263aec2
Ganeti remote API
Documents Ganeti version |version|
Contents
- Introduction
- Users and passwords
- Protocol
- Generic parameters
- Usage examples
-
Resources
-
/ -
/2 -
/2/info -
/2/redistribute-config -
/2/instances -
/2/instances/[instance_name] -
/2/instances/[instance_name]/info -
/2/instances/[instance_name]/reboot -
/2/instances/[instance_name]/shutdown -
/2/instances/[instance_name]/startup -
/2/instances/[instance_name]/reinstall -
/2/instances/[instance_name]/replace-disks -
/2/instances/[instance_name]/activate-disks -
/2/instances/[instance_name]/deactivate-disks -
/2/instances/[instance_name]/tags -
/2/jobs -
/2/jobs/[job_id] -
/2/nodes /2/nodes/[node_name]-
/2/nodes/[node_name]/evacuate -
/2/nodes/[node_name]/migrate -
/2/nodes/[node_name]/role -
/2/nodes/[node_name]/storage -
/2/nodes/[node_name]/storage/modify -
/2/nodes/[node_name]/storage/repair -
/2/nodes/[node_name]/tags -
/2/os -
/2/tags -
/version
-
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.
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 optional dry-run argument, if provided and set to a positive
integer value (e.g. ?dry-run=1), 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.
Shell
Using wget:
wget -q -O - https://CLUSTERNAME:5080/2/infoor curl:
curl https://CLUSTERNAME:5080/2/infoPython
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/instances
The 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 a 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
},
...
]POST
Creates an instance.
If the optional dry-run argument is provided and set to a positive
integer valu (e.g. ?dry-run=1), the job will not be actually
executed, only the pre-execution checks will be done. Query-ing the job
result will return, in both dry-run and normal case, the list of nodes
selected for the instance.
Returns: a job ID that can be used later for polling.
/2/instances/[instance_name]
Instance-specific resource.
It supports the following commands: GET, DELETE.
GET
Returns information about an instance, similar to the bulk output from the instance list.
DELETE
Deletes an instance.
It supports the dry-run argument.
/2/instances/[instance_name]/info
It supports the following commands: GET.
GET
Requests detailed information about the instance. An optional parameter,
static (bool), can be set to return only static information from the
configuration without querying the instance's nodes. The result will be
a job id.
/2/instances/[instance_name]/reboot
Reboots URI for an instance.
It supports the following commands: POST.
POST
Reboots the instance.
The URI takes optional type=hard|soft|full and
ignore_secondaries=False|True parameters.
It supports the dry-run argument.
/2/instances/[instance_name]/shutdown
Instance shutdown URI.
It supports the following commands: PUT.
PUT
Shutdowns an instance.