Review and finalize platformoverview

Jira: DOCS-42
Collected all comments.
Many comments done, open points marked in commentary (".. text")
Patchset 2: resolve most of the comments. Don't merge yet.

Change-Id: I3d676a6510ff3c3190110773649265a182b6f762
Signed-off-by: ulik <ulrich.kleber@huawei.com>

4 files changed, 303 insertions, 105 deletions

diff --git a/docs/platformoverview/deploymenttools.rst b/docs/platformoverview/deploymenttools.rst
index 1cbf3bb71..a8037184a 100644
--- a/docs/platformoverview/deploymenttools.rst
+++ b/docs/platformoverview/deploymenttools.rst
@@ -12,36 +12,36 @@ The installers will deploy the target platform onto a set of virtual or bare met
 to the configuration files. After the deployment, it doesn't matter which of the installers had been used
 to deploy the target scenario.
 
-
-Apex
-====
-
-Apex is an OPNFV Installation tool based on RDO Manager that deploys OPNFV using the RDO Project
+**Apex** is an OPNFV Installation tool based on RDO Manager that deploys OPNFV using the RDO Project
 OpenStack Distribution.
 RDO manager is a Triple-O based installation tool.
 Triple-O is an image based life cycle deployment tool that is a member of the OpenStack Big Tent Governance.
-
 Apex uses Centos on all target platforms and can deploy all SDN controllers.
+Find more information at
+`OpenStack Wiki for Triple-O <https://wiki.openstack.org/wiki/Tripleo>`_ and the OPNFV user guide and
+config guide.
 
-Compass
-=======
-
-Compass is an installer project based on open source project Compass, which provides automated deployment
+**Compass** is an installer project based on open source project Compass, which provides automated deployment
 and management of OpenStack and other distributed systems.
 It can be considered as what the LiveCD to a single box for a pool of servers – bootstrapping the server pool.
-
 Compass is based on Ansible.
 It can deploy Ubuntu or Centos as target operating system and ODL and ONOS as SDN controllers.
-
-
-Fuel
-====
-
-Editors note:
-Just a high level intro and link to the main fuel documents.
-
-Joid
-====
-
-Editors note:
-Just a high level intro and link to the main joid documents.
+Find more information at
+`OpenStack Wiki for Compass <https://wiki.openstack.org/wiki/Complass>`_ and the OPNFV user guide and
+config guide.
+
+**Fuel** is an installer project based on the Fuel OpenStack open source project
+providing automated deployment and management of OpenStack and other distributed systems.
+Fuel is based on puppet and deploys the Ubuntu Linux operating system;
+the OpenStack virtual Infra-structure manager, and OpenDaylight or ONOS SDN controllers.
+Find more information at
+`OpenStack Wiki for Fuel <https://wiki.openstack.org/wiki/Fuel>`_ and the OPNFV user guide and
+config guide.
+
+**Joid** installer utilizes the technology developed in Juju and MAAS.
+Juju allows you to deploy, configure, manage, maintain, and scale
+cloud services quickly and efficiently on public clouds, as well as on physical servers,
+OpenStack, and containers. Together with MAAS hardware usage can be optimized.
+For more info on Juju and MAAS, please visit `<https://jujucharms.com/>`_,
+`<http://maas.ubuntu.com>`_ and the
+`Joid Userguide <http://artifacts.opnfv.org/joid/docs/userguide/userguide.pdf>`_.
diff --git a/docs/platformoverview/introduction.rst b/docs/platformoverview/introduction.rst
index dcc7a49de..0c878afbb 100644
--- a/docs/platformoverview/introduction.rst
+++ b/docs/platformoverview/introduction.rst
@@ -2,13 +2,17 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Huawei
 
+.. ==> All actions still to be resolved during the review are marked "==>" in comments.
+
 ============
 Introduction
 ============
 
