371ad9e981
This removes extra whitespace that is not needed Change-Id: If3ab21b7d13a378e254df408fab33b12cf794dad
470 lines
27 KiB
XML
470 lines
27 KiB
XML
<?xml version="1.0" encoding="UTF-8"?><book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" version="5.0" status="draft">
|
|
<title>OpenStack API Extensions</title>
|
|
<subtitle>An Overview</subtitle>
|
|
<info>
|
|
<copyright>
|
|
<year>2010</year>
|
|
<year>2011</year>
|
|
<holder>Rackspace US, Inc.</holder>
|
|
</copyright>
|
|
<pubdate>2011-06-10</pubdate>
|
|
<legalnotice role="apache2">
|
|
<annotation>
|
|
<remark>Copyright details are filled in by the template.</remark>
|
|
</annotation>
|
|
</legalnotice>
|
|
<abstract>
|
|
<para>
|
|
This document provides an overview of the OpenStack API extension
|
|
mechanism.
|
|
</para>
|
|
</abstract>
|
|
</info>
|
|
<chapter version="5.0" xml:base="chapters/overview.xml">
|
|
<title>Overview</title>
|
|
<para>
|
|
The OpenStack extension mechanism makes it possible to add
|
|
functionality to OpenStack APIs in a manner that ensures
|
|
compatibility with existing clients. This capability
|
|
allows OpenStack operators and vendors to provide
|
|
innovative functionality to their clients and provides a
|
|
means by which new features may be considered in upcoming
|
|
versions of OpenStack APIs.
|
|
</para>
|
|
<para>
|
|
This document describes the extension mechanism in detail.
|
|
It provides guidance to API implementors and clients on
|
|
developing and consuming API extensions, it describes the
|
|
rules by which extensions are governed, and it describes
|
|
the process used to promote API extensions to new features.
|
|
</para>
|
|
<warning security="draft">
|
|
<para>Please note that this document is a <emphasis role="strong">draft</emphasis>. It
|
|
is intended to give developers an opportunity to provide feedback. If you begin
|
|
implementing against this early access specification, please recognize that it is
|
|
still subject to change. Comments, feedback, and bug reports are always welcomed;
|
|
please submit these in the webhelp discussion forum at: <link xlink:href="http://docs.openstack.org/">http://docs.openstack.org/</link>.</para>
|
|
</warning>
|
|
<section>
|
|
<title>Intended Audience</title>
|
|
<para>This document is intended for software developers who wish either to implement or
|
|
to consume an extendable OpenStack API. It assumes that the reader has a general
|
|
understanding of:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>ReSTful web services</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>HTTP/1.1</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>JSON and/or XML data serialization formats</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>At least one OpenStack API: Compute,
|
|
Object Storage, etc.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Organization of this Document</title>
|
|
<variablelist spacing="normal">
|
|
<?dbfo list-presentation="blocks"?>
|
|
<varlistentry>
|
|
<term><xref linkend="Background"/></term>
|
|
<listitem>
|
|
<para>
|
|
Provides background information on
|
|
OpenStack extensions and the OpenStack
|
|
extension mechanism.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><phrase security="draft">Chapter 3, <firstterm>Extensions and ReST</firstterm></phrase></term>
|
|
<listitem>
|
|
<para>
|
|
Describes the specifics of implementing
|
|
and consuming extensions in ReST APIs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><phrase security="draft">Chapter 4, <firstterm>Extension Governance and Promotion</firstterm></phrase></term>
|
|
<listitem>
|
|
<para>
|
|
Describes API governance and the process
|
|
by which extensions can be promoted to new
|
|
features in future revisions of an API.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><phrase security="draft">Chapter 5, <firstterm>Summary</firstterm></phrase></term>
|
|
<listitem>
|
|
<para>Briefly summarizes the benefits of the extension mechanism and
|
|
provides a brief overview of how extensions are used.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section>
|
|
<title>Document Change History</title>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<td align="center" colspan="1">Revision Date</td>
|
|
<td align="center" colspan="4">Summary of Changes</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1" align="center">June 10, 2011</td>
|
|
<td colspan="4">
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Initial draft.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Background" version="5.0" xml:base="chapters/background.xml">
|
|
<title>Background</title>
|
|
<para>
|
|
This chapter provides background information on OpenStack
|
|
extensions and the OpenStack extension mechanism. It
|
|
describes what extensions are, how the extension mechanism
|
|
in OpenStack is related to the OpenGL extension mechanism,
|
|
the differences between extensions and versions, the
|
|
concept of versioning extensions, and why extensions are
|
|
vital when defining a pluggable architecture.
|
|
</para>
|
|
<section>
|
|
<title>What are Extensions?</title>
|
|
<para>
|
|
OpenStack APIs are defined strictly in two forms: a
|
|
human-readable specification (usually in the form of a
|
|
developer's guide) and a machine-processable
|
|
WADL. These specifications define the core actions,
|
|
capabilities, and media-types of the API. A client can
|
|
always depend on the availability of this
|
|
<firstterm>core API</firstterm> and implementers are
|
|
always required to support it in its entirety. Requiring strict adherence to the
|
|
core API allows clients to rely upon a minimal level
|
|
of functionality when interacting with multiple
|
|
implementations of the same API.
|
|
</para>
|
|
<para>
|
|
Note that it is quite possible that distinct
|
|
implementations of an OpenStack API exist. First
|
|
because API specifications are released under a free
|
|
license, so anyone may use them to implement a core
|
|
API. Furthermore, the OpenStack implementations
|
|
themselves are released under a free license, making
|
|
it possible to alter the code to create a specialized
|
|
version. Such a specialized implementation could
|
|
remain OpenStack-compatible even if it were to
|
|
implement new features or add new capabilities, but
|
|
only if it made the changes in a manner that ensures
|
|
that a client expecting a core API would continue to
|
|
function normally — this is where extensions
|
|
come in.
|
|
</para>
|
|
<para>An <firstterm>extension</firstterm> adds capabilities to an API beyond those
|
|
defined in the core. The introduction of new features, MIME types, actions, states,
|
|
headers, parameters, and resources can all be accomplished by means of extensions to
|
|
the core API. In order for extensions to work, the core API must be written in such
|
|
a manner that it allows for extensibility. Additionally, care should be taken to
|
|
ensure that extensions defined by different implementers don't clash with one
|
|
another, that clients can detect the presence of extensions via a standard method,
|
|
and that there is a clear promotion path at the end of which an extension may become
|
|
part of a future version of the core API. These actions, rules, and processes
|
|
together form the <firstterm>extension mechanism</firstterm>. It is important that
|
|
core APIs adhere to this mechanism in order to ensure compatibility as new
|
|
extensions are defined. Note also that while a core API may be written to allow for
|
|
extensibility, the extensions themselves are never part of the core.</para>
|
|
</section>
|
|
<section>
|
|
<title>Relationship to OpenGL</title>
|
|
<para>
|
|
In the 1990s, OpenGL was developed as a portable open
|
|
graphics library standard. The goal was to provide a
|
|
cross-platform library that could enable developers to
|
|
produce 3D graphics at real time speeds (30-120 frames
|
|
per second). There were several major challenges to
|
|
meeting this goal. In order to be considered an open
|
|
standard, control needed to shift from Silicon
|
|
Graphics (SGI), who originally developed OpenGL, to an
|
|
independent Architecture Review Board (ARB) who would
|
|
be responsible for approving specification changes,
|
|
marking new releases, and ensuring conformance
|
|
testing. Additionally, the graphics library itself
|
|
would need to be designed in a manner that would allow
|
|
the establishment of a stable and portable platform
|
|
for developers. Finally, the library would need to
|
|
garner the support of graphics hardware vendors as
|
|
they would be providing the hardware acceleration
|
|
needed to meet the goal of performing at real-time
|
|
speeds.
|
|
</para>
|
|
<para>Gaining vendor support is challenging because vendors are often in direct
|
|
competition with one another. They differentiate themselves by creating innovative
|
|
new features and by providing niche functionality to their users. Thus, OpenGL was
|
|
faced with two competing requirements. On the one hand, it needed to abstract away
|
|
vendor differences in order to provide a stable cross-platform environment to
|
|
developers. On the other hand, in order to garner vendor support, it needed a method
|
|
by which vendors could differentiate themselves and provide innovative new features
|
|
and niche functionality to their users.</para>
|
|
<para>The OpenGL extension mechanism was developed to solve these problems. The
|
|
extension mechanism achieved balance between the two requirements by maintaining the
|
|
core specification under the direction of the Architecture Review Board while
|
|
allowing vendors to define extensions to the core OpenGL specification. The core
|
|
specification remained uncluttered and presented a unified view of common
|
|
functionality. Because extensions were detectable at run time, developers could
|
|
write portable applications that could adapt to the hardware on which they were
|
|
running. This method of allowing for an extensible API has proven to be a very
|
|
successful strategy. More than 500 extensions have been defined in OpenGL's lifetime
|
|
and many vendors, including NVidia, ATI, Apple, IBM, and Intel, have participated in
|
|
the process by developing their own custom extensions. Additionally, many key
|
|
innovations (such as vertex and fragment shaders) have been developed via the
|
|
extension process and are now part of the core OpenGL API.</para>
|
|
<para>OpenStack, while very different from OpenGL, shares many similar goals and faces
|
|
many of the same challenges. OpenStack APIs are designed to be open API standards.
|
|
An important goal is to provide developers with a ubiquitous, stable, any-scale
|
|
cloud development platform that abstracts away many of the differences between
|
|
hosting providers and their underlying infrastructure (hypervisors, load balancers,
|
|
etc.). A Policy Review Board, similar to OpenGL's Architecture Review Board, is
|
|
responsible for directing development of these APIs in a manner that ensures these
|
|
goals are met. As with OpenGL, OpenStack requires support from vendors (and cloud
|
|
providers) in order to be successful. As a result, OpenStack APIs also aim to
|
|
provide vendors with a platform which allows them to differentiate themselves by
|
|
providing innovative new features and niche functionality to their users. Because of
|
|
these similarities, the OpenStack extension mechanism described in this document is
|
|
modeled after the OpenGL extension mechanism. The methods by which extensions are
|
|
defined vary drastically, of course, since the nature of the APIs is very different
|
|
(C versus ReST); however, the manner in which extensions are documented, the way in
|
|
which vendors are attributed, and the promotion path that an extension follows, all
|
|
borrow heavily from OpenGL.</para>
|
|
</section>
|
|
<section>
|
|
<title>Extensions and Versions</title>
|
|
<para>Extensions are always interpreted in relation to a version of the core API. In
|
|
other words, from a client's perspective, an extension modifies <emphasis>a
|
|
particular version</emphasis> of the core API in some way. In reality, an
|
|
extension may be applicable to several versions of an API at once. For example, a
|
|
particular extension may continue to be available as a core API moves from one
|
|
version to another. In fact, different implementations may decide to include support
|
|
for an extension at different versions. As explained in
|
|
<phrase security="draft">the chapter on "Extension Governance and Promotion"</phrase>,
|
|
when an extension is defined, the minimal version of the core API that is required
|
|
to run the extension is specified; implementers are free to support the extension in
|
|
that version or in a later version of the core. Note, however, that because the
|
|
extension mechanism allows for promotion, an extension in one version of a core API
|
|
may become a standard feature in a later version.</para>
|
|
<note>
|
|
<para>
|
|
As always, implementers are not required to
|
|
support an extension unless it is promoted to the
|
|
core.
|
|
</para>
|
|
</note>
|
|
<para>Because several versions of the core API may be supported simultaneously, and
|
|
because each version may offer support for a different set of extensions, clients
|
|
must be able to detect what versions and extensions are available in a particular
|
|
deployment. Thus, both extensions and versions are queryable. Issuing a <command>GET</command> on the
|
|
base URL (<code>/</code>) of the API endpoint returns information about what
|
|
versions are available. Similarly, issuing a <command>GET</command> on the API's extensions resource
|
|
(<code>/v1.1/extensions</code>) returns information about what extensions are
|
|
available. (See
|
|
<phrase security="draft">the chapter on "Extensions and ReST"</phrase>
|
|
for details of such requests.) Note that,
|
|
since extensions modify a particular version of the API, the <code>extensions</code>
|
|
resource itself is always accessed at a particular version.</para>
|
|
<para>Backward-compatible changes in an API usually require a minor version bump. In an
|
|
extensible API, however, these changes can be brought in as extensions. The net
|
|
effect is that versions change infrequently and thus provide a stable platform on
|
|
which to develop. The Policy Review Board (PRB), with the help of project team
|
|
leaders, is responsible for ensuring that this stability is maintained by closely
|
|
guarding core API versions. Extensions, however, can be developed without the
|
|
consent or approval of the PRB. They can be developed in a completely decentralized
|
|
manner both by individual OpenStack developers and by commercial vendors. Because
|
|
extensions can be promoted to standard features, the development of new versions can
|
|
be influenced significantly by individual developers and the OpenStack client
|
|
community and is therefore not strictly defined by the PRB. In other words, new
|
|
features of a core API may be developed in a bottom-up fashion.</para>
|
|
<para>
|
|
That said, not all extensions are destined to be
|
|
promoted to the next API version. Core APIs always
|
|
deals with core functionality — functionality
|
|
that is supported by all implementations and is
|
|
applicable in common cases. Extensions that deal with
|
|
niche functionality should always remain extensions.
|
|
</para>
|
|
<para>
|
|
The table below summarizes the differences between
|
|
versions and extensions.
|
|
</para>
|
|
<table frame="all">
|
|
<title>Versions versus Extensions</title>
|
|
<tgroup cols="2">
|
|
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
|
|
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Versions</entry>
|
|
<entry>Extensions</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Rare</title>
|
|
<para>
|
|
Versions provide a stable
|
|
platform on which to develop.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Frequent</title>
|
|
<para>
|
|
Extensions bring new features
|
|
to the market quickly and in a
|
|
compatible manner.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Centralized</title>
|
|
<para>
|
|
Versions are maintained by the
|
|
entity that controls the API
|
|
Spec: the OpenStack Policy
|
|
Review Board. Only the PRB can
|
|
create a new version; only the
|
|
PRB defines what "OpenStack
|
|
Compute 1.1" means.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Decentralized</title>
|
|
<para>
|
|
Extensions are maintained by
|
|
third parties, including
|
|
individual OpenStack
|
|
developers and software
|
|
vendors. Anyone can create an
|
|
extension.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Core</title>
|
|
<para>
|
|
Versions support core
|
|
functionality.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Niche</title>
|
|
<para>
|
|
Extensions provide specialized
|
|
functionality.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Queryable</title>
|
|
<para>
|
|
Issuing a <command>GET</command> on the base
|
|
URL (<code>/</code>) of the
|
|
API endpoint returns
|
|
information about what
|
|
versions are available.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
<entry>
|
|
<formalpara>
|
|
<title>Queryable</title>
|
|
<para>
|
|
Issuing a <command>GET</command> on the API's
|
|
extensions resource
|
|
(<code>/v1.1/extensions</code>)
|
|
returns information about what
|
|
extensions are available.
|
|
</para>
|
|
</formalpara>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</section>
|
|
<section>
|
|
<title>Versioning Extensions</title>
|
|
<para>There is no explicit versioning mechanism for extensions. Nonetheless, there may
|
|
be cases in which a developer decides to update an extension after the extension has
|
|
been released and client support for the extension has been established. In these
|
|
cases, it is recommended that a new extension be created. The extension may have a
|
|
name that signifies its relationship to the previous version. For example, a
|
|
developer may append an integer to the extension name to signify that one extension
|
|
updates another: <code>RAX-PIE2</code> updates <code>RAX-PIE</code>.</para>
|
|
<para>Extensions may have dependencies on other extensions. For example,
|
|
<code>RAX-PIE2</code> may depend on <code>RAX-PIE</code> and may simply add
|
|
additional capabilities to it. In general, dependencies of this kind are discouraged
|
|
and implementers should strive to keep extensions independent. That said, extension
|
|
dependencies allow for the possibility of providing updates to existing extensions
|
|
even if the original extension is under the control of a different vendor. This is
|
|
particularly useful in cases where an existing extension has good client support.</para>
|
|
</section>
|
|
<section>
|
|
<title>Extensions and Pluggability</title>
|
|
<para>Core APIs abstract away vendor differences in order to provide a cross-platform
|
|
environment to their clients. For example, a client should be able to interact with
|
|
an OpenStack load balancing service without worrying about whether the deployment
|
|
utilizes Zeus, Pound, or HAProxy on the backend. OpenStack implementations strive to
|
|
support multiple backends out of the box. They do so by employing software drivers.
|
|
Each driver is responsible for communicating to a specific backend and is in charge
|
|
of translating core API requests to it.</para>
|
|
<para>The core API contains only those capabilities which are applicable to all
|
|
backends; however, not all backends are created equal, with each backend offering a
|
|
distinct set of capabilities. Extensions play a critical role in exposing these
|
|
capabilities to clients. This is illustrated below. Here, extensions fill in the gap
|
|
between the common capabilities that the core API provides and the unique
|
|
capabilities of the Zeus load balancer. In a sense, one can think of extensions as
|
|
providing frontends to OpenStack plug-ins.</para>
|
|
<figure xml:id="core-extensions">
|
|
<title>Extensions and Pluggability</title>
|
|
<mediaobject>
|
|
<imageobject role="fo">
|
|
<imagedata scale="100" fileref="../figures/apix-1service-core-extensions-manybackends.svg" format="SVG" align="center"/>
|
|
</imageobject>
|
|
<imageobject role="html">
|
|
<imagedata fileref="../figures/apix-1service-core-extensions-manybackends.png" format="PNG" align="center"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</section>
|
|
</chapter>
|
|
</book>
|