diff --git a/doc-test.conf b/doc-test.conf index a789536..23abbb2 100644 --- a/doc-test.conf +++ b/doc-test.conf @@ -6,10 +6,9 @@ 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 target_dir = target/docbkx/webhelp/openstack-network # Published at http://docs.openstack.org/api/openstack-network/2.0 -publish_dir = api/openstack-network/2.0 \ No newline at end of file +publish_dir = api/openstack-network/2.0 diff --git a/tox.ini b/tox.ini index 0846149..0424684 100644 --- a/tox.ini +++ b/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 diff --git a/v1.0/neutron-api-guide.xml b/v1.0/neutron-api-guide.xml index fe0f5f6..1ba14a8 100644 --- a/v1.0/neutron-api-guide.xml +++ b/v1.0/neutron-api-guide.xml @@ -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"> - Quantum API Guide (1.0) - - Quantum API 1.0 + status="final" xml:id="openstack-networking-v1.0-api-spec"> + OpenStack Networking API Guide (1.0) + + OpenStack Networking API 1.0 @@ -51,8 +51,8 @@ 2014 OpenStack - Quantum API v1.0 - OpenStack Quantum (virtual network + Networking API v1.0 + OpenStack Networking (virtual network service) @@ -62,10 +62,9 @@ - This document is intended for software developers - interested in developing applications using the - OpenStack Quantum Layer-2 Networking Service - (API). + This document is intended for software developers interested + in developing applications using the OpenStack Networking + Layer-2 Networking Service (API). @@ -84,8 +83,7 @@ - Corrected the titles of some - examples. + Corrected the titles of some examples. @@ -95,13 +93,13 @@ - Fixed incorrect mention of &PUT; - verb in . Verb changed to &DELETE;. + Fixed incorrect mention of &PUT; verb in . Verb changed to + &DELETE;. - Fixed formatting issues in request - and response examples. + Fixed formatting issues in request and + response examples. @@ -114,8 +112,7 @@ Initial release. - First edition of this - document. + First edition of this document. @@ -124,38 +121,35 @@ Overview - 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 () and + 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 () and the NetStack home page (). + xlink:href="http://wiki.openstack.org/Network"/>). We welcome feedback, comments, and bug reports at bugs.launchpad.net/Quantum. + xlink:href="http://bugs.launchpad.net/neutron" + >bugs.launchpad.net/neutron.
Intended Audience - 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 + 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: - Openvswitch - Implementing Quantum API with - Open vSwitch + Openvswitch - Implementing OpenStack Networking API + with Open vSwitch - Cisco - Implementing Quantum API for Cisco - UCS blades and Nexus switches + Cisco - Implementing OpenStack Networking API for + Cisco UCS blades and Nexus switches You should also be familiar with: @@ -194,53 +188,51 @@ Entity - 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. + 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. Layer-2 network - A virtual Ethernet network - managed by the Quantum service. For the - time being, Quantum will manage only + A virtual Ethernet network managed by + the OpenStack Networking service. For the time + being, OpenStack Networking will manage only Ethernet networks. Network - 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. + 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. Plug-in - Software component that - provides the actual implementation for - Quantum APIs. + Software component that provides the + actual implementation for OpenStack Networking + APIs. Port - A port on the virtual network - switch represented by a Quantum virtual + A port on the virtual network switch + represented by a OpenStack Networking virtual Layer-2 network. VIF - A Virtual network InterFace - plugged into a port of a Quantum network. - Typically a virtual network interface - belonging to a VM. + A Virtual network InterFace plugged into + a port of a OpenStack Networking network. Typically + a virtual network interface belonging to a VM. Attachment @@ -255,38 +247,36 @@
Theory of Operation - This section presents the objects and semantics of - Quantum’s logical model. - 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. - 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. - 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'. - 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. - 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. + This section presents the objects and semantics of OpenStack + Networking’s logical model. + 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. + 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. + 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'. + 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. + 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. 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 @@ Concepts - To use the Quantum API effectively, developers should + To use the OpenStack Networking API effectively, developers should understand the concepts introduced in this chapter.
Network @@ -323,40 +313,38 @@ logical port. At any time at most one attachment can be plugged into a given port. 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.
General API Information - 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. + 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.
Authentication - The current version of the OpenStack Quantum service - does not require that each request will include the - credentials of the user submitting the request. - However, Quantum deployments can support several + The current version of the OpenStack Networking service does + not require that each request will include the credentials of + the user submitting the request. + 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. - Ideally, middleware modules for Authentication - and/or Authorization should be inserted in the first - stages of the Quantum pipeline (available in - etc/quantum.conf). + 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. + Ideally, middleware modules for Authentication and/or + Authorization should be inserted in the first stages of the + OpenStack Networking pipeline (available in etc/OpenStack + Networking.conf). Some authentication schemes may require that the API operate using SSL over HTTP (HTTPS). @@ -365,16 +353,17 @@
URI structure - 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. - 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: + 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. + 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: - /{Quantum-version}/tenants/{tenant-id}/{Quantum-API-entity} + /{OpenStack + Networking-version}/tenants/{tenant-id}/{OpenStack + Networking-API-entity} As an example, the following URI represents a request for retrieving all the networks configured for @@ -385,13 +374,12 @@
Request/Response Types - 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 Content-Type header, the - Accept header or adding an - .xml or .json extension - to the request URI. + 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 + Content-Type header, the Accept + header or adding an .xml or .json + extension to the request URI. 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
- Asynchronous Behavior by Quantum Plugins - 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. + Asynchronous Behavior by OpenStack Networking Plugins + 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. 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 Future versions of the API may expose a notion of an "operational status" on a logical entity like a network or port. - 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. + 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. For example, a port might have an operational status of "DOWN" because the VM interface specified as an attachment was not @@ -530,8 +516,8 @@ Content-Length 59
Versions - The Quantum API uses a URI based versioning scheme. - The first element of the URI path contains the target + The OpenStack Networking API uses a URI based versioning + scheme. The first element of the URI path contains the target version identifier. Request with URI versioning @@ -543,10 +529,10 @@ Content-Length 22 - 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. + 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. Versions List Request/Response (XML) @@ -572,7 +558,7 @@ Content-Type application/json
Extensions - The Quantum API is extensible. Extensions serve + The OpenStack Networking API is extensible. Extensions serve several purposes: @@ -679,9 +665,9 @@ Content-Type application/json 400 - Malformed request body. The - Quantum service is unable to parse the - contents of the request body. + Malformed request body. The OpenStack + Networking service is unable to parse the contents + of the request body. Unauthorized @@ -707,8 +693,8 @@ Content-Type application/json ItemNotFound 404 - The requested resource does - not exist on the Quantum API server. + The requested resource does not exist on + the OpenStack Networking API server. @@ -761,9 +747,9 @@ Content-Type application/json - The error codes 401 and 403 will be returned - only if some Authentication/Authorization system - has been enabled in the Quantum pipeline + The error codes 401 and 403 will be returned only if some + Authentication/Authorization system has been enabled in the + OpenStack Networking pipeline
@@ -771,8 +757,8 @@ Content-Type application/json API Operations
Networks - This section describes the operations exposed by - Quantum API for manipulating network resources. + This section describes the operations exposed by OpenStack + Networking API for manipulating network resources.
List Networks @@ -788,10 +774,10 @@ Content-Type application/json &GET; /tenants/tenant-id/networks - Lists summary of networks - configured in Quantum for a given - tenant, identified by - tenant-id. + Lists summary of networks configured + in OpenStack Networking for a given tenant, + identified by + tenant-id. @@ -801,19 +787,17 @@ Content-Type application/json Error Response Code(s): Unauthorized (401), Forbidden (403) - 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. + 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. - TenantId is a unique - tenant identifier. The Quantum service does - not directly manages tenants. Tenant - management should be performed by the identity - service + TenantId is a unique tenant + identifier. The OpenStack Networking service does not + directly manages tenants. Tenant management should be + performed by the identity service This operation does not require a request body. @@ -850,11 +834,10 @@ Content-Type application/json &GET; /tenants/tenant-id/networks/detail - Lists more detailed - information about networks configured - in Quantum for a given tenant, - identified by - tenant-id. + Lists more detailed information + about networks configured in OpenStack + Networking for a given tenant, identified by + tenant-id. @@ -864,9 +847,9 @@ Content-Type application/json Error Response Code(s): Unauthorized (401), Forbidden (403) - This operation returns the list of all networks - currently defined in Quantum; for each network, - its identifier and name are returned. + This operation returns the list of all networks currently + defined in OpenStack Networking; for each network, its + identifier and name are returned. This operation does not require a request body. @@ -918,9 +901,8 @@ Content-Type application/json (401), Forbidden (403), NetworkNotFound (420) - This operation returns the identifier and the - name for a specific network configured in - Quantum. + This operation returns the identifier and the name for a + specific network configured in OpenStack Networking. This operation does not require a request body. @@ -1028,27 +1010,25 @@ Content-Type application/json (400) Unauthorized (401), Forbidden (403) - This operation creates a Layer-2 network in - Quantum based on the information provided in the - request body. - 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 + This operation creates a Layer-2 network in OpenStack + Networking based on the information provided in the request + body. + 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. If the validation phase fails, the network object is not created at all, and a 400 error is returned to the caller. - The Quantum API v1.0 does not provide an - interface for checking the progress of - asynchronous operations performed by - plugins. - This will be addressed in future releases of - the Quantum API. + The OpenStack Networking API v1.0 does not provide an + interface for checking the progress of asynchronous + operations performed by plugins. + This will be addressed in future releases of the + OpenStack Networking API. The body for this request must contain a Network object specifying a symbolic name for the @@ -1103,8 +1083,8 @@ Content-Type application/json (401), Forbidden (403) NetworkNotFound (420) - This operation renames a Quantum network using - the data provided in the request body. + This operation renames a OpenStack Networking network + using the data provided in the request body. 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. - 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. + 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. This operation cannot be undone. @@ -1199,8 +1178,8 @@ Content-Type application/json
Ports - This section describes the operations exposed by - Quantum API for manipulating port resources. + This section describes the operations exposed by OpenStack + Networking API for manipulating port resources.
List Ports @@ -1217,10 +1196,10 @@ Content-Type application/json /tenants/tenant-id/networks/ network-id/ports - Lists all the ports - currently defined for a Quantum - network, identified by - network-id + Lists all the ports currently + defined for a OpenStack Networking network, + identified by + network-id @@ -1457,12 +1436,11 @@ Content-Type application/json (403), NetworkNotFound (420), RequestedStateInvalid (431) - 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. + 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. This operation could not be implemented for some plugins as the number of ports available might be fixed when the network is created. @@ -1541,11 +1519,11 @@ Content-Type application/json (420), PortNotFound (430), RequestedStateInvalid (431) - This operation sets the administrative state for - a port. Currently Quantum recognizes two port - states: DOWN and ACTIVE. - In the DOWN state a port will not - provide connectivity to the network. + This operation sets the administrative state for a port. + Currently OpenStack Networking recognizes two port states: + DOWN and ACTIVE. In the + DOWN state a port will not provide + connectivity to the network. This feature allows the tenant the ability to take entities offline without affecting the logical topology. @@ -1611,11 +1589,11 @@ Content-Type application/json (420), PortNotFound (430), PortInUse (432) - 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. + 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. The operation is not recoverable and will fail if an attachment is plugged into the port. # @@ -1641,8 +1619,8 @@ Content-Type application/json
Attachments - This section describes the operations exposed by - Quantum API for manipulating port attachments. + This section describes the operations exposed by OpenStack + Networking API for manipulating port attachments. An attachment is typically a virtual network interface belonging to a VM instance. Different kinds of resources can be defined in the future. @@ -1745,10 +1723,10 @@ Content-Type application/json (440) This operation plugs an attachment into the port specified in the request URL. - 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. + 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. The validation can fail if: