Uplink network spec

Write the spec for the MidoNet plugin implementation of the
provider network Neutron extension and modification to the
port binding extension API to integrate the uplink network
configuration of MidoNet in Neutron.

Change-Id: I3423d981f0cdaeff98c0ec22043be94ee8a2e39e
Fixes: MNP-72

specs/kilo/provider_net.rst

@@ -0,0 +1,136 @@
+..
+ This work is licensed under a Creative Commons Attribution 4.0 International
+ License.
+
+ http://creativecommons.org/licenses/by/4.0/
+
+
+==================
+Uplink Network API
+==================
+
+MidoNet plugin implements the provider network Neutron extension API, and makes
+slight modification to the port binding extension API implementation to
+simplify the uplink port configuration of the edge routers.
+
+
+Problem Description
+===================
+
+The edge routers are virtual routers that interface with the uplink routers
+outside of the cloud.  Thus, the ports on these virtual routers must be bound
+to the interfaces on the edge hosts of the MidoNet deployment.  The MidoNet
+Neutron Plugin, however, does not offer any API to create a port on the edge
+router.  Furthermore, Neutron requires that all ports are created on a network,
+so the concept of having a port directly on a router must be emulated using
+the Neutron constructs.
+
+
+Proposed Change
+===============
+
+Because Neutron does not allow creation of a port directly on a router, a
+network must be created for any port to exist.  This network must be flagged as
+a special network to indicate that it is an 'uplink' network so that MidoNet
+would know that the ports on this network need be treated as router ports bound
+directly on the physical hosts (as opposed to normal network ports).  Normal
+networks cannot be used for this purpose because in the future MidoNet will
+support binding of ports on any network, which must be differentiated from
+binding ports on the edge router.
+
+To mark these networks as uplink networks, implement the "provider network"
+Neutron extension API to map virtual networks to the uplink networks in the
+underlay.  Once a virtual network is mapped to a physical network, you
+could create a port on this network with binding details to control exactly
+which host interface that the port should be bound to.
+
+The 'provider network' extension lets you map a physical network to a virtual
+network by associating the virtual network with attributes decribing the
+physical network.  One of the attributes is called 'network_type' which
+could be 'LOCAL', 'FLAT', 'VXLAN', 'VLAN' and 'GRE'.  For the purpose of uplink
+network mapping, only the 'LOCAL' network type is accepted by the plugin
+because it requires the least amount of extra configurations.  To create an
+uplink network, only 'network_type' needs to be specified.
+
+MidoNet currently does not support binding a vlan tagged interface, so the
+'VLAN' type cannot be used, but it will be supported in the future.  Likewise,
+GRE and VXLAN are not currently supported for binding.
+
+The uplink set up workflow is as follows:
+
+ 1. The operator creates a Neutron network mapped to each uplink physical
+    network.  The following field should be set for the network to create:
+
+        * "provider:network_type" => Type of the uplink network.  Only 'LOCAL'
+                                     type is accepted.
+
+ 2. On these networks, create a port for each interface on the host nodes that
+    are connected to the uplink networks.  Supply these additional binding
+    details for each port created as follows:
+
+        * "binding:host_id" => ID of the host to bind the port on
+        * "binding:profile['if_name']" => Name of the interface to bind to
+
+    The host IDs and interface names can be fetched from the 'agents' extension
+    API.
+
+ 3. For each uplink network port created, execute 'router interface add'
+    standard Neutron API to connect the uplink network and the edge router.
+    This triggers the binding of the port to the physical interface.  The
+    detail of how the binding is achieved is outside of this document's scope.
+
+There are no changes required in the REST API, DB models or client since only
+the standard Neutron extension API is invoked.  Please refer to the provider
+network extension API document[1] for more details on the workflow.
+
+
+Database
+--------
+
+The only visible change is that the network and port tasks contain new fields:
+
+Network:
+
+::
+    "provider:network_type": "LOCAL"
+
+Port:
+
+::
+    "binding:host_id": "HOST_ID",
+    "binding:profile": {"if_name": "eth0"}
+
+
+Plugin
+------
+
+The 'provider' extension alias is added to the MidoNet plugin.  When looking
+up a network, the provider extension attributes must be added to the network
+API request and response.
+
+Also, although the plugin already supported 'binding' extension API, the
+binding does not include, 'binding:host_id' and 'binding:profile', that are
+added to the port API request and response.
+
+
+Documentation
+-------------
+
+The setup of the uplink networks must be described in the Deployment Guide
+and/or the Operational Guide.
+
+
+Alternative Proposal
+====================
+
+Instead of using the provider network extension to specify the binding
+information for the edge hosts, store the binding information in the MidoNet
+agent configuration.  The reason for choosing the proposed approach is that
+there was no concrete design agreed by all stakeholders on the agent
+configuration approach.
+
+
+References
+==========
+
+[1] http://docs.openstack.org/admin-guide-cloud/content/provider_api_workflow.html