+.. ==> take some more inputs from the marketing message
+
 OPNFV is an integration effort that takes outputs from several open source communities to build a NFV platform. This task of integration leads to providing different kinds of output to its users.
 
-First of all there is of course the **target software platform**, which is a integrated solution
+The primary goal of the OPNFV project is the **target software platform**, which is a integrated solution
 of a set of components/building blocks of the ETSI ISG NFV reference architecture.
 In the Brahmaputra release, this is limited to the NFVI and VIM blocks.
 OPNFV users will be able to deploy their VNFs there using some MANO solution.
@@ -40,7 +44,7 @@ It will execute and test major functions of the platform relevant to NFV applica
 the user can be confident that VNFs can successfully run.
 
 Of course, the OPNFV releases come with the necessary **documentation**, describing
-target software platform, deployment tools, tests, etc. in their architecture and usage.
+target software platform, deployment tools, tests, etc. in their architecture, configuration and usage.
 The most important documents here are configuration guides and user guides that help to set up
 a OPNFV deployment and use it.
 
@@ -48,6 +52,8 @@ The OPNFV project takes major effort to provide **lab environments** to the comm
 The OPNFV community labs of course need to be Pharos-compliant. They are used for OPNFV development
 tasks and release creation, but should also provide users with the opportunity to run their own
 OPNFV tests. OPNFV community labs are not part of a OPNFV release.
+Please find more information on the labs in the
+`Pharos project documentation <http://artifacts.opnfv.org/pharos/docs/index.html>`_.
 
 We should also mention that OPNFV works on **requirements** of open source projects used in OPNFV to
 make these projects better suitable for NFV telco carrier use cases.
@@ -56,8 +62,7 @@ to the "upstream" projects in the format required by these projects.
 These requirement documents are not bound to OPNFV releases.
 
 OPNFV bundles the target software, installers, documentation, test cases and lab
-description to **releases** and provides documentation describing the scope and features
-provided.
+description to **releases**.
 
 This overview document introduces these components and scenarios on a high level and
 points you to more detailed documentation.
diff --git a/docs/platformoverview/softwarearchitecture.rst b/docs/platformoverview/softwarearchitecture.rst
index 43a5022c7..a3e815ec5 100644
--- a/docs/platformoverview/softwarearchitecture.rst
+++ b/docs/platformoverview/softwarearchitecture.rst
@@ -2,37 +2,94 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Huawei
 
-========================
-Target software platform
+===========================
+OPNFV Platform Architecture
+===========================
+
+.. ==> Add reference links from https://wiki.opnfv.org/releases/brahmaputra/releasedocs
+
+.. ==> All links should point to release docs, not to OPNFV-Wiki or artifacts.
+
+
+OPNFV Lab Infrastructure
 ========================
 
+The `Pharos Project <https://www.opnfv.org/developers/pharos>`_ provides a lab infrastructure
+that is geographically and technically diverse.
+Labs instantiate **bare-metal** and **virtual** environments that are accessed remotely by the
+community and used for OPNFV platform and feature development, builds, deploys and testing.
+This will greatly assist in developing a highly robust and stable OPNFV platform
+with well understood performance characteristics.
+
+Community labs are hosted by OPNFV member companies on a voluntary basis.
+The Linux Foundation also hosts an OPNFV lab that provides centralised CI
+and other production resources which are linked to community labs.
+Future lab capabilities will include the ability easily automate deploy and test of any
+OPNFV install scenario in any lab environemnt as well as a *Virtual Lab* for
+developer on-boarding with minimal effort.
+
+.. ==> I am not sure this is the best place to include this.
+
+
 Software architecture
 =====================
 
 This section will provide information which upstream projects, versions and components are
-integrated in the Brahmaputra release
+integrated in the release to implement OPNFV requirement. You can find a requirement list
+`here <http://artifacts.opnfv.org/genesisreq/docs/requirements.pdf>`_.
 
 OpenStack
 ---------
 
