SFC design Documents for Brahmaptura release

- Patch set 9  : Addressed Jim Guichard's review comments.
- Patch set 10 : Removed date and revision as its duplicated, according to
                 Chris' review comments.

Change-Id: Idca9696c4b703a3ef93b553fe785449cea0935f0
Signed-off-by: Brady Johnson <brady.allen.johnson@ericsson.com>

11 files changed, 192 insertions, 25 deletions

diff --git a/docs/design/architecture.rst b/docs/design/architecture.rst
index 24be1675..d2a1bb4d 100644
--- a/docs/design/architecture.rst
+++ b/docs/design/architecture.rst
@@ -1,4 +1,126 @@
 Architecture
-============
+------------
+
+This section describes the architectural approach to incorporating the upstream
+OpenDaylight (ODL) SFC project into the OPNFV Brahmaputra platform.
+
+Service Functions
++++++++++++++++++
+
+A Service Function (SF) is a Function that provides services to flows traversing
+a Service Chain. Examples of typical SFs include: Firewall, NAT, QoS, and DPI.
+In the context of OPNFV, the SF will be a Virtual Network Function. The SFs
+receive data packets from a Service Function Forwarder.
+
+Service Function Forwarders
++++++++++++++++++++++++++++
+
+The Service Function Forwarder (SFF) is the core element used in Service
+Chaining. It is an OpenFlow switch that, in the context of OPNFV, is hosted
+in an OVS bridge. In OPNFV there will be one SFF per Compute Node that will
+be hosted in the "br-int" OpenStack OVS bridge.
+
+The responsibility of the SFF is to steer incoming packets to the corresponding
+Service Function, or to the SFF in the next compute node. The flows in the SFF
+are programmed by the OpenDaylight SFC SDN Controller.
+
+Service Chains
+++++++++++++++
+
+Service Chains are defined in the OpenDaylight SFC Controller using the
+following constructs:
+
+SFC
+  A Service Function Chain (SFC) is an ordered list of abstract SF types.
+
+SFP
+  A Service Function Path (SFP) references an SFC, and optionally provides
+  concrete information about the SFC, like concrete SF instances. If SF
+  instances are not supplied, then the RSP will choose them.
+
+RSP
+  A Rendered Service Path (RSP) is the actual Service Chain. An RSP references
+  an SFP, and effectively merges the information from the SFP and SFC to create
+  the Service Chain. If concrete SF details were not provided in the SFP, then
+  SF selection algorithms are used to choose one. When the RSP is created, the
+  OpenFlows will be programmed and written to the SFF(s).
+
+Service Chaining Encapsulation
+++++++++++++++++++++++++++++++
+
+Service Chaining Encapsulation encapsulates traffic sent through the Service
+Chaining domain to facilitate easier steering of packets through Service Chains.
+If no Service Chaining Encapsulation is used, then packets much be classified
+at every hop of the chain, which would be slow and would not scale well.
+
+In ODL SFC, Network Service Headers (NSH) is used for Service Chaining
+encapsulation. NSH is an IETF specification that uses 2 main header
+fields to facilitate packet steering, namely:
+
+NSP (NSH Path)
+  The NSP is the Service Path ID.
+
+NSI (NSH Index)
+  The NSI is the Hop in the Service Chain. The NSI starts at 255 and is
+  decremented by every SF. If the NSI reaches 0, then the packet is dropped
+  which avoids loop detections.
+
+NSH also has metadata fields, but that's beyond the scope of this architecture.
+
+In ODL SFC, NSH packets are encapsulated in VXLAN-GPE.
+
+Classifiers
++++++++++++
+
+A classifier is the entry point into Service Chaining. The role of the
+classifier is to map incoming traffic to Service Chains. In ODL SFC, this
+mapping is performed by matching the packets and encapsulating the packets in
+a VXLAN-GPE NSH tunnel.
+
+The packet matching is specific to the classifier implementation, but can be
+as simple as an ACL, or can be more complex by using PCRF information or DPI.
+
+VNF Manager
++++++++++++
+
+In OPNFV SFC, a VNF Manager is needed to spin-up VMs for Service Functions.
+It has been decided to use the OpenStack Tacker VNF Mgr to spin-up and manage
+the life cylcle of the SFs. Tacker will receive the ODL SFC configuration,
+manage the SF VMs, and forward the configuration to ODL SFC. The following
+sequence diagram details the interactions with the VNF Mgr:
+
+.. image:: ./images/OPNFV_SFC_Brahmaputra_SfCreation.jpg
+
+OPNFV SFC Network Topology
+++++++++++++++++++++++++++
+
+The following image details the Network Topology used in OPNFV Brahmaputra SFC:
+
+.. image:: ./images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg
+
+
+OVS NSH patch workaround
+++++++++++++++++++++++++
+
+When using NSH with VXLAN tunnels, its important that the VXLAN tunnel is
+terminated in the SF VM. This allows the SF to see the NSH header, allowing
+it to decrement the NSI and also to use the NSH metadata. When using VXLAN with
+OpenStack, the tunnels are not terminated in the VM, but in the "br-int" OVS
+bridge. There is work ongoing in the upstream OVS community to implemement NSH
+encapsulation. To get around the way OpenStack handles VXLAN tunnels, the OVS
+work will also include the ability to encapsulate/decapsulate VXLAN tunnels from
+OpenFlow rules, instead of relying on the Vtep ports. The ongoing upstream OVS
+work will probably not be finished by the time OPNFV Brahmaputra is released, so
+a work-around has been created. This work-around will use a private branch of
+OVS that has a preliminary version of NSH implemented.
+
+The following diagram illustrates how packets will be sent to an SF, when the
+SFF has processed the packet and wants to send it to the SF:
+
+.. image:: ./images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg
+
+The following diagram illustrates how packets will sent from an SF to an SFF,
+once the SF has processed a packet:
+
+.. image:: ./images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg
 
-This section will describe the architectural approach to incorporating SFC into the OPNFV platform.
\ No newline at end of file
diff --git a/docs/design/definitions.rst b/docs/design/definitions.rst
index effaf0ec..38263044 100644
--- a/docs/design/definitions.rst
+++ b/docs/design/definitions.rst
@@ -1,20 +1,13 @@
 Definitions
-===========
+-----------
 
-Definitions of most terms used here are provided in the `IETF SFC Architecture draft <https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/>`_. Additional terms specific to the OPNFV SFC project are defined below.
+Definitions of most terms used here are provided in the `IETF SFC Architecture RFC <https://datatracker.ietf.org/doc/rfc7665/>`_.
+Additional terms specific to the OPNFV SFC project are defined below.
 
-.. list-table:: Definitions
-   :widths: 15 85
-   :header-rows: 1
-
-   * - Term
-     - Meaning
-
-   * - ...
-     - ...
 
 Abbreviations
-=============
+-------------
+
 .. list-table:: Abbreviations
    :widths: 15 85
    :header-rows: 1
@@ -31,9 +24,18 @@ Abbreviations
    * - NF
      - Network Function
 
+   * - NSH
+     - Network Services Header (Service chaining encapsulation)
+
+   * - ODL
+     - OpenDaylight SDN Controller
+
    * - RSP
      - Rendered Service Path
 
+   * - SDN
+     - Software Defined Networking
+
    * - SF
      - Service Function
 
diff --git a/docs/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg b/docs/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg
new file mode 100644
index 00000000..1b542888
--- /dev/null
+++ b/docs/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg
diff --git a/docs/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg b/docs/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg
new file mode 100644
index 00000000..11eaf87b
--- /dev/null
+++ b/docs/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg
diff --git a/docs/design/images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg b/docs/design/images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg
new file mode 100644
index 00000000..c183486e
--- /dev/null
+++ b/docs/design/images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg
diff --git a/docs/design/images/OPNFV_SFC_Brahmaputra_SfCreation.jpg b/docs/design/images/OPNFV_SFC_Brahmaputra_SfCreation.jpg
new file mode 100644
index 00000000..345317dd
--- /dev/null
+++ b/docs/design/images/OPNFV_SFC_Brahmaputra_SfCreation.jpg
diff --git a/docs/design/images/OPNFV_SFC_Brahmaputra_UseCase.jpg b/docs/design/images/OPNFV_SFC_Brahmaputra_UseCase.jpg
new file mode 100644
index 00000000..efc0df33
--- /dev/null
+++ b/docs/design/images/OPNFV_SFC_Brahmaputra_UseCase.jpg
diff --git a/docs/design/index.rst b/docs/design/index.rst
index c878b872..138a1817 100644
--- a/docs/design/index.rst
+++ b/docs/design/index.rst
@@ -26,7 +26,3 @@ Indices and tables
 ==================
 
 * :ref:`search`
-
-Revision: _sha1_
-
-Build date: |today|
diff --git a/docs/design/introduction.rst b/docs/design/introduction.rst
index 746ba05c..441ed999 100644
--- a/docs/design/introduction.rst
+++ b/docs/design/introduction.rst
@@ -1,5 +1,5 @@
 .. two dots create a comment. please leave this logo at the top of each of your rst files.
-.. image:: ../etc/opnfv-logo.png 
+.. image:: ../etc/opnfv-logo.png
   :height: 40
   :width: 200
   :alt: OPNFV
@@ -8,13 +8,13 @@
 |
 |
 Introduction
-============
+------------
 
 ..
  This work is licensed under a Creative Commons Attribution 3.0 Unported License.
 
  http://creativecommons.org/licenses/by/3.0/legalcode
- 
+
 .. NOTE::
    This is the working documentation for the SFC project.
 
diff --git a/docs/design/requirements.rst b/docs/design/requirements.rst
index dbedc6f7..3a716351 100644
--- a/docs/design/requirements.rst
+++ b/docs/design/requirements.rst
@@ -1,4 +1,41 @@
 Requirements
-============
+------------
+
+This section defines requirements for the initial OPNFV SFC implementation,
+including those requirements driving upstream project enhancements.
+
+Minimal Viable Requirement
+++++++++++++++++++++++++++
+
+Deploy a complete SFC solution by integrating OpenDaylight SFC with OpenStack
+in an OPNFV environment.
+
+Detailed Requirements
++++++++++++++++++++++
+
+These are the Brahmaputra specific requirements:
+
+1 Placement of SFs on only one Compute node will be supported.
+
+2 The supported Service Chaining encapsulation will be NSH VXLAN-GPE.
+
+3 The version of OVS used must support NSH.
+
+4 The SF VM life cycle will be managed by the Tacker VNF Mgr.
+
+5 The supported classifiers will be either ODL Netvirt or ODL GBP.
+
+6 ODL will be the OpenStack Neutron backend and will handle all networking
+  on the compute nodes.
+
+Long Term Requirements
+++++++++++++++++++++++
+
+These requirements are out of the scope of the Brahmaputra release.
+
+1 Placing SFs on multiple Compute nodes.
+
+2 Dynamic movement of SFs across multiple Compute nodes.
+
+3 Load Balancing across multiple SFs
 
-This section will define requirements for the initial OPNFV SFC implementation, including those requirements driving upstream project enhancements.
diff --git a/docs/design/usecases.rst b/docs/design/usecases.rst
index 9b886982..b42fcbde 100644
--- a/docs/design/usecases.rst
+++ b/docs/design/usecases.rst
@@ -1,4 +1,14 @@
 Use Cases
-=========
+---------
 
-This section will outline use cases driving the initial OPNFV SFC implementation.
\ No newline at end of file
+This section outlines the Brahmaputra use cases driving the initial OPNFV
+SFC implementation.
+
+
+The use cases targeted in the OPNFV SFC Brahmaputra release focus on creating
+simple Service Chains using Firewall Service Functions. As can be seen in the
+following diagram, 2 service chains are created, each through a different
+Service Function Firewall. Service Chain 1 will block HTTP, while Service
+Chain 2 will block SSH.
+
+.. image:: ./images/OPNFV_SFC_Brahmaputra_UseCase.jpg