Moving documentation content into new template

JIRA: DOCS-103, DOCS-134, SDNVPN-40

Moving documentation content into new feature description and user guide template.

Change-Id: I2c1549b44ef43e28961f1a0d2885adc0dd161910
Signed-off-by: Tim Irnich <tim.irnich@ericsson.com>

11 files changed, 237 insertions, 320 deletions

diff --git a/docs/configguide/featureconfig.rst b/docs/configguide/featureconfig.rst
deleted file mode 100644
index 437f783..0000000
--- a/docs/configguide/featureconfig.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Tim Irnich  (tim.irnich@ericsson.com)
-
-Configuring SDNVPN features
----------------------------
-
-Fuel installer configuration
-
-In order to install the BGPVPN feature, the corresponding checkbox in Fuel has to be
-selected. This will trigger installation of the OpenStack BGPVPN API extension for
-Neutron (set up for using the ODL driver).
-
-In addition, ODL has to be installed, see the corresponding section in the respective
-installer documentation on how to install ODL. If the BGPVPN feature is installed,
-ODL will automatically be installed with VPN Service karaf feature activated.
-
-No post-deploy configuration is necessary. The Fuel BGPVPN plugin and the ODL plugin
-should set up the cluster ready for BGPVPNs being created. This includes the set-up
-of internal VxLAN transport tunnels between compute nodes.
-
-No post-configuration activities are required.
-
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/abstract.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/abstract.rst
deleted file mode 100644
index 189f9ff..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/abstract.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Tim Irnich <tim.irnich@ericsson.com>
-
-This document will give the user instructions on how to deploy
-the SDN VPN scenarios verfied for the Colorado release of the OPNFV
-platform, using the Fuel installer.
-
-A sister document covers installation using the APEX installer.
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/hardware.requirements.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/hardware.requirements.rst
deleted file mode 100644
index affeb03..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/hardware.requirements.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License. .. http://creativecommons.org/licenses/by/4.0 ..
-.. (c) Christopher Price (Ericsson AB), Nikolas Hermanns (Ericsson)
-
-Hardware requirements
-=====================
-
-Bare metal deployment on Pharos Lab
------------------------------------
-
-Hardware requirements for bare-metal deployments of the OPNFV infrastucture are specified
-by the Pharos project. The Pharos project provides an OPNFV hardware specification for
-configuring your hardware at: http://artifacts.opnfv.org/pharos/docs/pharos-spec.html.
-
-Virtual deployment hardware requirements
-----------------------------------------
-
-To perform a virtual deployment of an OPNFV scenario on a single host, that host has to
-meet the hardware requirements outlined in the <missing spec>.
-
-Additional Hardware requirements
---------------------------------
-
-When ODL is used as SDN Controller in an OPNFV, virtual deployment, ODL is
-running on the OpenStack Controller VMs. it is therefore recommmended to
-increase the amount of resources these VMs have.
-
-Our recommendation is to have 2 more virtual cores and 8GB more virtual memory. Together with the commonly used recommendation this sums up to:
-::
-
- 4 virtual cores
- 16 GB virtual memory
-
-See in Installation section how to configure this.
-
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/index.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/index.rst
deleted file mode 100755
index 150fbf5..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/index.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) 2016 Tim Irnich <tim.irnich@ericsson.com>
-
-================================
-SDNVPN Colorado documentation
-================================
-
-.. toctree::
-   :maxdepth: 2
-
-   ./abstract.rst
-   ./introduction.rst
-   ./hardware.requirements.rst
-   ./preparation.rst
-   ./installation.rst
-   ./references.rst
-
-Indices
-=======
-* :ref:`search`
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/installation.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/installation.rst
deleted file mode 100644
index 649b5a4..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/installation.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License. .. http://creativecommons.org/licenses/by/4.0 ..
-.. (c) Christopher Price (Ericsson AB), Nikolas Hermanns (Ericsson AB) and other
-
-Fuel installation and scenario deployment
-================================================
-
-This section describes the installation of the os-odl_l2-bgpvpn-ha or
-os-odl_l2-bgpvpn-noha OPNFV reference platform stack across a server cluster.
-
-Scenario Preparation
---------------------
-dea.yaml and dha.yaml need to be copied and changed according to the lap/host
-where you deploy.
-Copy the full lab config from:
-::
-
- cp <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: 100G
-   controller: 100G
-   compute: 100G
-
- define_vms:
-   controller:
-     vcpu:
-       value: 4
-     memory:
-       attribute_equlas:
-         unit: KiB
-       value: 16388608
-     currentMemory:
-       attribute_equlas:
-         unit: KiB
-       value: 16388608
-
-Check if dea.yaml contains all your needed changes.
-
-Installation procedures
------------------------
-
-We describe several alternative procedures in the following.
-Go to
-::
-
- cd <opnfv-fuel-repo>/ci
-
-Full automatic virtual deployment High Availablity Mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-::
-
- sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> -s os-odl_l2-bgpvpn-ha -i file://<path-to-fuel-iso>
-
-Full automatic virtual deployment NO High Availablity Mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-::
-
- sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> -s os-odl_l2-bgpvpn-noha -i file://<path-to-fuel-iso>
-
-Automatic Fuel installation and manual scenario deployment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-::
-
- sudo bash ./deploy.sh -b file://<path-to-opnfv-fuel-repo>/config/ -l devel-pipeline -p <your-lab-name> -s os-odl_l2-bgpvpn-ha -i file://<path-to-fuel-iso> -e
-
-With -e option the installer does not launch environment deployment, so
-a user can do some modification before the scenario is really deployed. Another interesting option is the -f option which deploys the scenario  on existing Fuel.
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/introduction.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/introduction.rst
deleted file mode 100644
index b91e19d..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/introduction.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License. .. http://creativecommons.org/licenses/by/4.0 ..
-.. (c) Tim Irnich and Nikolas Hermanns, Ericsson AB
-
-Introduction
-============
-
-This document provides guidelines on how to install and configure the
-os-odl_l2_bgpvpn_ha and os-odl_l2_bgpvpn_ha scenarios of OPNFV including
-required software and hardware configurations.
-
-Description of bgpvpn scenarios
-Internal transport tunnel mesh
-Install Neutron BGPVPN additions (networking-bgpvpn)
-Neutron odl additions (networking-odl)
-install and configure Quagga (incl. config on ODL side)
-configure OVS to connect to ODL and set up the right bridges (network architecture)
-set up iptables to allow connections between OVS and ODL
-set up HA proxy so that ODL can be reached
-
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/preparation.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/preparation.rst
deleted file mode 100644
index 9fc26d3..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/preparation.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License. .. http://creativecommons.org/licenses/by/4.0 ..
-.. (c) Tim Irnich (Ericsson AB) and others
-
-Preparing your 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 <scenario> scenario some preparation of the
-machine that will host the Fuel VM 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 \
-                  python-novaclient python-neutronclient python-glanceclient \
-                  python-keystoneclient debtcollector netifaces enum
-
-Download the source code and artifact
--------------------------------------
-To be able to install the scenario os-odl_l2-bgpvpn one can follow the way
-CI is deploying the scenario.
-First of all the opnfv-fuel repo needs to be cloned:
-::
-
- git clone ssh://<user>@gerrit.opnfv.org:29418/fuel
-
-This command downloads the whole repo fuel. We need now to switch it to
-the stable Brahmaputra branch:
-::
-
- cd fuel
- git checkout stable/brahmaputra
-
-Now download the appropriate OPNFV Fuel ISO into an appropriate folder:
-::
-
- wget http://artifacts.opnfv.org/fuel/brahmaputra/opnfv-brahmaputra.3.0.iso
-
-The ISO version may change.
-Check https://www.opnfv.org/opnfv-brahmaputra-fuel-users to get the latest ISO.
diff --git a/docs/installationprocedure/os-odl_l2-bgpvpn/references.rst b/docs/installationprocedure/os-odl_l2-bgpvpn/references.rst
deleted file mode 100644
index 5cafbab..0000000
--- a/docs/installationprocedure/os-odl_l2-bgpvpn/references.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License. .. http://creativecommons.org/licenses/by/4.0 ..
-.. (c) Christopher Price (Ericsson AB) and others
-
-
-References
-==========
-
-OPNFV
------
-
-1) `OPNFV Home Page <http://www.opnfv.org>`_
-
-2) `OPNFV documentation- and software downloads <https://www.opnfv.org/software/download>`_
-
-OpenStack
----------
-
-3) `OpenStack Liberty Release artifacts <http://www.openstack.org/software/liberty>`_
-
-4) `OpenStack documentation <http://docs.openstack.org>`_
-
-OpenDaylight
-------------
-
-5) `OpenDaylight artifacts <http://www.opendaylight.org/software/downloads>`_
-
-Fuel
-----
-6) `The Fuel OpenStack project <https://wiki.openstack.org/wiki/Fuel>`_
-
-7) `Fuel documentation overview <https://docs.fuel-infra.org/openstack/fuel/fuel-8.0/>`_
-
-8) `Fuel planning guide <https://docs.fuel-infra.org/openstack/fuel/fuel-8.0/mos-planning-guide.html>`_
-
-9) `Fuel quick start guide <https://docs.mirantis.com/openstack/fuel/fuel-8.0/quickstart-guide.html>`_
-
-10) `Fuel operations guide <https://docs.mirantis.com/openstack/fuel/fuel-8.0/operations.html>`_
-
-11) `Fuel Plugin Developers Guide <https://wiki.openstack.org/wiki/Fuel/Plugins>`_
-
-12) `Fuel OpenStack Hardware Compatibility List <https://www.mirantis.com/products/openstack-drivers-and-plugins/hardware-compatibility-list>`_
-
-Fuel in OPNFV
--------------
-
-13) `OPNFV Installation instruction for the Brahmaputra release of OPNFV when using Fuel as a deployment tool <http://artifacts.opnfv.org/fuel/brahmaputra/docs/installation-instruction.html>`_
-
-14) `OPNFV Build instruction for the Brahmaputra release of OPNFV when using Fuel as a deployment tool <http://artifacts.opnfv.org/fuel/brahmaputra/docs/build-instruction.html>`_
-
-15) `OPNFV Release Note for the Brahmaputra release of OPNFV when using Fuel as a deployment tool <http://artifacts.opnfv.org/fuel/brahmaputra/docs/release-notes.html>`_
diff --git a/docs/platformoverview/platformoverview.rst b/docs/platformoverview/platformoverview.rst
deleted file mode 100644
index 9a7068f..0000000
--- a/docs/platformoverview/platformoverview.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) Tim Irnich (tim.irnich@ericsson.com)
-
-SDNVPN platform components and features
----------------------------------------
-
-The SDN VPN feature enhances OPNFV's baseline OpenStack deployment with the
-possibility to configure BGP based VPNs according to the OpenStack Neutron
-Stadium project BGPVPN. The BGPVPN project consists of an API specification,
-framework implementation and a number of backend drivers (Bagpipe, OpenContrail,
-Nuage and OpenDaylight currently). In OPNFV Brahmaputra only the ODL backend
-is supported.
diff --git a/docs/scenarios/os-odl_l2-bgpvpn/scenario.description.rst b/docs/scenarios/os-odl_l2-bgpvpn/scenario.description.rst
index b7ef93a..4af9de6 100644
--- a/docs/scenarios/os-odl_l2-bgpvpn/scenario.description.rst
+++ b/docs/scenarios/os-odl_l2-bgpvpn/scenario.description.rst
@@ -6,15 +6,39 @@ Introduction
 ============
 .. In this section explain the purpose of the scenario and the types of capabilities provided
 
-Many telecom network functions are relying on layer-3 infrastructure services, within a VNF
+Many Telecom network functions are relying on layer-3 infrastructure services, within a VNF
 between components, or towards existing external networks. In many cases, these external
 networks are implemented in MPLS/BGP technology in existing service provider wide-area-networks (WAN).
-
 This proven technology provides a good mechanism for inter-operation of a NFV Infrastructure (NFVI)
-and wide-area networks (WAN) and is the main feature set provided by the BGP VPN project.
+and wide-area networks (WAN) and is the main capability provided by the OPNFV SDNVPN project.
+
+.. should we explain here what a deployment scenario is?
+The OPNFV SDNVPN feature is made available through additional OPNFV deployment scenarios, which are derived
+from the baseline scenarios os-odl_l2-nofeature and os-odl_l3-nofeature. This document
+provides an outline of the os-odl_l2-bgpvpn scenarios including guidelines and references to
+required installation, software and hardware configuration documents.
+
+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.
+
+The SDN VPN feature enhances OPNFV's baseline OpenStack deployment with the
+possibility to configure BGP based VPNs according to the OpenStack Neutron
+Stadium project BGPVPN. The BGPVPN project consists of a Neutron API extension and a
+service plugin which has a driver framework similar to the ML2 plugin. BGPVPN today
+has a quite large number of backend drivers (Bagpipe, OpenContrail,
+Nuage and OpenDaylight currently). In OPNFV, currently only the OpenDaylight driver
+is supported.
 