+.. ==> didn't understand Chris' suggestion about reducing the heading level for these sub-topics
+
 OPNFV uses OpenStack as cloud management system.
-Brahmaputra is based on OpenStack Liberty Release. It comprises the following sub-projects
-and modules:
-
-* Nova (Compute)
-* Neutron (Network)
-* Cinder (Block Storage)
-* Swift (Object Storage)
-* Ceilometer (Telemetry)
-* Keystone (Identity)
-* Glance (Image Service)
-* Heat (Orchestration)
-* etc.
+Brahmaputra is based on OpenStack Liberty Release.
+The set of sub-projects varies slightly depending on the installer.
+
+.. ==> If possible replace the list of OpenStack components here by a link to an
+.. appropriate document
+.. (http://artifacts.opnfv.org/genesisreq/review/10155/requirements/component-support.html
+.. was suggested, but this is different infomation.)
+
+The following table shows which components are deployed.
+
++------------+----------------+-----------+-----------+-----------+-----------+
+| services   | type           | Apex      | Compass   | Fuel      | Joid      |
++============+================+===========+===========+===========+===========+
+| ceilometer | metering       | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| cinder     | volume         | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| cloud      | cloudformation | ---       | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| glance     | image          | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| heat       | orchestration  | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| keystone   | identity       | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| neutron    | network        | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| nova       | compute        | Available | Available | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+| swift      | object-store   | Available | ---       | Available | Available |
++------------+----------------+-----------+-----------+-----------+-----------+
+
+.. This table is created by outputs from jenkins functest log, components registering at keystone
+.. would prefer a table per scenario.
 
 Some of the sub-projects are not deployed in all scenarios.
-Besides target software, also deployment and test framework use OpenStack components
-(Fuel, Tempest, Rally)
 
+.. end of the part to be replaced by link if possible.
+
+Note that additional components of OpenStack are used as part of deployment tools and test frameworks
+(Fuel, Tempest, Rally).
+
+For more information about the OpenStack features and usage refer to the
+`official OpenStack documentation page <http://docs.openstack.org/>`_.
+Please ensure that you have the Liberty release selected at the
+``More Releases & Languages`` drop down menu.
 
 Operating System
 ----------------
@@ -47,67 +104,82 @@ CentOS 7 supported by Apex and Compass
 SDN Controllers
 ---------------
 
-OPNFV Brahmaputra release supports three different SDN controllers:
-
-* OpenDaylight (ODL, Beryllium release)
-* ONOS (Emu release)
-* OpenContrail (?)
+OPNFV Brahmaputra release supports different SDN controllers.
+Some scenarios don't use an SDN controller but rely just on **Neutron** networking capabilities.
 
 Depending on the SDN controller you are using, the featureset will vary.
 Brahmaputra also provides scenarios without an SDN controller, just using OpenStack Neutron.
 
-OpenDaylight
-++++++++++++
+The OpenDaylight project is a collaborative open source project that aims to accelerate
+adoption of Software-Defined Networking (SDN) and Network Functions Virtualization
+(NFV) with a transparent approach that fosters new innovation.
+
+**OpenDaylight** is an SDN controller that aims to accelerate
+adoption of Software-Defined Networking (SDN) and Network Functions Virtualization
+(NFV) with a transparent approach that fosters new innovation.
+OpenDaylight runs within a JVM and is installed in OPNFV within a container and integrated with OpenStack
+using the ODL device driver. The Brahmaputra release of OPNFV integrates the Beryllium release.
+You can find more information about OpenDaylight among the release artifacts at the
+`Downloads page <https://www.opendaylight.org/downloads>`_.
+Please ensure you are using the Beryllium documentation.
+
+**ONOS** is an SDN controller written in Java with a distributed architecture with special focus to
+support scalability, fault tolerance and hardware and software upgrades without
+interrupting network traffic.
+More information on the internal design of ONOS may be found in
+`User's Guide <https://wiki.onosproject.org/display/ONOS/User's+Guide>`_ and
+`Architecture+Guide <https://wiki.onosproject.org/display/ONOS/Architecture+Guide>`_ on the
+`wiki of the ONOS project <https://wiki.onosproject.org>`_.
+ONOS is integrated to OPNFV using a framework ONOSFW and Neutron plugins. Details can be found in the
+ONOS specific OPNFV documents,
 
