summaryrefslogtreecommitdiffstats
path: root/docs/configurationguide
diff options
context:
space:
mode:
authorswatisharma <swatix.sharma@intel.com>2016-08-18 21:06:56 +0530
committerswatisharma <swatix.sharma@intel.com>2016-08-19 17:16:30 +0530
commit5a56bf69988b7c72e88546eb4659576fb51bfb77 (patch)
treef2484c75795c41b596e4671aab33d7edcdb88e42 /docs/configurationguide
parent2aa991a490387f3910a7e1bf02de83a7efb28014 (diff)
OPNFV KVM4NFV: Documentation
This patch contains the full documentation required for KVM4NFV project. The documents are organized into the following sections- user guide, configuration guide, installation guide. requirement document, design document, release notes and glossary. Co-Authored-By: Gundarapu Reddy <reddyx.gundarapu@intel.com> Signed-off-by: Swati Sharma <swatix.sharma@intel.com>
Diffstat (limited to 'docs/configurationguide')
-rw-r--r--docs/configurationguide/abstract.rst16
-rw-r--r--docs/configurationguide/configuration.options.render.rst23
-rw-r--r--docs/configurationguide/images/brahmaputrafeaturematrix.jpgbin0 -> 62966 bytes
-rw-r--r--docs/configurationguide/images/brahmaputrascenariomatrix.jpgbin0 -> 51071 bytes
-rw-r--r--docs/configurationguide/images/weather-clear.jpgbin0 -> 1286 bytes
-rw-r--r--docs/configurationguide/images/weather-dash.jpgbin0 -> 1010 bytes
-rw-r--r--docs/configurationguide/images/weather-few-clouds.jpgbin0 -> 1348 bytes
-rw-r--r--docs/configurationguide/images/weather-overcast.jpgbin0 -> 1215 bytes
-rw-r--r--docs/configurationguide/index.rst16
-rw-r--r--docs/configurationguide/low-latency.feature.configuration.description.rst93
-rw-r--r--docs/configurationguide/os-nosdn-kvm-ha.description.rst126
-rw-r--r--docs/configurationguide/scenariomatrix.rst100
12 files changed, 374 insertions, 0 deletions
diff --git a/docs/configurationguide/abstract.rst b/docs/configurationguide/abstract.rst
new file mode 100644
index 000000000..a5066c284
--- /dev/null
+++ b/docs/configurationguide/abstract.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
+
+========
+Abstract
+========
+
+This document provides guidance for the configurations available in the
+Colorado release of OPNFV.
+
+The release includes four installer tools leveraging different technologies;
+Apex, Compass4nfv, Fuel and JOID, which deploy components of the platform.
+
+This document also includes the selection of tools and components including
+guidelines for how to deploy and configure the platform to an operational
+state.
diff --git a/docs/configurationguide/configuration.options.render.rst b/docs/configurationguide/configuration.options.render.rst
new file mode 100644
index 000000000..93add7755
--- /dev/null
+++ b/docs/configurationguide/configuration.options.render.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+======================
+Configuration Options
+======================
+
+OPNFV provides a variety of virtual infrastructure deployments called scenarios
+designed to host virtualised network functions (VNF's). KVM4NFV scenarios
+provide specific capabilities and/or components aimed to solve specific
+problems for the deployment of VNF's. KVM4NFV scenario includes components
+such as OpenStack,KVM etc. which includes different source components or
+configurations.
+
+KVM4NFV Scenarios
+===================
+
+Each KVM4NFV scenario provides unique features and capabilities, it is
+important to understand your target platform capabilities before installing
+and configuring. This configuration guide outlines how to install and
+configure components in order to enable the features required.
+
+.. include:: scenariomatrix.rst
diff --git a/docs/configurationguide/images/brahmaputrafeaturematrix.jpg b/docs/configurationguide/images/brahmaputrafeaturematrix.jpg
new file mode 100644
index 000000000..0d2a12279
--- /dev/null
+++ b/docs/configurationguide/images/brahmaputrafeaturematrix.jpg
Binary files differ
diff --git a/docs/configurationguide/images/brahmaputrascenariomatrix.jpg b/docs/configurationguide/images/brahmaputrascenariomatrix.jpg
new file mode 100644
index 000000000..84fc87a76
--- /dev/null
+++ b/docs/configurationguide/images/brahmaputrascenariomatrix.jpg
Binary files differ
diff --git a/docs/configurationguide/images/weather-clear.jpg b/docs/configurationguide/images/weather-clear.jpg
new file mode 100644
index 000000000..011ad52e9
--- /dev/null
+++ b/docs/configurationguide/images/weather-clear.jpg
Binary files differ
diff --git a/docs/configurationguide/images/weather-dash.jpg b/docs/configurationguide/images/weather-dash.jpg
new file mode 100644
index 000000000..3bf98dd27
--- /dev/null
+++ b/docs/configurationguide/images/weather-dash.jpg
Binary files differ
diff --git a/docs/configurationguide/images/weather-few-clouds.jpg b/docs/configurationguide/images/weather-few-clouds.jpg
new file mode 100644
index 000000000..51994ee84
--- /dev/null
+++ b/docs/configurationguide/images/weather-few-clouds.jpg
Binary files differ
diff --git a/docs/configurationguide/images/weather-overcast.jpg b/docs/configurationguide/images/weather-overcast.jpg
new file mode 100644
index 000000000..bdc1e0487
--- /dev/null
+++ b/docs/configurationguide/images/weather-overcast.jpg
Binary files differ
diff --git a/docs/configurationguide/index.rst b/docs/configurationguide/index.rst
new file mode 100644
index 000000000..6ad3b282c
--- /dev/null
+++ b/docs/configurationguide/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
+
+*************************
+OPNFV Configuration Guide
+*************************
+Colorado 1.0
+------------
+
+.. toctree::
+ :maxdepth: 2
+
+ ./abstract.rst
+ ./configuration.options.render.rst
+ ./low-latency.feature.configuration.description.rst
+ ./os-nosdn-kvm-ha.description.rst
diff --git a/docs/configurationguide/low-latency.feature.configuration.description.rst b/docs/configurationguide/low-latency.feature.configuration.description.rst
new file mode 100644
index 000000000..bb2bbd1ba
--- /dev/null
+++ b/docs/configurationguide/low-latency.feature.configuration.description.rst
@@ -0,0 +1,93 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Introduction
+============
+
+In KVM4NFV project, we focus on the KVM hypervisor to enhance it for NFV, by
+looking at the following areas initially
+
+* Minimal Interrupt latency variation for data plane VNFs:
+ * Minimal Timing Variation for Timing correctness of real-time VNFs
+ * Minimal packet latency variation for data-plane VNFs
+* Inter-VM communication,
+* Fast live migration
+
+Configuration of Cyclictest
+===========================
+
+Cyclictest measures Latency of response to a stimulus. Achieving low latency
+with the KVM4NFV project requires setting up a special test environment.
+This environment includes the BIOS settings, kernel configuration, kernel
+parameters and the run-time environment.
+
+* For more information regarding the test environment, please visit
+ https://wiki.opnfv.org/display/kvm/KVM4NFV+Test++Environment
+ https://wiki.opnfv.org/display/kvm/Nfv-kvm-tuning
+
+Pre-configuration activities
+----------------------------
+
+Intel POD1 is currently used as OPNFV-KVM4NFV test environment. The latest
+build packages are downloaded onto Intel Pod1-jump server from artifact
+repository. Yardstick running in a ubuntu docker container on Intel Pod1-jump
+server will trigger the cyclictest.
+
+Running cyclictest through Yardstick will Configure the host(Pod1-node1), the
+guest, executes cyclictest on the guest.
+
+The following scripts are used for configuring host and guest to create a
+special test environment and achieve low latency.
+
+**host-setup0.sh**: On running this script will install latest kernel rpm
+on host and will make necessary changes as following to create special test
+environment
+
+ * Isolates CPUs from the general scheduler
+ * Stops timer ticks on isolated CPUs whenever possible
+ * Stops RCU callbacks on isolated CPUs
+ * Enables intel iommu driver and disables DMA translation for devices
+ * Sets HugeTLB pages to 1GB
+ * Disables machine check
+ * Disables clocksource verification at runtime
+
+**host-setup1.sh**: On running this script will make following test
+environment changes
+
+ * Disabling watchdogs to reduce overhead
+ * Disabling RT throttling
+ * Reroute interrupts bound to isolated CPUs to CPU 0
+ * Change the iptable so that we can ssh to the guest remotely
+
+**host-run-qemu.sh**: On running this script will launch a guest vm on host.
+ Note: download guest disk image from artifactory
+
+**guest-setup0.sh**: On running this scrcipt on guest vm will install the
+latest build kernel rpm, cyclictest and makes following configuration on
+guest vm.
+
+ * Isolates CPUs from the general scheduler
+ * Stops timer ticks on isolated CPUs whenever possible
+ * Uses polling idle loop to improve performance
+ * Disables clocksource verification at runtime
+
+**guest-setup1.sh**: On running this script on guest vm will make following
+configurations
+
+ * Disable watchdogs to reduce overhead
+ * Routes device interrupts to non-RT CPU
+ * Disables RT throttling
+
+Hardware configuration
+----------------------
+
+Currently Intel POD1 is used as test environment for kvmfornfv to execute
+cyclictest. As part of this test environment Intel pod1-jump is configured as
+jenkins slave and all the latest build artifacts are downloaded on to it.
+Intel pod1-node1 is the host on which a guest vm will be launched as a part of
+running cylictest through yardstick.
+
+* For more information regarding hardware configuration, please visit
+ https://wiki.opnfv.org/display/pharos/Intel+Pod1
+ https://build.opnfv.org/ci/computer/intel-pod1/
+ http://artifacts.opnfv.org/octopus/brahmaputra/docs/octopus_docs/opnfv-jenkins-slave-connection.html
diff --git a/docs/configurationguide/os-nosdn-kvm-ha.description.rst b/docs/configurationguide/os-nosdn-kvm-ha.description.rst
new file mode 100644
index 000000000..d60276e0f
--- /dev/null
+++ b/docs/configurationguide/os-nosdn-kvm-ha.description.rst
@@ -0,0 +1,126 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. http://creativecommons.org/licenses/by/4.0
+
+
+Introduction
+============
+
+.. In this section explain the purpose of the scenario and the
+ types of capabilities provided
+
+The purpose of os-nosdn-kvm-ha scenario testing is to test the
+High Availability deployment and configuration of OPNFV software suite
+with OpenStack and without SDN software. This OPNFV software suite
+includes OPNFV KVM4NFV latest software packages for Linux Kernel and
+QEMU patches for achieving low latency. High Availability feature is achieved
+by deploying OpenStack multi-node setup with 3 controllers and 2 computes nodes
+
+KVM4NFV packages will be installed on compute nodes as part of deployment.
+This scenario testcase deployment is happening on multi-node by using
+OPNFV Fuel deployer.
+
+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 deploys the High Availability OPNFV Cloud based on the
+configurations provided in ha_nfv-kvm_heat_ceilometer_scenario.yaml.
+This yaml file contains following configurations and is passed as an
+argument to deploy.py script
+
+* scenario.yaml:This configuration file defines translation between a
+ short deployment scenario name(os-nosdn-kvm-ha) and an actual deployment
+ scenario configuration file(ha_nfv-kvm_heat_ceilometer_scenario.yaml)
+
+* deployment-scenario-metadata:Contains the configuration metadata like
+ title,version,created,comment.
+
+* stack-extensions:Stack extentions are opnfv added value features in form
+ of a fuel-plugin.Plugins listed in stack extensions are enabled and
+ configured.
+
+* dea-override-config: Used to configure the HA mode,network segmentation
+ types and role to node assignments.These configurations overrides
+ corresponding keys in the dea_base.yaml and dea_pod_override.yaml.
+ These keys are used to deploy multiple nodes(3 controllers,2 computes)
+ as mention below.
+
+ * **Node 1**: This node has MongoDB and Controller roles. The controller
+ node runs the Identity service, Image Service, management portions of
+ Compute and Networking, Networking plug-in and the dashboard. The
+ Telemetry service which was designed to support billing systems for
+ OpenStack cloud resources uses a NoSQL database to store information.
+ The database typically runs on the controller node.
+
+ * **Node 2**: This node has Controller and Ceph-osd roles. Ceph is a
+ massively scalable, open source, distributed storage system. It is
+ comprised of an object store, block store and a POSIX-compliant distributed
+ file system. Enabling Ceph, configures Nova to store ephemeral volumes in
+ RBD, configures Glance to use the Ceph RBD backend to store images,
+ configures Cinder to store volumes in Ceph RBD images and configures the
+ default number of object replicas in Ceph.
+
+ * **Node 3**: This node has Controller role in order to achieve high
+ availability.
+
+ * **Node 4**: This node has Compute role. The compute node runs the
+ hypervisor portion of Compute that operates tenant virtual machines
+ or instances. By default, Compute uses KVM as the hypervisor.
+
+ * **Node 5**: This node has compute role.
+
+* dha-override-config:Provides information about the VM definition and
+ Network config for virtual deployment.These configurations overrides
+ the pod dha definition and points to the controller,compute and
+ fuel definition files.
+
+* os-nosdn-kvm-ha scenario is successful when all the 5 Nodes are accessible,
+ up and running
+
+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
+
+* The high availability feature can be acheived by executing deploy.py with
+ ha_nfv-kvm_heat_ceilometer_scenario.yaml as an argument.
+* Install Fuel Master and deploy OPNFV Cloud from scratch on Hardware
+ Environment:
+
+ -Example:
+
+ sudo python deploy.py -iso ~/ISO/opnfv.iso -dea ~/CONF/hardware/dea.yaml -dha ~/CONF/hardware/dha.yaml -s /mnt/images -b pxebr -log ~/Deployment-888.log.tar.gz
+
+* Install Fuel Master and deploy OPNFV Cloud from scratch on Virtual
+ Environment:
+
+ -Example:
+
+ sudo python deploy.py -iso ~/ISO/opnfv.iso -dea ~/CONF/virtual/dea.yaml -dha ~/CONF/virtual/dha.yaml -s /mnt/images -log ~/Deployment-888.log.tar.gz
+
+* os-nosdn-kvm-ha scenario can be executed from the jenkins project
+ "fuel-os-nosdn-kvm-ha-baremetal-daily-master"
+* This scenario provides the High Availability feature by deploying
+ 3 controller,2 compute nodes and checking if all the 5 nodes
+ are accessible(IP,up & running).
+* Test Scenario is passed if deployment is successful and all 5 nodes have
+ accessibility (IP , up & running).
+* Observed that scenario is not running any testcase on top of deployment.
+
+Known Limitations, Issues and Workarounds
+=========================================
+.. Explain any known limitations here.
+
+* Test scenario os-nosdn-kvm-ha result is not stable. After node reboot
+ triggered by kvm plugin, sometimes puppet agent (mcollective) is not
+ responding with in the given time.
+
+References
+==========
+
+For more information on the OPNFV Colorado release, please visit
+http://www.opnfv.org/colorado
diff --git a/docs/configurationguide/scenariomatrix.rst b/docs/configurationguide/scenariomatrix.rst
new file mode 100644
index 000000000..1e2cef90a
--- /dev/null
+++ b/docs/configurationguide/scenariomatrix.rst
@@ -0,0 +1,100 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. http://creativecommons.org/licenses/by/4.0
+
+Scenarios are implemented as deployable compositions through integration with an installation tool.
+OPNFV supports multiple installation tools and for any given release not all tools will support all
+scenarios. While our target is to establish parity across the installation tools to ensure they
+can provide all scenarios, the practical challenge of achieving that goal for any given feature and
+release results in some disparity.
+
+Colorado scenario overeview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following table provides an overview of the installation tools and available scenario's
+in the Colorado release of OPNFV.
+
+Scenario status is indicated by a weather pattern icon. All scenarios listed with
+a weather pattern are possible to deploy and run in your environment or a Pharos lab,
+however they may have known limitations or issues as indicated by the icon.
+
+Weather pattern icon legend:
+
++---------------------------------------------+----------------------------------------------------------+
+| Weather Icon | Scenario Status |
++=============================================+==========================================================+
+| .. image:: ../images/weather-clear.jpg | Stable, no known issues |
++---------------------------------------------+----------------------------------------------------------+
+| .. image:: ../images/weather-few-clouds.jpg | Stable, documented limitations |
++---------------------------------------------+----------------------------------------------------------+
+| .. image:: ../images/weather-overcast.jpg | Deployable, stability or feature limitations |
++---------------------------------------------+----------------------------------------------------------+
+| .. image:: ../images/weather-dash.jpg | Not deployed with this installer |
++---------------------------------------------+----------------------------------------------------------+
+
+Scenarios that are not yet in a state of "Stable, no known issues" will continue to be stabilised
+and updates will be made on the stable/colorado branch. While we intend that all Colorado
+scenarios should be stable it is worth checking regularly to see the current status. Due to
+our dependency on upstream communities and code some issues may not be resolved prior to the D release.
+
+Scenario Naming
+^^^^^^^^^^^^^^^
+
+In OPNFV scenarios are identified by short scenario names, these names follow a scheme that
+identifies the key components and behaviours of the scenario. The rules for scenario naming are as follows:
+
+ os-[controller]-[feature]-[mode]-[option]
+
+Details of the fields are
+ * os: mandatory
+
+ * Refers to the platform type used
+ * possible value: os (OpenStack)
+
+* [controller]: mandatory
+
+ * Refers to the SDN controller integrated in the platform
+ * example values: nosdn, ocl, odl, onos
+
+ * [feature]: mandatory
+
+ * Refers to the feature projects supported by the scenario
+ * example values: nofeature, kvm, ovs, sfc
+
+ * [mode]: mandatory
+
+ * Refers to the deployment type, which may include for instance high availability
+ * possible values: ha, noha
+
+ * [option]: optional
+
+ * Used for the scenarios those do not fit into naming scheme.
+ * The optional field in the short scenario name should not be included if there is no optional scenario.
+
+Some examples of supported scenario names are:
+
+ * os-nosdn-kvm-noha
+
+ * This is an OpenStack based deployment using neutron including the OPNFV enhanced KVM hypervisor
+
+ * os-onos-nofeature-ha
+
+ * This is an OpenStack deployment in high availability mode including ONOS as the SDN controller
+
+ * os-odl_l2-sfc
+
+ * This is an OpenStack deployment using OpenDaylight and OVS enabled with SFC features
+
+Installing your scenario
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two main methods of deploying your target scenario, one method is to follow this guide which will
+walk you through the process of deploying to your hardware using scripts or ISO images, the other method is
+to set up a Jenkins slave and connect your infrastructure to the OPNFV Jenkins master.
+
+For the purposes of evaluation and development a number of Colorado scenarios are able to be deployed
+virtually to mitigate the requirements on physical infrastructure. Details and instructions on performing
+virtual deployments can be found in the installer specific installation instructions.
+
+To set up a Jenkins slave for automated deployment to your lab, refer to the `Jenkins slave connect guide.
+<http://artifacts.opnfv.org/brahmaputra.1.0/docs/opnfv-jenkins-slave-connection.brahmaputra.1.0.html>`_