-This document provides an outline of the os-odl_l2-bgpvpn scenarios of OPNFV including
-guidelines and references to required installation, software and hardware configuration documents.
+The BGPVPN ODL driver maps the BGPVPN API onto the OpenDaylight VPNService, which exposes the data
+center overlay like a virtual router to which Neutron Networks and Routers (and in the future also Ports)
+are connected. The VPNService has access to the state of the Neutron API through the OpenDaylight
+Neutron Northbound Interface module, which has been enhanced to support the BGPVPN API extension.
+It uses an internal mesh of VxLAN tunnels to interconnect the vSwitches on the data
+center compute nodes. For the purpose of BGP based route exchange with other BGP speakers the ODL
+controller makes use of Quagga BGP as an external BGP speaker.
 
   <To be completed, this outlines the basic content and flow>
   Description of bgpvpn scenarios
@@ -26,12 +50,6 @@ guidelines and references to required installation, software and hardware config
   set up iptables to allow connections between OVS and ODL
   set up HA proxy so that ODL can be reached
 
-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.
-
   <Where applicable and without copying the installation procedure in the install guides>
   Describe Neutron BGPVPN additions (networking-bgpvpn)
   Neutron odl additions (networking-odl)
@@ -43,12 +61,37 @@ Scenario components and composition
 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,