-Editor's note:
-We need a high level paragraph here and a description of how we use ODL.
+`Design guide <http://artifacts.opnfv.org/onosfw/brahmaputra/docs/design/design.pdf>`_,
+`User guide <http://artifacts.opnfv.org/onosfw/brahmaputra/docs/userguide/index.html>`_ and
+`Config guide <http://artifacts.opnfv.org/onosfw/brahmaputra/docs/configguide/index.html>`_.
 
+.. **OpenContrail** SDN controller will be supported in the next drop of the Brahmaputra release.
 
-ONOS
-++++
 
-.. ONOS intro shortened from https://wiki.onosproject.org/pages/viewpage.action?pageId=2851517
+Data Plane
+----------
 
-ONOS stands for **O** pen **N** etwork **O** perating **S** ystem. ONOS provides the control plane
-for a software-defined network (SDN), managing network components, such as switches and links,
-and running software programs or modules to provide communication services to end hosts and
-neighboring networks.
+OPNFV extends Linux's virtual networking capabilies by using virtual switch
+and router components including improving those components by requirements
+specific to telco use cases.
 
-ONOS provides a platform for SDN applications and use cases for routing, management, or
-monitoring services for software-defined networks.
+For instance some scenarios use **OpenVSwich**
+to replace Linux bridges as it offers advantages in terms of mobility, hardware
+integration and use by network controllers. OPNFV leverages these by upgrade
+to a specific installation using user-space datapath. This includes changes to
+other dataplane components, including libvirt, qemu, DPDK etc.
+Please find more information in
+`OVSNFV User's Guide <http://artifacts.opnfv.org/ovsnfv/docs/userguides/userguides.pdf>`_
 
-ONOS can run as a distributed system across multiple servers, allowing it to use the CPU and
-memory resources of multiple servers while providing fault tolerance in the face of server
-failure and potentially supporting live/rolling upgrades of hardware and software without
-interrupting network traffic.
+.. ==> need input, if we mention other components
 
-The ONOS kernel and core services, as well as ONOS applications, are written in Java as bundles
-that are loaded into the Karaf OSGi container. OSGi is a component system for Java that allows
-modules to be installed and run dynamically in a single JVM.
+Other Components
+----------------
 
-More information on the internal design of ONOS may be found in
-`User's Guide <https://wiki.onosproject.org/display/ONOS/User's+Guide>`_ and
-`Architecture+Guide <https://wiki.onosproject.org/display/ONOS/Architecture+Guide>`_ on the
-`wiki of the ONOS project <https://wiki.onosproject.org>`_.
+**KVM**
 
-ONOS is integrated to OPNFV using a framework ONOSFW and Neutron plugins. Details can be found in the
-ONOS specific OPNFV documents:
+NFV infrastructure has special requirements on hypervisors with respect of
+interrupt latency (timing correctness and packet latency in data plane) and
+live migration.
 
-.. Link to be added.
+Besides additional software changes, this requires
+some adjustments to system configuration
+information, like hardware, BIOS, OS, etc.
 
+.. KVM4NFV is one implementation, we have three implementations of the OS virtualization layer
+.. to capture here.
+.. ==> need more input
 
-OpenContrail
-++++++++++++
+Please find more information at
+`KVM4NFV project documentation <http://artifacts.opnfv.org/kvmfornfv/docs/all/all.pdf>`_
 
-Editors note:
-We need a high level paragraph here and a description of how we use OpenContrail, including
-its vRouter capabilities.
+.. As it is a platform overview I think if we mention KVM as hypervisor we should focus on which version we are using and how as opposed to the OPNFV project that deals with KVM itself.
 
