-***********************************************
-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:
:maxdepth: 2
-============
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.
-** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA **
+High level architecture
+-----------------------
+
+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 installation of the OPNFV solution is out of scope of this document but can be found in XXX.
-In the rest of the document the OPNFV solution would be considered as the System Under Test (SUT).
-
-Several prerequisites are needed for functest:
- 1) docker must be installed on the Jumphost
- 2) a connectivity from the jumphost to the SUT management network is needed
- 3) an external network must be configured
+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:
+
+ #. A Jumphost to run Functest on
+ #. 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 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: 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 <your_user>
+A reconnect is needed. There are 2 ways for this:
+ #. Re-login to your account
+ #. su - <username>
-References:
+References - Installing Docker Engine on different Linux Operating Systems:
* Ubuntu_
* RHEL_
+ * 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
-Connectivy 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 and besides the public network, you need to configure an interface on the management network as well in your jumphost (or wherever you want to deploy the Functest docker to run the tests).
-
-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 on VIM need an external network. You may perform functest without an external network but some of the tests will fail.
-A default floating ip pool must be configured in nova.conf.
-
-
-
-=======================
-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 | | | | | |
- | | | -- Tempest | | | | | |
- | | | -- Rally | | | | | |
- | | | - Controller | | | | | |
- | | | -- odl | | | | | |
- | | | -- onos | | | | | |
- | | | -- opencontrail | | | | | |
- | | | | | | | | |
- | | | Features | | | | | |
- | | | - vIMS | | | | | |
- | | | | | | | | |
- | | +------------------+ | | | | |
- | | +----------------------------------------+ |
- | | Functest Docker | | | | |
- | | +-------------------------------------------------+
- | | | | | | |
- | +--------------------------+ | | | |
- | | | | |
- | +----------------+ | | | |
- | | 1 | | | | |
- +----+ +--------------+-+ | | | |
- | | | 2 | | | | |
- | | | +--------------+-+ | | | |
- | | | | 3 | | | | |
- | | | | +--------------+-+ | | | |
- | | | | | 4 | | | | |
- | +-+ | | +--------------+-+ | | | |
- | | | | | 5 +-----------------------+ | | |
- | +-+ | | nodes for | | | | |
- | | | | deploying +---------------------------------+ | |
- | +-+ | opnfv | | | | |
- | | | SUT +-------------------------------------------+ |
- | +-+ | | | | |
- | | +----------------------------------------------------+
- | +----------------+ | | | |
- | | | | |
- | + + + +
-
-All the components needed by Functest are in the docker file.
-Thanks to docker, there is no more library issues.
-
-This docker file will:
- * prepare the environment for functional testing
- * retrieve SUT credentials
- * perform the tests
- * push the results into the OPNFV test result database
-
-This docker file can be integrated into CI or deployed independantly 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.
-
-===================
-Manual Installation
-===================
-
-Pull the Functest Docker image from the hub::
-
- $ docker pull opnfv/functest
-
-Check that the image is available::
-
- $ docker images
-
-Run the docker container giving the environment variables
- - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel", "joid" or "foreman" (Arno).
- - INSTALLER_IP. each installer has its installation strategy. Functest may need to know the IP of the installer to retrieve the credentials (e.g. usually "10.20.0.2" for fuel, not neede for joid, "172.30.10.73" foreman...)
-
-The minimum command to create the Functest docker file can be described as follow::
-
- docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
-
-Optionnaly, it is possible to precise the container name through the option --name::
-
- docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
-
-It is also possible to to indicate the path of the OpenStack creds using -v::
-
- docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -v <path_to_your_local_creds_file>:/home/opnfv/functest/conf/openstack.creds opnfv/functest:latest_stable /bin/bash
-
-Your local file will be paste within the container under /home/opnfv/functest/conf/openstack.creds and used by the different test suites.
-
-Once run you shall be inside the docker container and ready to run Functest.
-
-Inside the container, you must have the following arborescence::
-
- `-- home
- `-- opnfv
- |-- functest
- | |-- conf
- | |-- data
- | `-- results
- `-- repos
- |-- bgpvpn
- |-- functest
- |-- odl_integration
- |-- rally
- |-- releng
- `-- vims-test
-
-
-Basically the container includes:
-
- * Functest directory to store the configuration (the OpenStack creds are paste in /home/opngb/functest/conf), the data (images neede for test for offline testing), results (some temporary artifacts may be stored here)
- * Repositories: the functest repository will be used to prepare the environement, run the tests. Other repositories are used for the installation of the tooling (e.g. rally) and/or the retrieval of feature projects scenarios (e.g. bgpvpn)
-
-The arborescence under the functest repo can be described as follow::
-
- .
- |-- INFO
- |-- LICENSE
- |-- commons
- | |-- ims
- | |-- mobile
- | `-- traffic-profile-guidelines.rst
- |-- docker
- | |-- Dockerfile
- | |-- common.sh
- | |-- prepare_env.sh
- | |-- requirements.pip
- | `-- run_tests.sh
- |-- docs
- | |-- configguide
- | |-- functest.rst
- | |-- images
- | `-- userguide
- `-- testcases
- |-- Controllers
- |-- VIM
- |-- __init__.py
- |-- config_functest.py
- |-- config_functest.yaml
- |-- functest_utils.py
- |-- functest_utils.pyc
- |-- vIMS
- `-- vPing
-
-We may distinguish 4 different folders:
-
- * commons: it is a folder dedicated to store traffic profile or any test inputs that could be reused by any test project
- * docker: this folder includes the scripts that will be used to setup the environment and run the tests
- * docs: this folder includes the user and installation/configuration guide
- * testcases: this folder includes the scripts required by Functest internal test cases
-
-
-Firstly run the script to install functest environment::
-
- $ ${repos_dir}/functest/docker/prepare_env.sh
-
-NOTE: ${repos_dir} is a default environment variable inside the docker container, which points to /home/opnfv/repos
-
-Run the script to start the tests::
-
- $ ${repos_dir}/functest/docker/run_tests.sh
-
-NOTE: This will run ALL the tests by default, see `[2]`_ for details
-
-Focus on the OpenStack credentials
-==================================
-
-The OpenStack creds are needed to test the VIM. They can be retrieved in several ways:
- * using the -v option when creating
- * sourcing them manually once connected on the docker, once log perform a source <openstack_creds>
- * automatically retrieved via a script (CI)
-
-If not source you will get an error during the test environnement preparation.
-
-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]`_::
fi
-=============
-Configuration
-=============
-
-Everything is preconfigured in the docker file. So except the credentials, there is no specific configuration needed. it is 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 chan: #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
Code Review / functest.git / blobdiff