Networking-vpp/L3 routing support

= Overview = This page describes the L3 functionality that will be added to networking-vpp. It is not currently available functionality. It will also describe what the team plans to deliver with respect to code, test, documentation and any other deliverables. This project will add code to networking-vpp repository to enable L3 support when the networking-vpp driver is used in conjunction with an vpp based vswitch in an openstack installation. For this work centralized router (not-dvr) based approach will be provided. There are numerous documents describing the openstack neutron routing model including:
 * http://docs.openstack.org/developer/neutron/devref/layer3.html
 * https://developer.rackspace.com/blog/neutron-networking-l3-agent/

= Functionality that will be added =
 * Support for Router API operations (http://developer.openstack.org/api-ref/networking/v2/#routers-routers)
 * Support for floating-IP API operations (http://developer.openstack.org/api-ref/networking/v2/#floating-ips-floatingips)
 * Full support for East-West based routing between tenant networks (only via a centralized network node)
 * Floating IP One-to-One NAT support for an instance (http://docs.openstack.org/newton/networking-guide/intro-nat.html)
 * Centralized network or control node approach (provide figure)
 * Internal gateways hosted on VPP
 * External gateways - All traffic from the internal networks on the router are NATed to the router external IP
 * Support for IPv4 and IPV6
 * support for restarts of the agent and/or vpp
 * Evaluate support for the external and internal scopes being the same (IOW NAT is not performed for IPv4).

= Functionality not supported =
 * HA or any VRRP based solutions
 * Distributed Virtual Router topologies (DVR)
 * LISP-GPE (when GPE is better defined we will describe how they interwork)
 * Setting the "enable_snat = FALSE" API network extension has no affect. IOW in the case of IPv4 NAT will always be used when sending/receiving from an external network
 * Any tie in with the dynamic routing or BGPVPN functionality available in Neutron
 * No support for additional static routes (normally available to the user via an API call)

= Limitations =
 * Must be coupled with the networking-vpp mechanism driver
 * The L3 agent should only be run on control or network nodes
 * The L2 agent should be run on all nodes.
 * All testing will be based on Newton release of Openstack.

= What will be delivered =
 * Code merged in to the networking-vpp repository to add the functionality described above
 * Unit tests merged in to the networking-vpp repository to test the code added in step 1
 * Documentation to describe the functionality provided and the usage/installation requirements - via internal wiki
 * A TOI and code walk-through to a responsible person that can continue the work after initial merge.

= Test methodology = The tests included as part of this deliverable is limited to unit tests and a small number of "smoke tests" with a VPP instance installed. Complete functional tests on physical servers in configuration representative of a real deployment is outside of the scope of this deliverable. = Dependencies = This work will have a few dependencies to properly deliver the functionality. The following are the key items.


 * 17.01 based vpp and vpp python library RPMs available for installation
 * Timely code reviews and code merge from the networking-vpp community and core reviewers
 * Support for the necessary L3 functionality from the vpp vswitch/vrouter including:
 * 1) Support for NAT
 * 2) Support for proxy ARP
 * 3) Support for routing
 * 4) Support for an SVI/BVI type interface on an L2 bridge domain.
 * Timely response from the fd.io community for any bugs or issues uncovered while testing.
 * A responsible party that can continue the work after initial merge and guide this through functional testing.
 * For customer release an comprehensive functionality test suite and execution would be required.

= Installation/Usage Instructions =

Packet Flows
East - West Routing

Compute node      ||                      ||       Network Node        ||                           ||   Compute Node

VM1_net1 --- vpp - fabric GW net1 vpp GW net2 - fabric  -- vpp  -- VM2_net2

GW net1 = gateway of network1 installed as a BVI on vpp

GW net2 = gateway of network2 installed as a BVI on vpp

Floating IP (AKA 1-1 NAT)

Compute node      ||                      ||           Network Node              ||

VM1_net1 --- vpp - fabric GW net1 vpp ext IP - external network

GW net1 = gateway of network1 installed as a BVI on vpp

Ext IP = Routers IP address on external subnet install as an L3 subinterface on vpp

vpp will be configured to NAT any packets from VM1 to the assigned floating IP

External gateway (AKA SNAT) configured with neutron router-gateway-set

Compute node      ||                      ||           Network Node              ||

VM1_net1 --- vpp - fabric GW net1 vpp ext GW IP - external network

GW net1 = gateway of network1 installed as a BVI on vpp

Ext GW IP = IP address neutron assigns to port connected to the public subnet

vpp will be configured to NAT all traffic received on the BVI destined to the Internet using the Ext. GW address