+.. user.  This should be an "introduction" to the user guide document, and explicitly link to it,
 .. where the specifics of the features are covered including examples and API's
 
-  When would I use this scenario, what value does it provide?  Refer to the userguide for details
+  When would I use this scenario, what value does it provide?  Refer to the user guide for details
   of configuration etc...
 
+Configuring SDNVPN features
+---------------------------
+
+Each installer has specific procedures to deploy the OPNFV platform so that the SDNVPN feature is enabled.
+
+Fuel installer configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To install the SDNVPN feature using Fuel, follow the Fuel installation guide ensuring to select the SDNVPN
+feature when prompted <add link to Fuel docs once artifact locations are known>.
+
+This will trigger installation of the OpenStack BGPVPN API extension for
+Neutron, set up for using the ODL driver, in addition to vanilla Neutron.
+In addition, the required karaf features will be activated when ODL is installed and the compute nodes
+will be configured including the VPN Service internal transport tunnel mesh.
+
+No post-deploy configuration is necessary. The Fuel BGPVPN plugin and the ODL plugin
+should set up the cluster ready for BGPVPNs being created.
+
+APEX installer configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To install the SDNVPN feature using the APEX installer, follow the APEX installation guide and
+activate the SDNVPN feature when prompted.
+
 Limitations, Issues and Workarounds
 ===================================
 .. Explain scenario limitations here, this should be at a design level rather than discussing
@@ -59,8 +102,9 @@ Currently, in OPNFV only ODL is supported as a backend for BGPVPN. API calls are
 mapped onto the ODL VPN Service REST API through the BGPVPN ODL driver and the
 ODL Neutron Northbound module.
 
-Are there places these basic procedures will not work.  Do we have constraints on the use of
-Quagga that may change in the future?
+No DPDK-enabled vhost user ports
+
+Integration with data center gateway will not work due to missing OVS patches for MPLSoGRE.
 
 References
 ==========
diff --git a/docs/userguide/feature.userguide.rst b/docs/userguide/feature.userguide.rst
index a531fe2..deb22e9 100644
--- a/docs/userguide/feature.userguide.rst
+++ b/docs/userguide/feature.userguide.rst
@@ -1,6 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. (c) Tim Irnich, (tim.irnich@ericsson.com) and others
+.. (c) Tim Irnich, Nikolas Hermanns, Christopher Price and others
 
 Introduction
 ============
@@ -8,22 +8,193 @@ Introduction
 .. to ensure the user understand the context for the user guide instructions to follow.
 
 This document will provide an overview of how to work with the SDN VPN features in
-OPNFV.  For a description of the scenarios and their provided capabilities refer to
-the scenario description document:
-http://artifacts.opnfv.org/colorado/sdnpvn/scenarios/os-odl_l2-bgpvpn/index.html
+OPNFV.
 
 SDN VPN feature description
 ===========================
 .. Describe the specific usage for <XYZ> feature.
 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 
