diff options
Diffstat (limited to 'docs/release')
| -rw-r--r-- | docs/release/configguide/featureconfig.rst | 24 | ||||
| -rw-r--r-- | docs/release/configguide/postinstall.rst | 26 | ||||
| -rw-r--r-- | docs/release/installation/feature.configuration.rst | 256 | ||||
| -rw-r--r-- | docs/release/installation/index.rst | 13 | ||||
| -rw-r--r-- | docs/release/release-notes/index.rst | 13 | ||||
| -rw-r--r-- | docs/release/release-notes/releasenotes.rst | 204 | ||||
| -rw-r--r-- | docs/release/scenarios/os-odl_l2-sfc-ha/index.rst | 16 | ||||
| -rw-r--r-- | docs/release/scenarios/os-odl_l2-sfc-ha/scenario.description.rst | 118 | ||||
| -rw-r--r-- | docs/release/scenarios/os-odl_l2-sfc-noha/index.rst | 16 | ||||
| -rw-r--r-- | docs/release/scenarios/os-odl_l2-sfc-noha/scenario.description.rst | 118 | ||||
| -rw-r--r-- | docs/release/userguide/feature.userguide.rst | 50 | ||||
| -rw-r--r-- | docs/release/userguide/index.rst | 13 |
12 files changed, 867 insertions, 0 deletions
diff --git a/docs/release/configguide/featureconfig.rst b/docs/release/configguide/featureconfig.rst new file mode 100644 index 00000000..9189902c --- /dev/null +++ b/docs/release/configguide/featureconfig.rst @@ -0,0 +1,24 @@ +<Project> configuration +======================= +Add a brief introduction to configure OPNFV with this specific feature including +dependancies on platform components, this description should be at a level that +will apply to any installer providing the pre-requisite components. + +Pre-configuration activities +---------------------------- +Describe specific pre-configuration activities. This should include ensuring the +right components are installed by the installation tools as required for your +feature to function. Refer to the previous installer configuration chapters, +installations guide and release notes + +Hardware configuration +---------------------- +Describe the hardware configuration needed for this specific feature + +Feature configuration +--------------------- +Describe the procedures to configure your feature on the platform in order +that it is ready to use according to the feature instructions in the platform +user guide. Where applicable you should add content in the postinstall.rst +to validate the feature is configured for use. +(checking components are installed correctly etc...) diff --git a/docs/release/configguide/postinstall.rst b/docs/release/configguide/postinstall.rst new file mode 100644 index 00000000..1702cea5 --- /dev/null +++ b/docs/release/configguide/postinstall.rst @@ -0,0 +1,26 @@ +<Project> post installation procedures +====================================== +Add a brief introduction to the methods of validating the installation +according to this specific installer or feature. + +Automated post installation activities +-------------------------------------- +Describe specific post installation activities performed by the OPNFV +deployment pipeline including testing activities and reports. Refer to +the relevant testing guides, results, and release notes. + +note: this section should be singular and derived from the test projects +once we have one test suite to run for all deploy tools. This is not the +case yet so each deploy tool will need to provide (hopefully very simillar) +documentation of this. + +<Project> post configuration procedures +-------------------------------------- +Describe any deploy tool or feature specific scripts, tests or procedures +that should be carried out on the deployment post install and configuration +in this section. + +Platform components validation +--------------------------------- +Describe any component specific validation procedures necessary for your +deployment tool in this section. diff --git a/docs/release/installation/feature.configuration.rst b/docs/release/installation/feature.configuration.rst new file mode 100644 index 00000000..e2fcbbb0 --- /dev/null +++ b/docs/release/installation/feature.configuration.rst @@ -0,0 +1,256 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Ferenc Cserepkei, Brady Allen Johnson, Manuel Buil and others + +Abstract +======== +This document provides information on how to install the OpenDayLigh SFC +features in OPNFV with the use of os_odl-l2_sfc-(no)ha scenario. + +SFC feature desciription +======================== +For details of the scenarios and their provided capabilities refer to +the scenario description documents: + +- http://artifacts.opnfv.org/sfc/colorado/docs/scenarios_os-odl_l2-sfc-ha/index.html + +- http://artifacts.opnfv.org/sfc/colorado/docs/scenarios_os-odl_l2-sfc-noha/index.html + + +The SFC feature enables creation of Service Fuction Chains - an ordered list +of chained network funcions (e.g. firewalls, NAT, QoS) + +The SFC feature in OPNFV is implemented by 3 major components: + +- OpenDayLight SDN controller + +- Tacker: Generic VNF Manager (VNFM) and a NFV Orchestrator (NFVO) + +- OpenvSwitch: The Service Function Forwarder(s) + +Hardware requirements +===================== + +The SFC scenarios can be deployed on a bare-metal OPNFV cluster or on a +virtual environment on a single host. + +Bare metal deployment on (OPNFV) Pharos lab +------------------------------------------- +Hardware requirements for bare-metal deployments of the OPNFV infrastructure +are given by the Pharos project. The Pharos project provides an OPNFV +hardware specification for configuring your hardware: +http://artifacts.opnfv.org/pharos/docs/pharos-spec.html + + +Virtual deployment +------------------ +To perform a virtual deployment of an OPNFV SFC scenario on a single host, +that host has to meet the following hardware requirements: + +- SandyBridge compatible CPU with virtualization support + +- capable to host 5 virtual cores (5 physical ones at least) + +- 8-12 GBytes RAM for virtual hosts (controller, compute), 48GByte at least + +- 128 GiBiBytes room on disk for each virtual host (controller, compute) + + 64GiBiBytes for fuel master, 576 GiBiBytes at least + +- Ubuntu Trusty Tahr - 14.04(.5) server operating system with at least ssh + service selected at installation. + +- Internet Connection (preferably http proxyless) + + +Pre-configuration activites - Preparing the host to install Fuel by script +========================================================================== +.. Not all of these options are relevant for all scenario's. I advise following the +.. instructions applicable to the deploy tool used in the scenario. + +Before starting the installation of the SFC scenarios some preparation of the +machine that will host the Colorado Fuel cluster must be done. + +Installation of required packages +--------------------------------- +To be able to run the installation of the basic OPNFV fuel installation the +Jumphost (or the host which serves the VMs for the virtual deployment) needs to +install the following packages: +:: + + sudo apt-get install -y git make curl libvirt-bin libpq-dev qemu-kvm \ + qemu-system tightvncserver virt-manager sshpass \ + fuseiso genisoimage blackbox xterm python-pip \ + python-git python-dev python-oslo.config \ + python-pip python-dev libffi-dev libxml2-dev \ + libxslt1-dev libffi-dev libxml2-dev libxslt1-dev \ + expect curl python-netaddr p7zip-full + + sudo pip install GitPython pyyaml netaddr paramiko lxml scp \ + scp pycrypto ecdsa debtcollector netifaces enum + +During libvirt install the user is added to the libvirtd group, so you have to +logout then login back again + + +Download the installer source code and artifact +----------------------------------------------- +To be able to install the scenario os_odl-l2_sfc-(no)ha one can follow the way +CI is deploying the scenario. +First of all the opnfv-fuel repository needs to be cloned: +:: + + git clone -b 'stable/colorado' ssh://<user>@gerrit.opnfv.org:29418/fuel + +This command copies the whole colorado branch of repository fuel. + +Now download the appropriate OPNFV Fuel ISO into an appropriate folder: +:: + + wget http://artifacts.opnfv.org/fuel/colorado/opnfv-colorado.1.0.iso + +The exact name of the ISO image may change. +Check https://www.opnfv.org/opnfv-colorado-fuel-users to get the latest ISO. + +Simplified scenario deployment procedure using Fuel +=================================================== + +This section describes the installation of the os-odl-l2_sfc or +os-odl-l2_sfc-noha OPNFV reference platform stack across a server cluster +or a single host as a virtual deployment. + +Scenario Preparation +-------------------- +dea.yaml and dha.yaml need to be copied and changed according to the +lab-name/host where you deploy. +Copy the full lab config from: +:: + + cp -r <path-to-opnfv-fuel-repo>/deploy/config/labs/devel-pipeline/elx \ + <path-to-opnfv-fuel-repo>/deploy/config/labs/devel-pipeline/<your-lab-name> + +Add at the bottom of dha.yaml +:: + + disks: + fuel: 64G + controller: 128G + compute: 128G + + define_vms: + controller: + vcpu: + value: 2 + memory: + attribute_equlas: + unit: KiB + value: 12521472 + currentMemory: + attribute_equlas: + unit: KiB + value: 12521472 + compute: + vcpu: + value: 2 + memory: + attribute_equlas: + unit: KiB + value: 8388608 + currentMemory: + attribute_equlas: + unit: KiB + value: 8388608 + fuel: + vcpu: + value: 2 + memory: + attribute_equlas: + unit: KiB + value: 2097152 + currentMemory: + attribute_equlas: + unit: KiB + value: 2097152 + +Check if the default settings in dea.yaml are in line with your intentions +and make changes as required. + +Installation procedures +----------------------- + +We state here several alternatives. +First, we describe methods that are based on the use of the deploy.sh script, +what is used by the OPNFV CI system and can be found in the Fuel repository. + +In addition, the SFC feature can also be configured manually in the Fuel GUI +what we will show in the last subsection. + +Before starting any of the following procedures, go to +:: + + cd <opnfv-fuel-repo>/ci + +Full automatic virtual deployment, High Availablity mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example will deploy the high-availability flavor of SFC scenario +os_odl-l2_sfc-ha in a fully automatic way, i.e. all installation steps +(Fuel server installation, configuration, node discovery and platform +deployment) will take place without any further prompt for user input. +:: + + sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> + -s os_odl-l2_sfc-ha -i file://<path-to-fuel-iso> + +Full automatic virtual deployment, non HIGH Availablity mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following command will deploy the SFC scenario with non-high-availability +flavor (note the different scenario name for the -s switch). Otherwise it +does the same as described above. +:: + + sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> + -s os_odl-l2_sfc-noha -i file://<path-to-fuel-iso> + +Automatic Fuel installation and manual scenario deployment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A useful alternative to the full automatic procedure is to only deploy the Fuel host and to run host selection, role assignment and SFC scenario configuration manually. +:: + + sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> -s os_odl-l2_sfc-ha -i file://<path-to-fuel-iso> -e + +With -e option the installer will skip environment deployment, so an user +can do some modification before the scenario is really deployed. Another +useful option is the -f option which deploys the scenario using an existing +Fuel host. + +The result of this installation is a well configured Fuel sever. The use of +the deploy button on Fuel dashboard can initiate the deployment. A user may +perform manual post-configuration as well. + +Feature configuration on existing Fuel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a Fuel server is already provisioned but the fuel plugins for Opendaylight, +Openvswitch are not provided install them by: +:: + + cd /opt/opnfv/ + fuel plugins --install fuel-plugin-ovs-*.noarch.rpm + fuel plugins --install opendaylight-*.noarch.rpm + +If plugins are installed and you want to update them use --force flag. + +Note that One may inject other - Colorado compatible - plugins to the Fuel +Master host using the command scp: + +scp <plugin>.rpm root@10.20.0.2:<plugin>.rpm + +Now the feature can be configured. Create a new environment with +Networking Setup:"OpenDayLight with tunneling segmentation". Then go to +settings/other and check "OpenDaylight plugin, SFC enabled", +"Install Openvswitch with NSH/DPDK, with NSH enabled". During node provision +remember assign the OpenDayLight role to the (primary)controller + +Now the deploy button on fuel dashboard can be used to deploy the environment. diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst new file mode 100644 index 00000000..53279035 --- /dev/null +++ b/docs/release/installation/index.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + .. (c) <optionally add copywriters name> + +********************************************** +SFC installation and configuration instruction +********************************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + feature.configuration.rst diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst new file mode 100644 index 00000000..e5e1dc60 --- /dev/null +++ b/docs/release/release-notes/index.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + .. (c) <optionally add copywriters name> + +***************** +SFC Release Notes +***************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + releasenotes.rst diff --git a/docs/release/release-notes/releasenotes.rst b/docs/release/release-notes/releasenotes.rst new file mode 100644 index 00000000..bf07e59a --- /dev/null +++ b/docs/release/release-notes/releasenotes.rst @@ -0,0 +1,204 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Brady Johnson (Ericsson Inc.) and others + +Abstract +======== + +This document compiles the release notes for the Colorado release of +OPNFV SFC. + +Important notes +=============== + +These notes provide release information for the use of SFC with the Fuel +and Apex installer tools for the Colorado release of OPNFV. + +Summary +======= + +The goal of the SFC Colorado release is to integrate the OpenDaylight +SFC project into an OPNFV environment, with either the Fuel or Apex +installer. In subsequent releases, other OPNFV installers will be +considered. + +More information about OpenDaylight and SFC can be found here. + +- `OpenDaylight <http://www.opendaylight.org/software>`_ version "Boron" + +- `Service function chaining <https://wiki.opnfv.org/display/sfc/Service+Function+Chaining+Home>`_ + + +- Documentation built by Jenkins + + - Overall OPNFV documentation + + - `Design document <http://artifacts.opnfv.org/sfc/colorado/docs/design/index.html>`_ + + - `User Guide <http://artifacts.opnfv.org/sfc/colorado/docs/userguide/index.html>`_ + + - `Installation Instructions <http://artifacts.opnfv.org/sfc/colorado/docs/installationprocedure/index.html>`_ + + - Release Notes (this document) + + +Release Data +============ + ++--------------------------------------+--------------------------------------+ +| **Project** | sfc | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/tag** | colorado.2.0 | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | Colorado base release | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | November 10 2016 | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | Improve functionality provided in | +| | Brahmaputra release. Increased test | +| | coverage with new Funtest cases. | +| | Make SFC/Tacker work on multiple | +| | compute nodes | +| | | ++--------------------------------------+--------------------------------------+ + +Version change +-------------- + +Module version changes +~~~~~~~~~~~~~~~~~~~~~~ +This is the second tracked release of OPNFV sfc. It is based on +following upstream versions: + +- OpenStack Mitaka release + +- OpenDaylight Boron release + +- Open vSwitch 2.5.90 with Yi Yang NSH patch + +Document changes +~~~~~~~~~~~~~~~~ +This is the second tracked version of OPNFV SFC. It comes with +the following documentation: + +- `Design document <http://artifacts.opnfv.org/sfc/colorado/docs/design/index.html>`_ + +- `User Guide <http://artifacts.opnfv.org/sfc/colorado/docs/userguide/index.html>`_ + +- `Installation Instructions <http://artifacts.opnfv.org/sfc/colorado/docs/installationprocedure/index.html>`_ + +- Release notes (This document) + +Reason for version +------------------ + +Feature additions +~~~~~~~~~~~~~~~~~ + +**JIRA TICKETS:** + +`JIRA EPIC with the new features in SFC Colorado <https://jira.opnfv.org/browse/SFC-33>`_ + +Bug corrections +~~~~~~~~~~~~~~~ + +**JIRA TICKETS:** + +`Bug-fixes <https://jira.opnfv.org/browse/SFC-34>`_ + +Deliverables +------------ + +Software deliverables +~~~~~~~~~~~~~~~~~~~~~ + +No specific deliverables are created, as SFC is included with Apex and Fuel. + +Documentation deliverables +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `Design document <http://artifacts.opnfv.org/sfc/colorado/docs/design/index.html>`_ + +- `User Guide <http://artifacts.opnfv.org/sfc/colorado/docs/userguide/index.html>`_ + +- `Installation Instructions <http://artifacts.opnfv.org/sfc/colorado/docs/installationprocedure/index.html>`_ + +- Release notes (This document) + +Known Limitations, Issues and Workarounds +========================================= + +System Limitations +------------------ + +The Colorado 2.0 release has several limitations: + +1 - OPNFV SFC only works in non-HA environments with the Fuel installer. +There is a bug in ODL which is fixed in ODL Boron SR1 and will be part +of Colorado 3.0 + +2 - Any VM (e.g. SFs) must have only one security group. +There is a bug in ODL Boron which only one security group is read. +The rest are silently ignored. This issue will be fixed in ODL +Boron SR1, which will be included in Colorado 3.0. + +Known issues +------------ + +OpenDaylight SFC relies on a version of Open vSwitch (OVS) with +Network Service Headers (NSH). A version of OVS with NSH currently +exists, but it is in a branched version of OVS. Extensive upstream +work has been done to merge the NSH patches into mainstream OVS, +but the work is still not complete. More information about this +can be found in the OPNFV SFC design document (link provided above). + +Workarounds +----------- + +The way OpenStack handles VXLAN-GPE tunnels doesnt work well with +SFC, since OpenStack terminates the VXLAN tunnels in the br-int +bridge instead of the SF VM. Ideally, the tunnel should be terminated +in the VM so the SF has access to the NSH header carried in the tunnel. +A workaround was created to send the packets to the SF VM with the +VXLAN-GPE headers intact and can be found in the OPNFV SFC design +document (link provided above). + +Test results +============ +The Colorado release of SFC has undergone QA test runs +with Functest tests on the Fuel and Apex installers. + +References +========== +For more information on the OPNFV Colorado release, please see: + +OPNFV +----- + +1) `OPNFV Home Page <https://www.opnfv.org>`_ + +2) `OPNFV documentation- and software downloads <https://www.opnfv.org/software/download>`_ + +3) `OPNFV Colorado release <http://wiki.opnfv.org/releases/colorado>`_ + +OpenStack +--------- + +4) `OpenStack Mitaka Release artifacts <http://www.openstack.org/software/mitaka>`_ + +5) `OpenStack documentation <http://docs.openstack.org>`_ + +OpenDaylight +------------ + +6) `OpenDaylight artifacts <http://www.opendaylight.org/software/downloads>`_ + +Open vSwitch with NSH +--------------------- + +7) https://github.com/yyang13/ovs_nsh_patches + diff --git a/docs/release/scenarios/os-odl_l2-sfc-ha/index.rst b/docs/release/scenarios/os-odl_l2-sfc-ha/index.rst new file mode 100644 index 00000000..d72e657c --- /dev/null +++ b/docs/release/scenarios/os-odl_l2-sfc-ha/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 +.. (c) <optionally add copywriters name> + +========================================= +os-odl_l2-sfc-ha overview and description +========================================= +.. This document will be used to provide a description of the scenario for an end user. +.. You should explain the purpose of the scenario, the types of capabilities provided and +.. the unique components that make up the scenario including how they are used. + +.. toctree:: + :maxdepth: 3 + + ./scenario.description.rst + diff --git a/docs/release/scenarios/os-odl_l2-sfc-ha/scenario.description.rst b/docs/release/scenarios/os-odl_l2-sfc-ha/scenario.description.rst new file mode 100644 index 00000000..cb918002 --- /dev/null +++ b/docs/release/scenarios/os-odl_l2-sfc-ha/scenario.description.rst @@ -0,0 +1,118 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) <optionally add copywriters name> + +Introduction +============ +.. In this section explain the purpose of the scenario and the types of capabilities provided +The os-odl_l2-sfc-ha is intended to be used to install the OPNFV SFC project in a standard +OPNFV High Availability mode. The OPNFV SFC project integrates the OpenDaylight SFC project +into the OPNFV environment. The OPNFV SFC Colorado release uses the OpenDaylight Boron release. + +Scenario components and composition +=================================== +.. In this section describe the unique components that make up the scenario, +.. what each component provides and why it has been included in order +.. to communicate to the user the capabilities available in this scenario. + +This scenario installs everything needed to use the SFC OpenDaylight project in an OPNFV +environment. The classifier used in this scenario is implemented by the Netvirt OpenDaylight +project. + +Following is a detailed list of what is included with this scenario: + +OpenDaylight features installed +------------------------------- + +The OpenDaylight SDN controller is installed in the controller node. + +The following are the SFC features that get installed: + +- odl-sfc-model +- odl-sfc-provider +- odl-sfc-provider-rest +- odl-sfc-ovs +- odl-sfc-openflow-renderer + +The following are the Netvirt features that get installed: + +- odl-ovsdb-openstack +- odl-mdsal-xsql +- odl-neutron-service +- odl-neutron-northbound-api +- odl-neutron-spi +- odl-neutron-transcriber +- odl-mdsal-apidocs +- odl-ovsdb-southbound-impl-rest +- odl-ovsdb-southbound-impl-ui + +By simply installing the odl-ovsdb-openstack feature, all the dependant features +will automatically be installed. + +The VNF Manager +--------------- + +In order to create a VM for each Service Function, a VNF Manager is needed. The OPNFV +SFC project currently uses the Tacker OpenStack project as a VNF Manager. Tacker is +installed on the controller node and manages VNF life cycle, and coordinates VM creation +with the OpenDaylight SFC project. + +Scenario usage overview +======================= +.. Provide a brief overview on how to use the scenario and the features available to the +.. user. This should be an "introduction" to the userguide document, and explicitly link to it, +.. where the specifics of the features are covered including examples and API's + +Once this scenario is installed, it will be possible to create Service Chains and +classification entries to map tenant traffic to individual, pre-defined Service Chains. +All configuration can be performed using the Tacker CLI. + +Limitations, Issues and Workarounds +=================================== +.. Explain scenario limitations here, this should be at a design level rather than discussing +.. faults or bugs. If the system design only provide some expected functionality then provide +.. some insight at this point. +This scenario is not working in Colorado 1.0 with the Fuel installer, since Tacker is not +registered in the HA Proxy and calls to Tacker fail. This will be fixed in Colorado 2.0. + +Specific version of OVS +----------------------- + +SFC needs changes in OVS to include the Network Service Headers (NSH) Service Chaining +encapsulation. This OVS patch has been ongoing for quite a while (2 years+), and still +has not been officially merged. Previously, SFC used NSH from a branched version of OVS +based on 2.3.90, called the "Pritesh Patch". In the OpenDaylight Boron release, SFC was +changed to use a newer, branched version of OVS based on 2.5.90, called the "Yi Yang +Patch". + +The older version of OVS only supported VXLAN-GPE + NSH encapsulation, but the newer +version supports both ETH + NSH and VXLAN-GPE + ETH + NSH. Currently SFC is only +implemented with VXLAN-GPE + ETH + NSH. + +Workaround for VXLAN and OpenStack +---------------------------------- + +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 SF VM, but in the “br-int” OVS bridge. A work-around has +been created to address this issue, which can be found here: + +http://artifacts.opnfv.org/sfc/brahmaputra/docs/design/architecture.html#ovs-nsh-patch-workaround + +In subsequent versions of SFC, we will change the SFF-SF transport to be ETH + NSH, +which will obviate this work around. + +References +========== + +For more information about SFC, please visit: + +https://wiki.opnfv.org/display/sfc/Service+Function+Chaining+Home + +https://wiki.opendaylight.org/view/Service_Function_Chaining:Main + +For more information on the OPNFV Colorado release, please visit: + +http://www.opnfv.org/colorado + diff --git a/docs/release/scenarios/os-odl_l2-sfc-noha/index.rst b/docs/release/scenarios/os-odl_l2-sfc-noha/index.rst new file mode 100644 index 00000000..ef3e4fbe --- /dev/null +++ b/docs/release/scenarios/os-odl_l2-sfc-noha/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 +.. (c) <optionally add copywriters name> + +=========================================== +os-odl_l2-sfc-noha overview and description +=========================================== +.. This document will be used to provide a description of the scenario for an end user. +.. You should explain the purpose of the scenario, the types of capabilities provided and +.. the unique components that make up the scenario including how they are used. + +.. toctree:: + :maxdepth: 3 + + ./scenario.description.rst + diff --git a/docs/release/scenarios/os-odl_l2-sfc-noha/scenario.description.rst b/docs/release/scenarios/os-odl_l2-sfc-noha/scenario.description.rst new file mode 100644 index 00000000..b5d41044 --- /dev/null +++ b/docs/release/scenarios/os-odl_l2-sfc-noha/scenario.description.rst @@ -0,0 +1,118 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) <optionally add copywriters name> + +Introduction +============ +.. In this section explain the purpose of the scenario and the types of capabilities provided +The os-odl_l2-sfc-noha is intended to be used to install the OPNFV SFC project in a standard +OPNFV Non-High Availability mode. The OPNFV SFC project integrates the OpenDaylight SFC +project into the OPNFV environment. The OPNFV SFC Colorado release uses the OpenDaylight +Boron release. + +Scenario components and composition +=================================== +.. In this section describe the unique components that make up the scenario, +.. what each component provides and why it has been included in order +.. to communicate to the user the capabilities available in this scenario. + +This scenario installs everything needed to use the SFC OpenDaylight project in an OPNFV +environment. Since this scenario is Non-High Availability, then only one controller and +one compute node will be deployed. The classifier used in this scenario is implemented +by the Netvirt OpenDaylight project. + +Following is a detailed list of what is included with this scenario: + +OpenDaylight features installed +------------------------------- + +The OpenDaylight SDN controller is installed in the controller node. + +The following are the SFC features that get installed: + +- odl-sfc-model +- odl-sfc-provider +- odl-sfc-provider-rest +- odl-sfc-ovs +- odl-sfc-openflow-renderer + +The following are the Netvirt features that get installed: + +- odl-ovsdb-openstack +- odl-mdsal-xsql +- odl-neutron-service +- odl-neutron-northbound-api +- odl-neutron-spi +- odl-neutron-transcriber +- odl-mdsal-apidocs +- odl-ovsdb-southbound-impl-rest +- odl-ovsdb-southbound-impl-ui + +By simply installing the odl-ovsdb-openstack feature, all the dependant features +will automatically be installed. + +The VNF Manager +--------------- + +In order to create a VM for each Service Function, a VNF Manager is needed. The OPNFV +SFC project currently uses the Tacker OpenStack project as a VNF Manager. Tacker is +installed on the controller node and manages VNF life cycle, and coordinates VM creation +with the OpenDaylight SFC project. + +Scenario usage overview +======================= +.. Provide a brief overview on how to use the scenario and the features available to the +.. user. This should be an "introduction" to the userguide document, and explicitly link to it, +.. where the specifics of the features are covered including examples and API's + +Once this scenario is installed, it will be possible to create Service Chains and +classification entries to map tenant traffic to individual, pre-defined Service Chains. +All configuration can be performed using the Tacker CLI. + +Limitations, Issues and Workarounds +=================================== +.. Explain scenario limitations here, this should be at a design level rather than discussing +.. faults or bugs. If the system design only provide some expected functionality then provide +.. some insight at this point. + +Specific version of OVS +----------------------- + +SFC needs changes in OVS to include the Network Service Headers (NSH) Service Chaining +encapsulation. This OVS patch has been ongoing for quite a while (2 years+), and still +has not been officially merged. Previously, SFC used NSH from a branched version of OVS +based on 2.3.90, called the "Pritesh Patch". In the OpenDaylight Boron release, SFC was +changed to use a newer, branched version of OVS based on 2.5.90, called the "Yi Yang +Patch". + +The older version of OVS only supported VXLAN-GPE + NSH encapsulation, but the newer +version supports both ETH + NSH and VXLAN-GPE + ETH + NSH. Currently SFC is only +implemented with VXLAN-GPE + ETH + NSH. + +Workaround for VXLAN and OpenStack +---------------------------------- + +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 SF VM, but in the “br-int” OVS bridge. A work-around has +been created to address this issue, which can be found here: + +http://artifacts.opnfv.org/sfc/brahmaputra/docs/design/architecture.html#ovs-nsh-patch-workaround + +In subsequent versions of SFC, we will change the SFF-SF transport to be ETH + NSH, +which will obviate this work around. + +References +========== + +For more information about SFC, please visit: + +https://wiki.opnfv.org/display/sfc/Service+Function+Chaining+Home + +https://wiki.opendaylight.org/view/Service_Function_Chaining:Main + +For more information on the OPNFV Colorado release, please visit: + +http://www.opnfv.org/colorado + diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst new file mode 100644 index 00000000..6e80a391 --- /dev/null +++ b/docs/release/userguide/feature.userguide.rst @@ -0,0 +1,50 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) <optionally add copywriters name> + +SFC description +===================== +.. Describe the specific features and how it is realised in the scenario in a brief manner +.. to ensure the user understand the context for the user guide instructions to follow. + +The OPNFV SFC feature will create service chains, classifiers, and create VMs for Service +Functions, allowing for client traffic intended to be sent to a server to first traverse +the provisioned service chain. + +The Service Chain creation consists of configuring the OpenDaylight SFC feature. This +configuration will in-turn configure Service Function Forwarders to route traffic to +Service Functions. A Service Function Forwarder in the context of OPNFV SFC is the +"br-int" OVS bridge on an Open Stack compute node. + +The classifier(s) consist of configuring the OpenDaylight Netvirt feature. Netvirt is +a Neutron backend which handles the networking for VMs. Netvirt can also create simple +classification rules (5-tuples) to send specific traffic to a pre-configured Service +Chain. A common example of a classification rule would be to send all HTTP traffic +(tcp port 80) to a pre-configured Service Chain. + +Service Function VM creation is performed via a VNF Manager. Currently, OPNFV SFC +is integrated with OpenStack Tacker, which in addition to being a VNF Manager, also +orchestrates the SFC configuration. In OPNFV SFC Tacker creates service chains, +classification rules, creates VMs in OpenStack for Service Functions, and then +communicates the relevant configuration to OpenDaylight SFC. + +SFC capabilities and usage +================================ +.. Describe the specific capabilities and usage for <XYZ> feature. +.. Provide enough information that a user will be able to operate the feature on a deployed scenario. + +The OPNFV SFC feature can be deployed with either the "os-odl_l2-sfc-ha" or the +"os-odl_l2-sfc-noha" scenario. SFC usage for both of these scenarios is the same. + +As previously mentioned, Tacker is used as a VNF Manager and SFC Orchestrator. All +the configuration necessary to create working service chains and classifiers can +be performed using the Tacker command line. Refer to the `Tacker walkthrough <https://github.com/trozet/sfc-random/blob/master/tacker_sfc_apex_walkthrough.txt>`_ +(step 3 and onwards) for more information. + +SFC API usage guidelines and example +----------------------------------------------- +.. Describe with examples how to use specific features, provide API examples and details required to +.. operate the feature on the platform. + +Refer to the `Tacker walkthrough <https://github.com/trozet/sfc-random/blob/master/tacker_sfc_apex_walkthrough.txt>`_ +for Tacker usage guidelines and examples. diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst new file mode 100644 index 00000000..9bfd2433 --- /dev/null +++ b/docs/release/userguide/index.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + .. (c) <optionally add copywriters name> + +************** +SFC User Guide +************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + feature.userguide.rst |