X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fconfigguide%2Findex.rst;h=411f68d68da9d17c206c087016f6578877ccb318;hb=6790e17eb7c1a3eaaccfe97ac90932e3c15eea6d;hp=47e430d21e2105912c9d1434174abffce6594d63;hpb=137ca3bf6f6da44aebcaabfae4d017c28c37fb41;p=functest.git diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst index 47e430d21..411f68d68 100644 --- a/docs/configguide/index.rst +++ b/docs/configguide/index.rst @@ -1,77 +1,62 @@ -=============================================== -OPNFV FUNCTEST configuration/installation guide -=============================================== +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 -.. contents:: +================================== +OPNFV FUNCTEST Configuration Guide +================================== ------------- -Introduction ------------- - -** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA ** - -.. _prereqs: - -------------- -Prerequisites -------------- - -The installation of the OPNFV solution is out of scope of this document but can be found XXX. -In the rest of the document the OPNFV solution would be considered as the System Under Test (SUT). - -The installation and configuration of the tools needed to perform the tests will be described in the following sections. +.. toctree:: + :numbered: + :maxdepth: 2 -Since Arno SR1, the tools are automatically installed. Manual sourcing of OpenStack credentials is no more required if you are fully integrated in the continuous integration. -A script has been added to automatically retrieve the credentials. -However, if you still install manually functest, you will need to source the rc file on the machine you are running the tests. -More details will be provided in the configuration section. - -.. _pharos: https://wiki.opnfv.org/pharos - -It is recommended to install the different tools on the jump host server as defined in the pharos_ project. - -For functest, the following libraries are needed. You can install them either with yum install or apt-get install, depending on your operating system: - * python-pip - * python-dev - * libffi-dev - * libxml2-dev - * libxslt1-dev +Introduction +============ -You will also need some Python modules: - * sudo pip install GitPython - * sudo pip install python-novaclient - * sudo pip install python-neutronclient - * sudo pip install python-glanceclient - * sudo pip install python-keystoneclient +This document describes how to install and configure Functest in OPNFV. +High level architecture +----------------------- -The high level architecture can be described as follow:: +The high level architecture of Functest within OPNFV can be described as follows:: - CIMC/Lights+out management Admin Private Public Storage - PXE + CIMC/Lights+out management Admin Private Public Storage + PXE + + + IP_PRIV/24 | | | | + + | | | | IP_PUB/24 | - | +-----------------+ | | + | - | | | | | | | - +-----+ Jumpserver | | | | | - | | +---------------------+ | | | - | | | | | | | - | | +----------+ | | | | | - | | | Rally | +---- --------------------------+ | | - | | | | | | | | | - | | | Robot | | | | | | - | | | | | | | | | - | | | vPing | | | | | | - | | | | | | | | | - | | | Tempest | | | | | | - | | +----------+ | | | | | - | | FuncTest +-----------------------------------------+ | - | | | | | | | - | | +--------------------------------------------------+ - | | | | | | | - | +-----------------+ | | | | + | +----------------------------+ | | + | + | | | | | | | + +-----+ Jumphost | | | | | + | | +----------+ | | | + | | | | | | | + | | +--------------------+ | | | | | + | | | | | | | | | + | | | Tools | +--------------------+ | | + | | | - Rally | | | | | | + | | | - Robot | | | | | | + | | | - TestON | | | | | | + | | | | | | | | | + | | | Testcases | | | | | | + | | | - VIM | | | | | | + | | | -- vPing | | | | | | + | | | -- vPing_userdata | | | | | | + | | | -- Tempest | | | | | | + | | | -- Rally | | | | | | + | | | - Controller | | | | | | + | | | -- odl | | | | | | + | | | -- onos | | | | | | + | | | -- opencontrail | | | | | | + | | | | | | | | | + | | | Features | | | | | | + | | | - vIMS | | | | | | + | | | | | | | | | + | | +--------------------+ | | | | | + | | +------------------------------+ | + | | Functest Docker | | | | | + | | +---------------------------------------+ + | | | | | | | + | +----------------------------+ | | | | | | | | | | +----------------+ | | | | | | 1 | | | | | @@ -93,32 +78,187 @@ The high level architecture can be described as follow:: | | | | | | + + + + +All the libraries and dependencies needed by all the Functest tools are +pre-installed in the Docker image. +This allows running Functest on any platform on any Operating System. + +The automated mechanisms inside the Functest Docker container will: + + * retrieve OpenStack credentials + * prepare the environment according to the SUT + * perform the appropriate tests + * push the results into the OPNFV test result database + + +This Docker image can be integrated into CI or deployed independently. + +Please note that the Functest container has been designed for OPNFV, however, it +would be possible to adapt it to any VIM+controller environment since most of the +test cases are integrated from upstream communities. + +The test cases are described in the Functest User Guide `[2]`_ + + +Prerequisites +============= + +The OPNFV deployment is out of the scope of this document but it can be found in +`[4]`_. The OPNFV platform is considered as the System Under Test (SUT) in this +document. + +Several prerequisites are needed for Functest: + + #. A Jumphost to run Functest on + #. Docker daemon shall be installed on the Jumphost + #. A public/external network created on the SUT + #. Connectivity from the Jumphost to the SUT public/external network + #. Connectivity from the Jumphost to the SUT management network + +NOTE: “Jumphost” refers to any server which meets the previous requirements. +Normally it is the same server from where the OPNFV deployment has been +triggered previously. + +Docker installation +------------------- + +.. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/ +.. _RHEL: https://docs.docker.com/installation/rhel/ + +Log on your Jumphost and install docker (e.g. for Ubuntu):: -.. _tooling_installation: + curl -sSL https://get.docker.com/ | sh ------------- -Installation ------------- +Add your user to docker group to be able to run commands without sudo:: + + sudo usermod -aG docker + +A reconnect is needed. There are 2 ways for this: + #. Re-login to your account + #. su - + +References: + + * Ubuntu_ + * RHEL_ + +External network on SUT +----------------------- + +Some of the tests against the VIM (Virtual Infrastructure Manager) need an +existing public network to succeed. This is needed, for example, to create +floating IPs to access instances from the public network (i.e. Docker container). + +By default, the four OPNFV installers provide a fresh installation with +an external network created along with a router. Make sure that subnet +is reachable from the Jumphost + + +Connectivity to OPNFV management network +---------------------------------------- + +Some of the Functest tools need to have access to the OpenStack management +network of the controllers `[1]`_. + +For this reason, an interface shall be configured in the Jumphost in the +OpenStack management network range. + +For example, if the management network is on VLAN 300 and subnet 192.168.1.0/24 +and assuming that eth1 is the physical interface with access to that subnet:: + + ip link add name eth1.300 link eth1 type vlan id 300 + ip link set eth1.300 up + ip addr add 192.168.1.66/24 dev eth1.300 + +This is just an example about how to configure an interface with vlan, but it might +differ depending on the deployment settings on each installer. Check the +corresponding installer instructions for more info. + + +Installation and configuration +============================== + +.. include:: ./configguide.rst -------------- -Configuration -------------- ------------------ Integration in CI ------------------ +================= + +In CI we use the Docker image and execute the appropriate commands within the +container from Jenkins. + +Docker creation in set-functest-env builder `[3]`_:: + + envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}" + [...] + docker pull opnfv/functest:latest_stable + cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash" + echo "Functest: Running docker run command: ${cmd}" + ${cmd} + docker ps -a + sleep 5 + container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1) + echo "Container ID=${container_id}" + if [ -z ${container_id} ]; then + echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing." + docker ps -a + exit 1 + fi + echo "Starting the container: docker start ${container_id}" + docker start ${container_id} + sleep 5 + docker ps + if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then + echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..." + exit 1 + fi + cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh" + echo "Executing command inside the docker: ${cmd}" + docker exec ${container_id} ${cmd} + + +Test execution in functest-all builder `[3]`_:: + + echo "Functest: run $FUNCTEST_SUITE_NAME" + cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}" + container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1) + docker exec $container_id $cmd + +Docker clean in functest-cleanup builder `[3]`_:: + + echo "Cleaning up docker containers/images..." + # Remove previous running containers if exist + if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then + echo "Removing existing opnfv/functest containers..." + docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop + docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm + fi + + # Remove existing images if exist + if [[ ! -z $(docker images | grep opnfv/functest) ]]; then + echo "Docker images to remove:" + docker images | head -1 && docker images | grep opnfv/functest + image_tags=($(docker images | grep opnfv/functest | awk '{print $2}')) + for tag in "${image_tags[@]}"; do + echo "Removing docker image opnfv/functest:$tag..." + docker rmi opnfv/functest:$tag + done + fi ----------- References ----------- +========== +.. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/ +.. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html +.. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml +.. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/index.html + OPNFV main site: opnfvmain_. OPNFV functional test page: opnfvfunctest_. -IRC support chan: #opnfv-testperf +IRC support channel: #opnfv-testperf .. _opnfvmain: http://www.opnfv.org .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing