11 files changed, 275 insertions, 0 deletions
diff --git a/docs/development/design/architecture.rst b/docs/development/design/architecture.rst
new file mode 100644
index 00000000..679bb2f9
--- /dev/null
+++ b/docs/development/design/architecture.rst
@@ -0,0 +1,129 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Architecture
+------------
+
+This section describes the architectural approach to incorporating the upstream
+OpenDaylight (ODL) SFC project into the OPNFV Colorado 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 Colorado 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 not be finished by the time OPNFV Colorado 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
+
diff --git a/docs/development/design/definitions.rst b/docs/development/design/definitions.rst
new file mode 100644
index 00000000..85416fb8
--- /dev/null
+++ b/docs/development/design/definitions.rst
@@ -0,0 +1,64 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Definitions
+-----------
+
+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.
+
+
+Abbreviations
+-------------
+
+.. list-table:: Abbreviations
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Abbreviation
+     - Term
+
+   * - NS
+     - Network Service
+
+   * - NFVO
+     - Network Function Virtualization Orchestrator
+
+   * - 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
+
+   * - SFC
+     - Service Function Chain(ing)
+
+   * - SFF
+     - Service Function Forwarder
+
+   * - SFP
+     - Service Function Path
+
+   * - VNF
+     - Virtual Network Function
+
+   * - VNFM
+     - Virtual Network Function Manager
+
+   * - VNF-FG
+     - Virtual Network Function Forwarding Graph
+
+   * - VIM
+     - Virtual Infrastructure Manager
diff --git a/docs/development/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg b/docs/development/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg
new file mode 100644
index 00000000..1b542888
--- /dev/null
+++ b/docs/development/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_fromSf.jpg
diff --git a/docs/development/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg b/docs/development/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg
new file mode 100644
index 00000000..11eaf87b
--- /dev/null
+++ b/docs/development/design/images/OPNFV_SFC_BrahmaputraOvsNshWorkaround_toSf.jpg
diff --git a/docs/development/design/images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg b/docs/development/design/images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg
new file mode 100644
index 00000000..c183486e
--- /dev/null
+++ b/docs/development/design/images/OPNFV_SFC_Brahmaputra_NW_Topology.jpg
diff --git a/docs/development/design/images/OPNFV_SFC_Brahmaputra_SfCreation.jpg b/docs/development/design/images/OPNFV_SFC_Brahmaputra_SfCreation.jpg
new file mode 100644
index 00000000..345317dd
--- /dev/null
+++ b/docs/development/design/images/OPNFV_SFC_Brahmaputra_SfCreation.jpg
diff --git a/docs/development/design/images/OPNFV_SFC_Brahmaputra_UseCase.jpg b/docs/development/design/images/OPNFV_SFC_Brahmaputra_UseCase.jpg
new file mode 100644
index 00000000..efc0df33
--- /dev/null
+++ b/docs/development/design/images/OPNFV_SFC_Brahmaputra_UseCase.jpg
diff --git a/docs/development/design/index.rst b/docs/development/design/index.rst
new file mode 100644
index 00000000..f13d575b
--- /dev/null
+++ b/docs/development/design/index.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*******************************
+Service Function Chaining (SFC)
+*******************************
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   introduction.rst
+   definitions.rst
+   usecases.rst
+   architecture.rst
+   requirements.rst
diff --git a/docs/development/design/introduction.rst b/docs/development/design/introduction.rst
new file mode 100644
index 00000000..f7b7df76
--- /dev/null
+++ b/docs/development/design/introduction.rst
@@ -0,0 +1,10 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Introduction
+------------
+
+The `OPNFV Service Function Chaining (SFC) <https://wiki.opnfv.org/display/sfc/Service+Function+Chaining+Home>`_
+project aims to provide the ability to define an ordered list of a network services (e.g. firewalls, NAT, QoS).
+These service are then "stitched" together in the network to create a service chain.
+This project provides the infrastructure to install the upstream ODL SFC implementation project in an NFV environment.
diff --git a/docs/development/design/requirements.rst b/docs/development/design/requirements.rst
new file mode 100644
index 00000000..1c15a9b9
--- /dev/null
+++ b/docs/development/design/requirements.rst
@@ -0,0 +1,40 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+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 Colorado specific requirements:
+
+1 The supported Service Chaining encapsulation will be NSH VXLAN-GPE.
+
+2 The version of OVS used must support NSH.
+
+3 The SF VM life cycle will be managed by the Tacker VNF Mgr.
+
+4 The supported classifiers will be either ODL Netvirt or ODL GBP.
+
+5 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 Colorado release.
+
+1 Dynamic movement of SFs across multiple Compute nodes.
+
+2 Load Balancing across multiple SFs
+
diff --git a/docs/development/design/usecases.rst b/docs/development/design/usecases.rst
new file mode 100644
index 00000000..23e94417
--- /dev/null
+++ b/docs/development/design/usecases.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Use Cases
+---------
+
+This section outlines the Colorado use cases driving the initial OPNFV
+SFC implementation.
+
+The use cases targeted in the OPNFV SFC Colorado 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