X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fconfigguide%2Findex.rst;h=b61bf8ff551afc77b1824c1da6e50a9a0d7256a2;hb=refs%2Fchanges%2F95%2F24295%2F1;hp=7519bb85babc9fbe5ad00811a5ccf2f61cb8a1e5;hpb=63c77f27ec173fc3684ed980e82a4a7ed97beb6b;p=functest.git diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst index 7519bb85b..b61bf8ff5 100644 --- a/docs/configguide/index.rst +++ b/docs/configguide/index.rst @@ -1,6 +1,9 @@ -=============================================== -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 + +================================== +OPNFV FUNCTEST Configuration Guide +================================== .. toctree:: :numbered: @@ -8,207 +11,209 @@ OPNFV FUNCTEST configuration/installation guide Introduction ============ +This document describes how to install and configure Functest in OPNFV. +The Functest CLI is utilized during the Functest environment preparation +step. The given example commands should work in both virtual and bare +metal cases alike. + +High level architecture +----------------------- -** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA ** +The high level architecture of Functest within OPNFV can be described as +follows:: + + CIMC/Lights+out management Admin Private Public Storage + PXE + + + + + + + | | | | | + | +----------------------------+ | | | | + | | | | | | | + +-----+ Jumphost | | | | | + | | +--------+ | | | + | | | | | | | + | | +--------------------+ | | | | | + | | | | | | | | | + | | | Tools | +----------------+ | | + | | | - Rally | | | | | | + | | | - Robot | | | | | | + | | | - TestON | | | | | | + | | | | | | | | | + | | | Testcases | | | | | | + | | | - VIM | | | | | | + | | | -- healthcheck | | | | | | + | | | -- vPing_ssh | | | | | | + | | | -- vPing_userdata | | | | | | + | | | -- Tempest_smoke | | | | | | + | | | -- Rally_sanity | | | | | | + | | | -- Tempest_full | | | | | | + | | | -- Rally_full | | | | | | + | | | | | | | | | + | | | - SDN Controller | | | | | | + | | | -- odl | | | | | | + | | | -- onos | | | | | | + | | | | | | | | | + | | | - VNF | | | | | | + | | | -- vIMS | | | | | | + | | | | | | | | | + | | +--------------------+ | | | | | + | | +-------------------------+ | + | | Functest Docker | | | | | + | | +---------------------------------+ + | | | | | | | + | +----------------------------+ | | | | + | | | | | + | +----------------+ | | | | + | | 1 | | | | | + +----+ +--------------+-+ | | | | + | | | 2 | | | | | + | | | +--------------+-+ | | | | + | | | | 3 | | | | | + | | | | +--------------+-+ | | | | + | | | | | 4 | | | | | + | +-+ | | +--------------+-+ | | | | + | | | | | 5 +-------------+ | | | + | +-+ | | nodes for | | | | | + | | | | deploying +---------------------+ | | + | +-+ | OPNFV | | | | | + | | | +------------------------------+ | + | +-+ SUT | | | | | + | | +--------------------------------------+ + | +----------------+ | | | | + | | | | | + + + + + + + SUT = System Under Test + +All the libraries and dependencies needed by all of the Functest tools +are pre-installed into 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 functional tests + * Push the test results into the OPNFV test result database + +This Docker image can be integrated into CI or deployed independently. + +Please note that the Functest Docker 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 functional test cases are described in the Functest User Guide `[2]`_ -This document describes how to install and configure Functest in OPNFV. Prerequisites ============= - -The OPNFV deployment is out of the scope of this document but it can be found in -XXX. The OPNFV platform is considered as the System Under Test (SUT) in this +The OPNFV deployment is out of the scope of this document but it can be +found in http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html. +The OPNFV platform is considered as the System Under Test (SUT) in this document. -Several prerequisites are needed for functest: +Several prerequisites are needed for Functest: #. A Jumphost to run Functest on - #. Docker daemon shall be installed on the Jumphost + #. A Docker daemon shall be installed on the Jumphost #. A public/external network created on the SUT + #. An admin/management network created on the SUT #. Connectivity from the Jumphost to the SUT public/external network - #. Connectivity from the Jumphost to the SUT management network + #. Connectivity from the Jumphost to the SUT admin/management network + +WARNING: Connectivity from Jumphost is essential and it is of paramount +importance to make sure it is working before even considering to install +and run Functest. Make also sure you understand how your networking is +designed to work. + +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. -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. +NOTE: If your Jumphost is operating behind a company http proxy and/or +Firewall, please consult first the section `Proxy Support`_, towards +the end of this document. The section details some tips/tricks which +*may* be of help in a proxified environment. Docker installation ------------------- +Docker installation and configuration is only needed to be done once +through the life cycle of Jumphost. -.. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/ -.. _RHEL: https://docs.docker.com/installation/rhel/ +If your Jumphost is based on Ubuntu, RHEL or CentOS linux, please +consult the references below for more detailed instructions. The +commands below are offered as a short reference. -Log on your jumphost then install docker (e.g. for Ubuntu):: +*Tip:* For running docker containers behind the proxy, you need first +some extra configuration which is described in section +`Docker Installation on CentOS behind http proxy`_. You should follow +that section before installing the docker engine. + +Docker installation needs to be done as root user. You may use other +userid's to create and run the actual containers later if so desired. +Log on to your Jumphost as root user and install the Docker Engine +(e.g. for CentOS family):: curl -sSL https://get.docker.com/ | sh + systemctl start docker + + *Tip:* If you are working through proxy, please set the https_proxy + environment variable first before executing the curl command. 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: - +References - Installing Docker Engine on different Linux Operating Systems: * Ubuntu_ * RHEL_ - -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. - -Example:: - - The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as - Openstack Management network. - . - Supposing 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 - - -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. Jumphost). - -By default, any of the four OPNFV installers provide a fresh installation with -an external network created along with a router. - - - -High level architecture -======================= - -The high level architecture of Functest within OPNFV can be described as follow:: - - CIMC/Lights+out management Admin Private Public Storage - PXE - + - + + IP_PRIV/24 | | - | | + + | - | | | IP_PUB/24 | - | +----------------------------+ | | + | - | | | | | | | - +-----+ Jumphost | | | | | - | | +----------+ | | | - | | | | | | | - | | +--------------------+ | | | | | - | | | | | | | | | - | | | Tools | +--------------------+ | | - | | | - Rally | | | | | | - | | | - Robot | | | | | | - | | | - TestON | | | | | | - | | | | | | | | | - | | | Testcases | | | | | | - | | | - VIM | | | | | | - | | | -- vPing | | | | | | - | | | -- vPing_userdata | | | | | | - | | | -- Tempest | | | | | | - | | | -- Rally | | | | | | - | | | - Controller | | | | | | - | | | -- odl | | | | | | - | | | -- onos | | | | | | - | | | -- opencontrail | | | | | | - | | | | | | | | | - | | | Features | | | | | | - | | | - vIMS | | | | | | - | | | | | | | | | - | | +--------------------+ | | | | | - | | +------------------------------+ | - | | Functest Docker | | | | | - | | +---------------------------------------+ - | | | | | | | - | +----------------------------+ | | | | - | | | | | - | +----------------+ | | | | - | | 1 | | | | | - +----+ +--------------+-+ | | | | - | | | 2 | | | | | - | | | +--------------+-+ | | | | - | | | | 3 | | | | | - | | | | +--------------+-+ | | | | - | | | | | 4 | | | | | - | +-+ | | +--------------+-+ | | | | - | | | | | 5 +---------------+ | | | - | +-+ | | nodes for | | | | | - | | | | deploying +-------------------------+ | | - | +-+ | opnfv | | | | | - | | | SUT +-----------------------------------+ | - | +-+ | | | | | - | | +--------------------------------------------+ - | +----------------+ | | | | - | | | | | - | + + + + - -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 with any Operating System. - -The Docker image 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** of the CI. -A description of the Brahmaputra testcases can be retrieved in the Functest user -guide `[2]`_ - -Please note that the Functest container has been designed for OPNFV, however, it -would be possible to adapt it to any VIM+controller environment as most of the -testcases are upstream testcases. + * CentOS_ + +.. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/ +.. _RHEL: https://docs.docker.com/engine/installation/linux/rhel/ +.. _CentOS: https://docs.docker.com/engine/installation/linux/centos/ + +Public/External network on SUT +------------------------------ +Some of the tests against the VIM (Virtual Infrastructure Manager) need +connectivity through an existing public/external network in order to +succeed. This is needed, for example, to create floating IPs to access +VM instances through the public/external network (i.e. from the Docker +container). + +By default, the four OPNFV installers provide a fresh installation with +a public/external network created along with a router. Make sure that +the public/external subnet is reachable from the Jumphost. + +*Hint:* For the given OPNFV Installer in use, the IP sub-net address +used for the public/external network is usually a planning item and +should thus be known. Consult the OPNFV Configuration guide `[4]`_, and +ensure you can reach each node in the SUT, from the Jumphost using the +'ping' command using the respective IP address on the public/external +network for each node in the SUT. The details of how to determine the +needed IP addresses for each node in the SUT may vary according to the +used installer and are therefore ommitted here. + +Connectivity to Admin/Management network on SUT +----------------------------------------------- +Some of the Functest tools need to have access to the OpenStack +admin/management network of the controllers `[1]`_. + +For this reason, check the connectivity from the Jumphost to all the +controllers in cluster in the OpenStack admin/management network range. + +Installation and configuration +============================== .. include:: ./configguide.rst -NOTE: This will run ALL the tests by default, see `[2]`_ for details - -Focus on the OpenStack credentials ----------------------------------- - -The OpenStack credentials are needed to test the VIM. There are 3 ways to -provide them to Functest: - - * using the -v option when running the Docker container - * create an empty file in /home/opnfv/functest/conf/openstack.creds and paste - the needed info in it. - * automatically retrieved using the following script:: - $repos_dir/releng/utils/fetch_os_creds.sh - -Once the credentials are there, they shall be sourced before running the tests:: - - source /home/opnfv/functest/conf/openstack.creds - -Additional Options ------------------- - -In case you need to provide different configuration parameters to Functest (e.g. - commit IDs or branches for the repositories, ...) copy the config_functest.yaml - from the repository to your current directory and run docker with a volume:: - - $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml - $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh" - $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh" - $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \ - -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \ - "${cmd1} && ${cmd2}" - - Integration in CI ================= - -In CI we use the docker file and execute commande within the container from -Jenkins. +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]`_:: @@ -269,35 +274,19 @@ Docker clean in functest-cleanup builder `[3]`_:: fi -Configuration -============= - -Everything is preconfigured in the docker file. -It is however possible to customize the list of tests, see `[2]` for details. - -Errors -====== - - - - - References ========== .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/ -.. _`[2]`: url functest user guide +.. _`[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/colorado/docs/configguide/index.html OPNFV main site: opnfvmain_. OPNFV functional test page: opnfvfunctest_. -IRC support channel: #opnfv-testperf +IRC support channel: #opnfv-functest .. _opnfvmain: http://www.opnfv.org .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing -.. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html -.. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html -.. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py -.. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml