Working on comments and document cleanup

Commenting out some of my previous comments so that they are not
part of the final document but remain in the source code. Added
conclusion to L3VPN use cases.

Change-Id: I1f51cbce1fb496d05d005cfd440cc16a52eab0d8
Signed-off-by: Georg Kunz <georg.kunz@ericsson.com>

9 files changed, 56 insertions, 90 deletions

diff --git a/docs/requirements/use_cases/georedundancy.rst b/docs/requirements/use_cases/georedundancy.rst
index f5d4de9..d168206 100644
--- a/docs/requirements/use_cases/georedundancy.rst
+++ b/docs/requirements/use_cases/georedundancy.rst
@@ -10,17 +10,17 @@ It is possible that the VNF application layer provides additional redundancy
 with VNF pooling on top of the georedundancy functionality described here.
 
 It is possible that either the VNFC-s of a single VNF are spread across several
-datacenters (this case is covered by the OPNFV multisite project [MULTISITE]_
+datacenters (this case is covered by the OPNFV multi-site project [MULTISITE]_
 or different, redundant VNF-s are started in different datacenters.
 
 When the different VNF-s are started in different datacenters the redundancy
 can be achieved by redundant VNF-s in a hot (spare VNF is running its
-configuration and internal state is synchronised to the active VNF),
-warm (spare VNF is running, its configuration is synchronised to the active VNF)
+configuration and internal state is synchronized to the active VNF),
+warm (spare VNF is running, its configuration is synchronized to the active VNF)
 or cold (spare VNF is not running, active VNF-s configuration is stored in a
 persistent, central store and configured to the spare VNF during its activation)
 standby state in a different datacenter from where the active VNF-s are running.
-The synchronisation and data transfer can be handled by the application or by
+The synchronization and data transfer can be handled by the application or by
 the infrastructure.
 
 In all of these georedundancy setups there is a need for a network connection
@@ -31,10 +31,10 @@ In case of a distributed cloud it is possible that the georedundant cloud of an
 application is not predefined or changed and the change requires configuration
 in the underlay networks when the network operator uses network isolation.
 Isolation of the traffic between the datacenters might be needed due to the
-multitenant usage of NFVI/VIM or due to the IP pool management of the network
+multi-tenant usage of NFVI/VIM or due to the IP pool management of the network
 operator.
 
-This set of georedundancy use cases is about enabling the possiblity to select a
+This set of georedundancy use cases is about enabling the possibility to select a
 datacenter as backup datacenter and build the connectivity between the NFVI-s in
 the different datacenters in a programmable way.
 
@@ -43,7 +43,7 @@ considered how the provisioning of physical resources is handled by the SDN
 controllers to interconnect the two datacenters.
 
 As an example the following picture (:numref:`georedundancy-before`) shows a
-multicell cloud setup where the underlay network is not fully meshed.
+multi-cell cloud setup where the underlay network is not fully meshed.
 
 .. figure:: images/georedundancy-before.png
     :name:  georedundancy-before
@@ -52,7 +52,7 @@ multicell cloud setup where the underlay network is not fully meshed.
 Each datacenter (DC) is a separate OpenStack cell, region or instance. Let's
 assume that a new VNF is started in DC b with a Redundant VNF in DC d. In this
 case a direct underlay network connection is needed between DC b and DC d. The
-configuration of this connection should be programable in both DC b and DC d.
+configuration of this connection should be programmable in both DC b and DC d.
 The result of the deployment is shown in the following figure
 (:numref:`georedundancy-after`):
 
diff --git a/docs/requirements/use_cases/georedundancy_cells.rst b/docs/requirements/use_cases/georedundancy_cells.rst
index c71d2de..36964ac 100644
--- a/docs/requirements/use_cases/georedundancy_cells.rst
+++ b/docs/requirements/use_cases/georedundancy_cells.rst
@@ -15,12 +15,12 @@ problem between the main cell and the sub cells.
 
 The functionality behind the API depends on the underlying network providers (SDN
 controllers) and the networking setup.
-(For example OpenDaylight has an API to add new BGP neighbour.)
+(For example OpenDaylight has an API to add new BGP neighbor.)
 
 OpenStack Neutron should provide an abstracted API for this functionality what
 calls the underlying SDN controllers API.
 
-Derrived Requirements
+Derived Requirements
 ~~~~~~~~~~~~~~~~~~~~~
    - Possibility to define a remote and a local endpoint
    - As in case of cells the nova-api service is shared it should be possible
diff --git a/docs/requirements/use_cases/georedundancy_regions_insances.rst b/docs/requirements/use_cases/georedundancy_regions_insances.rst
index dfbfb7d..27eae65 100644
--- a/docs/requirements/use_cases/georedundancy_regions_insances.rst
+++ b/docs/requirements/use_cases/georedundancy_regions_insances.rst
@@ -11,12 +11,12 @@ OpenStack regions or instances.
 
 The functionality behind the API depends on the underlying network providers (SDN
 controllers) and the networking setup.
-(For example OpenDaylight has an API to add new BGP neighbour.)
+(For example OpenDaylight has an API to add new BGP neighbor.)
 
 OpenStack Neutron should provide an abstracted API for this functionality what
 calls the underlying SDN controllers API.
 
-Derrived Requirements
+Derived Requirements
 ~~~~~~~~~~~~~~~~~~~~~
 - Possibility to define a remote and a local endpoint
 - As in case of cells the nova-api service is shared it should be possible
diff --git a/docs/requirements/use_cases/l3vpn.rst b/docs/requirements/use_cases/l3vpn.rst
index b1ee030..c2da424 100644
--- a/docs/requirements/use_cases/l3vpn.rst
+++ b/docs/requirements/use_cases/l3vpn.rst
@@ -14,5 +14,16 @@ L3VPN Use Cases
 Conclusion
 ----------
 
-[**Georg: add conclusion here, covering the identified gaps of the three use
-cases above**]
+Based on the gap analyses of the three specific L3VPN use cases we conclude that
+there are gaps in both the functionality provided by the BGPVPN project as well
+as the support for multiple backends in Neutron.
+
+Some of the identified gaps [L3VPN-ECMP-GAP1, L3VPN-ECMP-GAP2, L3VPN-HS-GAP3]
+in the BGPVPN project are merely missing functionality which can be integrated
+in the existing OpenStack networking architecture.
+
+Other gaps, such as the inability to explicitly disable the layer 2 semantics of
+Neutron networks [L3VPN-HS-GAP1] or the tight integration of ports and networks
+[L3VPN-HS-GAP2] hinder a clean integration of the needed functionality. In order
+to close these gaps, fundamental changes in Neutron or alternative approaches
+need to be investigated.
diff --git a/docs/requirements/use_cases/l3vpn_any_to_any.rst b/docs/requirements/use_cases/l3vpn_any_to_any.rst
index b11a381..574eac6 100644
--- a/docs/requirements/use_cases/l3vpn_any_to_any.rst
+++ b/docs/requirements/use_cases/l3vpn_any_to_any.rst
@@ -55,13 +55,13 @@ subnet 10.1.1.0/24.
 
 
 
-Derrived Requirements
+Derived Requirements
 ~~~~~~~~~~~~~~~~~~~~~
 
 Northbound API / Workflow
 +++++++++++++++++++++++++
 
-[**Georg: this section needs to be made more readable**]
+.. **Georg: this section needs to be made more readable**
 
 An example of the desired workflow is as follows:
 
@@ -87,21 +87,6 @@ An example of the desired workflow is as follows:
 
 
 
-Data model objects
-++++++++++++++++++
-   - TBD
-
-
-Orchestration
-+++++++++++++
-   - TBD
-
-
-Dependencies on compute services
-++++++++++++++++++++++++++++++++
-   - TBD
-
-
 
 Current implementation
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -181,16 +166,18 @@ Comments:
 
 * The ports are associated indirectly to the VPN through their networks.
 
-* The BGPVPN backend takes care of distributing the /32 routes to the OVR instances
-  and assigning appropriate RD values.
+* The BGPVPN backend takes care of distributing the /32 routes to the vForwarder
+  instances and assigning appropriate RD values.
 
 
 
 Gaps in the current solution
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are no gaps in the currently available solution which prevent realizing
-this particular use case.
-[**Georg: there are no gaps in terms of functionality provided by the BGPVPN
-project. However, a better analysis of the multi-backend support in Neutron is
-needed**]
+In terms of the functionality provided by the BGPVPN project, there are no gaps
+preventing this particular use case from a L3VPN perspective.
+
+However, in order to support the multi-vendor aspects of this use case, a better
+support for integrating multiple backends is needed (see previous use case).
+
+
diff --git a/docs/requirements/use_cases/l3vpn_ecmp.rst b/docs/requirements/use_cases/l3vpn_ecmp.rst
index da96cfb..b3d5b63 100644
--- a/docs/requirements/use_cases/l3vpn_ecmp.rst
+++ b/docs/requirements/use_cases/l3vpn_ecmp.rst
@@ -35,29 +35,6 @@ Here, the Network VRF Policy Resource is ``ECMP/AnyCast``. Traffic to **Anycast
 can be load split from either WAN GW or another VM like G5.
 
 
-Derived Requirements
-~~~~~~~~~~~~~~~~~~~~~
-
-Northbound API / Workflow
-+++++++++++++++++++++++++
-   - TBD
-
-
-Data model objects
-++++++++++++++++++
-   - TBD
-
-
-Orchestration
-+++++++++++++
-   - TBD
-
-
-Dependencies on compute services
-++++++++++++++++++++++++++++++++
-   - TBD
-
-
 
 Current implementation
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -90,7 +67,7 @@ ECMP load balancing. This behavior and the corresponding API for configuring the
 behavior is currently not available. It is nevertheless on the road map of the
 BGPVPN project.
 
-**[ Georg: we could add an API usage example here similarly to the one below]**
+.. **Georg: we could add an API usage example here similarly to the one below**
 
 
 Static Routes to ports with unique IP addresses
diff --git a/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst b/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst
index a000046..07004ef 100644
--- a/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst
+++ b/docs/requirements/use_cases/l3vpn_hub_and_spoke.rst
@@ -19,8 +19,8 @@ Furthermore, there is no layer 2 connectivity between the VNFs.
 
 In addition, in this use case, the deployed network infrastructure comprises
 equipment from two different vendors, Vendor A and Vendor B. There are 2 hosts
-(compute nodes). SDN Controller A and vRouter A are provided by Vendor A, and
-run on host A. SDN Controller B and vRouter B are provided by Vendor B, and run
+(compute nodes). SDN Controller A and vForwarder A are provided by Vendor A, and
+run on host A. SDN Controller B and vForwarder B are provided by Vendor B, and run
 on host B.
 
 There is 1 tenant. Tenant 1 creates L3VPN Blue with 2 subnets: 10.1.1.0/24 and 10.3.7.0/24.
@@ -44,21 +44,21 @@ Derived Requirements
 Northbound API / Workflow
 +++++++++++++++++++++++++
 
-[**Georg: this needs to be made more readable / explanatory**]
+.. Georg: this needs to be made more readable / explanatory
 
 Exemplary vFW(H) Hub VRF is as follows:
 
-* RD1 10.1.1.5  IP_OVR1 Label1
-* RD1 0/0 IP_OVR1 Label1
+* RD1 10.1.1.5  IP_vForwarder1 Label1
+* RD1 0/0 IP_vForwarder1 Label1
 * Label 1 Local IF (10.1.1.5)
-* RD3 10.3.7.9  IP_OVR1 Label2
-* RD2 10.1.1.6  IP_OVR2 Label3
-* RD4 10.3.7.10 IP_OVR2 Label3
+* RD3 10.3.7.9  IP_vForwarder1 Label2
+* RD2 10.1.1.6  IP_vForwarder2 Label3
+* RD4 10.3.7.10 IP_vForwarder2 Label3
 
 Exemplary VNF1(S) Spoke VRF is as follows:
 
-* RD1 0/0 IP_OVR1 Label1
-* RD3 10.3.7.9  IP_OVR1 Label2
+* RD1 0/0 IP_vForwarder1 Label1
+* RD3 10.3.7.9  IP_vForwarder1 Label2
 
 Exemplary workflow is described as follows:
 
@@ -77,10 +77,6 @@ Exemplary workflow is described as follows:
   4.2. VRF Policy Resource, [H | S]
 
 
-Data model objects
-++++++++++++++++++
-   - TBD
-
 
 Current implementation
 ++++++++++++++++++++++
@@ -95,16 +91,10 @@ BGPVPN
 ''''''
 
 Support for creating and managing L3VPNs is in general available in OpenStack
-Neutron by means of the BGPVPN API [BGPVPN]_. However, the [BGPVPN]_ API
-does not support creating the Hub-and-Spoke topology as outlined above, i.e.
-setting up specific VRFs of vFW(H) and other VNFs(S) within one L3VPN to direct
-the traffic from vFW(H) to VNFs(S).
-[**Georg: I'd like to move the last statement further down as this is already a
-conclusion without having done any kind of analysis.**]
-
-The [BGPVPN]_ API currently supports the concepts of network- and
-router-associations. An association maps Neutron network objects (networks and
-routers) to a VRF with the following semantics:
+Neutron by means of the BGPVPN API [BGPVPN]_.  The [BGPVPN]_ API currently
+supports the concepts of network- and router-associations. An association maps
+Neutron network objects (networks and routers) to a VRF with the following
+semantics:
 
 * A *network association* interconnects all subnets and ports of a Neutron
   network by binding them to a given VRF
@@ -205,7 +195,8 @@ or not the service chain from vFW(H) to VNFs(S) can be created in the way of L3V
 VRF policy approach using [NETWORKING-SFC]_ API.
 
 Hence, it is currently not possible to configure the networking use case as described above.
-**Georg: we need to look deeper into SFC to substantiate our claim here.**
+
+.. **Georg: we need to look deeper into SFC to substantiate our claim here.**
 
 
 Gaps in the Current Solution
diff --git a/docs/requirements/use_cases/programmable_provisioning.rst b/docs/requirements/use_cases/programmable_provisioning.rst
index de45ca3..8d143f3 100644
--- a/docs/requirements/use_cases/programmable_provisioning.rst
+++ b/docs/requirements/use_cases/programmable_provisioning.rst
@@ -7,13 +7,13 @@ Description
 ~~~~~~~~~~~
 In NFV environment the VNFM (consumer of OpenStack IaaS API) have no
 administrative rights, however in the telco domain provider networks are used in
-some cases. When a provider network is ceated administrative rights are needed
+some cases. When a provider network is created administrative rights are needed
 what in the case of a VNFM without administrative rights needs manual work.
 It shall be possible to configure provider networks without administrative rights.
 It should be possible to assign the capability to create provider networks to
 any roles.
 
-Derrived Requirements
+Derived Requirements
 ~~~~~~~~~~~~~~~~~~~~~
    - Authorize the possibility of provider network creation based on policy
    - There should be a new entry in :code:`policy.json` which controls the provider network creation
diff --git a/docs/requirements/use_cases/service-binding-pattern.rst b/docs/requirements/use_cases/service-binding-pattern.rst
index 5b288bd..a5088a3 100644
--- a/docs/requirements/use_cases/service-binding-pattern.rst
+++ b/docs/requirements/use_cases/service-binding-pattern.rst
@@ -63,7 +63,7 @@ L3VPN service. Hence, there would be no entity "service" but rather "L3VPN".
   instance by the compute service (Nova).
 
   *Attributes:* Since an instance-port is a layer 2 device, its attributes
-  include the MAC address, MTU and others (TBD).
+  include the MAC address, MTU and others.
 
 
 * ``interface``