From 4f52d0005651b071e6de018bb15ee4aedff91b69 Mon Sep 17 00:00:00 2001 From: Federico Ressi Date: Fri, 26 Apr 2019 13:30:57 +0200 Subject: [PATCH] Add quick start guide to RST documentation. Change-Id: I33f8fd242745a8779cb6133a37fc91e8f34bb22a --- README.rst | 2 +- doc/quick-start.md | 74 ----------------- doc/source/index.rst | 4 +- doc/source/install/index.rst | 12 +-- doc/source/user/index.rst | 5 ++ doc/source/user/quick-start.rst | 136 ++++++++++++++++++++++++++++++++ doc/usage.md | 12 --- 7 files changed, 151 insertions(+), 94 deletions(-) delete mode 100644 doc/quick-start.md create mode 100644 doc/source/user/quick-start.rst delete mode 100644 doc/usage.md diff --git a/README.rst b/README.rst index ca6e21b3f..52a132cd2 100644 --- a/README.rst +++ b/README.rst @@ -20,4 +20,4 @@ Links * Documentation: `Tobiko Documentation `__ * Source: https://opendev.org/x/tobiko.git * Bugs: `StoryBoard `__ -* Usage: `Quick Start Guide `__ +* Usage: `Quick Start Guide `__ diff --git a/doc/quick-start.md b/doc/quick-start.md deleted file mode 100644 index aee45dec3..000000000 --- a/doc/quick-start.md +++ /dev/null @@ -1,74 +0,0 @@ -# Quick start guide - -## Install Tobiko -sudo yum install python-virtualenv -virtualenv path/to/yuor/venv -source path/to/yuor/venv/bin/activate -pip install tobiko - -## Set up credentials - -In order to run the tests successfully you'll need to set up OpenStack credentials. -You can do it in one of two ways: - -1. Using environment variables. - Either by downloading the credentials file directly from your OpenStack project or - setting them up manually like this: - - export API_VERSION = 2 - export OS_USERNAME = admin - export OS_PASSWORD = admin - export PROJECT_NAME = admin - export OS_USER_DOMAIN_NAME="Default" - export OS_PROJECT_DOMAIN_NAME = admin - export OS_AUTH_URL=https://my_cloud:13000/v3 - - -2. Setting up tobiko.conf file with the following format: - - api_version = 2 - username = admin - password = admin - project_name = admin - user_domain_name = admin - project_domain_name = admin - auth_url = http://my_cloud:13000/v3 - -## Run Tests - -To run neutron tests, use the following command: - - tox -e neutron - - -## Quick Start Setup&Run Template: -```bash -sudo yum install python-virtualenv.noarch -y -virtualenv ~/tobiko_venv && source ~/tobiko_venv/bin/activate -wget https://bootstrap.pypa.io/get-pip.py -python get-pip.py -pip install tox -sudo yum install gcc python-devel -y -git clone https://opendev.org/x/tobiko.git -cd tobiko -pip install -r extra-requirements.txt; pip install . - -. ~/overcloudrc -wget http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img -openstack image create "cirros" \ - --file cirros-0.3.5-x86_64-disk.img \ - --disk-format qcow2 --container-format bare \ - --public -openstack flavor create --id 0 --vcpus 1 --ram 64 --disk 1 m1.tiny - -cat > tobiko.conf <`__ * Source: https://opendev.org/x/tobiko.git * Bugs: `StoryBoard `__ -* Usage: `Quick Start Guide `__ +* Usage: `Quick Start Guide `__ Document Overview diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 878e26580..12c9c15d3 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,13 +1,15 @@ -============ -Installation -============ +.. _tobiko-install-guide: + +========================= +Tobiko Installation Guide +========================= Document Overview ----------------- This document describes how to install Tobiko inside a Python virtualenv. For -a quick and simpler start you can jump to the Quick Start Guide. +a quick and simpler start you can jump to the :ref:`quick-start-guide`. Install Tobiko Using Virtualenv @@ -24,7 +26,7 @@ Make sure pip and setuptools are installed and up-to date:: sudo python get-pip.py sudo pip install --upgrade setuptools -Make sure tox, virtualenv and wheel are installed and up to date:: +Make sure virtualenv and wheel are installed and up to date:: sudo pip install --upgrade tox virtualenv wheel diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index e1ad97a0b..c93e9cf88 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,3 +1,8 @@ ================= Tobiko User Guide ================= + +.. toctree:: + :maxdepth: 2 + + quick-start diff --git a/doc/source/user/quick-start.rst b/doc/source/user/quick-start.rst new file mode 100644 index 000000000..0e43cae57 --- /dev/null +++ b/doc/source/user/quick-start.rst @@ -0,0 +1,136 @@ +.. _quick-start-guide: + +================= +Quick Start guide +================= + + +Document Overview +----------------- + +This document describes how to install execute Tobiko scenarios test cases +using Tox. To install Tobiko inside a virtualenv directory please refers to +:ref:`tobiko-install-guide`. + + +Install Required Packages +------------------------- + +Make sure Gcc, Git and base Python packages are installed on your system. +For instance on RHEL Linux you could type:: + + sudo yum install -y gcc git python python-devel + +Make sure pip and setuptools are installed and up-to date:: + + wget https://bootstrap.pypa.io/get-pip.py + sudo python get-pip.py + sudo pip install --upgrade setuptools + +Make sure tox, virtualenv and wheel are installed and up to date:: + + sudo pip install --upgrade tox virtualenv wheel + + +Get Tobiko +---------- + +Get Tobiko source code using Git:: + + git clone https://opendev.org/x/tobiko.git + cd tobiko + + +Configure Tobiko Credentials +---------------------------- + +In order to run the tests successfully you'll need to set up OpenStack +credentials. You can do it in one of below ways: + +- :ref:`credentials-from-env` +- :ref:`credentials-from-config` + + +.. _credentials-from-env: + +Set Tobiko Credentials Via Environment Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use an existing shell rc file that is valid for Python OpenStack +client:: + + source openstackrc + +An example of 'openstackrc' file could looks like below:: + + export API_VERSION=2 + export OS_USERNAME=admin + export OS_PASSWORD=secret + export PROJECT_NAME=admin + export OS_USER_DOMAIN_NAME=Default + export OS_PROJECT_DOMAIN_NAME=admin + export OS_AUTH_URL=https://my_cloud:13000/v3 + + +.. _credentials-from-config: + +Set Tobiko Credentials Via 'tobiko.conf' File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create a file at ~/.tobiko/tobiko.conf adding a section like below:: + + [keystone] + api_version = 2 + username = admin + password = secret + project_name = admin + user_domain_name = admin + project_domain_name = admin + auth_url = http://my_cloud:13000/v3 + + +Create Required Resources +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install Python OpenStack client:: + + source overcloudrc + sudo pip install python-openstackclient \ + python-novaclient \ + python-glanceclient + +Create an image for Nova instances created by Tobiko:: + + wget http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img + openstack image create "cirros" \ + --file cirros-0.3.5-x86_64-disk.img \ + --disk-format qcow2 \ + --container-format bare \ + --public + +Create a flavor to be used with above image:: + + openstack flavor create --id 0 --vcpus 1 --ram 64 --disk 1 m1.tiny + +Add reference to above resources into your `tobiko.conf` file:: + + [nova] + image = cirros + flavor = m1.tiny + + +Configure Public Network Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add reference to the network where Tobiko should create floating IP instances:: + + [neutron] + floating_network = public + + +Run Test Cases +-------------- + +Run Tobiko scenario test cases using Tox:: + + tox -e scenario diff --git a/doc/usage.md b/doc/usage.md deleted file mode 100644 index 93a5e5924..000000000 --- a/doc/usage.md +++ /dev/null @@ -1,12 +0,0 @@ -# Tobiko Usage Examples - - -## Faults - -Use `tobiko-fault` to run only faults, without running resources population or tests. - -Note: `tobiko-fault` can executed only from undercloud node. - -To restart openvswitch service, run the following command: - - tobiko-fault --fault "restart openvswitch service"