From da7661c300bfb1a5368bf40906dfb69fb170bef4 Mon Sep 17 00:00:00 2001 From: Eliad Cohen Date: Fri, 10 Jul 2020 09:37:48 -0400 Subject: [PATCH] Offers some revisions to quickstart guide Refresh some of the language and some minor typographical corrections. Content and messages are largely unchanged. Change-Id: I8b20a136b75f405192ffcebae8ace00e7b729c80 --- doc/source/user/quick-start.rst | 157 ++++++++++++++++---------------- 1 file changed, 78 insertions(+), 79 deletions(-) diff --git a/doc/source/user/quick-start.rst b/doc/source/user/quick-start.rst index b954e5a84..fa9dd1c71 100644 --- a/doc/source/user/quick-start.rst +++ b/doc/source/user/quick-start.rst @@ -30,7 +30,7 @@ Install Basic Python Packages Make sure Git and Python 3 are installed on your system. -For instance on RedHat Linux you could type:: +For instance on RedHat Linux / Fedora:: sudo yum install -y git python3 which @@ -38,7 +38,7 @@ Check your Python 3 version is greater than 3.6:: python3 --version -Make sure Pip is installed and up-to date:: +Make sure pip is installed and up-to date:: curl https://bootstrap.pypa.io/get-pip.py | sudo python3 @@ -55,10 +55,10 @@ Check installed Tox version:: tox --version -Get Tobiko Source Code -~~~~~~~~~~~~~~~~~~~~~~ +Clone the Tobiko repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Get Tobiko source code using Git:: +Clone the Tobiko repository using Git:: git clone https://opendev.org/x/tobiko.git cd tobiko @@ -75,31 +75,31 @@ Install required binary packages:: Configure Logging Options ------------------------- -Test cases load most of configurations parameters from a INI configuration file -typically found at one of below locations: +Test cases load most of the configuration parameters from an INI configuration file, +typically found at one of the following locations: - ./tobiko.conf (Tobiko source files directory) - ~/.tobiko/tobiko.conf - /etc/tobiko/tobiko.conf -Create it in Tobiko source directory with your very basic preferences. Example:: +Create it in the Tobiko source directory with the following (or as your preferences). Example:: [DEFAULT] debug = True log_file = tobiko.log -File 'tobiko.log' is the default file where test cases and the Python framework +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 -ensures messages with the lowest logging level are written there (DEBUG level). +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, thats mean on this case the Tobiko source files directory itself. +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 below ways: +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` @@ -112,17 +112,17 @@ credentials. You can do it in one of below ways: Set Tobiko Credentials from clouds.yaml file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Make sure in any of below locations there is a valid +Make sure that in any one of below locations there is a valid `OpenStack clouds file `__ -containing valid KeyStone credentials: +containing valid Keystone credentials: - Tobiko source files directory - ~/.config/openstack - /etc/openstack -Finally you need to specify which credentials Tobiko should pick up via -'OS_CLOUD' environment variable or by specifying cloud name in tobiko.conf file +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'). @@ -132,23 +132,23 @@ Specify 'OS_CLOUD' environment variable Ensure *OS_CLOUD* environment variable is defined before executing Tobiko test cases:: - export OS_CLOUD= + export OS_CLOUD= -Please chose a valid cloud name from your clouds.yaml file. +Please choose a valid cloud_name from your clouds.yaml file. -Specify cloud name in tobiko.conf 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 chose a valid cloud name from your clouds.yaml file. +Please choose a valid cloud_name from your clouds.yaml file. .. _credentials-from-env: @@ -189,7 +189,8 @@ Set Tobiko Credentials Via :ref:`tobiko-conf` File For more details about supported configuration options please read :ref:`authentication-configuration` section. -Create a file at `~/.tobiko/tobiko.conf` adding a section like below:: +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 @@ -205,7 +206,7 @@ Setup Required Resources ~~~~~~~~~~~~~~~~~~~~~~~~ A public Neutron network is required To be able to execute Tobiko scenario test -cases to be able to create floating IP port on it. +cases by creating a floating IP port on it. To execute commands from a virtualenv created by Tox you can type as below:: @@ -216,32 +217,31 @@ set so you can list available public netoworks:: tox -e venv -- openstack network list -If there is any valid public network you need to create one before running -Tobiko OpenStack test cases. Please refer to the -`Neutron documentation ` to know -how to do it. +If there is any valid public network, you need to create one before running +Tobiko OpenStack test cases. Please refer to the `Neutron documentation `__ +for additional information. -If there is a valid public network for creating floating IPs ports on it, -Tobiko tests cases would use it. In case you want to make sure they use -a specific network please add reference to such network in +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 -Run Test Cases --------------- +Running Test Cases +------------------ -Run Scenario Test Cases -~~~~~~~~~~~~~~~~~~~~~~~ +Running Scenario Test Cases +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Scenario test cases are in charge of creating workloads to simulate real use +Scenario test cases are used to create workloads that simulate real-world use of OpenStack. They create networks, virtual machines, ports, routers, etc. -They also tests these workloads are working. +They also test validate that these workloads functioning. -Run Tobiko scenario test cases using Tox (it is going to take some minutes):: +Running Tobiko scenario test cases using Tox (may take some time to complete (minutes)):: tox -e scenario @@ -250,7 +250,7 @@ To list Heat stacks and Glance images created by test cases:: tox -e venv -- openstack image list tox -e venv -- openstack stack list -Scenario test cases are also used to check if previously created resources are +Scenario test cases are also used to check that previously created resources are still up and working as expected. To ensure test cases will not create those resources again we can set `TOBIKO_PREVENT_CREATE` environment variable before re-running test cases:: @@ -258,72 +258,71 @@ re-running test cases:: TOBIKO_PREVENT_CREATE=yes tox -e scenario -Cleanup Tobiko Workloads -~~~~~~~~~~~~~~~~~~~~~~~~ +Cleanning Up Tobiko Workloads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once Tobiko test cases have been executed we could want to clean up all -workloads left on the cloud so that we restore it to the original state. +Once Tobiko test cases have been executed, we may want to clean up all +workloads remaining on the cloud so that we restore it to its original state. -Cleanup Heat Stacks -+++++++++++++++++++ +Cleanning Up Heat Stacks +++++++++++++++++++++++++ Because Tobiko is using Heat stacks for orchestrating the creation of most of -the resources, by cleaning up all stacks created with Tobiko will clean it up -almost all:: +the resources, deleting all stacks created with Tobiko will clean up +almost all resources:: tox -e venv -- bash -c 'openstack stack list -f value -c ID | xargs openstack stack delete' -Cleanup Glance Images -+++++++++++++++++++++ +Cleanning Up Glance Images +++++++++++++++++++++++++++ Because Heat doen't support creation of Glance images, Tobiko implemented some -specific fixtures to download images from the Web and upload them to Glance +specific fixtures to download images from the Web and upload them to the Glance service:: - tox -e venv -- bash -c 'openstack stack list -f value -c ID | xargs openstack stack delete' + tox -e venv -- bash -c 'openstack image list -f value -c ID | xargs openstack image delete' -Run Disruptive Test Cases -~~~~~~~~~~~~~~~~~~~~~~~~~ +Running Disruptive Test Cases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Disruptive test cases are in charge of testing that after executing some type of -critical operation on the cloud, the services return working as expected after +Disruptive test cases are used for testing that after inducing some critical +disruption to the operation of the cloud, the services return working as expected after a while. To execute them you can type:: tox -e faults -The kind operations executed by these test cases could be cloud nodes reboot, +The faults induced by these test cases could be cloud nodes reboot, OpenStack services restart, virtual machines migrations, etc. -Please note that while scenario test cases are being executing in parallel to -speed up test case execution, faults test case are only executed sequentially. -This is because operation executed by such cases could break some functionality -for a short time and alter the regular state of the system expected from other +Please note that while scenario test cases are being executed in parallel (to +speed up test case execution), disruptive test case are only executed sequentially. +This is because the operations executed by such cases could break some functionality +for a short time and alter the regular state of the system which may be assumed by other test cases to be executed. -Run the Tobiko Workflow -~~~~~~~~~~~~~~~~~~~~~~~ +Running the Tobiko Workflow +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Scenario and disruptive test cases, being executed in a specify sequence could -be used to detect more problems on the cloud the disruptive test cases alone -are not looking for. +Scenario and disruptive test cases, being executed in a specific sequence could +be used to uncover more issues with the cloud than disruptive test cases alone. -- First ensure there are workloads running fine by running scenario test cases:: +- First ensure there are workloads properly running by running scenario test cases:: tox -e scenario .. sidebar:: Note - As second step we could instead update or upgrade OpenStack nodes. + As second step we may, instead, update or upgrade OpenStack nodes. -- Second we could execute disruptive test cases to shake the system a bit:: +- Next we could execute disruptive test cases to "stress" the cloud:: tox -e faults -- Third we could re-run scenario test cases to check things are still running +- Finally we might re-run scenario test cases to check thateverything is still running as expected:: TOBIKO_PREVENT_CREATE=yes tox -e scenario @@ -332,32 +331,32 @@ are not looking for. Test Cases Report Files ~~~~~~~~~~~~~~~~~~~~~~~ -After executing test cases we can look at more details regarding test case -results in a small set of files: +After executing test cases we can view the results in greater detail via a small +set of files: - **test_results.html**: - an user browseable HTML view of test case results + A user-browseable HTML view of test case results - **test_results.log**: - a log file with logging traces recollected from every individual test case + a log file with logging traces collected from every individual test case - **test_results.subunit**: the original subunit binary file generated by test runner - **test_results.xml**: - an XML Junit file to be used for example to show test cases result by + an XML Junit file to be used, for example, to show test cases result by Jenkins CI server -The name of above files can be changed from default value (*test_results*) to a -custom one by setting *TOX_REPORT_NAME* environment variable. +The names of the above files can be changed from the default value (*test_results*) +to a custom one by setting the *TOX_REPORT_NAME* environment variable. -.. sidebar:: Legenda +.. sidebar:: Legend *{toxinidir}* stand for the Tobiko source files directory. *{envname}* is the name of the Tox enviroment to be executed (IE scenario, faults, etc.) -Above files are saved into a folder that can be specified with +The above files are saved into a folder that can be specified with *TOX_REPORT_DIR* environment variable. -By default the full path of report directory is made from below parts:: +By default the full path of the report directory is made from the below:: {toxinidir}/report/{envname}