diff options
| -rw-r--r-- | docs/configguide/configguide.rst | 204 | ||||
| -rw-r--r-- | docs/configguide/index.rst | 202 |
2 files changed, 250 insertions, 156 deletions
diff --git a/docs/configguide/configguide.rst b/docs/configguide/configguide.rst index 671b46333..82ba1e373 100644 --- a/docs/configguide/configguide.rst +++ b/docs/configguide/configguide.rst @@ -2,27 +2,27 @@ .. http://creativecommons.org/licenses/by/4.0 -Functional testing Installation -------------------------------- +Preparing the Docker container +------------------------------ Pull the Functest Docker image from the Docker hub:: - $ docker pull opnfv/functest:brahmaputra.1.0 + docker pull opnfv/functest:brahmaputra.1.0 Check that the image is available:: - $ docker images + docker images -Run the docker container giving the environment variables:: +Run the docker container giving the environment variables: - - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel" or "joid". - - INSTALLER_IP. each installer has its installation strategy. + * INSTALLER_TYPE : possible values are "apex", "compass", "fuel" or "joid". + * INSTALLER_IP : IP of the installer node/VM. -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...). +Functest may need to know the IP of the installer to retrieve the credentials from +the installer node/VM or even from the actual controllers. -The minimum command to create the Functest docker file can be described as +The minimum command to create the Functest Docker container can be described as follows:: docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash @@ -32,15 +32,18 @@ Optionally, it is possible to precise the container name through the option docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash -It is also possible to to indicate the path of the OpenStack creds using -v:: +It is also possible to to indicate the path of the OpenStack credentials 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:brahmaputra.1.0 /bin/bash The local file will be mounted in the container under /home/opnfv/functest/conf/openstack.creds -After the run command the prompt appears which means that we are inside the -container and ready to run Functest. +If the intention is to run Functest against any of the supported OPNFV scenarios, +it is recommended to include also the environment variable **DEPLOY_SCENARIO**, +For instance:: + + docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -e "DEPLOY_SCENARIO=os-odl_l2-nofeature-ha" opnfv/functest:brahmaputra.1.0 /bin/bash Inside the container, the following directory structure should be in place:: @@ -52,8 +55,11 @@ Inside the container, the following directory structure should be in place:: | `-- results `-- repos |-- bgpvpn + |-- doctor |-- functest |-- odl_integration + |-- onos + |-- promise |-- rally |-- releng `-- vims-test @@ -61,15 +67,15 @@ Inside the container, the following directory structure should be in place:: 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) + * Functest directory to store the configuration (the OpenStack creds are stored + in /home/opngb/functest/conf/openstack.creds), the data (cirros image needed for + some tests), results (some temporary result logs may be stored here) * Repositories: the functest repository will be used to prepare the - environment, 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) + environment and run the tests. Other repositories are used for the installation + of the needed tooling (e.g. rally) and/or the retrieval of feature projects + scenarios (e.g. promise) -The arborescence under the functest repo can be described as follow:: +The structure under the Functest repository can be described as follows:: . |-- INFO @@ -86,38 +92,164 @@ The arborescence under the functest repo can be described as follow:: | `-- run_tests.sh |-- docs | |-- configguide - | |-- functest.rst + | |-- devguide | |-- images + | |-- results | `-- userguide `-- testcases |-- Controllers + |-- features + |-- tests |-- VIM + |-- vIMS + |-- vPing |-- __init__.py |-- config_functest.py |-- config_functest.yaml - |-- functest_utils.py - |-- functest_utils.pyc - |-- vIMS - `-- vPing + `-- functest_utils.py We may distinguish 4 different folders: - * commons: it is a folder dedicated to store traffic profile or any test + * **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 + * **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 + * **docs**: this folder includes the user and installation/configuration guide + * **testcases**: this folder includes the scripts required by Functest internal + test cases and other feature projects test cases. + +After the *run* command, a new prompt appears which means that we are inside the +container and ready to move to the next step. + + +Useful Docker commands +---------------------- + +When typing **exit** in the container prompt, this will cause sometimes +exiting the container and stopping it. When stopping a running Docker container +all the changes will be lost when it is started again. There is a shortcut to +quit the container without stopping it. Type CTRL+P+Q to keep the changes. +To reconnect to the running container **DO NOT** use the *run* command again +(since it will create a new container) use *exec* instead:: + + docker ps + <copy the container ID> + docker exec -ti <CONTAINER_ID> bash + +or simply:: + + docker exec -ti $(docker ps|grep functest|awk '{print $1}') bash + +There are other useful Docker commands that might be needed to manage possible +issues with the containers. + + * List the running containers:: + + docker ps + + * List all the containers including the stopped ones:: + + docker ps -a + + * It is useful sometimes to remove a container if there are some problems:: + + docker rm <CONTAINER_ID> + + * Use the *-f* option if the container is still running, it will force to destroy it:: + + docker -f rm <CONTAINER_ID> + +The Docker image is named **opnfv/functest** and it is stored in the public +Docker registry under the OPNFV account: dockerhub_. +The are many different tags that have been created automatically by the CI +mechanisms, but the one that this document refers to is **brahmaputra.1.0**. +Other tags might cause some problems while running the tests. + +Check the Docker documentation dockerdocs_ for more information. + + +Preparing the Functest environment +---------------------------------- + +Once the docker container is up and running, execute the following command in the +prompt:: + + ${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/* + +This script will make sure that the requirements to run the tests are met and will +install the needed libraries and tools by all Functest test cases. It must be run +only once every time the docker is started. + + +Focus on the OpenStack credentials +---------------------------------- + +The OpenStack credentials are needed to run the tests against 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 credentials 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 + +or simply using the environment variable **$creds**:: + + . $creds + +After this, try to run any OpenStack command to see if you get any output, +for instance:: + + openstack user list + +This will return a list of the actual users in the OpenStack deployment. In any +other case, check that the credentials are sourced:: + + env|grep OS_ + +This command must show a set of environment variables starting with *OS_*, for example:: + + OS_REGION_NAME=RegionOne + OS_DEFAULT_DOMAIN=default + OS_PROJECT_NAME=admin + OS_PASSWORD=admin + OS_AUTH_STRATEGY=keystone + OS_AUTH_URL=http://172.30.10.3:5000/v2.0 + OS_USERNAME=admin + OS_TENANT_NAME=admin + OS_ENDPOINT_TYPE=internalURL + OS_NO_CACHE=true + +If still the OpenStack command does not show anything or complains about +connectivity issues, it could be due to an incorrect url given to the OS_AUTH_URL +environment variable. Check the deployment settings. + +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:: -Firstly run the script to install functest environment:: + wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml - $ ${repos_dir}/functest/docker/prepare_env.sh + <modify the file accordingly> -NOTE: ${repos_dir} is a default environment variable inside the docker -container, which points to /home/opnfv/repos + docker run -ti -e \ + "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" \ + opnfv/functest:brahmaputra.1.0 \ + -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \ + /bin/bash\ -Run the script to start the tests:: +However, this is not recommended since most of the test cases rely on static +parameters read from this file, and changing them might cause problems. - $ ${repos_dir}/functest/docker/run_tests.sh +.. _dockerdocs: https://docs.docker.com/ +.. _dockerhub: https://hub.docker.com/r/opnfv/functest/ diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst index e4a04330e..fc7b25bca 100644 --- a/docs/configguide/index.rst +++ b/docs/configguide/index.rst @@ -1,3 +1,6 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + =============================================== OPNFV FUNCTEST configuration/installation guide =============================================== @@ -9,85 +12,12 @@ OPNFV FUNCTEST configuration/installation guide Introduction ============ -** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA ** - 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 -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. - -Docker installation -------------------- - -.. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/ -.. _RHEL: https://docs.docker.com/installation/rhel/ - -Log on your jumphost then install docker (e.g. for Ubuntu):: - - curl -sSL https://get.docker.com/ | sh - -Add your user to docker group to be able to run commands without sudo:: - - sudo usermod -aG docker <your_user> - - -References: - - * 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:: +The high level architecture of Functest within OPNFV can be described as follows:: CIMC/Lights+out management Admin Private Public Storage PXE @@ -152,7 +82,7 @@ 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: +The automated mechanisms inside the Functest Docker container will: * retrieve OpenStack credentials * prepare the environment according to the SUT @@ -160,55 +90,98 @@ The Docker image will: * 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. +would be possible to adapt it to any VIM+controller environment since most of the +test cases are integrated from upstream communities. -.. include:: ./configguide.rst +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. + +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):: + + curl -sSL https://get.docker.com/ | sh + +Add your user to docker group to be able to run commands without sudo:: + + sudo usermod -aG docker <your_user> -NOTE: This will run ALL the tests by default, see `[2]`_ for details -Focus on the OpenStack credentials ----------------------------------- +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. Jumphost). + +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 +---------------------------------------- -The OpenStack credentials are needed to test the VIM. There are 3 ways to -provide them to Functest: +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. - * 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 +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:: -Once the credentials are there, they shall be sourced before running the tests:: + $ 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 - source /home/opnfv/functest/conf/openstack.creds +This is just an example about how to configure an interface with vlan, but it might +defer depending on the deployment settings on each installer. Check the +corresponding installer instructions for more info. -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:: +Installation and configuration +============================== - $ 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}" +.. include:: ./configguide.rst 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,24 +242,13 @@ 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/brahmaputra/docs/configguide/index.html OPNFV main site: opnfvmain_. |