openstack-attic/netconn-api
Code Issues Proposed changes

Rebuild 1.0 so that JSON fixes are picked up

Browse Source 
- I believe there could still be clouds running that API

Change-Id: If08c12b65fe02d6f4973b492a6caef472bf64d89
Partial-Bug: 1283715
This commit is contained in:
annegentle 2014-04-04 08:31:18 -05:00 committed by Andreas Jaeger
parent da301b16ce
commit 88e5f87f97
3 changed files with 229 additions and 252 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc-test.conf
View File

@ -6,7 +6,6 @@ api_site = True
# These three options need to come together # These three options need to come together
book = v1.0 book = v1.0
target_dir = target/docbkx/webhelp/openstack-network target_dir = target/docbkx/webhelp/openstack-network
# Not published but needs to be configured
publish_dir = api/openstack-network/1.0 publish_dir = api/openstack-network/1.0
book = v2.0 book = v2.0

6
tox.ini
View File

@ -21,10 +21,10 @@ commands = openstack-doc-test --check-syntax {posargs}
commands = openstack-doc-test --check-deletions {posargs} commands = openstack-doc-test --check-deletions {posargs}
[testenv:checkbuild] [testenv:checkbuild]
# Ignore directory v1.0, it is not published # Build both 1.0 and 2.0
commands = openstack-doc-test --check-build --only-book v2.0 {posargs} commands = openstack-doc-test --check-build {posargs}
[testenv:publishdocs] [testenv:publishdocs]
# Prepare all documents so that they can get published on # Prepare all documents so that they can get published on
# docs.openstack.org with just copying publish-docs/* over. # 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

466
v1.0/neutron-api-guide.xml
View File

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