Browse Source

[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
changes/11/775711/4
Nathan Weinberg 8 months ago
parent
commit
4911a1cbc2
  1. 41
      doc/source/user/config.rst
  2. 18
      doc/source/user/install.rst
  3. 18
      doc/source/user/quick-start.rst
  4. 10
      doc/source/user/run-test-cases.rst
  5. 6
      tobiko.conf.example

41
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://<proxy-host>:<proxy-port>/
@ -190,7 +191,7 @@ For convenience it is also possible to specify the same parameters via
https_proxy = http://<proxy-host>:<proxy-port>/
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
-----------

18
doc/source/user/install.rst

@ -9,7 +9,7 @@ Document Overview
-----------------
This document describes how to install Tobiko inside a
`Python Virtualenv <https://virtualenv.pypa.io/en/latest/>`__.
`Python virtualenv <https://virtualenv.pypa.io/en/latest/>`__.
.. 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

18
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 -- <your-commands>
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 <https://docs.openstack.org/neutron/latest/>`__
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 -- <your-commands>
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
------------------

10
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 <https://stestr.readthedocs.io/en/latest/>`__
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/

6
tobiko.conf.example

@ -73,12 +73,12 @@
# Username (string value)
#username = <None>
# Project name (string value)
#project_name = <None>
# Password (string value)
#password = <None>
# Project name (string value)
#project_name = <None>
# Domain name (string value)
#domain_name = <None>

Loading…
Cancel
Save