Refactor configuration part of Tobiko quick start guide
So far, the Tobiko docs were duplicated in some places, different
(although duplicated), and some fragments were not relevant (or
outdated).
This patch refactors the configuration part of Tobiko quick start guide
by modularizing the fragments ("spilling" fragments instead of coping
them), correcting typos, and deleting/updating irrelevant information.
Note: in order to see how the change will appear, download it with
`git review -d <change_url>`, run the `tox -e docs` command, and then
double click
(with the file explorer) tobiko/doc/build/html/<file-you-want>.
Change-Id: Ibb27382ec3c7a8969686cfd89c2205cdd2dd2525
This commit is contained in:
Omer
123
doc/source/user/_conf_credentials.rst
Normal file
123
doc/source/user/_conf_credentials.rst
Normal file
@@ -0,0 +1,123 @@
|
||||
Configure Tobiko Credentials
|
||||
----------------------------
|
||||
|
||||
Tobiko needs to have Keystone credentials in order to run the OpenStack test cases.
|
||||
We are going to assume you are using one of the two OpenStack distributions
|
||||
supported by Tobiko:
|
||||
|
||||
- DevStack
|
||||
- TripleO
|
||||
|
||||
Get credentials from a DevStack host
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Copy the `clouds.yaml <https://docs.openstack.org/python-openstackclient/pike/configuration/index.html#clouds-yaml>`__
|
||||
file from your remote cloud to any one of the below locations:
|
||||
|
||||
- Tobiko source files directory
|
||||
- ~/.config/openstack
|
||||
- /etc/openstack
|
||||
|
||||
|
||||
| The clouds.yaml file contains valid Keystone credentials.
|
||||
|
||||
You can copy the file in the following way::
|
||||
|
||||
ssh <... connection options here ...> cat /etc/openstack/clouds.yaml > clouds.yaml
|
||||
|
||||
|
||||
Get credentials from a TripleO undercloud host
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Tobiko test cases will be able to setup some type of SSH tunneling
|
||||
to be able to reach the remote cloud, but for achieving it you are
|
||||
required to be able to connect to a remote SSH server that is
|
||||
able to connect the OpenStack services and hosts. We will
|
||||
refer to that server as the SSH proxy host.
|
||||
|
||||
Tobiko test cases will execute some commands on the SSH proxy host
|
||||
(like ping, nc, curl, etc).
|
||||
Those commands need to have direct connectivity to target cloud.
|
||||
|
||||
Test cases will use Python REST API clients configured to make HTTP
|
||||
requests coming out from such SSH server (mainly by using nc
|
||||
command) or SSH server direct connect feature.
|
||||
|
||||
Test cases will make all SSH connection to cloud nodes by using
|
||||
this SSH proxy host.
|
||||
|
||||
To resume the purpose of the SSH proxy, all network packages
|
||||
sent by Tobiko test cases to the tested cloud will come from the
|
||||
SSH proxy host, while all Tobiko test cases will be executed
|
||||
from the developer workstation.
|
||||
|
||||
SetUp SSH public key to connect to remote cloud
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
First of all we need to make sure we can connect to the SSH proxy server
|
||||
without requiring any password.
|
||||
We therefore need to have a local SSH key pair to be used by tobiko.
|
||||
This key by default is the same default one used by openSSH client:
|
||||
- default SSH private key filename: `~/.ssh/id_rsa`
|
||||
- default SSH public key filename: `~/.ssh/id_rsa.pub`
|
||||
|
||||
|
||||
**Note: In case that you already have a public key which does not require a**
|
||||
**password (it requires an empty passphrase), you can skip the ssh keypair**
|
||||
**creation (continue with**
|
||||
:ref:`defining your ssh variables <define-your-ssh-variables>`
|
||||
**).**
|
||||
|
||||
In case that you don't, to avoid having problems with other uses of the same
|
||||
file, let's instead create our SSH key pair only for Tobiko in a sub-folder
|
||||
near to your tobiko.conf
|
||||
|
||||
Make sure you run the following commands in the tobiko directory.
|
||||
Ensure we do have this key pair on your workstation by typing::
|
||||
|
||||
mkdir -p .ssh
|
||||
chmod 700 .ssh
|
||||
ssh-keygen -v -f .ssh/id -N ''
|
||||
chmod 600 .ssh/id .ssh/id.pub
|
||||
|
||||
.. _define-your-ssh-variables:
|
||||
|
||||
Define the below SSH variables to later connect to your SSH server::
|
||||
|
||||
SSH_HOST=<your-ssh-proxy-address>
|
||||
SSH_USERNAME=<your-ssh-proxy-user>
|
||||
|
||||
For example::
|
||||
|
||||
SSH_HOST=seal100.your.domain
|
||||
SSH_USERNAME=root
|
||||
|
||||
Copy your SSH public key to your remote server::
|
||||
|
||||
ssh-copy-id -i .ssh/id "${SSH_USERNAME}@${SSH_HOST}"
|
||||
|
||||
|
||||
Make sure the SSH key pair is working::
|
||||
|
||||
ssh -i .ssh/id "${SSH_USERNAME}@${SSH_HOST}" hostname
|
||||
|
||||
|
||||
Now let's make sure Tobiko test cases will use the SSH key pair to connect
|
||||
to your SSH remote host. Add the following lines to tobiko.conf file::
|
||||
|
||||
[ssh]
|
||||
proxy_jump = SSH_USERNAME@SSH_HOST
|
||||
|
||||
For example::
|
||||
|
||||
[ssh]
|
||||
proxy_jump = root@seal100.your.domain
|
||||
#proxy_jump = root@seal99.your.domain
|
||||
#proxy_jump = root@seal98.your.domain
|
||||
|
||||
.. tip::
|
||||
You could have multiple hosts in your tobiko.conf [ssh] section, where the
|
||||
ones you are not currently using are commented (as appear above).
|
||||
Moving your tobiko tests from one host to another will be as easy as
|
||||
commenting the host you are stop using and uncommenting the one you are
|
||||
start using (remember to copy your SSH key to your other remote hosts as well).
|
||||
20
doc/source/user/_conf_explanation.rst
Normal file
20
doc/source/user/_conf_explanation.rst
Normal file
@@ -0,0 +1,20 @@
|
||||
.. _tobiko-conf:
|
||||
|
||||
tobiko.conf
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tobiko-conf-label
|
||||
|
||||
Tobiko tries to load the '`tobiko.conf`' file from one of the below locations:
|
||||
|
||||
* current directory::
|
||||
|
||||
./tobiko.conf
|
||||
|
||||
* user home directory::
|
||||
|
||||
~/.tobiko/tobiko.conf
|
||||
|
||||
* system directory::
|
||||
|
||||
/etc/tobiko/tobiko.conf
|
||||
25
doc/source/user/_conf_logging.rst
Normal file
25
doc/source/user/_conf_logging.rst
Normal file
@@ -0,0 +1,25 @@
|
||||
.. _conf_logging:
|
||||
|
||||
Configure Logging
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. configure-tobiko-logging-label
|
||||
|
||||
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
|
||||
debug = true
|
||||
|
||||
# Name of the file where log messages will be appended.
|
||||
log_file = tobiko.log
|
||||
|
||||
# The base directory used for relative log_file paths.
|
||||
log_dir = .
|
||||
|
||||
The file 'tobiko.log' is the default file where test cases and the Python framework
|
||||
are going to write their logging messages. By setting debug as 'True' you
|
||||
ensure that messages with the lowest logging level are written there (DEBUG level).
|
||||
The log_file location specified above is relative to the tobiko.conf file
|
||||
location. In this example it is the Tobiko source files' directory itself.
|
||||
15
doc/source/user/_conf_venv_with_tox.rst
Normal file
15
doc/source/user/_conf_venv_with_tox.rst
Normal file
@@ -0,0 +1,15 @@
|
||||
To execute commands from a virtualenv created by Tox, add the virtualenv name
|
||||
to tox.ini envlist variable in the following way (in this example, the virtual
|
||||
environment's name is 'venv')::
|
||||
|
||||
[tox]
|
||||
|
||||
envlist = other_environment_variables,venv
|
||||
|
||||
Run your commands as below::
|
||||
|
||||
tox -e venv -- <your-commands>
|
||||
|
||||
For example::
|
||||
|
||||
tox -e venv -- openstack network list
|
||||
@@ -1,12 +1,8 @@
|
||||
.. _tobiko-configuration-guide:
|
||||
|
||||
==========================
|
||||
Tobiko Configuration Guide
|
||||
==========================
|
||||
|
||||
|
||||
Document Overview
|
||||
-----------------
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
This document describes how to configure Tobiko.
|
||||
|
||||
@@ -34,26 +30,11 @@ To be able to execute scenario test cases there some OpenStack resources that
|
||||
have to be created before running test cases. Please look at
|
||||
:ref:`setup-required-resources` for more details.
|
||||
|
||||
|
||||
.. _tobiko-conf:
|
||||
|
||||
tobiko.conf
|
||||
~~~~~~~~~~~
|
||||
|
||||
Tobiko tries to load :ref:`tobiko-conf` file from one of the below locations:
|
||||
|
||||
* current directory::
|
||||
|
||||
./tobiko.conf
|
||||
|
||||
* user home directory::
|
||||
|
||||
~/.tobiko/tobiko.conf
|
||||
|
||||
* system directory::
|
||||
|
||||
/etc/tobiko/tobiko.conf
|
||||
|
||||
.. include:: _conf_explanation.rst
|
||||
:start-after: tobiko-conf-label
|
||||
|
||||
Configure Logging
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -20,162 +20,26 @@ This document describes how to setup an environment and how to run test cases
|
||||
.. include:: _install_venv.rst
|
||||
|
||||
|
||||
Configure tobiko with tobiko.conf
|
||||
---------------------------------
|
||||
|
||||
.. include:: _conf_explanation.rst
|
||||
:start-after: tobiko-conf-label
|
||||
|
||||
Configure Logging Options
|
||||
-------------------------
|
||||
|
||||
Test cases load most of the configuration parameters from an INI configuration file,
|
||||
typically found at one of the following locations:
|
||||
.. include:: _conf_logging.rst
|
||||
:start-after: configure-tobiko-logging-label
|
||||
|
||||
- ./tobiko.conf (Tobiko source files directory)
|
||||
- ~/.tobiko/tobiko.conf
|
||||
- /etc/tobiko/tobiko.conf
|
||||
.. include:: _conf_credentials.rst
|
||||
|
||||
Create it in the Tobiko source directory with the following (or as your preferences). Example::
|
||||
.. _generating-venv-with-tox:
|
||||
|
||||
[DEFAULT]
|
||||
debug = True
|
||||
log_file = tobiko.log
|
||||
Create a virtual environment with tox
|
||||
-------------------------------------
|
||||
|
||||
The file 'tobiko.log' is the default file where test cases and the Python framework
|
||||
are going to write their logging messages. By setting debug as 'true' you
|
||||
ensure that messages with the lowest logging level are written there (DEBUG level).
|
||||
The log_file location specified above is relative to the tobiko.conf file
|
||||
location. In this example it is the Tobiko source files' directory itself.
|
||||
|
||||
|
||||
Configure Tobiko Credentials
|
||||
----------------------------
|
||||
|
||||
In order to run the OpenStack test cases you'll need to set up Keystone
|
||||
credentials. You can do it in one of following ways:
|
||||
|
||||
- :ref:`credentials-from-clouds-file`
|
||||
- :ref:`credentials-from-env`
|
||||
- :ref:`credentials-from-config`
|
||||
|
||||
|
||||
.. _credentials-from-clouds-file:
|
||||
|
||||
|
||||
Set Tobiko Credentials from clouds.yaml file
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Make sure that in any one of below locations there is a valid
|
||||
`OpenStack clouds file <https://docs.openstack.org/python-openstackclient/pike/configuration/index.html#clouds-yaml>`__
|
||||
containing valid Keystone credentials:
|
||||
|
||||
- Tobiko source files directory
|
||||
- ~/.config/openstack
|
||||
- /etc/openstack
|
||||
|
||||
|
||||
Finally, you will need to specify which credentials Tobiko should pick up via
|
||||
'OS_CLOUD' environment variable or by specifying the cloud_name in tobiko.conf file
|
||||
(section 'keystone', option 'cloud_name').
|
||||
|
||||
|
||||
Specify 'OS_CLOUD' environment variable
|
||||
+++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Ensure *OS_CLOUD* environment variable is defined before executing Tobiko test
|
||||
cases::
|
||||
|
||||
export OS_CLOUD=<cloud_name>
|
||||
|
||||
|
||||
Please choose a valid cloud_name from your clouds.yaml file.
|
||||
|
||||
|
||||
Specify cloud_name in tobiko.conf file
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
|
||||
Create file `tobiko.conf` in Tobiko sources folder adding a section like below::
|
||||
|
||||
[keystone]
|
||||
cloud_name = <cloud_name>
|
||||
|
||||
|
||||
Please choose a valid cloud_name from your clouds.yaml file.
|
||||
|
||||
|
||||
.. _credentials-from-env:
|
||||
|
||||
|
||||
Set Tobiko Credentials Via Environment Variables
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. sidebar:: See also
|
||||
|
||||
For more details about supported environment variables please read
|
||||
:ref:`authentication-environment-variables` section.
|
||||
|
||||
You can use an existing shell RC file that is valid for
|
||||
`Python OpenStack client <https://docs.openstack.org/python-openstackclient/latest/cli/man/openstack.html#environment-variables>`__
|
||||
::
|
||||
|
||||
source openstackrc
|
||||
|
||||
An example of 'openstackrc' file could looks like below::
|
||||
|
||||
export OS_IDENTITY_API_VERSION=3
|
||||
export OS_AUTH_URL=https://my_cloud:13000/v3
|
||||
export OS_USERNAME=admin
|
||||
export OS_PASSWORD=secret
|
||||
export OS_PROJECT_NAME=admin
|
||||
export OS_USER_DOMAIN_NAME=Default
|
||||
export OS_PROJECT_DOMAIN_NAME=Default
|
||||
|
||||
|
||||
.. _credentials-from-config:
|
||||
|
||||
Set Tobiko Credentials Via :ref:`tobiko-conf` File
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. sidebar:: See also
|
||||
|
||||
For more details about supported configuration options please read
|
||||
:ref:`authentication-configuration` section.
|
||||
|
||||
Create a file at `~/.tobiko/tobiko.conf` and add a section as in the
|
||||
example below (Or add to your existing file)::
|
||||
|
||||
[keystone]
|
||||
api_version = 3
|
||||
auth_url = http://my_cloud:13000/v3
|
||||
username = admin
|
||||
password = secret
|
||||
project_name = admin
|
||||
user_domain_name = Default
|
||||
project_domain_name = Default
|
||||
|
||||
|
||||
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.
|
||||
|
||||
If there is a valid public network for creating floating-IP ports on,
|
||||
Tobiko tests cases will automatically use it. To explicitly select a network,
|
||||
please add a reference to the network in
|
||||
:ref:`tobiko-conf` file::
|
||||
|
||||
[neutron]
|
||||
floating_network = public
|
||||
.. include:: _conf_venv_with_tox.rst
|
||||
|
||||
Running Test Cases
|
||||
------------------
|
||||
|
||||
Reference in New Issue
Block a user