-Data Plane
-----------
 
-Other Components
-----------------
 
 Deployment Architecture
 =======================
@@ -124,29 +196,50 @@ is a virtual machine and provides the virtual resources using nested virtualizat
 
 The initial deployment is done using a so-called "jumphost". This server (either bare metal
 or virtual) is first installed with the installer program that then installs OpenStack
-and other components on the controller nodes and compute nodes. See the installer
-documentation for more details.
+and other components on the controller nodes and compute nodes. See the
+`OPNFV user guide <http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/userguide/userguide.pdf>`_
+for more details.
+
+.. Editors note:
+.. In a second level of detail, describe how software is distributed over the 3 controller
+.. nodes, compute nodes and other hardware.
+
+
+In Brahmaputra, different scenarios can be deployed to provide the different feature sets, e.g.
+HA, IPV6, BGPVPN, KVM, or select the different implementations, e.g. SDN controllers.
+
+.. ==> Is it described somewhere what we mean by scenarios? If yes, then the original text is better.
+.. If not, I would give a brief overview here to describe the term.
 
-Editors note:
-In a second level of detail, describe how software is distributed over the 3 controller
-nodes, compute nodes and other hardware.
+The following scenarios are supported, some of them can be deployed using different installers.
 
-In Brahmaputra, the following scenarios are supported:
+* nosdn-nofeature
+* odl_l2-ha
+* odl_l3-ha
+* odl_l2-bgpvpn-noha
+* onos-ha
+* nosdn-ovs-ha
+* nosdn-kvm-ha
+* nosdn-ovs_kvm-ha
 
+Please find more information at
+`<https://wiki.opnfv.org/functextnexttaks>`_
 
+.. ==> As soon as better information is available, the list can be replaced by a link to e.g.
+.. http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/configoptions.html#opnfv-scenario-s.
 
 
-Dynamic View
-============
+.. Dynamic View
+.. ============
 
-Editors note: we might skip this section completely for Brahmaputra.
+.. Editors note: we might skip this section completely for Brahmaputra.
 
-Or we provide rather short statements. In later versions, we have to describe which
-software is involved in which way during:
+.. Or we provide rather short statements. In later versions, we have to describe which
+.. software is involved in which way during:
 
-* VNF Life Cycle (onboarding, instantiate, scaling): we can reference to other documents
-* Hardware Life Cycle (mainly how to add compute nodes, but also other cases)
-* ...
+.. * VNF Life Cycle (onboarding, instantiate, scaling): we can reference to other documents
+.. * Hardware Life Cycle (mainly how to add compute nodes, but also other cases)
+.. * ...
 
 
 
diff --git a/docs/platformoverview/testcasesframework.rst b/docs/platformoverview/testcasesframework.rst
index 6a40e282d..301e1e0b4 100644
--- a/docs/platformoverview/testcasesframework.rst
+++ b/docs/platformoverview/testcasesframework.rst
@@ -2,9 +2,109 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Huawei
 
