GET'> PUT'> POST'> DELETE'> '> '> ]>

The provider networks extension allows OpenStack Networking API users with the appropriate rights, to specify how an OpenStack Networking network object is mapped to the underlying networking infrastructure. It also allows users with the appropriate rights to view such attributes when networks are queried. To this aim, it extends the network resource by defining a set of attributes prefixed with the provider prefix, which specify these attributes.

The provider networks extension is an attribute extension which adds the following set of attributes to the network resource: provider:network_type - Specifies the nature of the physical network mapped to this network resource. Examples are flat, vlan, or gre. provider:physical_network - Identifies 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 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 an isolated segment on the physical network; the nature of the segment depends on the segmentation model defined by network_type. For instance, if network_type is vlan, then this is a vlan identifier; otherwise, if network_type is gre, then this will be a gre key. 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 hidden from regular tenants. As a rule of thumb, if these attributes are not visible in a GET /networks/<network-id> operation, this implies the user submitting the request is not authorized to view or manipulate provider network attributes.

This section discusses operations for setting and retrieving the provider networks extension attributes for network objects.

Verb URI Description &GET; /networks Returns a list of networks with their provider networks attributes. Normal Response Code: 200 OK Error Response Codes: 401 Unauthorized This operation returns, for each network, its provider network attributes as well as all the attributes normally returned by the list networks operation. Provider networks attribute are returned only if the user is authorized to view them.

Verb URI Description &GET; /networks/network_id Returns details about a specific network, including provider networks attributes. Normal Response Code: 200 OK Error Response Code: 401 Unauthorized, 404 Not Found When the provider networks extension is enabled, and the user submitting the request is authorized to see provider networks mapping, this operation returns, for the network specified in the request URI, its provider network attributes, as well as all the attributes normally retuned by the show networks operation.

Verb URI Description &POST; /networks Creates a new network and explicitly specify attributes with the underlying infrastructure using the provider network extension attributes. Normal Response Code: 200 OK Error Response Code: 400 Bad Request, 401 Unauthorized, 403 Forbidden When the provider networks extension is enabled, and the user submitting the request is authorized to set provider networks mapping, this operation allows for specifying how a new 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 will be 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).

Verb URI Description &PUT; /networks/network_id Updates a network, including its mapping with the underlying infrastructure using the provider network extension 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 will be 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 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.