From afdea610dce5f96aad265806f925885c586d8bb2 Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Fri, 13 Sep 2013 10:59:06 -0500 Subject: [PATCH] Add the port bindings provider-prefixed extended attributes Partial-Bug: #1157159 Change-Id: I4b25011902128eba20667d9023806735581cce27 author: diane fleming --- v2.0/ch_preface.xml | 36 +- v2.0/neutron-agent-ext.xml | 2 +- v2.0/neutron-api-guide.xml | 493 +++++++++++--------- v2.0/neutron-extraroute-ext.xml | 230 ++++----- v2.0/neutron-loadbalancer-ext.xml | 44 +- v2.0/neutron-provider-ext.xml | 24 +- v2.0/neutron-quotas-ext.xml | 2 +- v2.0/samples/networks-get-res-prov.json | 2 +- v2.0/samples/networks-get-res-prov.xml | 10 +- v2.0/samples/networks-get-resp.json | 37 ++ v2.0/samples/networks-get-resp.xml | 30 ++ v2.0/samples/networks-post-req-prov.json | 3 +- v2.0/samples/networks-post-req-prov.xml | 8 +- v2.0/samples/networks-provider-get-resp.xml | 37 ++ v2.0/samples/networks-put-req-prov.xml | 1 - v2.0/samples/networks-show-res-prov.xml | 4 +- v2.0/samples/ports-get-res-prov.json | 28 ++ v2.0/samples/ports-get-res-prov.xml | 29 ++ v2.0/samples/ports-post-req-prov.json | 11 + v2.0/samples/ports-post-req-prov.xml | 12 + v2.0/samples/ports-put-req-prov.json | 13 + v2.0/samples/ports-put-req-prov.xml | 15 + v2.0/samples/ports-show-res-prov.json | 15 + v2.0/samples/ports-show-res-prov.xml | 16 + v2.0/section_binding_ext_ports.xml | 467 ++++++++++++++++++ v2.0/section_provider_ext_networks.xml | 288 ++++++++++++ v2.0/section_provider_extended_attrs.xml | 58 +++ 27 files changed, 1489 insertions(+), 426 deletions(-) mode change 100644 => 100755 v2.0/samples/networks-get-res-prov.json create mode 100644 v2.0/samples/networks-get-resp.json create mode 100644 v2.0/samples/networks-get-resp.xml create mode 100644 v2.0/samples/networks-provider-get-resp.xml create mode 100644 v2.0/samples/ports-get-res-prov.json create mode 100644 v2.0/samples/ports-get-res-prov.xml create mode 100644 v2.0/samples/ports-post-req-prov.json create mode 100644 v2.0/samples/ports-post-req-prov.xml create mode 100644 v2.0/samples/ports-put-req-prov.json create mode 100644 v2.0/samples/ports-put-req-prov.xml create mode 100644 v2.0/samples/ports-show-res-prov.json create mode 100644 v2.0/samples/ports-show-res-prov.xml create mode 100644 v2.0/section_binding_ext_ports.xml create mode 100644 v2.0/section_provider_ext_networks.xml create mode 100644 v2.0/section_provider_extended_attrs.xml diff --git a/v2.0/ch_preface.xml b/v2.0/ch_preface.xml index 80ab7b7..7e41620 100644 --- a/v2.0/ch_preface.xml +++ b/v2.0/ch_preface.xml @@ -35,18 +35,12 @@ format="SVG" scale="60"/> Preface The OpenStack Networking project provides virtual networking services among devices managed by the OpenStack + xlink:href="http://wiki.openstack.org/OpenStack">OpenStack compute service. - This document describes the features available with the - &APIv2;. + This document describes the + &APIv2; features. We welcome feedback, comments, and bug reports at bugs.launchpad.net/Neutron. + xlink:href="http://bugs.launchpad.net/Neutron">bugs.launchpad.net/Neutron.
Intended Audience general understanding of the OpenStack Networking service, the OpenStack compute service, and the integration between the two. You should also have access - to a plugin that implements the &APIv2;. + to a plug-in that implements the &APIv2;. You should also - be familiar with: - + be familiar with: + ReSTful web services @@ -93,13 +83,8 @@ format="SVG" scale="60"/>
Resources Use the following resources in conjunction with this - guide: - - + guide: + Resource @@ -122,7 +107,6 @@ format="SVG" scale="60"/> >http://wiki.openstack.org/Neutron - +
- diff --git a/v2.0/neutron-agent-ext.xml b/v2.0/neutron-agent-ext.xml index 8d5ee0d..bf6742d 100644 --- a/v2.0/neutron-agent-ext.xml +++ b/v2.0/neutron-agent-ext.xml @@ -45,7 +45,7 @@ a certain agent, and OpenStack Networking schedulers will not schedule resources to it. For how to use agent management extension and OpenStack Networking schedulers feature, - see the OpenStack Networking Administration Guide. + see the OpenStack Cloud Administrator Guide. diff --git a/v2.0/neutron-api-guide.xml b/v2.0/neutron-api-guide.xml index 4458ae0..2f3d27f 100644 --- a/v2.0/neutron-api-guide.xml +++ b/v2.0/neutron-api-guide.xml @@ -64,6 +64,17 @@ + + 2013-10-11 + + + + Added the Networking API ports + binding extension. + + + + 2013-05-22 @@ -71,7 +82,7 @@ Updated the title of the book and project name to "OpenStack - Networking." + Networking." Updated the title of the book to @@ -124,14 +135,14 @@ The Neutron project provides virtual networking services among devices that are managed by the OpenStack compute service. + >OpenStack compute service. The &APIv2; combines the Quantum API v1.1 with some essential Internet Protocol Address Management (IPAM) capabilities from the Melange API. + >Melange API. These IPAM capabilities enable you to: Associate IP address blocks and other @@ -147,19 +158,21 @@ port. To do this, the &APIv2; introduces the - subnet entity. A subnet can represent either an IP version - 4 or version 6 address block. Each OpenStack Networking network + subnet entity that can represent either an IP version 4 or + version 6 address block. Each OpenStack Networking network commonly has one or more subnets. When you create a port on the network, an available fixed IP address is allocated to it from one the designated subnets for each IP version. When you delete the port, the allocated addresses return to the pool of available IPs on the subnet. &APIv2; users can choose a specific IP address from the block or let - OpenStack Networking choose the first available IP address. + OpenStack Networking choose the first available IP + address. The Quantum API v1.x was removed from the source code tree. To use the Quantum API - v1.x, install the Quantum Essex release. + v1.x, install the Quantum Essex + release.
@@ -183,9 +196,9 @@ entity Any piece of hardware or software that can connect to the network - services provided by OpenStack Networking. An entity - can use OpenStack Networking services by - implementing a VIF. + services provided by OpenStack Networking. + An entity can use OpenStack Networking + services by implementing a VIF. IPAM @@ -200,9 +213,10 @@ layer-2 network A virtual Ethernet network - that is managed by the OpenStack Networking service. - Currently, OpenStack Networking manages only Ethernet - networks. + that is managed by the OpenStack + Networking service. Currently, OpenStack + Networking manages only Ethernet networks. + network @@ -216,7 +230,7 @@ - plugin + plug-in A software component that implements &APIv2;. @@ -263,14 +277,14 @@ that network, and booting a VM that is attached to the network. Clean-up includes deleting the VM, deleting any ports associated with the network, and deleting - the networks. OpenStack Networking deletes any subnets associated - with the deleted network. + the networks. OpenStack Networking deletes any subnets + associated with the deleted network. To use OpenStack Networking - high-level task - flow: + flow Create a network - The tenant creates a network. + The tenant creates a network. For example, the tenant creates the net1 network. Its ID is Associate a subnet with the network The tenant associates a subnet with that - network. + network. For example, the tenant associates the 10.0.0.0/24 subnet with the net1 network. @@ -291,38 +305,40 @@ network The tenant boots a virtual machine (VM) and specifies a single NIC that connects to the - network. + network. The following examples use the nova client - to boot a VM. - In the first example, Nova contacts OpenStack Networking - to create the NIC and attach it to the - net1 network, with the - ID net1_id: - $ nova boot <server_name> --image <image> --flavor <flavor> --nic net-id=<net1_id> + to boot a VM. + In the first example, Nova contacts + OpenStack Networking to create the NIC and + attach it to the net1 + network, with the ID net1_id: + $ nova boot <server_name> --image <image> --flavor <flavor> --nic net-id=<net1_id> In a second example, you first create the port1, port and then - you boot the VM with a specified port. OpenStack Networking - creates a NIC and attaches it to the - port1 port, with the ID - port1_id: - $ nova boot <server_name> --image <image> --flavor <flavor> --nic port-id=<port1_id> - OpenStack Networking chooses and assigns an IP address to - the port1 port. + you boot the VM with a specified port. + OpenStack Networking creates a NIC and + attaches it to the port1 + port, with the ID port1_id: + $ nova boot <server_name> --image <image> --flavor <flavor> --nic port-id=<port1_id> + OpenStack Networking chooses and assigns an + IP address to the port1 + port. For information about how to create ports, - see . + see . For more information about the nova boot command, enter: - $ nova help boot + $ nova help boot Delete the VM - The tenant deletes the VM. - Nova contacts OpenStack Networking and deletes the - port1 port. + The tenant deletes the VM. + Nova contacts OpenStack Networking and + deletes the port1 + port. The allocated IP address is returned to the - pool of available IP addresses. + pool of available IP addresses. Delete any ports @@ -337,26 +353,26 @@ operation deletes an OpenStack Networking network and its associated subnets provided that no port is currently configured on the - network. + network. See .
- The Plugin + The Plug-in Virtual networking services are implemented through - a plugin. A plugin can use different techniques and + a plug-in. A plug-in can use different techniques and technologies to provide isolated virtual networks to - tenants. A plugin also provides other services, such - as IP address management. Because each plugin - implements all the operations included in &APIv2;, do - not be concerned about which plugin is used. - However, some plugins might expose additional + tenants. A plug-in also provides other services, such + as IP address management. Because each plug-in + implements all the operations included in &APIv2;, you do + not need to be concerned about which plug-in is used. + However, some plug-ins might expose additional capabilities through API extensions, which are discussed in this document. For more information about - the extensions exposed by a particular plugin, see the - plugin documentation. + the extensions exposed by a particular plug-in, see the + plug-in documentation.
@@ -386,7 +402,7 @@ These entities have auto-generated unique identifiers and support basic create, read, update, and delete (CRUD) functions with the &POST;, &GET;, &PUT;, and &DELETE; - verbs. + verbs.
Network @@ -398,10 +414,10 @@ quotas. See . In the &APIv2;, the network is the main entity. Ports and subnets are always associated with a - network. + network. The following table describes the attributes for - network objects. + network objects. @@ -421,13 +437,13 @@ C. Use the attribute in - create operations. + create operations. R. This attribute is returned in response to show and - list operations. + list operations. D. You can delete the - value of this attribute. + value of this attribute. @@ -500,8 +516,8 @@ ERROR - Plugins might define - additional values. + Plug-ins might define + additional values. @@ -527,10 +543,11 @@ @@ -551,11 +568,11 @@ subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be - specified by the user. + specified by the user.A subnet can also optionally have a gateway, a list of dns name servers, and host routes. This information is pushed to instances whose interfaces are associated - with the subnet. + with the subnet.
Network Attributes
subnets tenant_id uuid-str No - If OpenStack Networking is not running with - the Keystone Identity service, the + If OpenStack Networking is not + running with the Keystone Identity + service, the tenant_id - attribute is required. + attribute is required. CR
@@ -576,13 +593,13 @@ C. Use the attribute in - create operations. + create operations. R. This attribute is returned in response to show and - list operations. + list operations. D. You can delete the - value of this attribute. + value of this attribute. @@ -714,10 +731,11 @@ @@ -739,7 +757,8 @@ to the interfaces plugged into them. When IP addresses are associated to a port, this also implies the port is associated with a subnet, as the IP address was - taken from the allocation pool for a specific subnet. + taken from the allocation pool for a specific + subnet.
Subnet Attributes
tenant_id uuid-str No - If OpenStack Networking is not running with - the Keystone Identity service, the + If OpenStack Networking is not + running with the Keystone Identity + service, the tenant_id - attribute is required. + attribute is required. CR N/A
@@ -760,13 +779,13 @@ C. Use the attribute in - create operations. + create operations. R. This attribute is returned in response to show and - list operations. + list operations. D. You can delete the - value of this attribute. + value of this attribute. @@ -850,8 +869,8 @@ ERROR - Plugins might define - additional values. + Plug-ins might define + additional values. @@ -900,10 +919,11 @@ @@ -948,25 +968,25 @@ xlink:href="https://openstack.keystone.org" >Keystone Identity Service as the default authentication service. When Keystone is enabled, - users that submit requests to the OpenStack Networking service must - provide an authentication token in X-Auth-Token request - header. You obtain the token by authenticating to the - Keystone endpoint. For more information about + users that submit requests to the OpenStack Networking + service must provide an authentication token in + X-Auth-Token + request header. You obtain the token by authenticating + to the Keystone endpoint. For more information about Keystone, see the OpenStack Identity Developer - Guide. + >OpenStack Identity Service API v2.0 Reference.When Keystone is enabled, the tenant_id attribute is not required in create requests because the tenant ID is - derived from the authentication token. + derived from the authentication token.The default authorization settings allow only administrative users to create resources on behalf of - a different tenant. - OpenStack Networking uses information received from Keystone to - authorize user requests. OpenStack Networking handles the following - types of authorization policies: + a different tenant. + OpenStack Networking uses information received from + Keystone to authorize user requests. OpenStack + Networking handles the following types of + authorization policies: Operation-based policies @@ -985,8 +1005,8 @@ The actual authorization policies enforced in - OpenStack Networking might vary from deployment to deployment. - + OpenStack Networking might vary from deployment to + deployment.
@@ -997,7 +1017,8 @@ The format for both the request and the response can be specified by using the Content-Type header, the Accept header or adding the - .json extension to the request URI. + .json extension to the request + URI. JSON Request with Headers @@ -1020,7 +1041,7 @@ Content-Length 204 Filtering and Column Selection The &APIv2; supports filtering based on all top level attributes of a resource. Filters are applicable - to all list requests. + to all list requests. For example, the following request returns all networks named foobar: GET /v2.0/networks?name=foobar @@ -1029,51 +1050,53 @@ Content-Length 204 The operation applies an AND condition among the filters. - OpenStack Networking does not offer an OR mechanism for - filters. + OpenStack Networking does not offer an OR + mechanism for filters. Alternatively, you can issue a distinct request for each filter and build a response set from the received - responses on the client-side. - By default, OpenStack Networking returns all attributes for any - show or list call. The &APIv2; has a mechanism to - limit the set of attributes returned. For example, - return id. + responses on the client-side. + By default, OpenStack Networking returns all + attributes for any show or list call. The &APIv2; has + a mechanism to limit the set of attributes returned. + For example, return id. You can use the fields query parameter to control the attributes returned from the - &APIv2;. + &APIv2;. For example, the following request returns only id and name for each network: GET /v2.0/networks.json?fields=id&fields=name
- Synchronous versus Asynchronous Plugin + <title>Synchronous versus Asynchronous Plug-in Behavior The &APIv2; presents a logical model of network connectivity consisting of networks, ports, and - subnets. It is up to the OpenStack Networking plugin to communicate - with the underlying infrastructure to ensure packet - forwarding is consistent with the logical model. A - plugin might perform these operations asynchronously. + subnets. It is up to the OpenStack Networking plug-in + to communicate with the underlying infrastructure to + ensure packet forwarding is consistent with the + logical model. A plug-in might perform these operations + asynchronously. When an API client modifies the logical model by issuing an HTTP &POST;, &PUT;, or &DELETE; request, - the API call might return before the plugin modifies + the API call might return before the plug-in modifies underlying virtual and physical switching devices. However, an API client is guaranteed that all subsequent API calls properly reflect the changed - logical model. + logical model. For example, if a client issues an HTTP &PUT; request to set the attachment for a port, there is no guarantee that packets sent by the interface named in the attachment are forwarded immediately when the HTTP call returns. However, it is guaranteed that a subsequent HTTP &GET; request to view the attachment - on that port returns the new attachment value. + on that port returns the new attachment value. You can use the status attribute with the network and port resources to determine - whether the OpenStack Networking plugin has successfully completed - the configuration of the resource. + whether the OpenStack Networking plug-in has + successfully completed the configuration of the + resource.
Bulk Create Operations @@ -1082,17 +1105,18 @@ Content-Length 204 operations use exactly the same API syntax as single create operations except that you specify a list of objects rather than a single object in the request - body. + body. Bulk operations are always performed atomically, meaning that either all or none of the objects in the - request body are created. If a particular plugin does + request body are created. If a particular plug-in does not support atomic operations, the &APIv2; emulates the atomic behavior so that users can expect the same - behavior regardless of the particular plugin running - in the background. - OpenStack Networking might be deployed without support for bulk - operations and when the client attempts a bulk create - operation, a 400 + behavior regardless of the particular plug-in running + in the background. + OpenStack Networking might be deployed without + support for bulk operations and when the client + attempts a bulk create operation, a + 400 Bad Request error is returned. For information about how to submit bulk requests to @@ -1115,7 +1139,8 @@ Content-Length 204 parameter sets the page direction. These parameters are optional. If the client requests a limit beyond the maximum limit configured by the deployment, the - server returns the maximum limit number of items. + server returns the maximum limit number of + items. For convenience, list responses contain atom "next" links and "previous" links. The last page in the list requested with 'page_reverse=False' will not contain @@ -1125,18 +1150,18 @@ Content-Length 204 three items. The first page was retrieved through: &GET; http://127.0.0.1:9696/v2.0/networks.json?limit=2 - Pagination is an optional feature of OpenStack Networking API, - and it might be disabled. If pagination is disabled, - the pagination parameters will be ignored and return - all the items. - If a particular plugin does not support pagination + Pagination is an optional feature of OpenStack + Networking API, and it might be disabled. If + pagination is disabled, the pagination parameters will + be ignored and return all the items. + If a particular plug-in does not support pagination operations, and pagination is enabled, the &APIv2; will emulate the pagination behavior so that users can expect the same behavior regardless of the particular - plugin running in the background. - Unfortunately OpenStack Networking does not expose any mechanism - to tell user if pagination is supported by particular - plugin or enabled. + plug-in running in the background. + Unfortunately OpenStack Networking does not expose + any mechanism to tell user if pagination is supported + by particular plug-in or enabled. Network Collection, First Page: JSON Request @@ -1207,23 +1232,24 @@ Accept: application/xml repeated, and the number of 'sort_key' and 'sort_dir' provided must be same. The sort_dir parameter indicates in which direction to sort. Acceptable - values are 'asc' (ascending) and 'desc' (descending). - Sorting is optional feature of OpenStack Networking API, and it - might be disabled. If sorting is disabled, the sorting - parameters will be ignored. - If a particular plugin does not support sorting + values are 'asc' (ascending) and 'desc' + (descending). + Sorting is optional feature of OpenStack Networking + API, and it might be disabled. If sorting is disabled, + the sorting parameters will be ignored. + If a particular plug-in does not support sorting operations, and sorting is enabled, the &APIv2; will emulate the sorting behavior so that users can expect - the same behavior regardless of the particular plugin - running in the background. - Unfortunately OpenStack Networking does provide a mechanism to - tell users if specific plugins support or have enabled - sorting. + the same behavior regardless of the particular plug-in + running in the background. + Unfortunately OpenStack Networking does provide a + mechanism to tell users if specific plug-ins support or + have enabled sorting.
Extensions - The &APIv2; is extensible. - The purpose of &APIv2; extensions is to: + The &APIv2; is extensible. + The purpose of &APIv2; extensions is to: Introduce new features in the API without @@ -1231,17 +1257,17 @@ Accept: application/xml Introduce vendor-specific niche - functionality. + functionality. Act as a proving ground for experimental functionalities that might be included in a - future version of the API. + future version of the API. To programmatically determine which extensions are available, issue a &GET; request on the - v2.0/extensions URI. + v2.0/extensions URI. To query extensions individually by unique alias, issue a &GET; request on the /v2.0/extensions/alias_name @@ -1256,9 +1282,9 @@ Accept: application/xml that prevent conflicts with other extensions that define attributes or resources with the same names, and with core resources and attributes. Because an - extension might not be supported by all plugins, the + extension might not be supported by all plug-ins, the availability of an extension varies with deployments - and the specific plugin in use. + and the specific plug-in in use. For more information regarding specific extensions, see
@@ -1266,10 +1292,11 @@ Accept: application/xml
Faults The &APIv2; returns an error response if a failure - occurs while processing a request. OpenStack Networking uses only - standard HTTP error codes. 4xx - errors indicate problems in the particular request - being sent from the client. + occurs while processing a request. OpenStack + Networking uses only standard HTTP error codes. + 4xx errors indicate problems in + the particular request being sent from the + client.
@@ -1370,30 +1397,29 @@ Accept: application/xml - + - + - + - + - @@ -1416,10 +1442,8 @@ Accept: application/xml - + @@ -1428,13 +1452,12 @@ Accept: application/xml Error Response Codes: Unauthorized (401) - Lists a summary of all networks defined in - OpenStack Networking that are accessible to the tenant who - submits the request. The list provides the unique - ID for each network. + Lists networks that he tenant who submits the + request can access. The list show the ID for each + network.This operation does not require a request body, - unless the OpenStack Networking server is running without - Keystone integration. + unless the OpenStack Networking server is running + without Keystone integration.This operation returns a response body. List Networks: JSON Request @@ -1443,7 +1466,16 @@ Accept: application/json List Networks: JSON Response - + + + + List Networks: XML Request + GET /v2.0/networks +Accept: application/xml + + + List Networks: XML Response + @@ -1464,8 +1496,8 @@ Accept: application/json - + @@ -1509,7 +1541,7 @@ Accept: application/json - + @@ -1519,9 +1551,9 @@ Accept: application/jsonError Response Codes: Bad Request (400) Unauthorized (401) - This operation does not require a rest body. - If specified, the body might include one or more - of the following attributes: + This operation does not require a request + body. If specified, the body might include one or + more of the following attributes: name: @@ -1559,11 +1591,11 @@ Accept: application/json POST v2.0/networks.json Content-Type: application/json Accept: application/json - + Create Network: JSON Response - +
Bulk Create Networks @@ -1617,7 +1649,7 @@ Accept: application/json
- + @@ -1667,10 +1699,10 @@ Accept: application/json returned.This operation returns a response body. - Update operations in OpenStack Networking adopt patch - semantics. This implies that the &APIv2; does - not require the user to send the whole - resource to be updated, but just the + Update operations in OpenStack Networking + adopt patch semantics. This implies that the + &APIv2; does not require the user to send the + whole resource to be updated, but just the attributes that the user wishes to update, as shown in the following example. @@ -1725,7 +1757,7 @@ content-type: application/json - @@ -1902,7 +1934,6 @@ Accept: application/json Show Subnet: JSON Request GET /v2.0/subnets/4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861 - Accept: application/json @@ -1952,26 +1983,27 @@ content-type: application/json subnet, in the form: network_address/prefixThe remaining attributes are optional. - By default, OpenStack Networking creates IP v4 subnets. To - create an IP v6 subnet, you must specify the value - 6 for the + By default, OpenStack Networking creates IP v4 + subnets. To create an IP v6 subnet, you must + specify the value 6 for the ip_version attribute in - the request body. OpenStack Networking does not try to derive - the correct IP version from the provided CIDR. If - the parameter for the gateway address, - gateway_ip, is not - specified, OpenStack Networking allocates an address from the - cidr for the gateway for the subnet. + the request body. OpenStack Networking does not + try to derive the correct IP version from the + provided CIDR. If the parameter for the gateway + address, gateway_ip, is not + specified, OpenStack Networking allocates an + address from the cidr for the gateway for the + subnet. To specify a subnet without a gateway, specify the value null for the gateway_ip attribute in the request body. If allocation pools attribute, allocation_pools, is not - specified, OpenStack Networking automatically allocates pools - for covering all IP addresses in the CIDR, - excluding the address reserved for the subnet - gateway. Otherwise, you can explicitly specify - allocation pools as shown in the following + specified, OpenStack Networking automatically + allocates pools for covering all IP addresses in + the CIDR, excluding the address reserved for the + subnet gateway. Otherwise, you can explicitly + specify allocation pools as shown in the following example. When allocation_pools and gateway_ip are both @@ -2088,18 +2120,16 @@ Accept: application/json This operation requires a request body. This operation returns a response body. - Update operations in OpenStack Networking adopt patch - semantics. This implies that the &APIv2; does - not require you to send the whole resource to - be updated, but just the attributes that you - wish to update, as shown in the following - example. + Update operations in OpenStack Networking + adopt patch semantics. This implies that the + &APIv2; does not require you to send the whole + resource to be updated, but just the + attributes that you wish to update, as shown + in the following example. Update Subnet: JSON Request - PUT /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031 - Content-Type: application/json Accept: application/json { @@ -2144,9 +2174,9 @@ Accept: application/json (404), Conflict (409) This operation removes a subnet from a - OpenStack Networking network. The operation fails if IP - addresses from the subnet that you want to delete - are still allocated. + OpenStack Networking network. The operation fails + if IP addresses from the subnet that you want to + delete are still allocated. This operation does not require a request body. This operation does not return a response @@ -2240,7 +2270,8 @@ Accept: application/json has access. Default policy settings return only those subnets that are owned by the tenant who submits the request, unless the request is - submitted by an user with administrative rights. + submitted by an user with administrative + rights. Users can control which attributes are returned by using the fields query parameter. Additionally, you can filter results by @@ -2320,7 +2351,6 @@ Accept: application/json
Port Attributes
mac_address tenant_id uuid-str No - If OpenStack Networking is not running with - the Keystone Identity service, the + If OpenStack Networking is not + running with the Keystone Identity + service, the tenant_id - attribute is required. + attribute is required. CR
&GET; /networksLists a summary of all networks defined in - OpenStack Networking that are accessible to the tenant - who submits the request.Lists networks that he tenant who submits + the request can access.
&GET; /networks/network_idLists detailed information for the - specified network.Shows information for a specified + network.
&POST; /networksCreates a new OpenStack Networking network.Creates a network.
&PUT; /networks/network-idUpdates the specified network.Updates a specified network.
&DELETE; /networks/network-idDestroys the specified network and all + Deletes a specified network and its associated resources.
&GET; /networksLists a summary of all networks - defined in OpenStack Networking that are accessible - to the tenant who submits the request. - Lists networks that he tenant who + submits the request can access.
&GET; /networks/network_idLists detailed information for the - specified network ID.Shows information for a specified + network.
&POST; /networksCreates a new OpenStack Networking network.Creates a network.
&PUT; /networks/network-idUpdates the specified network.Updates a specified network.
&DELETE; /networks/network-idDeletes the specified network and all + Deletes a specified network and its associated resources.
- List Ports: JSON Request GET /v2.0/ports.json HTTP/1.1 @@ -2409,10 +2439,11 @@ accept: application/json (404), Conflict (409), MAC generation failure (503) - This operation creates a new OpenStack Networking port. You - must specify the network where the port is to - created on the network_id - attribute in the request body. + This operation creates a new OpenStack + Networking port. You must specify the network + where the port is to created on the + network_id attribute in + the request body. If you specify a security group ID, this port is associated with the security group. You can associate more than one security group with a @@ -2436,8 +2467,8 @@ accept: application/json in use, a 409 Conflict error is returned. When the MAC address is not specified, - OpenStack Networking tries to allocate one for the port - being created. + OpenStack Networking tries to allocate one + for the port being created. If a failure occurs while generating the address, a 503 Service Unavailable error is @@ -2453,15 +2484,16 @@ accept: application/json Fixed IPs If you specify just a subnet - ID, OpenStack Networking allocates an available - IP from that subnet to the - port. + ID, OpenStack Networking allocates + an available IP from that subnet to + the port. If you specify both a subnet - ID and an IP address, OpenStack Networking tries - to allocate the specified address - to the port. + ID and an IP address, OpenStack + Networking tries to allocate the + specified address to the + port. @@ -2642,15 +2674,15 @@ accept: application/json operation on an existing resource. - Generic API extensions are not plugin-specific. For - information about plugin-specific extensions that are - shipped with OpenStack Networking, see the extension documentation in - the source code tree. + Generic API extensions are not plug-in-specific. For + information about plug-in-specific extensions that are + shipped with OpenStack Networking, see the extension + documentation in the source code tree.
List Available Extensions You can list available extensions through the /v2.0/extensions - URI. + URI. You must authenticate these requests just like any other API request. @@ -2674,7 +2706,8 @@ Content-Type: application/xml; charset=UTF-8 Date: Wed, 12 Sep 2012 11:36:20 GMT
- + + diff --git a/v2.0/neutron-extraroute-ext.xml b/v2.0/neutron-extraroute-ext.xml index 3e4d3a3..a80fc61 100644 --- a/v2.0/neutron-extraroute-ext.xml +++ b/v2.0/neutron-extraroute-ext.xml @@ -35,123 +35,123 @@ xmlns:db="http://docbook.org/ns/docbook" version="5.0" status="final" xml:id="extraroute-ext"> The ExtraRoute Extension - - You can setup route configuration on the Router using this extension. - This extension augments the 'Router' resource by adding a new 'routes' attribute. - - - You can specify a set of nexthop IPs and destination CIDRs. + You can set up route configuration on the Router using this + extension. This extension augments the 'Router' resource by + adding a new 'routes' attribute. + You can specify a set of nexthop IPs and destination CIDRs. Note the nexthop IP must be a part of one of the subnets - router interfaces are connected to. - This is why configuration of route property is allowed only update operation on REST. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Router Attributes
Attribute Type Required CRUD - - - - C. Use the attribute in - create operations. - - - R. This attribute is - returned in response to show and - list operations. - - - U. You can update the - value of this attribute. - - - D. You can delete the - value of this attribute. - - - - Default Value Validation Constraints Notes
routeslist of dictNoUNoneList should be in this form. - [{'nexthop':IPAddress, 'destination':CIDR}] - Extra route configuration
-
- Update Extra route - - - - - - - - Verb - URI - Description - - - - - &PUT; - /routers/router_id - Update logical router with routes attribute. - - - - - Normal Response Code: 200 - - Error Response Codes: Unauthorized - (401), Bad Request - (400), Not Found - (404), Conflict - (409) - This operation configures extra routes on the router. Note the nexthop IP must be a - part of one of the subnets router interfaces are connected to, otherwise the server will - respond with 400 Bad Request. When a validation error is detected - (e.g. format error of IP address or CIDR), the server will respond with 400 Bad - Request When Neutron receives a request to delete the router interface for - subnets which are used by one or more routes, it willl respond with 409 - Conflict + router interfaces are connected to. This is why configuration + of route property is allowed only update operation on REST. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Router Attributes
Attribute Type Required CRUD + + + + C. Use the attribute in + create operations. + + + R. This attribute is + returned in response to show and + list operations. + + + U. You can update the + value of this attribute. + + + D. You can delete the + value of this attribute. + + + + Default Value Validation Constraints Notes
routeslist of dictNoUNoneList should be in this form. + [{'nexthop':IPAddress, 'destination':CIDR}] Extra route configuration
+
+ Update Extra route + + + + + + + + Verb + URI + Description + + + + + &PUT; + /routers/router_id + Update logical router with routes + attribute. + + + - - Update the routes attribute for a given router - - - + Normal Response Code: 200 + + Error Response Codes: Unauthorized + (401), Bad Request + (400), Not Found + (404), Conflict + (409) + This operation configures extra routes on the router. + The nexthop IP must be a part of one of the subnets + to which the router interfaces are connected. Otherwise, the server + responds with 400 Bad Request. When + a validation error is detected, such as a format error of IP + address or CIDR, the server responds with + 400 Bad Request. When Networking + receives a request to delete the router interface for + subnets that are used by one or more routes, it + responds with 409 Conflict. + + + Update the routes attribute for a given + router + + + Update routes: Response - -
- - + +
+
diff --git a/v2.0/neutron-loadbalancer-ext.xml b/v2.0/neutron-loadbalancer-ext.xml index b1503e6..48df0fb 100644 --- a/v2.0/neutron-loadbalancer-ext.xml +++ b/v2.0/neutron-loadbalancer-ext.xml @@ -75,12 +75,12 @@ member, a representation - of the application running on backend server. + of the application running on back end server. health_monitor, which is used - to determine whether or not back-end members of the pool + to determine whether or not back end members of the pool are usable for processing traffic. @@ -110,32 +110,32 @@ - A pool member represents the application running on the backend server. + A pool member represents the application running on the back end server. A Health Monitor - is used to determine whether or not back-end members of the VIP's + is used to determine whether or not back end members of the VIP's pool are usable for processing a request. A pool can have several health monitors associated with it. There are different types of - health monitors supported by the LBaaS extension: + health monitors supported by the LBaaS extension: - PING: used to ping the members using ICMP. + PING: pings the members by using ICMP. - TCP: used to connect to the members using TCP. + TCP: connects to the members by using TCP. - HTTP: used to send an HTTP request to the member. + HTTP: sends an HTTP request to the member. - HTTPS: used to send a secure HTTP request to the member. + HTTPS: sends a secure HTTP request to the member. - When a pool has several monitors associated with it, each member of + When a pool has several monitors associated with it, each member of the pool is monitored by all these monitors. If any monitor declares the member as unhealthy, then the member status is changed to inactive and the member won't participate in its pool's load @@ -147,35 +147,32 @@ Session persistence is a feature of the load balancing service. It attempts to force connections or requests in the same session to be processed by the same member as long as it is active. The - LBaaS extension supports three types of persistence: + LBaaS extension supports three types of persistence: SOURCE_IP: With this persistence mode, all connections originating from the same source - IP address will be handled by the same member of the + IP address are handled by the same member of the pool. HTTP_COOKIE: With this - persistence mode, the load balancing function will - create a cookie on the first request from a client. + persistence mode, the load balancing function creates a cookie on the first request from a client. Subsequent requests containing the same cookie value will be handled by the same member of the pool. APP_COOKIE: With this - persistence mode, the load balancing function will rely - on a cookie established by the backend application. All - requests carrying the same cookie value will be handled + persistence mode, the load balancing function relies + on a cookie established by the back end application. All + requests carrying the same cookie value is handled by the same member of the pool. - -
@@ -185,17 +182,17 @@ The high-level task flow for using LBaaS API to configure load - balancing is as follows: + balancing is as follows: - The tenant creates a Pool, which is initially empty + The tenant creates a pool, which is initially empty - The tenant creates one or several Members in the Pool + The tenant creates one or several members in the pool - The tenant create one or several Health Monitors + The tenant create one or several health monitors The tenant associates the Health Monitors with the Pool @@ -204,7 +201,6 @@ The tenant finally creates a VIP associated with the Pool - diff --git a/v2.0/neutron-provider-ext.xml b/v2.0/neutron-provider-ext.xml index 1970c80..2ec66bd 100644 --- a/v2.0/neutron-provider-ext.xml +++ b/v2.0/neutron-provider-ext.xml @@ -63,8 +63,8 @@ the physical network on top of which this network object is being implemented. The OpenStack Networking API does not expose any facility for retrieving the list of available physical networks. As an example, in the Open vSwitch - plugin this is a symbolic name which is then mapped to specific bridges on - each compute host through the Open vSwitch plugin configuration file. + plug-in this is a symbolic name which is then mapped to specific bridges on + each compute host through the Open vSwitch plug-in configuration file. provider:segmentation_id - Identifies @@ -78,11 +78,11 @@ - The actual semantics of these attributes depend on the technology backend of the - particular plugin. See the plugin document or the - OpenStack Networking Administration Guide to understand which values should be specific for - each of these attributes when OpenStack Networking is deployed with a particular plugin. The examples - shown in this chapter refer to the Open vSwitch plugin. + The actual semantics of these attributes depend on the technology back end of the + particular plug-in. See the plug-in documentation and the + OpenStack Cloud Administrator Guide to understand which values should be specific for + each of these attributes when OpenStack Networking is deployed with a particular plug-in. The examples + shown in this chapter refer to the Open vSwitch plug-in. It is also worth noting that the default policy settings allow only users with administrative rights to specify these parameters in requests, and to see their values in responses. By default, the provider network extension attributes are completely @@ -208,9 +208,9 @@ If the user submitting the request is not allowed to set provider networks attributes, a 403 Forbidden response will be returned. As stated earlier in this chapter, the semantics of the various provider networks - attribute vary with the particular plugin employed. The following example shows how + attribute vary with the particular plug-in employed. The following example shows how to create a network mapped to a specific vlan tag (the example refers to an OpenStack Networking - deployment which uses the Open vSwitch plugin). + deployment which uses the Open vSwitch plug-in). Create Network with provider attributes: JSON Request @@ -254,9 +254,9 @@ If the user submitting the request is not allowed to set provider networks attributes, a 403 Forbidden response will be returned. As stated earlier in this chapter, the semantics of the various provider networks - attribute vary with the particular plugin employed. The following example shows how - to update a network in order to map it to a flat network (ie: no vlan tag); the - example refers to an OpenStack Networking deployment which uses the Open vSwitch plugin. + attribute vary with the particular plug-in employed. The following example shows how + to update a network in order to map it to a flat network (such as, no vlan tag); the + example refers to an OpenStack Networking deployment that uses the Open vSwitch plug-in. Update provider attributes for a network: JSON Request diff --git a/v2.0/neutron-quotas-ext.xml b/v2.0/neutron-quotas-ext.xml index b53aebf..82e8167 100644 --- a/v2.0/neutron-quotas-ext.xml +++ b/v2.0/neutron-quotas-ext.xml @@ -42,7 +42,7 @@ to create at most X networks, and permit tenant B to create at most Y networks. If quotas per tenant is needed, you must enable the Quotas extension. For information, see the OpenStack - Network Administration Guide. + Cloud Administrator Guide. diff --git a/v2.0/samples/networks-get-res-prov.json b/v2.0/samples/networks-get-res-prov.json old mode 100644 new mode 100755 index 4e72025..4ae31f2 --- a/v2.0/samples/networks-get-res-prov.json +++ b/v2.0/samples/networks-get-res-prov.json @@ -23,6 +23,6 @@ "provider:network_type": "local", "provider:physical_network": null, "provider:segmentation_id": null - }, + } ] } \ No newline at end of file diff --git a/v2.0/samples/networks-get-res-prov.xml b/v2.0/samples/networks-get-res-prov.xml index a27d98e..8ef476e 100644 --- a/v2.0/samples/networks-get-res-prov.xml +++ b/v2.0/samples/networks-get-res-prov.xml @@ -12,7 +12,8 @@ 3a06dfc7-d239-4aad-9a57-21cd171c72e5 vlan physnet_1 - 101 + 101 ACTIVE @@ -22,8 +23,7 @@ False 7db8c5a4-6eb0-478d-856b-7cfda2b25e13 local - - + + - - + \ No newline at end of file diff --git a/v2.0/samples/networks-get-resp.json b/v2.0/samples/networks-get-resp.json new file mode 100644 index 0000000..0a6582a --- /dev/null +++ b/v2.0/samples/networks-get-resp.json @@ -0,0 +1,37 @@ +{ + "networks":[ + { + "status":"ACTIVE", + "subnets":[ + "a318fcb4-9ff0-4485-b78c-9e6738c21b26" + ], + "name":"private", + "admin_state_up":true, + "tenant_id":"625887121e364204873d362b553ab171", + "id":"9d83c053-b0a4-4682-ae80-c00df269ce0a", + "shared":false + }, + { + "status":"ACTIVE", + "subnets":[ + "aca4d43c-c48c-4a2c-9bb6-ba374ef7e135" + ], + "name":"nova", + "admin_state_up":true, + "tenant_id":"63878e4c5dd649d2a980e37aefddfa87", + "id":"ebda9658-093b-41ba-80ce-0cf8cb8365d4", + "shared":false + }, + { + "status":"ACTIVE", + "subnets":[ + "e12f0c45-46e3-446a-b207-9474b27687a6" + ], + "name":"network_3", + "admin_state_up":true, + "tenant_id":"ed680f49ff714162ab3612d7876ffce5", + "id":"afc75773-640e-403c-9fff-62ba98db1f19", + "shared":true + } + ] +} diff --git a/v2.0/samples/networks-get-resp.xml b/v2.0/samples/networks-get-resp.xml new file mode 100644 index 0000000..70d5df4 --- /dev/null +++ b/v2.0/samples/networks-get-resp.xml @@ -0,0 +1,30 @@ + + + + ACTIVE + + a318fcb4-9ff0-4485-b78c-9e6738c21b26 + + private + True + 625887121e364204873d362b553ab171 + False + False + 9d83c053-b0a4-4682-ae80-c00df269ce0a + + + ACTIVE + + aca4d43c-c48c-4a2c-9bb6-ba374ef7e135 + + nova + True + 63878e4c5dd649d2a980e37aefddfa87 + True + False + ebda9658-093b-41ba-80ce-0cf8cb8365d4 + + diff --git a/v2.0/samples/networks-post-req-prov.json b/v2.0/samples/networks-post-req-prov.json index 373a9e5..1791154 100644 --- a/v2.0/samples/networks-post-req-prov.json +++ b/v2.0/samples/networks-post-req-prov.json @@ -7,5 +7,4 @@ "provider:physical_network": "physnet_1", "provider:segmentation_id": 201 } -} - +} \ No newline at end of file diff --git a/v2.0/samples/networks-post-req-prov.xml b/v2.0/samples/networks-post-req-prov.xml index 7b4aa88..b3e8263 100644 --- a/v2.0/samples/networks-post-req-prov.xml +++ b/v2.0/samples/networks-post-req-prov.xml @@ -1,12 +1,8 @@ - - + + net-name True vlan physnet_1 201 - diff --git a/v2.0/samples/networks-provider-get-resp.xml b/v2.0/samples/networks-provider-get-resp.xml new file mode 100644 index 0000000..6c4f7ae --- /dev/null +++ b/v2.0/samples/networks-provider-get-resp.xml @@ -0,0 +1,37 @@ + + + + ACTIVE + + a318fcb4-9ff0-4485-b78c-9e6738c21b26 + + private + + True + 625887121e364204873d362b553ab171 + local + False + False + 9d83c053-b0a4-4682-ae80-c00df269ce0a + + + + ACTIVE + + aca4d43c-c48c-4a2c-9bb6-ba374ef7e135 + + nova + + True + 63878e4c5dd649d2a980e37aefddfa87 + local + True + False + ebda9658-093b-41ba-80ce-0cf8cb8365d4 + + + diff --git a/v2.0/samples/networks-put-req-prov.xml b/v2.0/samples/networks-put-req-prov.xml index f6b9bc1..39dc770 100644 --- a/v2.0/samples/networks-put-req-prov.xml +++ b/v2.0/samples/networks-put-req-prov.xml @@ -12,4 +12,3 @@ Accept: application/xml physnet_1 - diff --git a/v2.0/samples/networks-show-res-prov.xml b/v2.0/samples/networks-show-res-prov.xml index 91560bb..c37950e 100644 --- a/v2.0/samples/networks-show-res-prov.xml +++ b/v2.0/samples/networks-show-res-prov.xml @@ -11,6 +11,6 @@ 3a06dfc7-d239-4aad-9a57-21cd171c72e5 vlan physnet_1 - 101 + 101 - diff --git a/v2.0/samples/ports-get-res-prov.json b/v2.0/samples/ports-get-res-prov.json new file mode 100644 index 0000000..4e72025 --- /dev/null +++ b/v2.0/samples/ports-get-res-prov.json @@ -0,0 +1,28 @@ +{ + "networks": [ + { + "status": "ACTIVE", + "subnets": [], + "name": "network-1", + "admin_state_up": true, + "tenant_id": "c1210485b2424d48804aad5d39c61b8f", + "id": "3a06dfc7-d239-4aad-9a57-21cd171c72e5", + "shared": false, + "provider:network_type": "vlan", + "provider:physical_network": "physnet_1", + "provider:segmentation_id": 101 + }, + { + "status": "ACTIVE", + "subnets": [], + "name": "network-2", + "admin_state_up": true, + "tenant_id": "c1210485b2424d48804aad5d39c61b8f", + "id": "7db8c5a4-6eb0-478d-856b-7cfda2b25e13", + "shared": false, + "provider:network_type": "local", + "provider:physical_network": null, + "provider:segmentation_id": null + }, + ] +} \ No newline at end of file diff --git a/v2.0/samples/ports-get-res-prov.xml b/v2.0/samples/ports-get-res-prov.xml new file mode 100644 index 0000000..a27d98e --- /dev/null +++ b/v2.0/samples/ports-get-res-prov.xml @@ -0,0 +1,29 @@ + + + + ACTIVE + network-1 + True + c1210485b2424d48804aad5d39c61b8f + False + 3a06dfc7-d239-4aad-9a57-21cd171c72e5 + vlan + physnet_1 + 101 + + + ACTIVE + network-2 + True + c1210485b2424d48804aad5d39c61b8f + False + 7db8c5a4-6eb0-478d-856b-7cfda2b25e13 + local + + + + + diff --git a/v2.0/samples/ports-post-req-prov.json b/v2.0/samples/ports-post-req-prov.json new file mode 100644 index 0000000..373a9e5 --- /dev/null +++ b/v2.0/samples/ports-post-req-prov.json @@ -0,0 +1,11 @@ +{ + "network": + { + "name": "net-name", + "admin_state_up": true, + "provider:network_type": "vlan", + "provider:physical_network": "physnet_1", + "provider:segmentation_id": 201 + } +} + diff --git a/v2.0/samples/ports-post-req-prov.xml b/v2.0/samples/ports-post-req-prov.xml new file mode 100644 index 0000000..7b4aa88 --- /dev/null +++ b/v2.0/samples/ports-post-req-prov.xml @@ -0,0 +1,12 @@ + + + net-name + True + vlan + physnet_1 + 201 + + diff --git a/v2.0/samples/ports-put-req-prov.json b/v2.0/samples/ports-put-req-prov.json new file mode 100644 index 0000000..fea2df7 --- /dev/null +++ b/v2.0/samples/ports-put-req-prov.json @@ -0,0 +1,13 @@ +PUT /v2.0/networks/3a06dfc7-d239-4aad-9a57-21cd171c72e5.json + +Content-Type: application/json +Accept: application/json + +{ + "network": + { + "provider:network_type": "flat", + "provider:physical_network": "physnet_1", + "provider:segmentation_id": null + } +} \ No newline at end of file diff --git a/v2.0/samples/ports-put-req-prov.xml b/v2.0/samples/ports-put-req-prov.xml new file mode 100644 index 0000000..f6b9bc1 --- /dev/null +++ b/v2.0/samples/ports-put-req-prov.xml @@ -0,0 +1,15 @@ +PUT /v2.0/networks/3a06dfc7-d239-4aad-9a57-21cd171c72e5.xml + +Content-Type: application/xml +Accept: application/xml + + + + flat + physnet_1 + + + diff --git a/v2.0/samples/ports-show-res-prov.json b/v2.0/samples/ports-show-res-prov.json new file mode 100644 index 0000000..b8b45f1 --- /dev/null +++ b/v2.0/samples/ports-show-res-prov.json @@ -0,0 +1,15 @@ +{ + "network": + { + "status": "ACTIVE", + "subnets": [], + "name": "network-1", + "admin_state_up": true, + "tenant_id": "c1210485b2424d48804aad5d39c61b8f", + "id": "3a06dfc7-d239-4aad-9a57-21cd171c72e5", + "shared": false, + "provider:network_type": "vlan", + "provider:physical_network": "physnet_1", + "provider:segmentation_id": 101 + } +} \ No newline at end of file diff --git a/v2.0/samples/ports-show-res-prov.xml b/v2.0/samples/ports-show-res-prov.xml new file mode 100644 index 0000000..91560bb --- /dev/null +++ b/v2.0/samples/ports-show-res-prov.xml @@ -0,0 +1,16 @@ + + + ACTIVE + network-1 + True + c1210485b2424d48804aad5d39c61b8f + False + 3a06dfc7-d239-4aad-9a57-21cd171c72e5 + vlan + physnet_1 + 101 + + diff --git a/v2.0/section_binding_ext_ports.xml b/v2.0/section_binding_ext_ports.xml new file mode 100644 index 0000000..1bf6532 --- /dev/null +++ b/v2.0/section_binding_ext_ports.xml @@ -0,0 +1,467 @@ + + + + + + + + + GET'> + PUT'> + POST'> + DELETE'> + + + + + + + + + '> + + + + + + + + + '> + +]> +
+ The <literal>binding</literal> Extended Attributes for + Ports + Use the &APIv2; with the binding + extended attributes to get information about, create, and + update port objects. + The binding-prefixed extended + attributes for ports are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
binding Extended Attributes + for Ports
Attribute Type Required CRUD + + + C. Use the attribute in + create operations. + + + R. This attribute is + returned in response to show and + list operations. + + + U. You can update the + value of this attribute. + + + D. You can delete the + value of this attribute. + + + Default ValueValidation ConstraintsNotes
binding:vif_typeStringN/ARNoneN/ARead-only. The vif type for the specified + port. +
+ binding:host_iduuid-strN/ACRUNoneN/AThe ID of the host where the port is + allocated. In some cases different + implementations can run on different + hosts. +
+ binding:profilelist(dict)N/ACRUNoneN/AA dictionary that enables the application + running on the specified host to pass and + receive vif port-specific information to the + plug-in. +
+ binding:capabilitieslist(dict)N/ARNoneN/ARead-only. A dictionary that enables the + application to pass information about + functions that &APIv2; provides. Specify the + following value: port_filter : Boolean to + define whether &APIv2; provides port filtering + features such as security group and + anti-MAC/IP spoofing.
+
+ List Ports + + + + + + + Verb + URI + Description + + + + + &GET; + /ports + Lists ports to which the tenant has access. + The binding extended + attributes are visible to only administrative + users. + + + + Normal Response Code: 200 + + Error Response Codes: Unauthorized + (401) + This operation lists ports to which the tenant has + access. + This operation does not require a request body. + This operation returns a response body. + In addition to any other fields returned in response, the following + binding-prefixed fields are + visible to administrative users: + + + + Field + Description + + + + + binding:vif_type + + Read-only. The vif type for the + specified port. + + + + + binding:host_id + The ID of the host where the port is + allocated. In some cases different + implementations can run on different + hosts. + + + + + binding:profile + A dictionary that enables the + application running on the specified host + to pass and receive vif port-specific + information to the plug-in. + + + + + binding:capabilities + Read-only. A dictionary that enables the + application to pass information about + functions that &APIv2; provides. Specify + the following value: port_filter : Boolean + to define whether &APIv2; provides port + filtering features such as security group + and anti-MAC/IP spoofing. + + + + +
+ +
+ Show Port + + + + + + + Verb + URI + Description + + + + + &GET; + /ports/port-id + Shows information for a specified port. The + binding extended + attributes are visible to only administrative + users. + + + + Normal Response Code: 200 + + Error Response Codes: Unauthorized + (401), Not Found + (404) + This operation returns information for the port + specified in the request URI. + This operation does not require a request body. + This operation returns a response body. + In addition to any fields returned in the response, the following + binding-prefixed extended + attributes are visible to administrative users: + + + + Field + Description + + + + + binding:vif_type + + Read-only. The vif type for the + specified port. + + + + + binding:host_id + The ID of the host where the port is + allocated. In some cases different + implementations can run on different + hosts. + + + + + binding:profile + A dictionary that enables the + application running on the specified host + to pass and receive vif port-specific + information to the plug-in. + + + + + binding:capabilities + Read-only. A dictionary that enables the + application to pass information about + functions that &APIv2; provides. Specify + the following value: port_filter : Boolean + to define whether &APIv2; provides port + filtering features such as security group + and anti-MAC/IP spoofing. + + + + +
+ +
+ Create Port + + + + + + + Verb + URI + Description + + + + + &POST; + /ports + Creates a port on a specified network. Only + administrative users can add the + binding extended + attributes. + + + + Normal Response Code: 201 + + Error Response Codes: Bad Request + (400), Unauthorized + (401), Forbidden + (403), Not Found + (404), Conflict + (409), MAC generation failure + (503) + This operation creates an OpenStack Networking port. You + must specify the network where the port is to created on + the network_id attribute in the + request body. + This operation requires a request body. + This operation returns a response body. + In addition to any attributes that can be set in a operation, administrative + users can also set the following + binding-prefixed extended + attributes: + + + + Field + Description + + + + + + binding:host_id + The ID of the host where the port is + allocated. In some cases different + implementations can run on different + hosts. + + + + + binding:profile + A dictionary that enables the + application running on the specified host + to pass and receive vif port-specific + information to the plug-in. + + + + +
+
+ Update Port + + + + + + + Verb + URI + Description + + + + + &PUT; + /ports/port-id + Updates a specified port. Only administrative + users can update the + binding extended + attributes. + + + + Normal Response Code: 200 + + Error Response Codes: Bad Request + (400), Unauthorized + (401), Forbidden + (403), Not Found + (404), Conflict + (409) + Use this operation to update information for a + port. + This operation requires a request body. + This operation returns a response body. + In addition to any attributes that can be updated in + operation, + administrative users can also update the following + binding-prefixed extended + attributes: + + + + Field + Description + + + + + + binding:host_id + The ID of the host where the port is + allocated. In some cases different + implementations can run on different + hosts. + + + + + binding:profile + A dictionary that enables the + application running on the specified host + to pass and receive vif port-specific + information to the plug-in. + + + + +
+
diff --git a/v2.0/section_provider_ext_networks.xml b/v2.0/section_provider_ext_networks.xml new file mode 100644 index 0000000..d491cd6 --- /dev/null +++ b/v2.0/section_provider_ext_networks.xml @@ -0,0 +1,288 @@ + + + + + + + + + GET'> + PUT'> + POST'> + DELETE'> + + + + + + + + + '> + + + + + + + + + '> + +]> +
+ Network API Operations + Use the &APIv2; with the provider + extended attributes to get information about, create, and + update networks. + The provider-prefixed extended + attributes for networks are: + + + + + + + + + + + + + + + + + + + + + + + + +
provider Extended Attributes + for Networks
AttributeDescription
provider:network_typeThe type of physical network that maps to + this networks resource. Examples are + flat, + vlan, vxlan, local, and + gre.
+ provider:physical_networkThe physical network on which this network + object is implemented. The &APIv2; does not + provide a way to list available physical + networks. For example, the Open vSwitch + plug-in configuration file defines a symbolic + name that maps to specific bridges on each + Compute host.
+ provider:segmentation_idAn isolated segment on the physical network. + The network_type attribute + defines the segmentation model. For example, + if network_type is + vlan, this ID is a + vlan identifier. If + network_type is + gre, this ID is a + gre key.
+
+ List Networks + + + + + + + + Verb + URI + Description + + + + + &GET; + /networks + Lists networks. The + provider + extended attributes are visible to only + administrative users. + + + + + Normal Response Code: 200 OK + Error Response Codes: 401 Unauthorized + This operation lists network attributes including + provider extended attributes. + The provider extended attributes + are visible to only administrative users. + + List Networks with provider extended attributes: + JSON Response + + + + List Networks with provider extended attributes: + XML Response + + +
+
+ Show Network + + + + + + + + Verb + URI + Description + + + + + &GET; + /networks/network_id + Shows information for a specified network. + The provider + extended attributes are visible to only + administrative users. + + + + + Normal Response Code: 200 OK + Error Response Code: 401 Unauthorized, 404 Not + Found + This operation shows information for a specified + network. The provider extended + attributes are visible to only administrative + users. + + Show Network with provider extended attributes: + JSON Response + + + + Show Network with provider extended attributes: XML + Response + + +
+
+ Create Network + + + + + + + + Verb + URI + Description + + + + + &POST; + /networks + Creates a network. Only administrative + users can add the + provider + extended attributes. + + + + + Normal Response Code: 200 OK + Error Response Code: 400 Bad Request, 401 Unauthorized, + 403 Forbidden + This operation enables administrative users to create a + network and define how it is mapped on the underlying + network infrastructure. + If the user submitting the request is not allowed to set + provider networks attributes, a 403 Forbidden response is + returned. + As stated earlier in this chapter, the semantics of the + various provider networks attribute vary with the + particular plug-in employed. The following example shows + how to create a network mapped to a specific vlan tag (the + example refers to an OpenStack Networking deployment which + uses the Open vSwitch plug-in). + + Create Network with provider extended attributes: + JSON Request + + + + Create Network with provider extended attributes: + XML Request + + +
+
+ Update Network + + + + + + + + Verb + URI + Description + + + + + &PUT; + /networks/network_id + Updates a network. Only administrative + users can update the + provider + extended attributes. + + + + + Normal Response Code: 200 OK + Error Response Code: 400 Bad Request, 401 Unauthorized, + 404 Not Found, 403 Forbidden + When the provider networks extension is enabled, and the + user submitting the request is authorized to see provider + networks mapping, this operation allows for specifying how + an existing network should be mapped on the underlying + network infrastructure. + If the user submitting the request is not allowed to set + provider networks attributes, a 403 Forbidden response is + returned. + As stated earlier in this chapter, the semantics of the + various provider networks attribute vary with the + particular plug-in employed. The following example shows + how to update a network to map it to a flat network (such + as, the no vlan tag); the example refers to an OpenStack + Networking deployment that uses the Open vSwitch + plug-in. + + Update Network with provider extended attributes: + JSON Request + + + + Update Network with provider extended attributes: + XML Request + + +
+
diff --git a/v2.0/section_provider_extended_attrs.xml b/v2.0/section_provider_extended_attrs.xml new file mode 100644 index 0000000..e8e6c7a --- /dev/null +++ b/v2.0/section_provider_extended_attrs.xml @@ -0,0 +1,58 @@ + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + + '> + + + + + '> + +]> +
+ The <literal>provider</literal> Extended Attributes for + Networks + The provider extended attributes for + networks enables administrative users to specify how network + objects map to the underlying networking infrastructure. These + extended attributes also appear when administrative users + query networks. + The technology back end of the particular plug-in determines + the semantics of these attributes. To understand which values + to specify for each attribute when you deploy &APIv2; with a + particular plug-in, see the plug-in documentation and the + OpenStack Cloud Administrator + Guide. The following examples use the Open vSwitch + plug-in. + + The default policy settings enable only administrative + users to specify and view these attributes. If you cannot + see these attributes in a &GET; + /networks/<network-id> operation, + you do not have administrative privileges. + + +