REST API

Development of the RESTful API for GWM started as a Google Summer of Code 2011 project. The developer, Bojan Suzic, can be reached at bojan.suzic@gmail.com. The mentor for this project is Peter Krenesky.

The current version of the page describes its status as of ~end August 2011. Currently it supports a fair amount of the underlying functionality.

Additionally, this page is intented as a development resource and documentation source for the project.

The project code can be reached at https://github.com/bsu/GWM2. The additional code (changes in other related modules) can be found at the following locations:

Users and developers are encouraged to try this addon and send their suggestions/bug reports/improvements either directly to the author, using the GWM mailing list or issue tracker. Please put the line **[REST-API]** in the subject if you are sending email message.

REST API for GWM can now be considered as a beta software. For the further development the following is proposed:

Roadmap:

  • completion of unit tests

  • relocate parts of endpoints which may contain long answers - that variables should be accessed separately (such as object logs)

  • further refinement of the code and documentation

  • work on further integration (like cloud driver)

The users/developers/visitors are advised to test the code and submit the comments/notices/wishes. Comments can be submitted either directly to the author, here on this wiki or using the Redmine ticket

The version containing significant changes to this version may be expected in November 2011.

About this documentation

This documentation covers basic functionality of the REST API. It consists of the subsections, referring to particular endpoints forming the API. As an endpoints referred are application resources exposed as URIs through appropriate hierarchy. Currently, the system exposes the following resources as REST API endpoints: User, Group, Virtual Machine, Cluster, Node, Job. These are accessible in the form of CRUD operations using HTTP protocol.

By default, each API endpoint returns a list of resources.

For example:

/api/vm/

would return a list of Virtual Machines in the system, while the particular VM resource is accessed through:

/api/vm/1/

where 1 represents identifier of particular Virtual Machine. This way only that particular resource is returned. Each resource contains fields related to particular instance in the system. The field types and their properties are described further in the documentation, as a part of related subsections.

For each endpoint described is basic scheme of its resource representation. The scheme includes name, type and description of the particular fields, Additional properties described are possibility for the field to be modified and whether the field returned may be excluded from the representation e.g. nullable. The later one might be useful for clients to prevent unexpected behavior.

While type field represents basic data types, it should be noted that related type points to other resource in the system. For example:

...
<cluster>
...
<virtualmachine>
/api/vm/5
</virtualmachine>
</cluster>
...

says that particular cluster resource includes virtualmachine resource, described by related URI. Therefore, if necessary, the complete resource referred at that point may be obtained through provided URI.

This documentation trends to provide as much as complete list of resources and their schematic description. However, due to the level of deepness and limitations of the current wiki system, in some cases this representation is simplified and explained in words rather than in tabular form. It should be noted that all these descriptions are already included in the system.

Using:

http://somesite.com/api/?format=xml

user is able to get the list of resources exposed, while with the help of:

http://somesite.com/api/resource/schema/?format=xml

the system returns detailed schema of resource representation and field properties in XML format. Therefore, the user is always able to take a look and check detailed description about a resource, if the one provided here in documentation is not detailed and clear enough.

Design principles

This API aims to expose the resources of Ganeti Web Manager, making suitable for integration into other systems or just performing of simple operations on resources. It does not aim to expose all resources and functions contained in the software, but only the set deemed necessary in order to support its business functions. Currently, it means that the most of the functionality present in the web interface is available for usage and manipulation also using this REST API.

Installation

The most of the code of this addon comes under /api directory of GWM distribution. Other code changes are done in some of views and dependent modules (like django_object_log and django_object_permissions). Its inclusion in the GWM is done in /urls.py via:

