From 5a56bf69988b7c72e88546eb4659576fb51bfb77 Mon Sep 17 00:00:00 2001 From: swatisharma Date: Thu, 18 Aug 2016 21:06:56 +0530 Subject: 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 Signed-off-by: Swati Sharma --- docs/configurationguide/abstract.rst | 16 +++ .../configuration.options.render.rst | 23 ++++ .../images/brahmaputrafeaturematrix.jpg | Bin 0 -> 62966 bytes .../images/brahmaputrascenariomatrix.jpg | Bin 0 -> 51071 bytes docs/configurationguide/images/weather-clear.jpg | Bin 0 -> 1286 bytes docs/configurationguide/images/weather-dash.jpg | Bin 0 -> 1010 bytes .../images/weather-few-clouds.jpg | Bin 0 -> 1348 bytes .../configurationguide/images/weather-overcast.jpg | Bin 0 -> 1215 bytes docs/configurationguide/index.rst | 16 +++ ...w-latency.feature.configuration.description.rst | 93 +++++++++++++++ .../os-nosdn-kvm-ha.description.rst | 126 +++++++++++++++++++++ docs/configurationguide/scenariomatrix.rst | 100 ++++++++++++++++ 12 files changed, 374 insertions(+) create mode 100644 docs/configurationguide/abstract.rst create mode 100644 docs/configurationguide/configuration.options.render.rst create mode 100644 docs/configurationguide/images/brahmaputrafeaturematrix.jpg create mode 100644 docs/configurationguide/images/brahmaputrascenariomatrix.jpg create mode 100644 docs/configurationguide/images/weather-clear.jpg create mode 100644 docs/configurationguide/images/weather-dash.jpg create mode 100644 docs/configurationguide/images/weather-few-clouds.jpg create mode 100644 docs/configurationguide/images/weather-overcast.jpg create mode 100644 docs/configurationguide/index.rst create mode 100644 docs/configurationguide/low-latency.feature.configuration.description.rst create mode 100644 docs/configurationguide/os-nosdn-kvm-ha.description.rst create mode 100644 docs/configurationguide/scenariomatrix.rst (limited to 'docs/configurationguide') 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 Binary files /dev/null and b/docs/configurationguide/images/brahmaputrafeaturematrix.jpg differ diff --git a/docs/configurationguide/images/brahmaputrascenariomatrix.jpg b/docs/configurationguide/images/brahmaputrascenariomatrix.jpg new file mode 100644 index 000000000..84fc87a76 Binary files /dev/null and b/docs/configurationguide/images/brahmaputrascenariomatrix.jpg differ diff --git a/docs/configurationguide/images/weather-clear.jpg b/docs/configurationguide/images/weather-clear.jpg new file mode 100644 index 000000000..011ad52e9 Binary files /dev/null and b/docs/configurationguide/images/weather-clear.jpg differ diff --git a/docs/configurationguide/images/weather-dash.jpg b/docs/configurationguide/images/weather-dash.jpg new file mode 100644 index 000000000..3bf98dd27 Binary files /dev/null and b/docs/configurationguide/images/weather-dash.jpg 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 Binary files /dev/null and b/docs/configurationguide/images/weather-few-clouds.jpg differ diff --git a/docs/configurationguide/images/weather-overcast.jpg b/docs/configurationguide/images/weather-overcast.jpg new file mode 100644 index 000000000..bdc1e0487 Binary files /dev/null and b/docs/configurationguide/images/weather-overcast.jpg 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. +`_ -- cgit 1.2.3-korg