-=======================
-Testcases and Framework
-=======================
+=================
+Testing ecosystem
+=================
+
+Testing is a key area and also a challenge for OPNFV in order to be able to
+verify and validate the platform we are creating.
+
+This is a complex task as we have to test the integration of the components,
+the functionality we are creating and using and we have to verify
+that the platform is suitable for telecom applications.
+We do testing in an automated fashion by using several test tools and frameworks in our CI/CD pipeline.
+
+This chapter gives an overview about our testing tools and activities.
+
+
+Release verification
+====================
+
+OPNFV releases the target platform together with the deployment tools in a set of scenarios
+that provides choices regarding the deployed components and the available features.
+The scenarios and the provided functionality are tested automatically in the CI/CD pipeline
+mentioned above and they are considered to be ready for release after
+at least 4 successful consecutive iterations.
+
+The functional testing and the platform validation are divided between two projects called Functest and Yardstick.
+
+Functest
+--------
+
+Functest provides a functional testing framework along with a set of test suites
+and test cases that test and verify OPNFV platform functionality.
+The scope of Functest and relevant test cases can be found in its
+`user guide <http://artifacts.opnfv.org/functest/brahmaputra/docs/userguide/userguide.pdf>`_.
+
+In Brahmaputra, Functest is focusing on OpenStack and SDN controllers deployment testing.
+Its testing framework combines a number of testing tools
+to verify the key components of OPNFV platform running successfully.
+For example, Rally and Tempest are integrated for OpenStack basic functional testing and benchmark,
+Robot is used for ODL testing, and Teston is integrated for ONOS testing.
+Besides these, Functest also includes tests by deploying candidate VNFs such as vPing and vIMS, and testing their basic functionality.
+
+Yardstick
+---------
+
+Yardstick is a testing project for verifying the infrastructure compliance when running VNF applications.
+Yardstick can benchmark a number of characteristics/performance vectors about the infrastructure,
+that makes it become a useful pre-deployment NFVI testing tools.
+
+Yardstick is also a flexible testing framework supporting OPNFV feature testing by the various projects in OPNFV.
+Projects can plug in their test cases for specific features easily.
+
+The detail of Yardstick project can be found in the
+`yardstick user guide <http://artifacts.opnfv.org/yardstick/brahmaputra/docs/user_guides_framework/user_guides_framework.pdf>`_.
+
+There are two types of test cases in Yardstick: Yardstick generic test cases and OPNFV feature test cases.
+Yardstick generic test cases include basic characteristics benchmarking in compute/storage/network area.
+OPNFV feature test cases include basic telecom feature testing from OPNFV projects,
+for example nfv-kvm, sfc, ipv6, Parser, Availability and SDN VPN.
+
+All of the Yardstick test cases are listed on
+`<http://artifacts.opnfv.org/yardstick/docs/configguide_yardstick_testcases/03-list-of-tcs.html>`_
+
+
+Additional Testing
+==================
+
+Besides the test suites and cases for release verification, there are some additional testing
+for specific feature or characteristics on OPNFV platform.
+These testing framework and test cases may include some specific needs,
+such as extended measurements, or additional testing stimuli, or tests which cause disturbances on the environment.
+These additional testing can provide a more complete evaluation about OPNFV platform deployment.
+
+Qtip
+----
+
+Qtip is a performance benchmark testing project by using a "Bottom-Up" approach
+in characterizing and benchmarking OPNFV platform.
+Qtip aims to benchmark the performance of components for a quantitative analysis and doesn't deal with validation of the platform.
+
+In Brahmaputra, Qtip develops a flexible framework,
+adds a number of test cases covering compute/storage/network area,
+and compares these benchmarks on a bare metal machine vs a VM.
+These contrastive result can be used to evaluate the performance of these components on the OPNFV platform basically.
+
+VSPERF
+------
+
+VSPERF will develop a generic and architecture agnostic vSwitch testing framework and associated tests,
+that will serve as a basis for validating the suitability of different vSwitch implementations
+in a Telco NFV deployment environment.
+The output of this project will be utilized as part of OPNFV Platform and VNF level testing and validation.
+
+Bottlenecks
+-----------
+
+Bottlenecks will provide a framework to find system bottlenecks
+by testing and verifying OPNFV infrastructure in a staging environment before committing it to a production environment.
+The Bottlenecks framework can not only find specific system limitations and bottlenecks,
+but also the root cause of these bottlenecks.
+
+In Brahmaputra, Bottlenecks includes two test cases:
+rubbos and vstf. These test cases are executed on OPNFV community pods,
+and test result report are visible on the community testing dashboard.
+
+
 
-Editors note:
-Just a high level description about the different types of tests and the role of yardstick as central framework.