urlpatterns = patterns('',
...
    (r'^', include('api.urls')),
...

The prerequisite for running RESTful API over Ganeti Web Manager is to have django-tastypie installed. The latest active version/commit of tastypie should be used in order to support ApiKeys based authentication. That means, as of time of writing this documentation, that tastypie should be installed manually. Additionally, the following line in tastypie/authentication.py:

username = request.GET.get('username') or request.POST.get('username')

should be changed to:

username = request.GET.get('username') or request.POST.get('username')
or request.GET.get('user') or request.POST.get('user')

This is the known issue with tastypie already reported in its bug system. If not changed, the part username in /api/user/?api_key=xxx&username=xxx will produce error message during browsing the main user endpoint. This change makes tastypie to accept user for authentication instead of username. Later produces collision with the field of the same name under User model class.

The next change related to the installation of the module is inclusion of ‘tastypie’ in INSTALLED_APPS of settings.py. This will produce necessary tables during installation/migration.

Development

The code is prepared as a part of GSoC activities, and therefore by person not being a part of narrowed GWM development team before. As a such, the main principle to be followed is to try not to interfere too much with existing code. It implies further that the resulting code should be considered as an simple to install add-on. The core business logic of the GWM have not been changed or altered. The most changes done on GWM code are of technical nature, trying to make functions/views accessible to REST backend interface additionally. The code has been committed to separate repository. I tried mostly to perform smaller commits in size, in order to make the code and changes easily readable and trackable.

The framework used to introduce RESTful interface is django-tastypie. It has been selected after initial research and testing of several popular Python/Django/REST frameworks. The system supports both XML and JSON as input/output serializations.

Authentication and Authorization

The authentication is done using API keys. For each user the appropriate API key is generated automatically. The key can be renewed/recreated using POST request and appropriate action inside API. The access to the system looks like in the following example:

http://localhost:8000/api/?format=xml&api_key=381a5987a611fb1f8c68ffad49d2cd2b9f92db71&user=test

Note

username initially supported by tastypie has been replaced with user in the example query above. The changes and reasons are described in the installation section of this document.

Authorization is completely dependent on Django’s authorization system. The existing views from the GWM have been used to expose the most of resources available. Those views are already integrated in Django’s authorization system. Therefore, this API should not contain critical security flaws or problems and should be easier to maintenance.

REST API endpoints

/api/user

This endpoint exposes data and operations related to the user management. The following table provides the descriptions of the fields:

Name Type ReadOnly Nullable Description
username string Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters
ssh_keys list x SSH keys for user's account. The list may be composed of several objects.
first_name string Unicode string data. Ex: "Hello World"
last_name string Unicode string data. Ex: "Hello World"
actions_on_user list x x Returns the actions done on the user. The list is composed of objects, containing elements as described here.
groups related x x Returns the groups the user is member of
api_key string x x Returns the api key of the user
used_resources list x x Returns the resources used by the objects user has access to in the form of the list.
is_active boolean Designates whether this user should be treated as active. Unselect this instead of deleting accounts.
id string x Unicode string data. Ex: "Hello World"
is_superuser boolean Designates that this user has all permissions without explicitly assigning them.
is_staff boolean Designates whether the user can log into this admin site.
last_login datetime A date & time as a string. Ex: "2010-11-10T03:07:43"
date_joined datetime A date & time as a string. Ex: "2010-11-10T03:07:43"
user_actions list x Returns the actions done by the user. The list is composed of objects, containing elements as described here.
permissions list x x Returns the status of users permissions on different families of objects
password string Returns hashed password
email string Unicode string data. Ex: "Hello World"
resource_uri string x Unicode string data. Ex: "Hello World"

Explanations for particular list elements

Container: ssh_keys

The elements of the list are denoted as value nodes, containing paricular ssh key for the user in the form of string hash

Example:

<ssh_keys type="list">
<object type="hash">
<id type="integer">1</id>
<key>ssh-rsa
A398kuwNzaC1yc2EAAAADAQABAAABAQDI2oqyrleSvAg4CV5A/4ZZ2fTEFAYU1W2i8373zspaJCSO0eHIl+v4fGeIzH7CFokbM98ip2mwe7KtFk2VoO1
/E9ucXR4xcxo77sxGSGH8hiS89aUcHmPKyRYlYj5TwqkZopxYTFmeUhkhP9e5YrlTRXMdhMsIXqXAKRujjySycQ45QLqdYOHbfohU0aKtDN01bYFOQ7/y/9wepXczlXD7rTIhT6
/aq2vvOoyiGo9vaiIfqbtLjqkjwecDGykesw1c9d07vH53myiLLLkAGGk4KudKSWV6ZxK0ap3/olzzJ3HZpk5MAel5ELX6XuT8VmA3H3Yl5N//DrBUmKciMIaRx
xxx@gmail.com
</key>
</object>
<object>
<id type="integer">2</id>
<key>ssh-rsa
7398kuwNzaC1yc2EAAAADAQABAAABAQDI2oqyrleSvAg4CVjskajslajwFAYU1W2i8373zspaJCSO0eHIl+v4fGeIzH7CFokbM98ip2mwe7KtFk2VoO1
/E9ucXR4xcxo77sxGSGH8hiS89aUcHmPKyRYlYj5TwqkZopxYTFmeUhkhP9e5YrlTRXMdhMsIXqXAKRujjySycQ45QLqdYOHbfohU0aKtDN01bYFOQ7/y/9wepXczlXD7rTIhT6
/aq2vvOoyiGo9vaiIfqbtLjqkjwecDGykesw1c9d07vH53myiLLLkAGGk4KudKSWV6ZxK0ap3/olzzJ3HZpk5MAel5ELX6XuT8VmA3H3Yl5N//DrBUmKciMIYYY
yyy@gmail.com
</key>
</object>
</ssh_keys>

Containers: user_actions and actions_on_users

This is the list of objects, each object consisting of nullable fields denoted as obj1, obj2, user, action_name. The both containers share the representation. The difference between these is the fact that first describes actions performed by user, while the second one describes actions performed on user (by administrator, for instance). The both containers provide read only information.

Name Type Description
obj1, obj2 related Describe action object
timestamp timestamp> Date and time of action execution
user related User performing the action
action_name string Describes action name using internal descriptions

Example:

<user_actions type="list">
<object type="hash">
<obj1>/api/vm/3/</obj1>
<timestamp>2011-07-31T15:23:45.533479</timestamp>
<obj2>/api/job/68/</obj2>
<user>/api/user/2/</user>
<action_name>VM_REBOOT</action_name>
</object>
<object type="hash">
<obj1>/api/vm/3/</obj1>
<timestamp>2011-07-31T17:04:02.333061</timestamp>
<user>/api/user/2/</user>
<action_name>EDIT</action_name>
</object>

Container used_resources

This list consists of object elements, each containing resource, object and type. The field object represents related resource for which the system resources consumption is given. The type is string describing the object type using internal descriptions (like VirtualMachine for virtual machine). The resource contains subfields virtual_cpus, disk and ram, each of type integer and representing actual consumption of the particular system resource in system’s default dimension (e.g. MBs for RAM consumption).

Example:

<used_resources type="list">
<object type="hash">
<resource type="hash">
<virtual_cpus type="integer">0</virtual_cpus>
<disk type="integer">0</disk>
<ram type="integer">0</ram>
</resource>
<object>/api/vm/3/</object><
type>VirtualMachine</type>
</object>
<object type="hash">
<resource type="hash">
<virtual_cpus type="integer">0</virtual_cpus>
<disk type="integer">0</disk>
<ram type="integer">0</ram></resource>
<object>/api/vm/11/</object>
<type>VirtualMachine</type>
</object>
</used_resources>

Container permissions

Permissions contains elements describing particular resource type, each further containing a list of resources. The primary elements are described as Cluster, VirtualMachine, Group. Their list member main nodes are described as object, containing object reference (related resource) for which the permissions are set, and the permissions list containing list of values as strings, describing permission type in internal format (like create_vm).

Example:

<permissions type="hash">
<Cluster type="list"/>
<Group type="list"/>
<VirtualMachine type="list">
<object type="hash">
<object>/api/vm/3/</object>
<permissions type="list">
<value>admin</value>
<value>power</value>
<value>tags</value>
</permissions>
</object>
<object type="hash">
<object>/api/vm/11/</object>
<permissions type="list">
<value>admin</value>
</permissions></object>
</VirtualMachine>
</permissions>

Manipulation and operations using POST/PUT/DELETE methods

The fields marked as non-readonly (table above) can be subject of further manipulation and operations. The same applies to the rest of the document - those fields can be automatically updated or deleted by performing analog request. In order to maintain consistency with REST approach, the PUT method is used on currently available resources with purpose to change or update them. On another side, POST method is used either to generate new resources, or to perform predefined actions on currently existing resources.

The following example demonstrates changing of users lastname and status in system (disabling its account). Request URI:

PUT /api/user/1/?api_key=xxxxx&username=yyyyy

Request header:

Content-Type: application/json
Accept: application/json

Request payload:

{"last_name":"New LastName", "is_active":false}

Server response:

HTTP/1.1 204 NO CONTENT
Date: Sat, 06 Aug 2011 11:18:25 GMT
Server: WSGIServer/0.1 Python/2.7.1+
Vary: Accept-Language, Cookie
Content-Length: 0
Content-Type: text/html; charset=utf-8
Content-Language: en

The next example demonstrates generating of new Api key for the user:

Request URI:

POST /api/user/2/?api_key=xxxxx&username=yyyyy

Request header:

Content-Type: application/json
Accept: application/xml

Request payload:

{"action":"generate_api_key"}

Server response:

HTTP/1.1 201 CREATED
Date: Sat, 06 Aug 2011 11:21:56 GMT
Server: WSGIServer/0.1 Python/2.7.1+
Vary: Accept-Language, Cookie
Content-Type: text/html; charset=utf-8
Content-Language: en

Response body:

<?xml version='1.0' encoding='utf-8'?>
<object>
<api_key>de0a57db0ce43d0f3c52f83eaf33387750ac9953</api_key>
<userid>2</userid>
</object>

For the API Key manipulation under /api/user/ endpoint implemented are two POST actions: generate_api_key, as demonstrated in the example above, and clean_api_key. The former generates a new API key for the user and returns it in the response, while the later one cleans user’s API key. This way its access to the system using REST API is disabled, but the standard access using web interface is untouch.

Additionally, two POST actions are implemented for user-group membership manipulation.

Action Payload Description Example
add_to_group group Add the user to the group
{'action':'add_to_group', 'group':'/api/group/1/'}
remove_from_group group Remove the user from the group
{'action':'remove_from_group', 'group':'/api/group/1/'}
generate_api_key - Generate API key for the user
{'action':'generate_api_key'}
clean_api_key - Clean API key for the user
{'action':'clean_api_key'}

/api/group

This endpoint exposes data and operations related to the group management. The following table summarizes supported fields.

Name Type ReadOnly Nullable Description
actions_on_group list x Returns the actions done on the group. The list is composed of objects, containing elements as described here.
users related x Returns a list of the users belonging to the group.
used_resources list x x Returns the resources used by the objects the group has access to in the form of the list.
permissions list x x Returns the status of users permissions on different families of objects
resource_uri string x Unicode string data. Ex: "Hello World"
id string x Unicode string data. Ex: "Hello World"
name string Unicode string data. Ex: "Hello World"

Container: actions_on_group

This is the list of objects, each object consisting of nullable fields denoted as obj1, obj2, user, action_name. This container describes actions performed on the group (by administrator, for instance) in the form of read-only information. Please note that inclusion od obj1 and obj2 depends on the action type, e.g. one of these may be omitted.

Name Type Description
obj1, obj2 related Describe action object
timestamp timestamp> Date and time of action execution
user related User performing the action
action_name string Describes action name using internal descriptions

Example:

<actions_on_group type="list">
<object type="hash">
<obj1>/api/group/1/</obj1>
<timestamp>2011-07-29T08:28:24.566903</timestamp>
<user>/api/user/1/</user>
<action_name>CREATE</action_name>
</object>
<object type="hash">
<obj1>/api/cluster/1/</obj1>
<timestamp>2011-07-29T08:28:59.854791</timestamp>
<obj2>/api/group/1/</obj2>
<user>/api/user/1/</user>
<action_name>ADD_USER</action_name>
</object>
</actions_on_group>

Field: users

This simple field contains a list of users belonging to the group. The type of the resource is related, which means that it points to the URI representing the resource. Example:

<users type="list">
<value>/api/user/2/</value>
<value>/api/user/3/</value>
</users>

Container used_resources

The syntax used here is the same as used in the <object>User</object> resource. For more information and example, please refer to the user section of this document.

Container permissions

The syntax used here is the same as used in the <object>User</object> resource. For more information and example, please refer to the user section of this document.

Manipulation actions

Action Payload Description Example
add_user user Add the user to the group
{'action':'add_user', 'user':'/api/user/2/'}
remove_user user Remove the user from the group
{'action':'remove_user', 'user':'/api/user/2/'}

/api/vm

This endpoint exposes methods for VirtualMachine inspection and manipulation.

Important: as the attributes exposing VM object are related to many other objects and many calls are done on different views, here the somewhat different approach to attribute exposure is used. At the main point /api/vm/, which provides a list of virtual machines, only the basic attributes of VM are provided. However, when the particular object is called, sad /api/vm/3/, the system returns additional set of its attributes. This is due to need to perform additional calls which introduce network latency. Performing all those calls at once for all virtual machines could produce unnecessary overhead.

Fields exposed (main endpoint):

Name Type ReadOnly Nullable Description
pending_delete boolean Boolean data. Ex: True
ram integer Integer data. Ex: 2673
cluster related x A single related resource. Can be either a URI or set of nested resource data.
last_job related x A single related resource. Can be either a URI or set of nested resource data.
virtual_cpus integer Integer data. Ex: 2673
id string Unicode string data. Ex: "Hello World"
hostname string Unicode string data. Ex: "Hello World"
status string Unicode string data. Ex: "Hello World"
secondary_node related x A single related resource. Can be either a URI or set of nested resource data.
operating_system string Unicode string data. Ex: "Hello World"
disk_size integer Integer data. Ex: 2673
primary_node related x A single related resource. Can be either a URI or set of nested resource data.
resource_uri string Unicode string data. Ex: "Hello World"

Fields exposed (additionally, particular object):

Name Type ReadOnly Nullable Description
cluster_admin Boolean x Determines if the current user has admin permissions over cluster.
power Boolean x Determines if the current user has admin permissions to power vm.
modify Boolean x Determines if the current user has admin permissions to modify vm.
job Boolean x x Points to the jobs related to the vm, if any.
actions_on_vm list x x Returns the actions done on the user. The list is composed of objects, containing elements as described here.
permissions list x Lists the objects (users and groups) having permissions over vm. Contains sublists users and groups, each having objects pointing to related user/group.
admin Boolean x Determines if the current user has admin permissions over vm.
remove Boolean x Determines if the current user has permissions to remove vm.
migrate Boolean x Determines if the current user has admin permissions to migrate.

Containers: actions_on_vm and permissions

The format and members of those lists are similar to previous mentioned fields, e.g. in cluster endpoint. For detailed description, please refer to those.

The field actions_on_vm contains object(s) taking part in action, user initiated the action, timestamp and the internal description of the action in form of the string. The field permissions> lists users and groups (as related fields) which have any form of permissions on virtual machine.

Operations supported

Operations on VM are accomplished in form of action. Action is initiated using POST request. Example:

POST /api/vm/7
{"action":"shutdown"}

In this example, user initiates @POST@ request on Virtual Machine described with @id=7@. The action type is described in field @action@ in request header.

After the action is initiated, server sends back response. Example:

Header:

HTTP/1.1 200 OK
Date: Wed, 27 Jul 2011 18:39:31 GMT
Server: WSGIServer/0.1 Python/2.7.1+
Vary: Accept-Language, Cookie
Content-Type: application/json
Content-Language: en

Body:

{"end_ts": null, "id": "138722", "oplog": [[]], "opresult": [null],
"ops": [{"OP_ID": "OP_INSTANCE_SHUTDOWN", "debug_level": 0, "dry_run":
false, "ignore_offline_nodes": false, "instance_name":
"ooga.osuosl.org", "priority": 0, "timeout": 120}], "opstatus":
["running"], "received_ts": [1311791966, 837045], "start_ts":
[1311791966, 870332], "status": "running", "summary":
["INSTANCE_SHUTDOWN(ooga.osuosl.org)"]}

The following actions and parameters are supported:

Action Parameters Description
reboot Reboot VM
shutdown Shutdown VM
startup Start VM up
rename hostname,ip_check,name_check Rename VM

/api/cluster

This endpoint describes fields and operations available for the Cluster.

Name Type ReadOnly Nullable Description
ram integer x Integer data. Ex: 2673
nodes_count Integer x x Returns nodes count for the cluster.
default_hypervisor string x Returns a default hypervisor for the cluster.
virtual_cpus integer x Integer data. Ex: 2673
disk integer x Integer data. Ex: 2673
port integer Integer data. Ex: 2673
hostname string Unicode string data. Ex: "Hello World"
id string Unicode string data. Ex: "Hello World"
available_ram list x x Returns a list with elements describing RAM status, including total, allocated, used and free memory.
master string x Returns master node
missing_ganeti list x x Returns a list with names of missing nodes in ganeti.
username string x Unicode string data. Ex: "Hello World"
missing_db list x x Returns a list with names of missing nodes in DB.
description string x Unicode string data. Ex: "Hello World"
software_version string x Returns a software version.
quota list x x Returns a list containing objects describing quotas for the user performing the request.
slug string Unicode string data. Ex: "Hello World"
info list x x Complex container exposing many information related to the cluster. More details with example can be found in documentation/wiki.
available_disk list x x Returns a list with elements describing disk status, including total, allocated, used and free disk space.
default_quota list x x Returns a list containing objects describing default quotas.
resource_uri string Unicode string data. Ex: "Hello World"
vm_count Integer x x Returns a number of virtual machines on the cluster.

Containers: available_ram and available_disk

The first container provides information about status of the RAM in the cluster. Analogously, the second one provides information about disk space in the cluster.

Name Type Description
total Integer Total RAM available to the cluster
allocated Integer> Allocated RAM
used Integer Amount of RAM used in the cluster
free Integer Free RAM

Example:

<available_ram type="hash">
<allocated type="integer">1024</allocated>
<total type="integer">2004</total>
<used type="integer">874</used>
<free type="integer">980</free>
</available_ram>

Containers: missing_ganeti and missing_db

Here the names of the missing machines are provided in the simple form. The former container describes machines missing in the Ganeti, while the former contains the machines missing in the database.

Example:

<missing_db type="list">
<value>3429_test</value>
<value>breakthis.gwm.osuosl.org</value>
<value>brookjon.gwm.osuosl.org</value>
<value>noinstall2.gwm.osuosl.org</value>
</missing_db>

Container: quota and default_quota

This container returns the quotas for the user performing request. If the user is not found or do not have a quotas assigned, default quota is returned. If there are no values for the specific quota element, null is returned. Default_quota container is additionally returned for the case that quota for the user if found.

Name Type Description
default Integer Used if default quota is returned
virtual_cpus Integer Virtual CPUs
ram Integer Amount of RAM available to the user
disk Integer Amount of disk available to the user

Example:

<quota type="hash">
<default type="integer">1</default>
<virtual_cpus type="null"/>
<ram type="null"/>
<disk type="null"/>
</quota>

Container: info

This element provides extensive information related to the cluster. These information are used internally in Ganeti Web Manager to render specific pages. As of level of detail used, the field contained here will not be described but just provided in detail in example.

<info type="hash">
<default_iallocator/>
<maintain_node_health type="boolean">False</maintain_node_health>
<hvparams type="hash">
<kvm type="hash">
<nic_type>paravirtual</nic_type>
<use_chroot type="boolean">False</use_chroot>
<migration_port type="integer">8102</migration_port>
<vnc_bind_address>0.0.0.0</vnc_bind_address>
<cdrom2_image_path/>
<usb_mouse/>
<migration_downtime type="integer">30</migration_downtime>
<floppy_image_path/>
<kernel_args>ro</kernel_args>
<cdrom_image_path/>
<boot_order>disk</boot_order>
<vhost_net type="boolean">False</vhost_net>
<disk_cache>default</disk_cache>
<kernel_path/>
<initrd_path/>
<vnc_x509_verify type="boolean">False</vnc_x509_verify>
<vnc_tls type="boolean">False</vnc_tls>
<cdrom_disk_type/>
<use_localtime type="boolean">False</use_localtime>
<security_domain/>
<serial_console type="boolean">False</serial_console>
<kvm_flag/>
<vnc_password_file/>
<migration_bandwidth type="integer">32</migration_bandwidth>
<disk_type>paravirtual</disk_type>
<migration_mode>live</migration_mode>
<security_model>pool</security_model>
<root_path>/dev/vda3</root_path>
<vnc_x509_path/>
<acpi type="boolean">True</acpi>
<mem_path/>
</kvm>
</hvparams>
<default_hypervisor>kvm</default_hypervisor>
<uid_pool type="list">
<objects>
<value type="integer">8001</value>
<value type="integer">8030</value>
</objects>
</uid_pool>
<prealloc_wipe_disks type="boolean">False</prealloc_wipe_disks>
<primary_ip_version type="integer">4</primary_ip_version>
<mtime type="float">1308862451.98</mtime>
<os_hvp type="hash"/>
<osparams type="hash"/>
<uuid>0b3b2432-a8e1-4c17-a99b-87303841cb95</uuid>
<export_version type="integer">0</export_version>
<hidden_os type="list"/>
<master>gwm1.osuosl.org</master>
<nicparams type="hash">
<default type="hash">
<link>br0</link>
<mode>bridged</mode>
</default>
</nicparams>
<protocol_version type="integer">2040000</protocol_version>
<config_version type="integer">2040000</config_version>
<software_version>2.4.2</software_version>
<tags type="list"/>
<os_api_version type="integer">20</os_api_version>
<candidate_pool_size type="integer">10</candidate_pool_size>
<file_storage_dir>/var/lib/ganeti-storage/file</file_storage_dir>
<blacklisted_os type="list"/>
<enabled_hypervisors type="list">
<value>kvm</value>
</enabled_hypervisors>
<drbd_usermode_helper>/bin/true</drbd_usermode_helper>
<reserved_lvs type="list"/>
<ctime type="float">1292887189.41</ctime>
<name>gwm.osuosl.org</name>
<master_netdev>eth0</master_netdev>
<ndparams type="hash">
<oob_program type="null"/>
</ndparams>
<architecture type="list">
<value>64bit</value>
<value>x86_64</value>
</architecture>
<volume_group_name>ganeti</volume_group_name>
<beparams type="hash">
<default type="hash">
<auto_balance type="boolean">True</auto_balance>
<vcpus type="integer">2</vcpus>
<memory type="integer">512</memory>
</default>
</beparams>
</info>

/api/node

In this endpoint exposed are the attributes and operations on the Cluster.

Name Type ReadOnly Nullable Description
info list x This complex field returns various information related to the node.
ram_free integer x Integer data. Ex: 2673
Admin boolean x Determines if the user has admin status on the node
hostname string x Hostname of the node
modify boolean x Determines if the user is able to modify node parameters
cluster related x Cluster the node belongs to
disk_total integer Integer data. Ex: 2673
node_count Integer x Number of the nodes in the cluster
last_job related x A single related resource. Can be either a URI or set of nested resource data.
disk_free integer x Integer data. Ex: 2673
ram_total integer x Integer data. Ex: 2673
role string x Unicode string data. Ex: "Hello World"
offline boolean x Boolean data. Ex: True
id string x Unicode string data. Ex: "Hello World"
primary_list list x x List of virtual machines (primary node). Contains vm link (related) and hostname for particular object.
secondary_list list x x List of virtual machines (secondary node). Contains vm link (related) and hostname for particular object.
actions_on_node list x Returns the actions done on the node. The list is composed of objects, containing elements as described here.
resource_uri string x Unicode string data. Ex: "Hello World"

Container: actions_on_node

This container provides the actions done on the node in form of the log. It is similar in the form to the other actions_on_X containers in other endpoints. For more info please take a look there.

Container: primary_list and secondary_list

These containers provide the list of virtual machines existing on the node in primary and secondary node mode. The list is simple and includes object hostname and related link. Example:

<primary_list type="list">
<object type="hash">
<hostname>3429</hostname>
<resource>/api/vm/1/</resource>
</object>
<object type="hash">
<hostname>breakthis.gwm.osuosl.org</hostname>
<resource>/api/vm/2/</resource>
</object>
</primary_list>

Container: info

This element provides extensive information related to the node. These information are used internally in Ganeti Web Manager to render specific pages. As of level of detail used, the field contained here will be described partially only. It should be noted that the elements in the table may be nullable. The full example output is included after the table.

Name Type Description
pinst_cnt Integer Number of virtual machines for which the node is primary
sinst_cnt Integer Number of virtual machines for which the node is secondary
pinst_list List Virtual machines on this node (primary)
sinst_list List Virtual machines on this node (secondary)
drained Boolean Determines if the node is drained
offline Boolean Determines if the node is ofline
vm_capable Boolean Determines if the node is capable of hosting virtual machines
master_capable Boolean Determines if the node is capable to become master node
master_candidate Boolean Determines if the node is master candidate
mnode Boolean Determines if the node is active master node
pip String Primary IP address of the node
sip String Secondary IP address of the node
uuid String UUID
group.uuid String group UUID
tags List Tags attached to the node
<info type="hash">
<dfree type="integer">30336</dfree>
<cnodes type="integer">1</cnodes>
<serial_no type="integer">1</serial_no>
<dtotal type="integer">60012</dtotal>
<sinst_cnt type="integer">0</sinst_cnt>
<mtime type="null"/>
<pip>140.211.15.61</pip>
<mfree type="integer">1310</mfree>
<sip>140.211.15.61</sip>
<uuid>4a0e9df5-0b59-4643-b156-c133edb035bc</uuid>
<drained type="boolean">False</drained>
<sinst_list type="list"/>
<csockets type="integer">1</csockets>
<role>M</role>
<ctotal type="integer">2</ctotal>
<offline type="boolean">False</offline>
<vm_capable type="boolean">True</vm_capable>
<pinst_cnt type="integer">15</pinst_cnt>
<mtotal type="integer">2004</mtotal>
<tags type="list"/>
<group.uuid>e318906a-40cd-4702-813b-c2185abaf8ec</group.uuid>
<master_capable type="boolean">True</master_capable>
<ctime type="null"/>
<master_candidate type="boolean">True</master_candidate>
<name>gwm1.osuosl.org</name>
<mnode type="integer">730</mnode>
<pinst_list type="list">
<value>3429</value>
<value>noinstall2.gwm.osuosl.org</value>
<value>failed</value>
<value>success</value>
<value>derpers.gwm.osuosl.org</value>
<value>testtest</value
><value>breakthis.gwm.osuosl.org</value>
<value>foobarherpderp.gwm</value>
<value>brookjon.gwm.osuosl.org</value>
<value>orphanme</value>
<value>foobar352</value>
<value>testcdrom2.gwm.osuosl.org</value>
<value>ooga.osuosl.org</value>
<value>diskless3</value>
<value>noinstall.gwm.osuosl.org</value>
</pinst_list>
</info>

/api/job

This endpoint exposes information related to the job execution in the system.

Name Type ReadOnly Nullable Description
status string Unicode string data. Ex: "Hello World"
summarys string x x Describes the job summary.
job_id integer Integer data. Ex: 2673
cluster_admin Boolean x Determines if the current user has admin permissions over related cluster.
ops list x Complex field containing details about job. The field contents depend on the job type. More details can be found in the wiki.
opresult list x x Describes the error occurred during job execution.
cluster related A single related resource. Can be either a URI or set of nested resource data.
finished datetime x A date & time as a string. Ex: "2010-11-10T03:07:43"
cleared boolean Boolean data. Ex: True
resource_uri string Unicode string data. Ex: "Hello World"

Container: opresult

This field contains a detailed description of error encountered during job execution. The fields included are the following:

Name Type Description
error_type string Denotes the type of the error
error_message string Contains a summary description of the error. May be omitted.
error_family string Relates error to the family of errors. May be omitted.

Example:

<opresult type="hash">
<error_type>OpPrereqError</error_type>
<error_message>The given name (owelwjqe) does not resolve: Name or
service not known</error_message>
<error_family>resolver_error</error_family>
</opresult>

Container: ops This field contains information about the job executed. There may be many subfields included, spanned through several levels.

The following excerpts provide two typical example outputs:

<pre>
<ops type="list">
<object type="hash">
<hvparams type="hash">
<nic_type>paravirtual</nic_type>
<boot_order>disk</boot_order>
<root_path>/dev/vda3</root_path>
<serial_console type="boolean">False</serial_console>
<cdrom_image_path/>
<disk_type>paravirtual</disk_type>
<kernel_path/>
</hvparams>
<debug_level type="integer">0</debug_level>
<disk_template>plain</disk_template>
<name_check type="boolean">True</name_check>
<osparams type="hash"/>
<src_node type="null"/>
<source_x509_ca type="null"/>
<dry_run type="boolean">False</dry_run>
<pnode>gwm1.osuosl.org</pnode>
<nics type="list">
<object type="hash">
<link>br0</link>
<mode>bridged</mode>
</object>
</nics>
<wait_for_sync type="boolean">True</wait_for_sync>
<priority type="integer">0</priority>
<start type="boolean">True</start>
<ip_check type="boolean">True</ip_check>
<source_shutdown_timeout type="integer">120</source_shutdown_timeout>
<file_storage_dir type="null"/>
<no_install type="boolean">False</no_install>
<src_path type="null"/>
<snode type="null"/>
<identify_defaults type="boolean">False</identify_defaults>
<OP_ID>OP_INSTANCE_CREATE</OP_ID>
<source_instance_name type="null"/>
<source_handshake type="null"/>
<hypervisor>kvm</hypervisor>
<force_variant type="boolean">False</force_variant>
<disks type="list">
<object type="hash">
<size type="integer">408</size>
</object>
</disks>
<instance_name>owelwjqe</instance_name>
<mode>create</mode>
<iallocator type="null"/>
<file_driver>loop</file_driver>
<os_type>image+debian-squeeze</os_type>
<beparams type="hash">
<vcpus type="integer">2</vcpus>
<memory type="integer">512</memory>
</beparams>
</object>
</ops>
</pre>
<pre>
<ops type="list">
<object type="hash">
<instance_name>brookjon.gwm.osuosl.org</instance_name>
<ignore_secondaries type="boolean">False</ignore_secondaries>
<dry_run type="boolean">False</dry_run>
<priority type="integer">0</priority>
<debug_level type="integer">0</debug_level>
<OP_ID>OP_INSTANCE_REBOOT</OP_ID>
<reboot_type>hard</reboot_type>
<shutdown_timeout type="integer">120</shutdown_timeout>
</object>
</ops>
</pre>