diff options
Diffstat (limited to 'docs/testing/user/userguide/04-installation.rst')
| -rw-r--r-- | docs/testing/user/userguide/04-installation.rst | 147 |
1 files changed, 76 insertions, 71 deletions
diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst index 3ba312ce7..213821798 100644 --- a/docs/testing/user/userguide/04-installation.rst +++ b/docs/testing/user/userguide/04-installation.rst @@ -1,7 +1,17 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others. + License. + http://creativecommons.org/licenses/by/4.0 + (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others. + + + Convention for heading levels in Yardstick documentation: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. .. Convention for heading levels in Yardstick documentation: @@ -18,7 +28,6 @@ Yardstick Installation ====================== - Yardstick supports installation by Docker or directly in Ubuntu. The installation procedure for Docker and direct installation are detailed in the sections below. @@ -139,7 +148,7 @@ in the following sections. Before that, access the Yardstick container:: and then configure Yardstick environments in the Yardstick container. Using the CLI command ``env prepare`` (first way) (**recommended**) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ In the Yardstick container, the Yardstick repository is located in the ``/home/opnfv/repos`` directory. Yardstick provides a CLI to prepare OpenStack @@ -171,10 +180,10 @@ terminal window and execute the following command:: Manually exporting the env variables and initializing OpenStack (second way) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Export OpenStack environment variables -###################################### +'''''''''''''''''''''''''''''''''''''' Before running Yardstick it is necessary to export OpenStack environment variables:: @@ -200,7 +209,7 @@ A sample ``openrc`` file may look like this:: Manual creation of Yardstick flavor and guest images -#################################################### +'''''''''''''''''''''''''''''''''''''''''''''''''''' Before executing Yardstick test cases, make sure that Yardstick flavor and guest image are available in OpenStack. Detailed steps about creating the @@ -257,14 +266,14 @@ image. Add Cirros and Ubuntu images to OpenStack:: Automatic initialization of OpenStack (third way) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++++++++++++++++++++++++++++ Similar to the second way, the first step is also to `Export OpenStack environment variables`_. Then the following steps should be done. Automatic creation of Yardstick flavor and guest images -####################################################### +''''''''''''''''''''''''''''''''''''''''''''''''''''''' Yardstick has a script for automatically creating Yardstick flavor and building Yardstick guest images. This script is mainly used for CI and can be also used @@ -340,7 +349,6 @@ For installing Yardstick directly in Ubuntu, the ``yardstick env`` command is not available. You need to prepare OpenStack environment variables and create Yardstick flavor and guest images manually. - Uninstall Yardstick ^^^^^^^^^^^^^^^^^^^ @@ -455,112 +463,111 @@ These configuration files can be found in the ``samples`` directory. Default location for the output is ``/tmp/yardstick.out``. -Automatic installation of Yardstick using ansible -------------------------------------------------- +Automatic installation of Yardstick +----------------------------------- -Automatic installation can be used as an alternative to the manual. -Yardstick can be installed on the bare metal and to the container. Yardstick +Automatic installation can be used as an alternative to the manual by +providing parameters for ansible script ``install.yaml`` in a ``nsb_setup.sh`` +file. Yardstick can be installed on the bare metal and to the container. Yardstick container can be either pulled or built. Bare metal installation ^^^^^^^^^^^^^^^^^^^^^^^ -Use ansible script ``install.yaml`` to install Yardstick on Ubuntu server: +Modify ``nsb_setup.sh`` file ``install.yaml`` parameters to install Yardstick +on Ubuntu server: .. code-block:: console ansible-playbook -i install-inventory.ini install.yaml \ + -e IMAGE_PROPERTY='none' \ -e YARDSTICK_DIR=<path to Yardstick folder> .. note:: By default ``INSTALLATION_MODE`` is ``baremetal``. -.. note:: By default Ubuntu 16.04 is chosen (xenial). It can be changed to - Ubuntu 18.04 (bionic) by passing ``-e OS_RELEASE=bionic`` parameter. +.. note:: No modification in ``install-inventory.ini`` is needed for Yardstick + installation. .. note:: To install Yardstick in virtual environment pass parameter ``-e VIRTUAL_ENVIRONMENT=True``. -To build Yardstick NSB image pass ``IMG_PROPERTY=nsb`` as input parameter: - -.. code-block:: console - - ansible-playbook -i install-inventory.ini install.yaml \ - -e IMAGE_PROPERTY=nsb \ - -e YARDSTICK_DIR=<path to Yardstick folder> - -.. note:: In this ``INSTALLATION_MODE`` mode either Yardstick image or SampleVNF - images will be built. Image type is defined by parameter ``IMAGE_PROPERTY``. - By default Yardstick image will be built. - Container installation ^^^^^^^^^^^^^^^^^^^^^^ -Use ansible script ``install.yaml`` to pull or build Yardstick -container. To pull Yardstick image and start container run: +Modify ``install.yaml`` parameters in ``nsb_setup.sh`` file to pull or build +Yardstick container. To pull Yardstick image and start container run: .. code-block:: console ansible-playbook -i install-inventory.ini install.yaml \ - -e YARDSTICK_DIR=<path to Yardstick folder> \ + -e IMAGE_PROPERTY='none' \ -e INSTALLATION_MODE=container_pull -.. note:: In this ``INSTALLATION_MODE`` mode either Yardstick image or SampleVNF - images will be built. Image type is defined by variable ``IMG_PROPERTY`` in - file ``ansible/group_vars/all.yml``. By default Yardstick image will be - built. - -.. note:: Open question: How to know if Docker image is built on Ubuntu 16.04 and 18.04? - Do we need separate tag to be used? +.. note:: Yardstick docker image is available for both Ubuntu 16.04 and Ubuntu + 18.04. By default Ubuntu 16.04 based docker image is used. To use + Ubuntu 18.04 based docker image pass ``-i opnfv/yardstick-ubuntu-18.04`` + parameter to ``nsb_setup.sh``. -To build Yardstick image run: +To build Yardstick image modify Dockerfile as per comments in it and run: .. code-block:: console - ansible-playbook -i install-inventory.ini install.yaml \ - -e YARDSTICK_DIR=<path to Yardstick folder> \ - -e INSTALLATION_MODE=container + cd yardstick + docker build -f docker/Dockerfile -t opnfv/yardstick:<tag> . -.. note:: In this ``INSTALLATION_MODE`` mode neither Yardstick image nor SampleVNF - image will be built. +.. note:: Yardstick docker image based on Ubuntu 16.04 will be built. + Pass ``-f docker/Dockerfile_ubuntu18`` to build Yardstick docker image based + on Ubuntu 18.04. -.. note:: By default Ubuntu 16.04 is chosen (xenial). It can be changed to - Ubuntu 18.04 (bionic) by passing ``-e OS_RELEASE=bionic`` parameter. +.. note:: Add ``--build-arg http_proxy=http://<proxy_host>:<proxy_port>`` to + build docker image if server is behind the proxy. Parameters for ``install.yaml`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Description of the parameters used with ``install.yaml`` script +Description of the parameters used with ``install.yaml``: +-------------------------+-------------------------------------------------+ | Parameters | Detail | +=========================+=================================================+ - | -i install-inventory.ini| Installs package dependency to remote servers | - | | Mandatory parameter | - | | By default no remote servers are provided | - | | Needed packages will be installed on localhost | + | -i install-inventory.ini|| Installs package dependency to remote servers | + | || and localhost | + | || Mandatory parameter | + | || By default no remote servers are provided | +-------------------------+-------------------------------------------------+ - | -e YARDSTICK_DIR | Path to Yardstick folder | - | | Mandatory parameter | + | -e YARDSTICK_DIR || Path to Yardstick folder | + | || Mandatory parameter for Yardstick bare metal | + | || installation | +-------------------------+-------------------------------------------------+ - | -e INSTALLATION_MODE | baremetal: Yardstick is installed to the bare | - | | metal | - | | Default parameter | + | -e INSTALLATION_MODE || baremetal: Yardstick is installed to the bare | + | | metal | + | || Default parameter | | +-------------------------------------------------+ - | | container: Yardstick is installed in container | - | | Container is built from Dockerfile | + | || container: Yardstick is installed in container | + | || Container is built from Dockerfile | | +-------------------------------------------------+ - | | container_pull: Yardstick is installed in | - | | container | - | | Container is pulled from docker hub | + | || container_pull: Yardstick is installed in | + | || container | + | || Container is pulled from docker hub | + +-------------------------+-------------------------------------------------+ + | -e OS_RELEASE || xenial or bionic: Ubuntu version to be used for| + | || VM image (nsb or normal) | + | || Default is Ubuntu 16.04, xenial | +-------------------------+-------------------------------------------------+ - | -e OS_RELEASE | xenial or bionic: Ubuntu version to be used | - | | Default is Ubuntu 16.04 (xenial) | + | -e IMAGE_PROPERTY || nsb: Build Yardstick NSB VM image | + | || Used to run Yardstick NSB tests on sample VNF | + | || Default parameter | + | +-------------------------------------------------+ + | || normal: Build VM image to run ping test in | + | || OpenStack | + | +-------------------------------------------------+ + | || none: don't build a VM image. | +-------------------------+-------------------------------------------------+ - | -e IMAGE_PROPERTY | normal or nsb: Type of the VM image to be built | - | | Default image is Yardstick | + | -e VIRTUAL_ENVIRONMENT || False or True: Whether install in virtualenv | + | || Default is False | +-------------------------+-------------------------------------------------+ - | -e VIRTUAL_ENVIRONMENT | False or True: Whether install in virtualenv | - | | Default is False | + | -e YARD_IMAGE_ARCH || CPU architecture on servers | + | || Default is 'amd64' | +-------------------------+-------------------------------------------------+ @@ -655,11 +662,9 @@ Modify ``yardstick.conf`` to add the ``influxdb`` dispatcher:: Now Yardstick will store results in InfluxDB when you run a testcase. - Deploy InfluxDB and Grafana directly in Ubuntu (**Todo**) --------------------------------------------------------- - Proxy Support ------------- |