diff options
Diffstat (limited to 'docs/userguide')
| -rw-r--r-- | docs/userguide/apexlake_framework/apexlake_api.rst | 45 | ||||
| -rw-r--r-- | docs/userguide/apexlake_framework/apexlake_installation.rst | 119 |
2 files changed, 75 insertions, 89 deletions
diff --git a/docs/userguide/apexlake_framework/apexlake_api.rst b/docs/userguide/apexlake_framework/apexlake_api.rst index 94f07dc06..2ef3e43f5 100644 --- a/docs/userguide/apexlake_framework/apexlake_api.rst +++ b/docs/userguide/apexlake_framework/apexlake_api.rst @@ -1,8 +1,8 @@ ================================= -Apexlake API interface definition +Apexlake API Interface Definition ================================= -The API interface provided by the framework in order to execute the test cases is defined in the following. +The API interface provided by the framework to enable the execution of test cases is defined as follows. init @@ -15,37 +15,6 @@ init **Returns** None -get_available_test_cases ------------------------- - -**static get_available_test_cases()** - - Returns a list of available test cases. This list include eventual modules developed by the user, if any. - Each test case is returned as a string that represents the full name of the test case and that - can be used to get more information calling get_test_case_features(test_case_name) - - **Returns** list of strings - - -get_test_case_features ----------------------- - -**static get_test_case_features(test_case)** - - Returns a list of features (description, requested parameters, allowed values, etc.) - for a specified test case. - - **Parameters** - - - **test_case** - - Name of the test case (string). The string represents the test - case and can be obtained calling “get_available_test_cases()” method. - - **Returns** - dict() containing the features of the test case - - execute_framework ----------------- @@ -61,13 +30,13 @@ execute_framework openstack_credentials) - Executes the framework according the inputs + Executes the framework according the specified inputs **Parameters** - **test_cases** - Test cases to be ran on the workload (dict() of dict()) + Test cases to be run with the workload (dict() of dict()) Example: test_case = dict() @@ -85,10 +54,10 @@ execute_framework test_cases = [test_case] - **iterations** - Number of cycles to be executed (int) + Number of test cycles to be executed (int) - **heat_template** - (string) File name of the heat template of the workload to be deployed. + (string) File name of the heat template corresponding to the workload to be deployed. It contains the parameters to be evaluated in the form of #parameter_name. (See heat_templates/vTC.yaml as example). @@ -99,7 +68,7 @@ execute_framework - **deployment_configuration** ( dict[string] = list(strings) ) ) Dictionary of parameters - representing the deployment configuration of the workload + representing the deployment configuration of the workload. The key is a string corresponding to the name of the parameter, the value is a list of strings representing the value to be diff --git a/docs/userguide/apexlake_framework/apexlake_installation.rst b/docs/userguide/apexlake_framework/apexlake_installation.rst index 38c838494..2e129bfa2 100644 --- a/docs/userguide/apexlake_framework/apexlake_installation.rst +++ b/docs/userguide/apexlake_framework/apexlake_installation.rst @@ -1,42 +1,47 @@ .. _DPDK: http://dpdk.org/doc/nics .. _DPDK-pktgen: https://github.com/Pktgen/Pktgen-DPDK/ .. _SRIOV: https://wiki.openstack.org/wiki/SR-IOV-Passthrough-For-Networking +.. _here: https://wiki.opnfv.org/vtc -=========================== -Apexlake installation guide -=========================== -ApexLake is a framework that provides automatic execution of experiments and related data collection to help -the user validating the infrastructure from the perspective of a Virtual Network Function. -To do so in the context of Yardstick, the virtual Traffic Classifier network function is utilized. +============================ +Apexlake Installation Guide +============================ +ApexLake is a framework that provides automatic execution of experiments and related data collection to enable +a user validate infrastructure from the perspective of a Virtual Network Function (VNF). +In the context of Yardstick, a virtual Traffic Classifier (vTC) network function is utilized. -Hardware dependencies to run the framework -========================================== -In order to run the framework some hardware dependencies are required to run ApexLake. -The framework needs to be installed on a physical node where the DPDK packet DPDK-pktgen_ -can be correctly installed and executed. -That requires for the packet generator to have 2 NICs DPDK_ Compatible. +Framework Hardware Dependencies +=============================== +In order to run the framework there are some hardware related dependencies for ApexLake. -The 2 NICs will be connected to the switch where the Openstack VM network is managed. +The framework needs to be installed on the same physical node where DPDK-pktgen_ +is installed. +The installation requires the physical node hosting the packet generator must have 2 NICs +which are DPDK_ compatible. -The switch is required to support multicast traffic and snooping protocol. +The 2 NICs will be connected to the switch where the OpenStack VM network is managed. -The corresponding ports to which the cables are connected will be configured as VLAN trunks +The switch used must support multicast traffic and IGMP snooping. +Further details about the configuration are provided at the following here_. + +The corresponding ports to which the cables are connected need to be configured as VLAN trunks using two of the VLAN IDs available for Neutron. -The mentioned VLAN IDs will be required in further configuration steps. +Note the VLAN IDs used as they will be required in later configuration steps. + +Framework Software Dependencies +=============================== +Before starting the framework, a number of dependencies must first be installed. +The following describes the set of instructions to be executed via the Linux shell in order to install +and configure the required dependencies. -Software dependencies to run the framework -========================================== -Before to start the framework, a set of dependencies are required to be installed. -In the following a set of instructions to be executed on the Linux shell to install dependencies -and configure the environment is presented. +1. Install Dependencies. -1. Install dependencies. +To support the framework dependencies the following packages must be installed. +The example provided is based on Ubuntu and needs to be executed in root mode. -To install the dependencies required by the framework it is necessary install the following packages. -The following example is provided for Ubuntu and need to be executed as root. :: apt-get install python-dev @@ -45,10 +50,10 @@ The following example is provided for Ubuntu and need to be executed as root. apt-get install tcpreplay apt-get install libpcap-dev -2. Install the framework on the system. +2. Install the Framework on the Target System. + +After entering the Apexlake directory, run the following command. -The installation of the framework on the system requires the setup of the project. -After entering into the apexlake directory, it is sufficient to run the following command. :: python setup.py install @@ -59,12 +64,13 @@ After entering into the apexlake directory, it is sufficient to run the followin source openrc -4. Create 2 Networks based on VLANs in Neutron. +4. Create Two Networks based on VLANs in Neutron. + +To enable network communications between the packet generator and the compute node, +two networks must be created via Neutron and mapped to the VLAN IDs +that were previously used in the configuration of the physical switch. +The following shows the typical set of commands required to configure Neutron correctly. -In order for the network communication between the packet generator and the Compute node to -work fine, it is required to create through Neutron two networks and map those on the VLAN IDs -that have been previously used for the configuration on the physical switch. -The underlying switch needs to be configured accordingly. :: VLAN_1=2025 @@ -89,35 +95,41 @@ The underlying switch needs to be configured accordingly. neutron subnet-create apexlake_outbound_network 192.168.1.0/24 \ --name apexlake_outbound_subnet -5. Configure the Test Cases. -The VLAN tags are also required into the test case Yardstick yaml file as parameters the following test cases: +5. Configure the Test Cases + +The VLAN tags must also be included in the test case Yardstick yaml file +as parameters for the following test cases: - TC 006 - TC 007 - TC 020 - TC 021 -Install and configure DPDK Pktgen +Install and Configure DPDK Pktgen +++++++++++++++++++++++++++++++++ -The execution of the framework is based on DPDK Pktgen. -If DPDK Pktgen has not been installed on the system by the user, it is necessary to download, compile and configure it. +Execution of the framework is based on DPDK Pktgen. +If DPDK Pktgen has not installed, it is necessary to download, install, compile and configure it. The user can create a directory and download the dpdk packet generator source code: + :: cd experimental_framework/libraries mkdir dpdk_pktgen git clone https://github.com/pktgen/Pktgen-DPDK.git -For the installation and configuration of DPDK and DPDK Pktgen please follow the official DPDK Pktgen README file. +For instructions on the installation and configuration of DPDK and DPDK Pktgen please follow the official +DPDK Pktgen README file. Once the installation is completed, it is necessary to load the DPDK kernel driver, as follow: + :: insmod uio insmod DPDK_DIR/x86_64-native-linuxapp-gcc/kmod/igb_uio.ko -It is required to properly set the configuration file according to the system on Pktgen runs on. -A description of the required configuration parameters and examples is provided in the following: +It is necessary to set the configuration file to support the desired Pktgen configuration. +A description of the required configuration parameters and supporting examples is provided in the following: + :: [PacketGen] @@ -153,19 +165,21 @@ A description of the required configuration parameters and examples is provided bus_slot_nic_2 = 01:00.1 -To find the parameters related to names of the NICs and addresses of the PCI buses -the user may find useful to run the DPDK tool nic_bind as follows: +To find the parameters related to names of the NICs and the addresses of the PCI buses +the user may find it useful to run the DPDK tool nic_bind as follows: + :: DPDK_DIR/tools/dpdk_nic_bind.py --status -which lists the NICs available on the system, show the available drivers and bus addresses for each interface. +Lists the NICs available on the system, and shows the available drivers and bus addresses for each interface. Please make sure to select NICs which are DPDK compatible. -Installation and configuration of smcroute +Installation and Configuration of smcroute ++++++++++++++++++++++++++++++++++++++++++ The user is required to install smcroute which is used by the framework to support multicast communications. -In the following a list of commands to be ran to download and install smroute is provided. +The following is the list of commands required to download and install smroute. + :: cd ~ @@ -179,32 +193,35 @@ In the following a list of commands to be ran to download and install smroute is sudo make install cd .. -It is also required to create a configuration file using the following command: +It is also requires the creation a configuration file using the following command: SMCROUTE_NIC=(name of the nic) where name of the nic is the name used previously for the variable "name_if_2". -In the example it would be: +For example: + :: SMCROUTE_NIC=p1p2 Then create the smcroute configuration file /etc/smcroute.conf + :: echo mgroup from $SMCROUTE_NIC group 224.192.16.1 > /etc/smcroute.conf At the end of this procedure it will be necessary to perform the following actions to add the user to the sudoers: + :: adduser USERNAME sudo echo "user ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers -Experiment using SR-IOV configuration on the compute node +Experiment using SR-IOV Configuration on the Compute Node +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -In order to enable SR-IOV interfaces on the physical NIC of the compute node, a compatible NIC is required. +To enable SR-IOV interfaces on the physical NIC of the compute node, a compatible NIC is required. NIC configuration depends on model and vendor. After proper configuration to support SR-IOV, -a proper configuration of openstack is required. -For further information, please look at the _SRIOV configuration guide +a proper configuration of OpenStack is required. +For further information, please refer to the _SRIOV configuration guide |