diff options
Diffstat (limited to 'docs/testing/user/configguide')
| -rw-r--r-- | docs/testing/user/configguide/configguide.rst | 820 | ||||
| -rw-r--r-- | docs/testing/user/configguide/index.rst | 296 |
2 files changed, 1116 insertions, 0 deletions
diff --git a/docs/testing/user/configguide/configguide.rst b/docs/testing/user/configguide/configguide.rst new file mode 100644 index 000000000..1bb8358a8 --- /dev/null +++ b/docs/testing/user/configguide/configguide.rst @@ -0,0 +1,820 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Pulling the Docker image +------------------------ +Pull the Functest Docker image ('opnfv/functest') from the public +dockerhub registry under the OPNFV account: [dockerhub_], with the +following docker command:: + + docker pull opnfv/functest:<TagIdentifier> + +where <TagIdentifier> identifies a release of the Functest docker +container image in the public dockerhub registry. There are many tags +created automatically by the CI mechanisms, and you must ensure you +pull an image with the **correct tag** to match the OPNFV software +release installed in your environment. All available tagged images can +be seen from location [FunctestDockerTags_]. For example, when running +on the first official release of the OPNFV Colorado system platform, +tag "colorado.1.0" is needed. Pulling other tags might cause some +problems while running the tests. +Docker images pulled without a tag specifier bear the implicitly +assigned label "latest". If you need to specifically pull the latest +Functest docker image, then omit the tag argument:: + + docker pull opnfv/functest + +After pulling the Docker image, check that it is available with the +following docker command:: + + [functester@jumphost ~]$ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + opnfv/functest latest 8cd6683c32ae 2 weeks ago 1.321 GB + opnfv/functest danube.1.0 13fa54a1b238 4 weeks ago 1.29 GB + opnfv/functest colorado.1.0 94b78faa94f7 9 weeks ago 968 MB + +The Functest docker container environment can -in principle- be also +used with non-OPNFV official installers (e.g. 'devstack'), with the +**disclaimer** that support for such environments is outside of the +scope and responsibility of the OPNFV project. + +Accessing the Openstack credentials +----------------------------------- +OpenStack credentials are mandatory and can be retrieved in different +ways. From inside the running Functest docker container the +"functest env prepare" command will automatically look for the +Openstack credentials file "/home/opnfv/functest/conf/openstack.creds" +and retrieve it unless the file already exists. This Functest +environment preparation step is described later in this document. + +WARNING: When the installer type is "joid" you have to have the +credentials file inside the running container **before** initiating the +functest environment preparation. For that reason you have to choose +either one of the options below, since the automated copying does not +work for "joid". + +You can also specifically pass in the needed file prior to running the +environment preparation either: + + * by using the -v option when creating the Docker container. This is + referred to in docker documentation as "Bind Mounting". See the + usage of this parameter in the following chapter. + * or creating a local file '/home/opnfv/functest/conf/openstack.creds' + inside the running container with the credentials in it. Consult + your installer guide for further details. This is however not + instructed in this document. + +NOTE: When the installer type is "fuel" and virtualized deployment +is used, there you have to explicitly fetch the credentials file +executing the following sequence + + #. Create a container as described in next chapter but do not + "Bind Mount" the credentials + #. Log in to container and execute the following command. Replace + the IP with installer address after the "-a" parameter:: + + $REPOS_DIR/releng/utils/fetch_os_creds.sh \ + -d /home/opnfv/functest/conf/openstack.creds \ + -i fuel \ + -a 10.20.0.2 \ + -v + ( -d specifies the full path to the Openstack credential file + -i specifies the INSTALLER_TYPE + -a specifies the INSTALLER_IP + -v indicates a virtualized environment and takes no arguments ) + + #. Continue with your testing, initiate functest environment + preparation, run tests etc. + +In proxified environment you may need to change the credentials file. +There are some tips in chapter: `Proxy support`_ + +Functest Docker parameters +-------------------------- +This chapter explains how to run a container for executing functest +test suites. Numbered list below explains some details of the +recommended parameters for invoking docker container + + #. It is a good practice to assign a precise container name through + the **--name** option. + + #. Assign parameter for installer type:: + + -e "INSTALLER_TYPE=<type>" + # Use one of following apex, compass, fuel or joid + + #. Functest needs to know the IP of some installers:: + + -e "INSTALLER_IP=<Specific IP Address>" + + This IP is needed to fetch RC file from deployment, fetch logs, ... + If not provided, there is no way to fetch the RC file. It must be + provided manually as a volume + + #. Credentials for accessing the Openstack. + Most convenient way of passing them to container is by having a + local copy of the credentials file in Jumphost and then using the + **-v** option. In the example we have local file by the name of + "overcloudrc" and we are using that as an argument:: + + -v ~/overcloudrc:/home/opnfv/functest/conf/openstack.creds + + The credentials file needs to exist in the Docker container + under the path: '/home/opnfv/functest/conf/openstack.creds'. + + **WARNING:** If you are using the Joid installer, you must pass the + credentials using the **-v** option: + -v /var/lib/jenkins/admin-openrc:/home/opnfv/functest/conf/openstack.creds. + See the section `Accessing the Openstack credentials`_ above. + + #. Passing deployment scenario + When running Functest against any of the supported OPNFV scenarios, + it is recommended to include also the environment variable + **DEPLOY_SCENARIO**. The **DEPLOY_SCENARIO** environment variable + is passed with the format:: + + -e "DEPLOY_SCENARIO=os-<controller>-<nfv_feature>-<ha_mode>" + where: + os = OpenStack (No other VIM choices currently available) + controller is one of ( nosdn | odl_l2 | odl_l3 | onos | ocl) + nfv_feature is one or more of ( ovs | kvm | sfc | bgpvpn | nofeature ) + If several features are pertinent then use the underscore + character '_' to separate each feature (e.g. ovs_kvm) + 'nofeature' indicates no NFV feature is deployed + ha_mode (high availability) is one of ( ha | noha ) + + **NOTE:** Not all possible combinations of "DEPLOY_SCENARIO" are + supported. The name passed in to the Functest Docker container + must match the scenario used when the actual OPNFV platform was + deployed. See release note to see the list of supported scenarios. + + **NOTE:** The scenario name is mainly used to automatically detect + if a test suite is runnable or not (e.g. it will prevent ONOS test suite + to be run on ODL scenarios). If not set, Functest will try to run the + default test cases that might not include SDN controller or a specific + feature + + **NOTE:** A HA scenario means that 3 OpenStack controller nodes are + deployed. It does not necessarily mean that the whole system is HA. See + installer release notes for details. + + +Putting all above together, when using installer 'fuel' and an invented +INSTALLER_IP of '10.20.0.2', the recommended command to create the +Functest Docker container is as follows:: + + docker run --name "FunctestContainer" -it \ + -e "INSTALLER_IP=10.20.0.2" \ + -e "INSTALLER_TYPE=fuel" \ + -e "DEPLOY_SCENARIO=os-odl_l2-ovs_kvm-ha" \ + -v ~/overcloudrc:/home/opnfv/functest/conf/openstack.creds \ + opnfv/functest /bin/bash + +After the *run* command, a new prompt appears which means that we are inside +the container and ready to move to the next step. + +For tips on how to set up container with installer Apex, see chapter +`Apex Installer Tips`_. + +Finally, three additional environment variables can also be passed in +to the Functest Docker Container, using the -e +"<EnvironmentVariable>=<Value>" mechanism. The first two of these are +only relevant to Jenkins CI invoked testing and **should not be used** +when performing manual test scenarios:: + + -e "NODE_NAME=<Test POD Name>" \ + -e "BUILD_TAG=<Jenkins Build Tag>" \ + -e "CI_DEBUG=<DebugTraceValue>" + where: + <Test POD Name> = Symbolic name of the POD where the tests are run. + Visible in test results files, which are stored + to the database. This option is only used when + tests are activated under Jenkins CI control. + It indicates the POD/hardware where the test has + been run. If not specified, then the POD name is + defined as "Unknown" by default. + DO NOT USE THIS OPTION IN MANUAL TEST SCENARIOS. + <Jenkins Build tag> = Symbolic name of the Jenkins Build Job. + Visible in test results files, which are stored + to the database. This option is only set when + tests are activated under Jenkins CI control. + It enables the correlation of test results, + which + are independently pushed to the results datbase + from different Jenkins jobs. + DO NOT USE THIS OPTION IN MANUAL TEST SCENARIOS. + <DebugTraceValue> = "true" or "false" + Default = "false", if not specified + If "true" is specified, then additional debug trace + text can be sent to the test results file / log files + and also to the standard console output. + +Apex Installer Tips +------------------- +Some specific tips are useful for the Apex Installer case. If not using +Apex Installer; ignore this section. + +In case of Triple-O based installer (like Apex) the docker container +needs to connect to the installer VM, so it is then required that some +known SSH keys are present in docker container. Since the Jumphost root +SSH keys are already known, easiest way is to use those using the +'Bind mount' method. See below for sample parameter:: + + -v /root/.ssh/id_rsa:/root/.ssh/id_rsa + + NOTE: You need the "sudo" when creating the container to access root + users ssh credentials even the docker command itself might not + require that. + +HINT! In case of Triple-O installers you can find value for the +INSTALLER_IP parameter by executing command and note the returned IP +address:: + + inst=$(sudo virsh list | grep -iEo "undercloud|instack") + sudo virsh domifaddr ${inst} + + NOTE: In releases prior to Colorado, the name 'instack' was + used. Currently the name 'undercloud' is used. + +You can copy the credentials file from the "stack" users home directory +in installer VM to Jumphost. Please check the correct IP from the +command above. In the example below we are using invented IP address +"192.168.122.89":: + + scp stack@192.168.122.89:overcloudrc . + +Here is an example of the full docker command invocation for an Apex +installed system, using latest Functest docker container, for +illustration purposes:: + + sudo docker run -it --name "ApexFuncTestODL" \ + -e "INSTALLER_IP=192.168.122.89" \ + -e "INSTALLER_TYPE=apex" \ + -e "DEPLOY_SCENARIO=os-odl_l2-nofeature-ha" \ + -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \ + -v ~/overcloudrc:/home/opnfv/functest/conf/openstack.creds \ + opnfv/functest /bin/bash + +Compass installer local development env usage Tips +-------------------------------------------------- +In the compass-functest local test case check and development environment, +in order to get openstack service inside the functest container, some +parameters should be configured during container creation, which are +hard to guess for freshman. This section will provide the guideline, the +parameters values are defaults here, which should be adjusted according +to the settings, the complete steps are given here so as not to appear +too abruptly. + +1, Pull Functest docker image from public dockerhub:: + + docker pull opnfv/functest:<Tag> + +<Tag> here can be "brahmaputra.1.0", "colorado.1.0", etc. +Tag omitted means the latest docker image:: + + docker pull opnfv/functest + +2, Functest Docker container creation + +To make a file used for the environment, such as 'functest-docker-env':: + + OS_AUTH_URL=http://172.16.1.222:35357/v2.0 + OS_USERNAME=admin + OS_PASSWORD=console + OS_TENANT_NAME=admin + OS_VOLUME_API_VERSION=2 + OS_PROJECT_NAME=admin + INSTALLER_TYPE=compass + INSTALLER_IP=192.168.200.2 + EXTERNAL_NETWORK=ext-net + +Note: please adjust the content according to the environment, such as +'TENANT_ID' maybe used for some special cases. + +Then to create the Functest docker:: + + docker run --privileged=true --rm -t \ + --env-file functest-docker-env \ + --name <Functest_Container_Name> \ + opnfv/functest:<Tag> /bin/bash + +3, To attach Functest container + +Before trying to attach the Functest container, the status can be checked by:: + + docker ps -a + +to attach the 'Up' status Functest container and start bash mode:: + + docker exec -it <Functest_Container_Name> bash + +4, Functest environemnt preparation and check + +To see the Section below `Preparing the Functest environment`_. + +Functest docker container directory structure +--------------------------------------------- +Inside the Functest docker container, the following directory structure +should now be in place:: + + `-- home + `-- opnfv + |-- functest + | |-- conf + | |-- data + | `-- results + `-- repos + |-- bgpvpn + |-- copper + |-- doctor + |-- domino + |-- functest + |-- kingbird + |-- odl_test + |-- onos + |-- ovno + |-- parser + |-- promise + |-- rally + |-- releng + |-- sdnvpn + |-- securityscanning + |-- sfc + |-- tempest + |-- vims_test + `-- vnfs + +Underneath the '/home/opnfv/' directory, the Functest docker container +includes two main directories: + + * The **functest** directory stores configuration files (e.g. the + OpenStack creds are stored in path '/home/opnfv/functest/conf/openstack.creds'), + the **data** directory stores a 'cirros' test image used in some + functional tests and the **results** directory stores some temporary + result log files + * The **repos** directory holds various repositories. The directory + '/home/opnfv/repos/functest' is used to prepare the needed Functest + environment and to run the tests. The other repository directories + are used for the installation of the needed tooling (e.g. rally) or + for the retrieval of feature projects scenarios (e.g. promise) + +The structure under the **functest** repository can be described as +follows:: + + . |-- INFO + |-- LICENSE + |-- requirements.txt + |-- run_unit_tests.sh + |-- setup.py + |-- test-requirements.txt + |-- commons + | |-- ims + | |-- mobile + | `--traffic-profile-guidelines.rst + |-- docker + | |-- Dockerfile + | |-- config_install_env.sh + | `-- docker_remote_api + |-- docs + | |-- com + | |-- configguide + | |-- devguide + | |-- images + | |-- internship + | |-- release-notes + | |-- results + | `--userguide + |-- functest + |-- __init__.py + |-- ci + | |-- __init__.py + | |-- check_os.sh + | |-- config_functest.yaml + | |-- config_patch.yaml + | |-- generate_report.py + | |-- prepare_env.py + | |-- run_tests.py + | |-- testcases.yaml + | |-- tier_builder.py + | `-- tier_handler.py + |-- cli + | |-- __init__.py + | |-- cli_base.py + | |-- commands + | |-- functest-complete.sh + | `-- setup.py + |-- core + | |-- __init__.py + | |-- feature_base.py + | |-- pytest_suite_runner.py + | |-- testcase_base.py + | |-- vnf_base.py + |-- opnfv_tests + | |-- __init__.py + | |-- features + | |-- mano + | |-- openstack + | |-- sdn + | |-- security_scan + | `-- vnf + |-- tests + | |-- __init__.py + | `-- unit + `-- utils + |-- __init__.py + |-- config.py + |-- constants.py + |-- env.py + |-- functest_constants.py + |-- functest_logger.py + |-- functest_utils.py + |-- openstack + |-- openstack_clean.py + |-- openstack_snapshot.py + |-- openstack_tacker.py + `-- openstack_utils.py + + + (Note: All *.pyc files removed from above list for brevity...) + +We may distinguish several directories, the first level has 4 directories: + +* **commons**: This directory is dedicated for storage of traffic + profile or any other test inputs that could be reused by any test + project. +* **docker**: This directory includes the needed files and tools to + build the Funtest Docker image. +* **docs**: This directory includes documentation: Release Notes, + User Guide, Configuration Guide and Developer Guide. Test results + are also located in a sub--directory called 'results'. +* **functest**: This directory contains all the code needed to run + functest internal cases and OPNFV onboarded feature or VNF test cases. + +Functest directory has 6 directories: + * **ci**: This directory contains test structure definition files + (e.g <filename>.yaml) and bash shell/python scripts used to + configure and execute Functional tests. The test execution script + can be executed under the control of Jenkins CI jobs. + * **cli**: This directory holds the python based Functest CLI utility + source code, which is based on the Python 'click' framework. + * **core**: This directory holds the python based Functest core + source code. Three abstraction classes have been created to ease + the integration of internal, feature or vnf cases. + * **opnfv_tests**: This directory includes the scripts required by + Functest internal test cases and other feature projects test cases. + * **tests**: This directory includes the functest unit tests + * **utils**: this directory holds Python source code for some general + purpose helper utilities, which testers can also re-use in their + own test code. See for an example the Openstack helper utility: + 'openstack_utils.py'. + +Useful Docker commands +---------------------- +When typing **exit** in the container prompt, this will cause exiting +the container and probably stopping it. When stopping a running Docker +container all the changes will be lost, there is a keyboard shortcut +to quit the container without stopping it: <CTRL>-P + <CTRL>-Q. To +reconnect to the running container **DO NOT** use the *run* command +again (since it will create a new container), use the *exec* or *attach* +command instead:: + + docker ps # <check the container ID from the output> + docker exec -ti <CONTAINER_ID> /bin/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 + +Start a stopped container named "FunTest":: + + docker start FunTest + +Attach to a running container named "StrikeTwo":: + + docker attach StrikeTwo + +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 rm -f <CONTAINER_ID> + +Check the Docker documentation dockerdocs_ for more information. + +Preparing the Functest environment +---------------------------------- +Once the Functest docker container is up and running, the required +Functest environment needs to be prepared. A custom built **functest** +CLI utility is available to perform the needed environment preparation +action. Once the environment is prepared, the **functest** CLI utility +can be used to run different functional tests. The usage of the +**functest** CLI utility to run tests is described further in the +Functest User Guide `OPNFV_FuncTestUserGuide`_ + +Prior to commencing the Functest environment preparation, we can check +the initial status of the environment. Issue the **functest env status** +command at the prompt:: + + functest env status + Functest environment is not installed. + + Note: When the Functest environment is prepared, the command will + return the status: "Functest environment ready to run tests." + +To prepare the Functest docker container for test case execution, issue +the **functest env prepare** command at the prompt:: + + functest env prepare + +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 should be run only once every time the Functest docker +container is started from scratch. If you try to run this command, on +an already prepared enviroment, you will be prompted whether you really +want to continue or not:: + + functest env prepare + It seems that the environment has been already prepared. + Do you want to do it again? [y|n] + + (Type 'n' to abort the request, or 'y' to repeat the + environment preparation) + + +To list some basic information about an already prepared Functest +docker container environment, issue the **functest env show** at the +prompt:: + + functest env show + +======================================================+ + | Functest Environment info | + +======================================================+ + | INSTALLER: apex, 192.168.122.89 | + | SCENARIO: os-odl_l2-nofeature-ha | + | POD: localhost | + | GIT BRANCH: master | + | GIT HASH: 5bf1647dec6860464eeb082b2875798f0759aa91 | + | DEBUG FLAG: false | + +------------------------------------------------------+ + | STATUS: ready | + +------------------------------------------------------+ + + Where: + + INSTALLER: Displays the INSTALLER_TYPE value + - here = "apex" + and the INSTALLER_IP value + - here = "192.168.122.89" + SCENARIO: Displays the DEPLOY_SCENARIO value + - here = "os-odl_l2-nofeature-ha" + POD: Displays the value passed in NODE_NAME + - here = "localhost" + GIT BRANCH: Displays the git branch of the OPNFV Functest + project repository included in the Functest + Docker Container. + - here = "master" + (In first official colorado release + would be "colorado.1.0") + GIT HASH: Displays the git hash of the OPNFV Functest + project repository included in the Functest + Docker Container. + - here = "5bf1647dec6860464eeb082b2875798f0759aa91" + DEBUG FLAG: Displays the CI_DEBUG value + - here = "false" + + NOTE: In Jenkins CI runs, an additional item "BUILD TAG" + would also be listed. The valaue is set by Jenkins CI. + +Finally, the **functest** CLI has a **--help** options: + +Some examples:: + + functest --help Usage: functest [OPTIONS] COMMAND [ARGS]... + + Options: + --version Show the version and exit. + -h, --help Show this message and exit. + + Commands: + env + openstack + testcase + tier + + functest env --help + Usage: functest env [OPTIONS] COMMAND [ARGS]... + + Options: + -h, --help Show this message and exit. + + Commands: + prepare Prepares the Functest environment. + show Shows information about the current... + status Checks if the Functest environment is ready... + +Checking Openstack and credentials +---------------------------------- +It is recommended and fairly straightforward to check that Openstack +and credentials are working as expected. + +Once the credentials are there inside the container, they should be +sourced before running any Openstack commands:: + + source /home/opnfv/functest/conf/openstack.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 the OpenStack command still 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. + +SSL Support +----------- +If you need to connect to a server that is TLS-enabled (the auth URL +begins with "https") and it uses a certificate from a private CA or a +self-signed certificate, then you will need to specify the path to an +appropriate CA certificate to use, to validate the server certificate +with the environment variable OS_CACERT:: + + echo $OS_CACERT + /etc/ssl/certs/ca.crt + +However, this certificate does not exist in the container by default. +It has to be copied manually from the OpenStack deployment. This can be +done in 2 ways: + + #. Create manually that file and copy the contents from the OpenStack + controller. + #. (Recommended) Add the file using a Docker volume when starting the + container:: + + -v <path_to_your_cert_file>:/etc/ssl/certs/ca.cert + +You might need to export OS_CACERT environment variable inside the +container:: + + export OS_CACERT=/etc/ssl/certs/ca.crt + +Certificate verification can be turned off using OS_INSECURE=true. For +example, Fuel uses self-signed cacerts by default, so an pre step would +be:: + + export OS_INSECURE=true + +Proxy support +------------- +If your Jumphost node is operating behind a http proxy, then there are +2 places where some special actions may be needed to make operations +succeed: + + #. Initial installation of docker engine First, try following the + official Docker documentation for Proxy settings. Some issues were + experienced on CentOS 7 based Jumphost. Some tips are documented + in section: `Docker Installation on CentOS behind http proxy`_ + below. + + #. Execution of the Functest environment preparation inside the + created docker container Functest needs internet access to + download some resources for some test cases. This might not + work properly if the Jumphost is connecting to internet + through a http Proxy. + +If that is the case, make sure the resolv.conf and the needed +http_proxy and https_proxy environment variables, as well as the +'no_proxy' environment variable are set correctly:: + + # Make double sure that the 'no_proxy=...' line in the + # 'openstack.creds' file is commented out first. Otherwise, the + # values set into the 'no_proxy' environment variable below will + # be ovewrwritten, each time the command + # 'source ~/functest/conf/openstack.creds' is issued. + + cd ~/functest/conf/ + sed -i 's/export no_proxy/#export no_proxy/' openstack.creds + source ./openstack.creds + + # Next calculate some IP addresses for which http_proxy + # usage should be excluded: + + publicURL_IP=$(echo $OS_AUTH_URL | grep -Eo "([0-9]+\.){3}[0-9]+") + + adminURL_IP=$(openstack catalog show identity | \ + grep adminURL | grep -Eo "([0-9]+\.){3}[0-9]+") + + export http_proxy="<your http proxy settings>" + export https_proxy="<your https proxy settings>" + export no_proxy="127.0.0.1,localhost,$publicURL_IP,$adminURL_IP" + + # Ensure that "git" uses the http_proxy + # This may be needed if your firewall forbids SSL based git fetch + git config --global http.sslVerify True + git config --global http.proxy <Your http proxy settings> + +Validation check: Before running **'functest env prepare'** CLI command, +make sure you can reach http and https sites from inside the Functest +docker container. + +For example, try to use the **nc** command from inside the functest +docker container:: + + nc -v opnfv.org 80 + Connection to opnfv.org 80 port [tcp/http] succeeded! + + nc -v opnfv.org 443 + Connection to opnfv.org 443 port [tcp/https] succeeded! + +Note: In a Jumphost node based on the CentOS family OS, the **nc** +commands might not work. You can use the **curl** command instead. + + curl http://www.opnfv.org:80 + <HTML><HEAD><meta http-equiv="content-type" + . + . + </BODY></HTML> + + curl https://www.opnfv.org:443 + <HTML><HEAD><meta http-equiv="content-type" + . + . + </BODY></HTML> + + (Ignore the content. If command returns a valid HTML page, it proves + the connection.) + +Docker Installation on CentOS behind http proxy +----------------------------------------------- +This section is applicable for CentOS family OS on Jumphost which +itself is behind a proxy server. In that case, the instructions below +should be followed **before** installing the docker engine:: + + 1) # Make a directory '/etc/systemd/system/docker.service.d' + # if it does not exist + sudo mkdir /etc/systemd/system/docker.service.d + + 2) # Create a file called 'env.conf' in that directory with + # the following contents: + [Service] + EnvironmentFile=-/etc/sysconfig/docker + + 3) # Set up a file called 'docker' in directory '/etc/sysconfig' + # with the following contents: + HTTP_PROXY="<Your http proxy settings>" + HTTPS_PROXY="<Your https proxy settings>" + http_proxy="${HTTP_PROXY}" + https_proxy="${HTTPS_PROXY}" + + 4) # Reload the daemon + systemctl daemon-reload + + 5) # Sanity check - check the following docker settings: + systemctl show docker | grep -i env + + Expected result: + ---------------- + EnvironmentFile=/etc/sysconfig/docker (ignore_errors=yes) + DropInPaths=/etc/systemd/system/docker.service.d/env.conf + +Now follow the instructions in [`InstallDockerCentOS`_] to download +and install the **docker-engine**. The instructions conclude with a +"test pull" of a sample "Hello World" docker container. This should now +work with the above pre-requisite actions. + +.. _dockerdocs: https://docs.docker.com/ +.. _dockerhub: https://hub.docker.com/r/opnfv/functest/ +.. _Proxy: https://docs.docker.com/engine/admin/systemd/#http-proxy +.. _FunctestDockerTags: https://hub.docker.com/r/opnfv/functest/tags/ +.. _InstallDockerCentOS: https://docs.docker.com/engine/installation/linux/centos/ +.. _OPNFV_FuncTestUserGuide: http://artifacts.opnfv.org/functest/docs/userguide/index.html diff --git a/docs/testing/user/configguide/index.rst b/docs/testing/user/configguide/index.rst new file mode 100644 index 000000000..f12739e31 --- /dev/null +++ b/docs/testing/user/configguide/index.rst @@ -0,0 +1,296 @@ +.. 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 + +Version history +=============== + ++------------+----------+------------------+----------------------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++------------+----------+------------------+----------------------------------+ +| 2016-08-17 | 1.0.0 | Juha Haapavirta | Colorado release | +| | | Column Gaynor | | ++------------+----------+------------------+----------------------------------+ +| 2017-01-19 | 1.0.1 | Morgan Richomme | Adaptations for Danube | +| | | | * update testcase list | +| | | | * update docker command | ++------------+----------+------------------+----------------------------------+ + +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 +----------------------- + +The high level architecture of Functest within OPNFV can be described as +follows:: + + CIMC/Lights+out management Admin Mgmt/API Public Storage Private + PXE + + + + + + + + | | | | | | + | +----------------------------+ | | | | | + | | | | | | | | + +-----+ Jumphost | | | | | | + | | +--------+ | | | | + | | | | | | | | + | | +--------------------+ | | | | | | + | | | | | | | | | | + | | | Tools | +----------------+ | | | + | | | - Rally | | | | | | | + | | | - Robot | | | | | | | + | | | - TestON | | | | | | | + | | | | |-------------------------+ | | + | | | Testcases | | | | | | | + | | | - VIM | | | | | | | + | | | -- healthcheck | | | | | | | + | | | -- vPing_ssh | | | | | | | + | | | -- vPing_userdata | | | | | | | + | | | -- SNAPS_cases | | | | | | | + | | | -- Tempest_smoke | | | | | | | + | | | -- Rally_sanity | | | | | | | + | | | -- Tempest_full | | | | | | | + | | | -- Rally_full | | | | | | | + | | | | | | | | | | + | | | - SDN Controller | | | | | | | + | | | -- odl | | | | | | | + | | | -- onos | | | | | | | + | | | | | | | | | | + | | | - Features | | | | | | | + | | | | | | | | | | + | | | - VNF | | | | | | | + | | | | | | | | | | + | | +--------------------+ | | | | | | + | | 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]`_ + + +Prerequisites +============= +The OPNFV deployment is out of the scope of this document but it can be +found in http://docs.opnfv.org. +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. + +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. + +*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 - 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 + +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="-e INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}" + [...] + docker pull opnfv/functest:$DOCKER_TAG >/dev/null + cmd="sudo docker run -id ${envs} ${volumes} ${custom_params} ${TESTCASE_OPTIONS} opnfv/functest:${DOCKER_TAG} /bin/bash" + echo "Functest: Running docker run command: ${cmd}" + ${cmd} >${redirect} + sleep 5 + container_id=$(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | 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 >${redirect} + if [ $(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | wc -l) == 0 ]; then + echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..." + exit 1 + fi + + cmd="python ${FUNCTEST_REPO_DIR}/functest/ci/prepare_env.py start" + echo "Executing command inside the docker: ${cmd}" + docker exec ${container_id} ${cmd} + + +Test execution in functest-all builder `[3]`_:: + + branch=${GIT_BRANCH##*/} + echo "Functest: run $FUNCTEST_SUITE_NAME on branch ${branch}" + cmd="functest testcase run $FUNCTEST_SUITE_NAME" + fi + container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1) + docker exec $container_id $cmd + ret_value=$? + exit $ret_value + +Docker clean in functest-cleanup builder `[3]`_ calling docker rm and docker rmi + + +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/functest/danube/docs/configguide/index.html + + +OPNFV main site: opnfvmain_. + +OPNFV functional test page: opnfvfunctest_. + +IRC support channel: #opnfv-functest + +.. _opnfvmain: http://www.opnfv.org +.. _opnfvfunctest: https://wiki.opnfv.org/functest |