From 4911a1cbc20151bf4de18a58ac11f46ea1818588 Mon Sep 17 00:00:00 2001 From: Nathan Weinberg Date: Mon, 15 Feb 2021 16:58:02 -0500 Subject: [PATCH] [docs] Made additional updates to Tobiko documentation Also reorganized a few things in a way I think makes them a bit clearer, feel free to leave feedback in reviews Change-Id: I879cb957ef35f9b6e1176a4528d8f9f5f33a4c90 --- doc/source/user/config.rst | 41 +++++++++++++++--------------- doc/source/user/install.rst | 18 ++++++------- doc/source/user/quick-start.rst | 18 ++++++------- doc/source/user/run-test-cases.rst | 10 ++++---- tobiko.conf.example | 6 ++--- 5 files changed, 47 insertions(+), 46 deletions(-) diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst index 55eca452d..a504acf5f 100644 --- a/doc/source/user/config.rst +++ b/doc/source/user/config.rst @@ -27,11 +27,11 @@ Configure Tobiko Framework In order to make sure Tobiko tools can connect to OpenStack services via Rest API configuration parameters can be passed either via environment variables or -via a ini configuration file (referred here as :ref:`tobiko-conf`). Please look +via an INI configuration file (referred here as :ref:`tobiko-conf`). Please look at :ref:`authentication-methods` for more details. To be able to execute scenario test cases there some OpenStack resources that -has to be created before running test cases. Please look at +have to be created before running test cases. Please look at :ref:`setup-required-resources` for more details. @@ -40,7 +40,7 @@ has to be created before running test cases. Please look at tobiko.conf ~~~~~~~~~~~ -Tobiko tries to load :ref:`tobiko-conf` file from one of below locations: +Tobiko tries to load :ref:`tobiko-conf` file from one of the below locations: * current directory:: @@ -58,8 +58,8 @@ Tobiko tries to load :ref:`tobiko-conf` file from one of below locations: Configure Logging ~~~~~~~~~~~~~~~~~ -Tobiko can configure logging system to write messages to a log file. You can -edit below options in :ref:`tobiko-conf` to enable it as below:: +Tobiko can configure a logging system to write messages to a log file. You can +edit the below options in :ref:`tobiko-conf` to enable it as below:: [DEFAULT] # Whenever to allow debugging messages to be written out or not @@ -132,18 +132,19 @@ Currently supported variables are:: .. _authentication-configuration: -Autentication Configuration -+++++++++++++++++++++++++++ +Authentication Configuration +++++++++++++++++++++++++++++ You can also configure the same authentication parameters by editing 'keystone' section in :ref:`tobiko-conf` file. For example:: [keystone] + # Identity API version api_version = 3 - # URL to be used to connect to OpenStack Irentity Rest API service - auth_url=http://10.0.0.109:5000/v3 + # URL to be used to connect to OpenStack Identity REST API service + auth_url = http://10.0.0.109:5000/v3 # Authentication username (name or ID) username = admin @@ -160,7 +161,7 @@ section in :ref:`tobiko-conf` file. For example:: # Domain name or ID containing user user_domain_name = default - # Domain name or ID containing prject + # Domain name or ID containing project project_domain_name = default # ID of the trust to use as a trustee user @@ -172,10 +173,10 @@ section in :ref:`tobiko-conf` file. For example:: Proxy Server Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The first thing to make sure is Tobiko can reach OpenStack services. In case +The first thing to do is make sure Tobiko can reach OpenStack services. In case OpenStack is not directly accessible from where test cases or Tobiko CLI are -executed it is possible to use an HTTP proxy server running on a network that -is able to reach all OpenStack Rest API service. This can be performed +executed, it is possible to use an HTTP proxy server running on a network that +is able to reach all OpenStack REST API service. This can be performed by using below standard environment variables:: export http_proxy=http://:/ @@ -190,7 +191,7 @@ For convenience it is also possible to specify the same parameters via https_proxy = http://:/ no_proxy = 127.0.0.1,... -Because Tobiko test cases could execute local commands (like for example ping) +Because Tobiko test cases might execute local commands (like for example ping) to reach network services we have to specify in tobiko.conf file a shell (like OpenSSH client) to be used instead of the default local one ('/bin/sh'):: @@ -215,7 +216,7 @@ Setup Required Resources ~~~~~~~~~~~~~~~~~~~~~~~~ To be able to execute Tobiko scenario test cases there some OpenStack -resources that has to be created before running test cases. +resources that have to be created before running test cases. Install required Python OpenStack clients:: @@ -241,16 +242,16 @@ in :ref:`tobiko-conf` file:: Skipping resources creation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In some cases, for example when Tobiko is run after upgrade of cloud, it may be expected -that resources used for tests should be already created. Tobiko should not try to create -resources than and just run tests using what is already created. -To configure Tobiko to not create test resources, environment variable ``TOBIKO_PREVENT_CREATE`` +In some cases, for example when Tobiko is run after an upgrade of a cloud, it may be expected +that resources used for tests have already been created. Tobiko should not try to create +resources than and just run tests using what has already been created. +To configure Tobiko to not create test resources, the environment variable ``TOBIKO_PREVENT_CREATE`` can be used:: export TOBIKO_PREVENT_CREATE=True If this is set to ``True`` or ``1`` then Tobiko will not try to create resources like VMs, -networks, routers or images and just run validation of what is exists in the cloud already. +networks, routers, or images and just run validations of what exists in the cloud already. What's Next ----------- diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst index 173b4f519..6e0a8c9a5 100644 --- a/doc/source/user/install.rst +++ b/doc/source/user/install.rst @@ -9,7 +9,7 @@ Document Overview ----------------- This document describes how to install Tobiko inside a -`Python Virtualenv `__. +`Python virtualenv `__. .. sidebar:: See also @@ -21,27 +21,27 @@ This document describes how to install Tobiko inside a To run Tobiko scenario test cases please look at :ref:`tobiko-test-case-execution-guide`. -Install Tobiko Using Virtualenv +Install Tobiko Using virtualenv ------------------------------- -Make sure Gcc, Git and base Python packages are installed on your system. +Make sure gcc, Git and base Python packages are installed on your system. -For instance on RHEL Linux 7.6 or CentOS 7 you could type:: +For instance on a RHEL7 or CentOS 7 machine you could type:: sudo yum install -y gcc git python python-devel wget -For instance on RHEL Linux 8 or CentOS 8 you could type:: +For instance on a RHEL8 or CentOS 8 machine you could type:: sudo dnf install -y gcc git python3 python3-devel wget sudo alternatives --set python /usr/bin/python3 -Make sure pip is installed and up-to date:: +Make sure pip is installed and up-to-date:: wget https://bootstrap.pypa.io/get-pip.py sudo python get-pip.py PIP=$(which pip) -Make sure setuptools, virtualenv and wheel are installed and up to date:: +Make sure setuptools, virtualenv, and wheel are installed and up-to-date:: sudo $PIP install --upgrade setuptools virtualenv wheel @@ -50,8 +50,8 @@ Get Tobiko source code using Git and enter into Tobiko source folder:: git clone https://opendev.org/x/tobiko.git cd tobiko -To install Tobiko and its dependencies is safer to create a clean Virtualenv -where to install it. Create a Virtualenv and activate it:: +To install Tobiko and its dependencies it's safest to create a clean virtualenv +to install it. Create a virtualenv and activate it:: virtualenv .tobiko-env source .tobiko-env/bin/activate diff --git a/doc/source/user/quick-start.rst b/doc/source/user/quick-start.rst index a0c3c22fb..dc544c035 100644 --- a/doc/source/user/quick-start.rst +++ b/doc/source/user/quick-start.rst @@ -208,6 +208,15 @@ Setup Required Resources A public Neutron network is required to be able to execute Tobiko scenario test cases by creating a floating IP port on it. +To execute commands from a virtualenv created by Tox you can type as below:: + + tox -e venv -- + +You need to make sure :ref:`authentication-environment-variables` are properly +set so you can list available public networks:: + + tox -e venv -- openstack network list + If there isn't any valid public network, you need to create one before running Tobiko OpenStack test cases. Please refer to the `Neutron documentation `__ for additional information. @@ -220,15 +229,6 @@ please add a reference to the network in [neutron] floating_network = public -To execute commands from a virtualenv created by Tox you can type as below:: - - tox -e venv -- - -You need to make sure ref:`authentication-environment-variables` are properly -set so you can list available public netoworks:: - - tox -e venv -- openstack network list - Running Test Cases ------------------ diff --git a/doc/source/user/run-test-cases.rst b/doc/source/user/run-test-cases.rst index 8df12730d..833b41de6 100644 --- a/doc/source/user/run-test-cases.rst +++ b/doc/source/user/run-test-cases.rst @@ -11,7 +11,7 @@ This document describes how to execute Tobiko scenario test cases. For a quick and simpler start you can jump to the :ref:`tobiko-quick-start-guide`. - To install Tobiko inside a virutalenv please read + To install Tobiko inside a virtualenv please read :ref:`tobiko-installation-guide`. To configure Tobiko please read :ref:`tobiko-configuration-guide`. @@ -20,9 +20,9 @@ This document describes how to execute Tobiko scenario test cases. Prepare Your System ~~~~~~~~~~~~~~~~~~~ -Before running Tobiko test cases you need to be sure you are doing it from -Tobiko source files folder and that you have actived a Virtualenv where Tobiko -and its requirements are installed. Please refers to +Before running Tobiko test cases, you need to be sure you are doing it from +Tobiko source files folder and that you have activated a virtualenv where Tobiko +and its requirements are installed. Please refer to :ref:`tobiko-installation-guide` and :ref:`tobiko-configuration-guide` to know how to setup your system before running test cases. @@ -34,6 +34,6 @@ To run test cases you need a test runner able to execute Python test cases. Test cases delivered with Tobiko has been tested using `stestr `__ -From Tobiko source folder you can run scenario test cases using below command:: +From the Tobiko source folder you can run scenario test cases using the below command:: stestr run --test-path tobiko/tests/scenario/ diff --git a/tobiko.conf.example b/tobiko.conf.example index 2ec4df569..8f5977747 100644 --- a/tobiko.conf.example +++ b/tobiko.conf.example @@ -73,12 +73,12 @@ # Username (string value) #username = -# Project name (string value) -#project_name = - # Password (string value) #password = +# Project name (string value) +#project_name = + # Domain name (string value) #domain_name =