-The BGPVPN feature enables creation of BGP VPNs according to the OpenStack
+A high-level description of the scenarios is provided in this section.
+For details of the scenarios and their provided capabilities refer to
+the scenario description document:
+http://artifacts.opnfv.org/colorado/sdnpvn/scenarios/os-odl_l2-bgpvpn/index.html
+
+The BGPVPN feature enables creation of BGP VPNs on the Neutron API according to the OpenStack
 BGPVPN blueprint at https://blueprints.launchpad.net/neutron/+spec/neutron-bgp-vpn.
 In a nutshell, the blueprint defines a BGPVPN object and a number of ways
-how to associate it with the existing Neutron object model, including a unique
+how to associate it with the existing Neutron object model, as well as a unique
 definition of the related semantics. The BGPVPN framework supports a backend
 driver model with currently available drivers for Bagpipe, OpenContrail, Nuage
-and OpenDaylight.
+and OpenDaylight. The OPNFV scenario makes use of the OpenDaylight driver and backend
+implementation through the ODL VPNService project.
+
+Hardware requirements
+=====================
+
+The SDNVPN scenarios can be deployed as a bare-metal or a virtual environment on a single host.
+
+Bare metal deployment on Pharos Lab
+-----------------------------------
+
+Hardware requirements for bare-metal deployments of the OPNFV infrastructure are specified
+by the Pharos project. The Pharos project provides an OPNFV hardware specification for
+configuring your hardware at: http://artifacts.opnfv.org/pharos/docs/pharos-spec.html.
+
+Virtual deployment hardware requirements
+----------------------------------------
+
+To perform a virtual deployment of an OPNFV scenario on a single host, that host has to
+meet the hardware requirements outlined in the <missing spec>.
+
+When ODL is used as an SDN Controller in an OPNFV virtual deployment, ODL is
+running on the OpenStack Controller VMs. It is therefore recommended to
+increase the amount of resources for these VMs.
+
+Our recommendation is to have 2 additional virtual cores and 8GB additional virtual memory
+on top of the normally recommended configuration.
+
+Together with the commonly used recommendation this sums up to:
+::
+
+ 4 virtual cores
+ 16 GB virtual memory
+
+See in Installation section below how to configure this.
+
+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 <scenario> scenario some preparation of the
+machine that will host the Fuel VM 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 \
+                  python-novaclient python-neutronclient python-glanceclient \
+                  python-keystoneclient debtcollector netifaces enum
+
+Download the source code and artifact
+-------------------------------------
+To be able to install the scenario os-odl_l2-bgpvpn one can follow the way
+CI is deploying the scenario.
+First of all the opnfv-fuel repository needs to be cloned:
+::
+
+ git clone ssh://<user>@gerrit.opnfv.org:29418/fuel
+
+This command downloads the whole repository fuel. We need now to switch it to
+the stable Colorado branch:
+::
+
+ cd fuel
+ git checkout stable/colorado
+
+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-bgpvpn-ha or
+os-odl_l2-bgpvpn-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 <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: 100G
+   controller: 100G
+   compute: 100G
+
+ define_vms:
+   controller:
+     vcpu:
+       value: 4
+     memory:
+       attribute_equlas:
+         unit: KiB
+       value: 16388608
+     currentMemory:
+       attribute_equlas:
+         unit: KiB
+       value: 16388608
+
+
+Check if the default settings in dea.yaml are in line with your intentions
+and make changes as required.
+
+Installation procedures
+-----------------------
+
+We describe several alternative procedures in the following.
+
+Go to
+::
+
+ cd <opnfv-fuel-repo>/ci
+
+Full automatic virtual deployment High Availablity Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following command will deploy the high-availability flavor of SDNVPN scenario os-odl_l2-bgpvpn-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-bgpvpn-ha -i file://<path-to-fuel-iso>
+
+Full automatic virtual deployment NO High Availability Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following command will deploy the SDNVPN scenario in its non-high-availability flavor. 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-bgpvpn-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 autodeploy the Fuel host and to run host selection, role assignment and SDNVPN 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-bgpvpn-ha -i file://<path-to-fuel-iso> -e
+
+With -e option the installer does not launch environment deployment, so
+a user can do some modification before the scenario is really deployed.
+
+Another interesting option is the -f option which deploys the scenario using an existing Fuel host.
 
 Feature and API usage guidelines and example
 ============================================