Rebuild 1.0 so that JSON fixes are picked up
- I believe there could still be clouds running that API Change-Id: If08c12b65fe02d6f4973b492a6caef472bf64d89 Partial-Bug: 1283715
This commit is contained in:
annegentle
Andreas Jaeger
parent
da301b16ce
commit
88e5f87f97
@ -6,7 +6,6 @@ api_site = True
|
||||
# These three options need to come together
|
||||
book = v1.0
|
||||
target_dir = target/docbkx/webhelp/openstack-network
|
||||
# Not published but needs to be configured
|
||||
publish_dir = api/openstack-network/1.0
|
||||
|
||||
book = v2.0
|
||||
|
||||
6
tox.ini
6
tox.ini
@ -21,10 +21,10 @@ commands = openstack-doc-test --check-syntax {posargs}
|
||||
commands = openstack-doc-test --check-deletions {posargs}
|
||||
|
||||
[testenv:checkbuild]
|
||||
# Ignore directory v1.0, it is not published
|
||||
commands = openstack-doc-test --check-build --only-book v2.0 {posargs}
|
||||
# Build both 1.0 and 2.0
|
||||
commands = openstack-doc-test --check-build {posargs}
|
||||
|
||||
[testenv:publishdocs]
|
||||
# Prepare all documents so that they can get published on
|
||||
# docs.openstack.org with just copying publish-docs/* over.
|
||||
commands = openstack-doc-test --check-build --publish --only-book v2.0
|
||||
commands = openstack-doc-test --check-build --publish --force
|
||||
|
||||
@ -33,10 +33,10 @@
|
||||
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="final" xml:id="Quantum-api-spec">
|
||||
<title>Quantum API Guide (1.0)</title>
|
||||
<?rax pdf.url="../quantum-api-guide-1.0.pdf"?>
|
||||
<titleabbrev>Quantum API 1.0</titleabbrev>
|
||||
status="final" xml:id="openstack-networking-v1.0-api-spec">
|
||||
<title>OpenStack Networking API Guide (1.0)</title>
|
||||
<?rax pdf.url="../netconn-api-guide-1.0.pdf"?>
|
||||
<titleabbrev>OpenStack Networking API 1.0</titleabbrev>
|
||||
<info>
|
||||
<author>
|
||||
<personname>
|
||||
@ -51,8 +51,8 @@
|
||||
<year>2014</year>
|
||||
<holder>OpenStack</holder>
|
||||
</copyright>
|
||||
<releaseinfo>Quantum API v1.0</releaseinfo>
|
||||
<productname>OpenStack Quantum (virtual network
|
||||
<releaseinfo>Networking API v1.0</releaseinfo>
|
||||
<productname>OpenStack Networking (virtual network
|
||||
service)</productname>
|
||||
<pubdate/>
|
||||
<legalnotice role="apache2">
|
||||
@ -62,10 +62,9 @@
|
||||
</annotation>
|
||||
</legalnotice>
|
||||
<abstract>
|
||||
<para>This document is intended for software developers
|
||||
interested in developing applications using the
|
||||
OpenStack Quantum Layer-2 Networking Service
|
||||
(<abbrev>API</abbrev>).</para>
|
||||
<para>This document is intended for software developers interested
|
||||
in developing applications using the OpenStack Networking
|
||||
Layer-2 Networking Service (<abbrev>API</abbrev>).</para>
|
||||
</abstract>
|
||||
<revhistory>
|
||||
<revision>
|
||||
@ -84,8 +83,7 @@
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Corrected the titles of some
|
||||
examples.</para>
|
||||
<para>Corrected the titles of some examples.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
@ -95,13 +93,13 @@
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Fixed incorrect mention of &PUT;
|
||||
verb in <xref linkend="Delete_Network"
|
||||
/>. Verb changed to &DELETE;.</para>
|
||||
<para>Fixed incorrect mention of &PUT; verb in <xref
|
||||
linkend="Delete_Network"/>. Verb changed to
|
||||
&DELETE;.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Fixed formatting issues in request
|
||||
and response examples.</para>
|
||||
<para>Fixed formatting issues in request and
|
||||
response examples.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
@ -114,8 +112,7 @@
|
||||
<para>Initial release.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>First edition of this
|
||||
document.</para>
|
||||
<para>First edition of this document.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
@ -124,38 +121,35 @@
|
||||
</info>
|
||||
<chapter xml:id="Overview-d1e71">
|
||||
<title>Overview</title>
|
||||
<para>Quantum is a project to provide "network connectivity as
|
||||
a service" between devices managed by the OpenStack
|
||||
compute service. For more information on Quantum and the
|
||||
other network-related projects please check the Quantum
|
||||
home page (<link
|
||||
xlink:href="http://wiki.openstack.org/Quantum"/>) and
|
||||
<para>OpenStack Networking is a project to provide "network connectivity
|
||||
as a service" between devices managed by the OpenStack compute
|
||||
service. For more information on OpenStack Networking and the other
|
||||
network-related projects please check the OpenStack Networking home
|
||||
page (<link xlink:href="http://wiki.openstack.org/Neutron"/>) and
|
||||
the NetStack home page (<link
|
||||
xlink:href="http://wiki.openstack.org/Network"
|
||||
/>).</para>
|
||||
xlink:href="http://wiki.openstack.org/Network"/>).</para>
|
||||
<para>We welcome feedback, comments, and bug reports at <link
|
||||
xlink:href="http://bugs.launchpad.net/Quantum"
|
||||
>bugs.launchpad.net/Quantum</link>.</para>
|
||||
xlink:href="http://bugs.launchpad.net/neutron"
|
||||
>bugs.launchpad.net/neutron</link>.</para>
|
||||
<section xml:id="Intended_Audience-d1e85">
|
||||
<title>Intended Audience</title>
|
||||
<para>This guide is intended to assist software developers
|
||||
who want to develop applications using the Quantum
|
||||
API. To use the information provided here, you should
|
||||
first have a general understanding of the OpenStack
|
||||
Quantum network service, the OpenStack compute service
|
||||
(Nova), and the integration between the two. The user
|
||||
should also have access to a plugin providing the
|
||||
implementation for the API described in this document.
|
||||
Two plugins are included in the Quantum
|
||||
<para>This guide is intended to assist software developers who want
|
||||
to develop applications using the OpenStack Networking API. To
|
||||
use the information provided here, you should first have a
|
||||
general understanding of the OpenStack network service, the
|
||||
OpenStack compute service (Nova), and the integration between
|
||||
the two. The user should also have access to a plugin providing
|
||||
the implementation for the API described in this document. Two
|
||||
plugins are included in the OpenStack Networking
|
||||
distribution:</para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Openvswitch - Implementing Quantum API with
|
||||
Open vSwitch</para>
|
||||
<para>Openvswitch - Implementing OpenStack Networking API
|
||||
with Open vSwitch</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Cisco - Implementing Quantum API for Cisco
|
||||
UCS blades and Nexus switches</para>
|
||||
<para>Cisco - Implementing OpenStack Networking API for
|
||||
Cisco UCS blades and Nexus switches</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>You should also be familiar with:</para>
|
||||
@ -194,53 +188,51 @@
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="1" align="center">Entity</td>
|
||||
<td colspan="4">Any piece of hardware or
|
||||
software that wants to connect to the
|
||||
network services provided by Quantum. An
|
||||
entity can use Quantum network services by
|
||||
implementing a VIF.</td>
|
||||
<td colspan="4">Any piece of hardware or software that
|
||||
wants to connect to the network services provided by
|
||||
OpenStack Networking. An entity can use OpenStack
|
||||
Networking network services by implementing a
|
||||
VIF.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<!-- <td colspan="1" align="center" bgcolor="#4F91BD"> -->
|
||||
<td colspan="1" align="center">Layer-2
|
||||
network</td>
|
||||
<!-- <td colspan="4" bgcolor="#4F91BD"> -->
|
||||
<td colspan="4">A virtual Ethernet network
|
||||
managed by the Quantum service. For the
|
||||
time being, Quantum will manage only
|
||||
<td colspan="4">A virtual Ethernet network managed by
|
||||
the OpenStack Networking service. For the time
|
||||
being, OpenStack Networking will manage only
|
||||
Ethernet networks.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">Network</td>
|
||||
<td colspan="4">A virtual network providing
|
||||
connectivity between entities such as, a
|
||||
collection of virtual ports sharing
|
||||
network connectivity. In the Quantum
|
||||
terminology, a network is always a Layer-2
|
||||
network.</td>
|
||||
<td colspan="4">A virtual network providing connectivity
|
||||
between entities such as, a collection of virtual
|
||||
ports sharing network connectivity. In the OpenStack
|
||||
Networking terminology, a network is always a
|
||||
Layer-2 network.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<!-- <td align="center" bgcolor="#4F91BD"> -->
|
||||
<td align="center">Plug-in</td>
|
||||
<!-- <td colspan="4" bgcolor="#4F91BD"> -->
|
||||
<td colspan="4">Software component that
|
||||
provides the actual implementation for
|
||||
Quantum APIs.</td>
|
||||
<td colspan="4">Software component that provides the
|
||||
actual implementation for OpenStack Networking
|
||||
APIs.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">Port</td>
|
||||
<td colspan="4">A port on the virtual network
|
||||
switch represented by a Quantum virtual
|
||||
<td colspan="4">A port on the virtual network switch
|
||||
represented by a OpenStack Networking virtual
|
||||
Layer-2 network.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<!-- <td align="center" bgcolor="#4F91BD"> -->
|
||||
<td align="center">VIF</td>
|
||||
<!-- <td colspan="4" bgcolor="#4F91BD"> -->
|
||||
<td colspan="4">A Virtual network InterFace
|
||||
plugged into a port of a Quantum network.
|
||||
Typically a virtual network interface
|
||||
belonging to a VM.</td>
|
||||
<td colspan="4">A Virtual network InterFace plugged into
|
||||
a port of a OpenStack Networking network. Typically
|
||||
a virtual network interface belonging to a VM.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">Attachment</td>
|
||||
@ -255,38 +247,36 @@
|
||||
<?hard-pagebreak?>
|
||||
<section xml:id="Theory">
|
||||
<title>Theory of Operation</title>
|
||||
<para>This section presents the objects and semantics of
|
||||
Quantum’s logical model.</para>
|
||||
<para>Quantum abstracts the physical implementation of the
|
||||
network, allowing plugins to configure and manage
|
||||
physical resources. Quantum is a standalone service,
|
||||
in that it requires no other project within OpenStack
|
||||
to function correctly.</para>
|
||||
<para>Further Quantum is agnostic to the entities it
|
||||
allows to connect. While we anticipate Nova instances
|
||||
will be a heavy user of Quantum, any entity can make
|
||||
use of any Quantum created network so long as it
|
||||
provides an appropriate interfaces for exposing VIFs
|
||||
to Quantum itself.</para>
|
||||
<para>Virtual Interfaces (VIF) in the logical model are
|
||||
analogous to physical network interface cards (NICs).
|
||||
VIFs are typically owned a managed by an external
|
||||
service; for instance when Quantum is used for
|
||||
building OpenStack networks, VIFs would be created,
|
||||
owned, and managed in Nova. VIFs are connected to
|
||||
Quantum networks via ports. A port is analogous to a
|
||||
port on a network switch, and it has an administrative
|
||||
state. Quantum API allows for controlling the
|
||||
administrative state of the port, which can be either
|
||||
'DOWN' or 'ACTIVE'.</para>
|
||||
<para>When a VIF is attached to a port the Quantum API
|
||||
creates an attachment object, which specifies the fact
|
||||
that a VIF with a given identifier is plugged into the
|
||||
port.</para>
|
||||
<para>The Quantum plugin is responsible for managing
|
||||
virtual and/or physical network switches to implement
|
||||
the network forwarding connectivity described by the
|
||||
Quantum networks, ports, and attachments.</para>
|
||||
<para>This section presents the objects and semantics of OpenStack
|
||||
Networking’s logical model.</para>
|
||||
<para>OpenStack Networking abstracts the physical implementation of
|
||||
the network, allowing plugins to configure and manage physical
|
||||
resources. OpenStack Networking is a standalone service, in that
|
||||
it requires no other project within OpenStack to function
|
||||
correctly.</para>
|
||||
<para>Further OpenStack Networking is agnostic to the entities it
|
||||
allows to connect. While we anticipate Nova instances will be a
|
||||
heavy user of OpenStack Networking, any entity can make use of
|
||||
any OpenStack Networking created network so long as it provides
|
||||
an appropriate interfaces for exposing VIFs to OpenStack
|
||||
Networking itself.</para>
|
||||
<para>Virtual Interfaces (VIF) in the logical model are analogous to
|
||||
physical network interface cards (NICs). VIFs are typically
|
||||
owned a managed by an external service; for instance when
|
||||
OpenStack Networking is used for building OpenStack networks,
|
||||
VIFs would be created, owned, and managed in Nova. VIFs are
|
||||
connected to OpenStack Networking networks via ports. A port is
|
||||
analogous to a port on a network switch, and it has an
|
||||
administrative state. OpenStack Networking API allows for
|
||||
controlling the administrative state of the port, which can be
|
||||
either 'DOWN' or 'ACTIVE'.</para>
|
||||
<para>When a VIF is attached to a port the OpenStack Networking API
|
||||
creates an attachment object, which specifies the fact that a
|
||||
VIF with a given identifier is plugged into the port.</para>
|
||||
<para>The OpenStack Networking plugin is responsible for managing
|
||||
virtual and/or physical network switches to implement the
|
||||
network forwarding connectivity described by the OpenStack
|
||||
Networking networks, ports, and attachments.</para>
|
||||
<para>VIFs attached to ACTIVE ports are required to have
|
||||
access to the L2 broadcast domain defined by the
|
||||
network where they are attached. Each VIF shall be
|
||||
@ -298,7 +288,7 @@
|
||||
<chapter xml:id="Concepts-d1e369">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>Concepts</title>
|
||||
<para>To use the Quantum API effectively, developers should
|
||||
<para>To use the OpenStack Networking API effectively, developers should
|
||||
understand the concepts introduced in this chapter.</para>
|
||||
<section xml:id="Network">
|
||||
<title>Network</title>
|
||||
@ -323,40 +313,38 @@
|
||||
logical port. At any time at most one attachment can
|
||||
be plugged into a given port.</para>
|
||||
<para>An attachment typically identified a virtual network
|
||||
interface. Network interfaces are typically defined in
|
||||
an external services which uses Quantum, for instance
|
||||
interface. Network interfaces are typically defined in an
|
||||
external services which uses OpenStack Networking, for instance
|
||||
the OpenStack Compute service, Nova.</para>
|
||||
</section>
|
||||
</chapter>
|
||||
<chapter xml:id="General_API_Information-d1e436">
|
||||
<title>General API Information</title>
|
||||
<para>The OpenStack Quantum API is defined as a ReSTful HTTP
|
||||
service. The API takes advantage of all aspects of the
|
||||
HTTP protocol (methods, URIs, media types, response codes,
|
||||
etc.) and providers are free to use existing features of
|
||||
the protocol such as caching, persistent connections, and
|
||||
content compression among others. For example, providers
|
||||
who employ a caching layer may respond with a 203 when a
|
||||
request is served from the cache instead of a 200.
|
||||
Additionally, providers may offer support for conditional
|
||||
&GET; requests using ETags, or they may send a redirect in
|
||||
response to a &GET; request. Clients should be written to
|
||||
account for these differences.</para>
|
||||
<para>The OpenStack Networking API is defined as a ReSTful HTTP service.
|
||||
The API takes advantage of all aspects of the HTTP protocol
|
||||
(methods, URIs, media types, response codes, etc.) and providers are
|
||||
free to use existing features of the protocol such as caching,
|
||||
persistent connections, and content compression among others. For
|
||||
example, providers who employ a caching layer may respond with a 203
|
||||
when a request is served from the cache instead of a 200.
|
||||
Additionally, providers may offer support for conditional &GET;
|
||||
requests using ETags, or they may send a redirect in response to a
|
||||
&GET; request. Clients should be written to account for these
|
||||
differences.</para>
|
||||
<section xml:id="Authentication-d1e444">
|
||||
<title>Authentication</title>
|
||||
<para>The current version of the OpenStack Quantum service
|
||||
does not require that each request will include the
|
||||
credentials of the user submitting the request.</para>
|
||||
<para>However, Quantum deployments can support several
|
||||
<para>The current version of the OpenStack Networking service does
|
||||
not require that each request will include the credentials of
|
||||
the user submitting the request.</para>
|
||||
<para>However, OpenStack Networking deployments can support several
|
||||
authentication schemes (OAuth, Basic Auth, Token). The
|
||||
authentication scheme used is determined by the
|
||||
provider of the Quantum service. Please contact your
|
||||
provider to determine the best way to authenticate
|
||||
against this API.</para>
|
||||
<para>Ideally, middleware modules for Authentication
|
||||
and/or Authorization should be inserted in the first
|
||||
stages of the Quantum pipeline (available in
|
||||
<code>etc/quantum.conf</code>).</para>
|
||||
authentication scheme used is determined by the provider of the
|
||||
OpenStack Networking service. Please contact your provider to
|
||||
determine the best way to authenticate against this API.</para>
|
||||
<para>Ideally, middleware modules for Authentication and/or
|
||||
Authorization should be inserted in the first stages of the
|
||||
OpenStack Networking pipeline (available in <code>etc/OpenStack
|
||||
Networking.conf</code>).</para>
|
||||
<note>
|
||||
<para>Some authentication schemes may require that the
|
||||
API operate using SSL over HTTP (HTTPS).</para>
|
||||
@ -365,16 +353,17 @@
|
||||
<?hard-pagebreak?>
|
||||
<section xml:id="URI_structure">
|
||||
<title>URI structure</title>
|
||||
<para>Each request to the OpenStack Quantum API must refer
|
||||
to a specific version of the API itself, and it must
|
||||
also identify the tenant for which the request is
|
||||
being sent.</para>
|
||||
<para>This information is specified in the URI. The URI
|
||||
for each request to the OpenStack Quantum API should
|
||||
be prefixed with the API version identifier and the
|
||||
tenant identifier, as follows:</para>
|
||||
<para>Each request to the OpenStack Networking API must refer to a
|
||||
specific version of the API itself, and it must also identify
|
||||
the tenant for which the request is being sent.</para>
|
||||
<para>This information is specified in the URI. The URI for each
|
||||
request to the OpenStack Networking API should be prefixed with
|
||||
the API version identifier and the tenant identifier, as
|
||||
follows:</para>
|
||||
<para>
|
||||
<code>/{Quantum-version}/tenants/{tenant-id}/{Quantum-API-entity}</code>
|
||||
<code>/{OpenStack
|
||||
Networking-version}/tenants/{tenant-id}/{OpenStack
|
||||
Networking-API-entity}</code>
|
||||
</para>
|
||||
<para>As an example, the following URI represents a
|
||||
request for retrieving all the networks configured for
|
||||
@ -385,13 +374,12 @@
|
||||
</section>
|
||||
<section xml:id="Request_Response_Types">
|
||||
<title>Request/Response Types</title>
|
||||
<para>The OpenStack Quantum API supports both the JSON and
|
||||
XML data serialization formats. The format for both
|
||||
the request and the response can be specified either
|
||||
using the <code>Content-Type</code> header, the
|
||||
<code>Accept</code> header or adding an
|
||||
<code>.xml</code> or <code>.json</code> extension
|
||||
to the request URI.</para>
|
||||
<para>The OpenStack Networking API supports both the JSON and XML
|
||||
data serialization formats. The format for both the request and
|
||||
the response can be specified either using the
|
||||
<code>Content-Type</code> header, the <code>Accept</code>
|
||||
header or adding an <code>.xml</code> or <code>.json</code>
|
||||
extension to the request URI.</para>
|
||||
<para>If conflicting formats are specified in headers
|
||||
and/or format extensions, the latter takes precedence.
|
||||
XML is currently the default format for both requests
|
||||
@ -488,14 +476,13 @@ Content-Length 59
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="Async_behaviour">
|
||||
<title>Asynchronous Behavior by Quantum Plugins</title>
|
||||
<para>The Quantum API presents a logical model of network
|
||||
connectivity consisting of networks, ports, and
|
||||
attachments. It is up to the Quantum plugin to
|
||||
communicate with all managed virtual and/or physical
|
||||
switches to ensure that these devices implement packet
|
||||
forwarding behavior consistent with the logical
|
||||
model.</para>
|
||||
<title>Asynchronous Behavior by OpenStack Networking Plugins</title>
|
||||
<para>The OpenStack Networking API presents a logical model of
|
||||
network connectivity consisting of networks, ports, and
|
||||
attachments. It is up to the OpenStack Networking plugin to
|
||||
communicate with all managed virtual and/or physical switches to
|
||||
ensure that these devices implement packet forwarding behavior
|
||||
consistent with the logical model.</para>
|
||||
<para>The plug-in task of mapping from the logical model
|
||||
to the physical world might happen asynchronously.
|
||||
This means that when an API client modifies the
|
||||
@ -517,11 +504,10 @@ Content-Length 59
|
||||
<para>Future versions of the API may expose a notion
|
||||
of an "operational status" on a logical entity
|
||||
like a network or port.</para>
|
||||
<para>This would indicate whether the Quantum plugin
|
||||
had successfully configured virtual and/or
|
||||
physical switches in order to implement the
|
||||
network connectivity described by that element of
|
||||
the logical model.</para>
|
||||
<para>This would indicate whether the OpenStack Networking
|
||||
plugin had successfully configured virtual and/or physical
|
||||
switches in order to implement the network connectivity
|
||||
described by that element of the logical model.</para>
|
||||
<para>For example, a port might have an operational
|
||||
status of <code>"DOWN"</code> because the VM
|
||||
interface specified as an attachment was not
|
||||
@ -530,8 +516,8 @@ Content-Length 59
|
||||
</section>
|
||||
<section xml:id="Versions">
|
||||
<title>Versions</title>
|
||||
<para>The Quantum API uses a URI based versioning scheme.
|
||||
The first element of the URI path contains the target
|
||||
<para>The OpenStack Networking API uses a URI based versioning
|
||||
scheme. The first element of the URI path contains the target
|
||||
version identifier. <example>
|
||||
<title>Request with URI versioning</title>
|
||||
<literallayout class="monospaced">
|
||||
@ -543,10 +529,10 @@ Content-Length 22
|
||||
</literallayout>
|
||||
</example>
|
||||
</para>
|
||||
<para>Available API versions can be retrieved by
|
||||
performing a &GET; on the root URL (i.e. with the
|
||||
version and everything to the right of it truncated)
|
||||
of the Quantum Service.</para>
|
||||
<para>Available API versions can be retrieved by performing a &GET;
|
||||
on the root URL (i.e. with the version and everything to the
|
||||
right of it truncated) of the OpenStack Networking
|
||||
Service.</para>
|
||||
<example>
|
||||
<title>Versions List Request/Response (XML)</title>
|
||||
<literallayout class="monospaced">
|
||||
@ -572,7 +558,7 @@ Content-Type application/json
|
||||
<?hard-pagebreak?>
|
||||
<section xml:id="Extensions">
|
||||
<title>Extensions</title>
|
||||
<para>The Quantum API is extensible. Extensions serve
|
||||
<para>The OpenStack Networking API is extensible. Extensions serve
|
||||
several purposes:</para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
@ -679,9 +665,9 @@ Content-Type application/json
|
||||
<!-- <td bgcolor="#4F91BD"> -->
|
||||
<td>400</td>
|
||||
<!-- <td bgcolor="#4F91BD" colspan="2"> -->
|
||||
<td colspan="2">Malformed request body. The
|
||||
Quantum service is unable to parse the
|
||||
contents of the request body.</td>
|
||||
<td colspan="2">Malformed request body. The OpenStack
|
||||
Networking service is unable to parse the contents
|
||||
of the request body.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Unauthorized</td>
|
||||
@ -707,8 +693,8 @@ Content-Type application/json
|
||||
<tr>
|
||||
<td>ItemNotFound</td>
|
||||
<td>404</td>
|
||||
<td colspan="2">The requested resource does
|
||||
not exist on the Quantum API server.</td>
|
||||
<td colspan="2">The requested resource does not exist on
|
||||
the OpenStack Networking API server.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<!-- <td bgcolor="#4F91BD"> -->
|
||||
@ -761,9 +747,9 @@ Content-Type application/json
|
||||
</tbody>
|
||||
</table>
|
||||
<note>
|
||||
<para>The error codes 401 and 403 will be returned
|
||||
only if some Authentication/Authorization system
|
||||
has been enabled in the Quantum pipeline</para>
|
||||
<para>The error codes 401 and 403 will be returned only if some
|
||||
Authentication/Authorization system has been enabled in the
|
||||
OpenStack Networking pipeline</para>
|
||||
</note>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -771,8 +757,8 @@ Content-Type application/json
|
||||
<title>API Operations</title>
|
||||
<section xml:id="Networks">
|
||||
<title>Networks</title>
|
||||
<para>This section describes the operations exposed by
|
||||
Quantum API for manipulating network resources.</para>
|
||||
<para>This section describes the operations exposed by OpenStack
|
||||
Networking API for manipulating network resources.</para>
|
||||
<section xml:id="List_Networks">
|
||||
<title>List Networks</title>
|
||||
<informaltable rules="all">
|
||||
@ -788,9 +774,9 @@ Content-Type application/json
|
||||
<td colspan="1">&GET;</td>
|
||||
<td colspan="2"
|
||||
>/tenants/<parameter>tenant-id</parameter>/networks</td>
|
||||
<td colspan="3">Lists summary of networks
|
||||
configured in Quantum for a given
|
||||
tenant, identified by
|
||||
<td colspan="3">Lists summary of networks configured
|
||||
in OpenStack Networking for a given tenant,
|
||||
identified by
|
||||
<parameter>tenant-id</parameter>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
@ -801,19 +787,17 @@ Content-Type application/json
|
||||
<simpara>Error Response Code(s): Unauthorized
|
||||
(<errorcode>401</errorcode>), Forbidden
|
||||
(<errorcode>403</errorcode>) </simpara>
|
||||
<para>This operation returns the list of all networks
|
||||
currently defined in Quantum for the tenant
|
||||
specified in the request URI. The list provides
|
||||
the unique identifier of each network configured
|
||||
for the tenant specified in the resource
|
||||
URI.</para>
|
||||
<para>This operation returns the list of all networks currently
|
||||
defined in OpenStack Networking for the tenant specified in
|
||||
the request URI. The list provides the unique identifier of
|
||||
each network configured for the tenant specified in the
|
||||
resource URI.</para>
|
||||
<note>
|
||||
<para>
|
||||
<property>TenantId</property> is a unique
|
||||
tenant identifier. The Quantum service does
|
||||
not directly manages tenants. Tenant
|
||||
management should be performed by the identity
|
||||
service</para>
|
||||
<property>TenantId</property> is a unique tenant
|
||||
identifier. The OpenStack Networking service does not
|
||||
directly manages tenants. Tenant management should be
|
||||
performed by the identity service</para>
|
||||
</note>
|
||||
<para>This operation does not require a request
|
||||
body.</para>
|
||||
@ -850,10 +834,9 @@ Content-Type application/json
|
||||
<td colspan="1">&GET;</td>
|
||||
<td colspan="2"
|
||||
>/tenants/<parameter>tenant-id</parameter>/networks/detail</td>
|
||||
<td colspan="3">Lists more detailed
|
||||
information about networks configured
|
||||
in Quantum for a given tenant,
|
||||
identified by
|
||||
<td colspan="3">Lists more detailed information
|
||||
about networks configured in OpenStack
|
||||
Networking for a given tenant, identified by
|
||||
<parameter>tenant-id</parameter>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
@ -864,9 +847,9 @@ Content-Type application/json
|
||||
<simpara> Error Response Code(s): Unauthorized
|
||||
(<errorcode>401</errorcode>), Forbidden
|
||||
(<errorcode>403</errorcode>) </simpara>
|
||||
<para>This operation returns the list of all networks
|
||||
currently defined in Quantum; for each network,
|
||||
its identifier and name are returned.</para>
|
||||
<para>This operation returns the list of all networks currently
|
||||
defined in OpenStack Networking; for each network, its
|
||||
identifier and name are returned.</para>
|
||||
<para>This operation does not require a request
|
||||
body.</para>
|
||||
<example>
|
||||
@ -918,9 +901,8 @@ Content-Type application/json
|
||||
(<errorcode>401</errorcode>), Forbidden
|
||||
(<errorcode>403</errorcode>), NetworkNotFound
|
||||
(<errorcode>420</errorcode>)</simpara>
|
||||
<para>This operation returns the identifier and the
|
||||
name for a specific network configured in
|
||||
Quantum.</para>
|
||||
<para>This operation returns the identifier and the name for a
|
||||
specific network configured in OpenStack Networking.</para>
|
||||
<para>This operation does not require a request
|
||||
body.</para>
|
||||
<example>
|
||||
@ -1028,27 +1010,25 @@ Content-Type application/json
|
||||
(<errorcode>400</errorcode>) Unauthorized
|
||||
(<errorcode>401</errorcode>), Forbidden
|
||||
(<errorcode>403</errorcode>)</simpara>
|
||||
<para>This operation creates a Layer-2 network in
|
||||
Quantum based on the information provided in the
|
||||
request body.</para>
|
||||
<para>Quantum validates the request, and dispatches it
|
||||
to the plugin, and then returns the unique
|
||||
identifier of the network to the caller. Although
|
||||
the network API entity can be immediately used for
|
||||
other operations, this does not guarantee that the
|
||||
network will be available when the API call
|
||||
returns, as this depends on the particular plugin
|
||||
<para>This operation creates a Layer-2 network in OpenStack
|
||||
Networking based on the information provided in the request
|
||||
body.</para>
|
||||
<para>OpenStack Networking validates the request, and dispatches
|
||||
it to the plugin, and then returns the unique identifier of
|
||||
the network to the caller. Although the network API entity
|
||||
can be immediately used for other operations, this does not
|
||||
guarantee that the network will be available when the API
|
||||
call returns, as this depends on the particular plugin
|
||||
implementation.</para>
|
||||
<para>If the validation phase fails, the network
|
||||
object is not created at all, and a 400 error is
|
||||
returned to the caller.</para>
|
||||
<note>
|
||||
<para>The Quantum API v1.0 does not provide an
|
||||
interface for checking the progress of
|
||||
asynchronous operations performed by
|
||||
plugins.</para>
|
||||
<para>This will be addressed in future releases of
|
||||
the Quantum API.</para>
|
||||
<para>The OpenStack Networking API v1.0 does not provide an
|
||||
interface for checking the progress of asynchronous
|
||||
operations performed by plugins.</para>
|
||||
<para>This will be addressed in future releases of the
|
||||
OpenStack Networking API.</para>
|
||||
</note>
|
||||
<para>The body for this request must contain a Network
|
||||
object specifying a symbolic name for the
|
||||
@ -1103,8 +1083,8 @@ Content-Type application/json
|
||||
(<errorcode>401</errorcode>), Forbidden
|
||||
(<errorcode>403</errorcode>) NetworkNotFound
|
||||
(<errorcode>420</errorcode>) </simpara>
|
||||
<para>This operation renames a Quantum network using
|
||||
the data provided in the request body.</para>
|
||||
<para>This operation renames a OpenStack Networking network
|
||||
using the data provided in the request body.</para>
|
||||
<para>The body for this request must contain a Network
|
||||
object specifying a symbolic name for the network.
|
||||
The network entity specified in the request body
|
||||
@ -1169,11 +1149,10 @@ Content-Type application/json
|
||||
attachments plugged in it. If all ports on the
|
||||
networks are unattached, they will be destroyed
|
||||
together with the network itself.</para>
|
||||
<para>As for the create operation there is no
|
||||
guarantee that the plugin will have completely
|
||||
removed the network when the call returns. Quantum
|
||||
forwards the request to the plugin, which will
|
||||
then destroy the network.</para>
|
||||
<para>As for the create operation there is no guarantee that the
|
||||
plugin will have completely removed the network when the
|
||||
call returns. OpenStack Networking forwards the request to
|
||||
the plugin, which will then destroy the network.</para>
|
||||
<note>
|
||||
<para>This operation cannot be undone.</para>
|
||||
</note>
|
||||
@ -1199,8 +1178,8 @@ Content-Type application/json
|
||||
</section>
|
||||
<section xml:id="Ports">
|
||||
<title>Ports</title>
|
||||
<para>This section describes the operations exposed by
|
||||
Quantum API for manipulating port resources.</para>
|
||||
<para>This section describes the operations exposed by OpenStack
|
||||
Networking API for manipulating port resources.</para>
|
||||
<section xml:id="List_Ports">
|
||||
<title>List Ports</title>
|
||||
<informaltable rules="all">
|
||||
@ -1217,9 +1196,9 @@ Content-Type application/json
|
||||
<td colspan="2"
|
||||
>/tenants/<parameter>tenant-id</parameter>/networks/
|
||||
<parameter>network-id/ports</parameter></td>
|
||||
<td colspan="3"> Lists all the ports
|
||||
currently defined for a Quantum
|
||||
network, identified by
|
||||
<td colspan="3"> Lists all the ports currently
|
||||
defined for a OpenStack Networking network,
|
||||
identified by
|
||||
<parameter>network-id</parameter></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
@ -1457,12 +1436,11 @@ Content-Type application/json
|
||||
(<errorcode>403</errorcode>), NetworkNotFound
|
||||
(<errorcode>420</errorcode>),
|
||||
RequestedStateInvalid (<errorcode>431</errorcode>) </simpara>
|
||||
<para>This operation creates a port on a Quantum
|
||||
network based on the information provided in the
|
||||
request body. Quantum validates the request, and
|
||||
dispatches the request to the plugin, which
|
||||
creates the port and attaches it to the
|
||||
appropriate network.</para>
|
||||
<para>This operation creates a port on a OpenStack Networking
|
||||
network based on the information provided in the request
|
||||
body. OpenStack Networking validates the request, and
|
||||
dispatches the request to the plugin, which creates the port
|
||||
and attaches it to the appropriate network.</para>
|
||||
<para>This operation could not be implemented for some
|
||||
plugins as the number of ports available might be
|
||||
fixed when the network is created.</para>
|
||||
@ -1541,11 +1519,11 @@ Content-Type application/json
|
||||
(<errorcode>420</errorcode>), PortNotFound
|
||||
(<errorcode>430</errorcode>),
|
||||
RequestedStateInvalid (<errorcode>431</errorcode>) </simpara>
|
||||
<para>This operation sets the administrative state for
|
||||
a port. Currently Quantum recognizes two port
|
||||
states: <code>DOWN</code> and <code>ACTIVE</code>.
|
||||
In the <code>DOWN</code> state a port will not
|
||||
provide connectivity to the network.</para>
|
||||
<para>This operation sets the administrative state for a port.
|
||||
Currently OpenStack Networking recognizes two port states:
|
||||
<code>DOWN</code> and <code>ACTIVE</code>. In the
|
||||
<code>DOWN</code> state a port will not provide
|
||||
connectivity to the network.</para>
|
||||
<para>This feature allows the tenant the ability to
|
||||
take entities offline without affecting the
|
||||
logical topology.</para>
|
||||
@ -1611,11 +1589,11 @@ Content-Type application/json
|
||||
(<errorcode>420</errorcode>), PortNotFound
|
||||
(<errorcode>430</errorcode>), PortInUse
|
||||
(<errorcode>432</errorcode>) </simpara>
|
||||
<para>This operation removes a port from a Quantum
|
||||
network. This operation might not be available for
|
||||
plugins in which the number of ports is fixed at
|
||||
network creation; in this case ports should not be
|
||||
deleted, just as they cannot be created.</para>
|
||||
<para>This operation removes a port from a OpenStack Networking
|
||||
network. This operation might not be available for plugins
|
||||
in which the number of ports is fixed at network creation;
|
||||
in this case ports should not be deleted, just as they
|
||||
cannot be created.</para>
|
||||
<para>The operation is not recoverable and will fail
|
||||
if an attachment is plugged into the port.
|
||||
#</para>
|
||||
@ -1641,8 +1619,8 @@ Content-Type application/json
|
||||
</section>
|
||||
<section xml:id="Attachments">
|
||||
<title>Attachments</title>
|
||||
<para>This section describes the operations exposed by
|
||||
Quantum API for manipulating port attachments.</para>
|
||||
<para>This section describes the operations exposed by OpenStack
|
||||
Networking API for manipulating port attachments.</para>
|
||||
<para>An attachment is typically a virtual network
|
||||
interface belonging to a VM instance. Different kinds
|
||||
of resources can be defined in the future.</para>
|
||||
@ -1745,10 +1723,10 @@ Content-Type application/json
|
||||
(<errorcode>440</errorcode>) </simpara>
|
||||
<para>This operation plugs an attachment into the port
|
||||
specified in the request URL.</para>
|
||||
<para>Quantum validates the request and dispatches the
|
||||
request to the plugin. It is not guaranteed that
|
||||
the attached resource will be available as soon as
|
||||
the operation returns.</para>
|
||||
<para>OpenStack Networking validates the request and dispatches
|
||||
the request to the plugin. It is not guaranteed that the
|
||||
attached resource will be available as soon as the operation
|
||||
returns.</para>
|
||||
<para>The validation can fail if:</para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user