Jump to: navigation, search


#!wiki caution
'''This page is outdated'''

The content of this page has not been updated for a very long time. Sections of this page are incorrect when referring to the current release.

Live notes, yadda, yadda, yadda: http://etherpad.openstack.org/API

API Concepts:

Server: Within the current implementation of the OpenStack API, a Server is a client VM running on a host. Required elements for provisioning a Server are a Flavor and an Image.

Flavor: A flavor is a hardware configuration for the provisioning of VMs. Each flavor has a unique combination of disk space, RAM capacity, and CPU priority weighting.

Image: An image is a collection of files used to provision a server.

Resize: In addition to horizontally scaling, it is possible to change the flavor of a VM. A resize request requires a flavor - depending on the flavor and the image, a resize may fail for lack of space. Effectively, when a resize occurs we take a snapshot of the running VM and rsync it to the destination. We then bring down the running VM, and rsync the VM to the destination to get whatever changed while the instance was running. We then bring the instance up on the destination, and if the customer verifies that the instance is running correctly we destroy the VM on the source. If the customer chooses instead to revert, we delete the VM on the destination.

Rebuild: Rebuilding a VM wipes the disk and installs a clean installation of whatever image the request specifies.

Shared IP Addresses: All Rackspace Cloud VMs have at least one public facing, routable IP address and exactly one internally-routable RFC1918 address. A shared IP address is an IP that is associated with multiple slices. Each host server is configured for our ebtables, iptables rules to support the interface floating between VMs.

Shared IP Group: IP addresses may only be shared between VMs within the same cluster. In order to abstract sharing addresses without revealing the cluster concept to users, the RS cloud API offers shared IP groups. After a shared IP group is created, VMs may be created within the group and may shared addresses between each other.

Reboot: There are two types of reboot. A soft-reboot politely asks the VM to shut down. A hard-reboot is the VM equivalent of pulling the power. We actually attempt a graceful shutdown before killing the VM directly, so a hard-reboot could actually act as a soft-reboot.

Backup Schedule: The API allows you to schedule daily or weekly backups for each VM. Backups may be enabled or disabled per-VM and each VM has its own schedule. There is not currently a way to schedule backups for every VM at the same time.


Currently RS Cloud API authentication is handled by a RESTful authentication service. To authenticate, the user makes a GET request to the authentication end point with their username and API access key in the X-Auth-User and X-Auth-Key x-headers, respectively. If authentication is successful, the authentication service returns HTTP status 204 No Content and three cloud service headers, X-Server-Management-Url, X-Storage-Url, X-CDN-Management-Url and an X-Auth-Token header. If authentication is unsuccessful, the auth service returns 401 unauthorized. The authentication token is typically valid for 24 hours and applications should be designed to re-authenticate upon receipt of a 401 unauthorized header.

Namespacing: To support the APIs in addition to the core OpenStack RESTful API, we'll need to namespace all non-standard ones. How should that be implemented? http://api-endpoint/namespace/request? http://api-endpoint/namespace-request? http://namespace.api-endpoint.com/request? Are there any others?

Requirements: The current implementation of the API (the rackspace reference) is entirely synchronous end-to-end. The ozone implementation of the API must be written so that requests are entirely asynchronous. Any feature that would require or imply a synchronous API call must be optional. The ozone implementation of the API should be written in a modular fashion so that OpenStack may support multiple namespaced APIs in addition to the core, supported API.

Pithy Insights: