x
/
kloudbuster
Code Issues Proposed changes

Document updates for latest development 

Change-Id: I7242822c6cedbd2903c79073b522dd3ea20c74dc
This commit is contained in:
Yichen Wang 2015-11-13 13:20:45 -08:00
parent 244f525a89
commit 85f6630853
4 changed files with 132 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/development.rst
View File

@ -94,5 +94,6 @@ You need to comment out the secure_path option in your /etc/sudoers file (use
#Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
.. _build_web_ui:
.. include:: ../../kb_web/README.rst

65
doc/source/installation.rst
View File

@ -2,19 +2,28 @@
Installation
============
There are two ways to install and run KloudBuster tool. Users of KloudBuster should use regular PyPI based installation, while developers of KloudBuster should use GitHub/OpenStack Repository based installation. Normally, PyPI based installation will satisfy most of use cases, and it is the recommended way for running KloudBuster under production environments, or through an automated or scheduled job. A git repository based installation gives more flexibility, and it is a must for developers of KloudBuster.
There are two ways to install and run KloudBuster tool. Users of KloudBuster
should use regular PyPI based installation, while developers of KloudBuster
should use GitHub/OpenStack Repository based installation. Normally, PyPI
based installation will satisfy most of use cases, and it is the recommended
way for running KloudBuster under production environments, or through an
automated or scheduled job. A git repository based installation gives more
flexibility, and it is a must for developers of KloudBuster.
.. note:: Installation from PyPI will only have the latest stable version.
PyPI based Installation
-----------------------
This is the recommended way to install KloudBuster for non-development use, and KloudBuster is available in the Python Package Index (PyPI): `KloudBuster PyPI <https://pypi.python.org/pypi/KloudBuster>`_
This is the recommended way to install KloudBuster for non-development use,
and KloudBuster is available in the Python Package Index (PyPI):
`KloudBuster PyPI <https://pypi.python.org/pypi/KloudBuster>`_
Step 1
^^^^^^
You will need to have python 2.7, pip, and some dependencies installed before installing KloudBuster, run the command based on your distro.
You will need to have python 2.7, pip, and some dependencies installed
before installing KloudBuster, run the command based on your distro.
Ubuntu/Debian based:
@ -48,7 +57,8 @@ Create a virtual environment for Python, and install KloudBuster:
$ source vkb/bin/activate
$ pip install kloudbuster
Alternatively, if you have `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org>`_ installed:
Alternatively, if you have
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.org>`_ installed:
.. code-block:: bash
@ -56,7 +66,9 @@ Alternatively, if you have `virtualenvwrapper <https://virtualenvwrapper.readthe
$ pip install kloudbuster
.. note::
"A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them." It is optional but recommended. We could use::
"A Virtual Environment is a tool to keep the dependencies required by
different projects in separate places, by creating virtual Python
environments for them." It is optional but recommended. We could use::
$ sudo pip install kloudbuster
@ -72,7 +84,8 @@ To verify kloudbuster is installed, just type::
GitHub/OpenStack Repository based Installation
----------------------------------------------
It is recommended to run KloudBuster inside a virtual environment. However, it can be skipped if installed in a dedicated VM.
It is recommended to run KloudBuster inside a virtual environment. However,
it can be skipped if installed in a dedicated VM.
Super quick installation on Ubuntu/Debian
@ -104,7 +117,8 @@ Super quick installation on RHEL/Fedora/CentOS
Super quick installation on MacOSX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
KloudBuster can run natively on MacOSX. These instructions have been verified to work on MacOSX 10.10 (Yosemite).
KloudBuster can run natively on MacOSX. These instructions have been verified
to work on MacOSX 10.10 (Yosemite).
First, download XCode from App Store, then execute below commands:
@ -132,27 +146,46 @@ To verify kloudbuster is installed, just type:
$ python kloudbuster/kloudbuster.py --help
.. _upload_kb_image:
Upload VM Image
---------------
Upload KloudBuster Image
-------------------------
.. note::
If your OpenStack Glance can access the Internet, you can skip this section and you are done with the installation.
If your OpenStack Glance is able to access the Internet, and you don't
need to access the KloudBuster UI from the pre-built image, you can skip
this section and you are done with the installation.
KloudBuster needs one "universal" test VM image (referred to as "KloudBuster image") that contains the necessary test software. The KloudBuster image is then instantiated in potentially large number of VMs by the KloudBuster application using the appropriate role (HTTP server, HTTP traffic generator...).
Pre-built images are available for download from the `OpenStack App Catalog <http://apps.openstack.org>`_ (preferred method). For whatever reason the pre-built version doesn't work for you, the image can be re-built from MacOSX using Vagrant or from any Linux server. See :ref:`here <build_vm_image>` for more details.
KloudBuster needs one "universal" test VM image (referred to as "KloudBuster
image") that contains the necessary test software. The KloudBuster image is
then instantiated in potentially large number of VMs by the KloudBuster
application using the appropriate role (HTTP server, HTTP traffic generator,
etc.).
Pre-built images are available for download from the
`OpenStack App Catalog <http://apps.openstack.org>`_ (preferred method). For
whatever reason the pre-built version doesn't work for you, the image can be
re-built from MacOSX using Vagrant or from any Linux server. See
:ref:`here <build_vm_image>` for more details.
Manual upload of the KloudBuster VM image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If Glance does not have access to http://storage.apps.openstack.org on the Internet, the KloudBuster VM image must be downloaded from the OpenStack App Catalog to an intermediate location then uploaded to Glance using either a Glance CLI command or via Horizon dashboard.
In order to upload the KloudBuster Image to the cloud under test, the image
must be downloaded from the OpenStack App Catalog to an intermediate location,
e.g. the jump host which has the access to both Internet and the cloud under
test, then uploaded to Glance using either a Glance CLI command or via Horizon
dashboard.
The KloudBuster VM image can be downloaded from `<http://apps.openstack.org/#tab=glance-images>`_. Look for an image named with the "kloudbuster_v" prefix and download the one that has the latest version.
KloudBuster VM images are qcow2 images named "kloudbuster_v<version>.qcow2"
(e.g. "kloudbuster_v3.qcow2"). The image can be downloaded from
`<http://apps.openstack.org/#tab=glance-images>`_. Look for an image named
with the "kloudbuster_v" prefix and download the latest version from the list.
KloudBuster VM images are qcow2 images named "kloudbuster_v<version>.qcow2" (e.g. "kloudbuster_v3.qcow2"). The name of the image in Glance must match exactly the image name in the App Catalog (without the .qcow2 extension), for example to upload the image from a local copy of that image:
The name of the image in Glance must match exactly the image name in the App
Catalog (without the .qcow2 extension), for example to upload the image from
a local copy of that image:
.. code-block:: bash

115
doc/source/usage.rst
View File

@ -2,18 +2,6 @@
Usage
=====
Quick Start Guide
-----------------
This guide will allow you to run KloudBuster on your OpenStack cloud using
the default scale settings which is generally safe to run on any cloud, small
or large (it should also work on an all-in-one devstack cloud installation).
The minimal pre-requisites to run KloudBuster:
* Admin access to the cloud under test
* 3 available floating IPs
There are total of three ways of running KloudBuster, and the easiest way
to start is using the **Web UI**. It offers the most friendly interface, and
also needs the least learning to get started. **CLI** is the traditional way
@ -23,40 +11,47 @@ have a GUI enabled environment. **Rest API** gives another way to access
and control KloudBuster. All APIs provided are well documented, and the
built-in web UI is fully implemented on top of these APIs.
.. _run_kloudbuster_with_web_ui:
The default scale settings of KloudBuster is at minimal scale, which is
generally safe to run on any cloud, small or large. It should also work on
an all-in-one devstack cloud installation as well. The minimal pre-requisites
to run KloudBuster:
* Admin access to the cloud under test
* 3 available floating IPs
Running KloudBuster with Web UI
-------------------------------
.. note::
The Web UI is developed using AngularJS framework, which needs to be built
before serving. If you want the web app to run on localhost, you have to
build it from source, and start the KloudBuster server. Refer to
:ref:`here <build_web_ui>` for the steps to build the web app, and refer to
:ref:`below section <start_kloudbuster_server>` for the steps to start the
KloudBuster server.
As of now, the Web UI can only be started when KloudBuster is using
GitHub/OpenStack Repository based installation. Availability of running
under PyPI based installation is working in progress.
An easier and better way is to use the KloudBuster image. The KloudBuster
image has the Web UI built-in, and it is ready to use once up running. It
is as easy as create a new regular VM with OpenStack in OpenStack. Here
are the steps for get the KloudBuster Web UI running from scratch:
KloudBuster integrates a Python based web server
`Pecan <http://www.pecanpy.org/>`_ to host the KloudBuster front-end
website, which listens to localhost:8080 by default.
1. Follow the steps :ref:`here <upload_kb_image>` to upload the KloudBuster
image to the cloud uder test;
From the root of the KloudBuster repository, go to kb_server directory.
If this is the first time to start the server, run below command once
to setup the environment::
2. Create and configure the Routers, Networks for holding a new VM;
$ python setup.py develop
3. Create a new security group, which allows the ingress TCP traffic on
port 8080;
Then start the server by doing::
4. Launch an instance using the KloudBuster image，with the security group
we just created, and connect to the network we just created. Leave the
Key Pair as blank, as we don't need the SSH access to this VM;
$ pecan serve config.py
5. Associate a floating IP to the newly created VM;
Idealy, you should see a message like below, which indicates the server
is up running::
6. Open your browser, and type the below address to get started::
Starting server in PID 26431
serving on 0.0.0.0:8080, view at http://127.0.0.1:8080
Open your browser, and type the below address to start using it::
http://127.0.0.1:8080/ui/index.html
http://<floating_ip>:8080/ui/index.html
Running KloudBuster with CLI
@ -78,7 +73,6 @@ KloudBuster will run on a single cloud mode and create:
* 1 VM running the HTTP traffic generator (default to 1000 connections,
1000 requests per second, and 30 seconds duration)
Run kloudbuster with the following options::
kloudbuster --tested-rc <path_to_the_admin_rc_file> --tested-passwd <admin_password>
@ -332,15 +326,60 @@ for more options.
Running with Rest API
---------------------
.. note::
As of now, the Web UI can only be started when KloudBuster is using
GitHub/OpenStack Repository based installation.
All Rest APIs are well documented using `Swagger <http://swagger.io/>`_. In
order to view them in a nice format, copy the entire contents of file
kb_server/kloudbuster-swagger.yaml, and paste into the left panel of
http://editor.swagger.io. Then you will see the specification of all Rest
APIs in the right panel of the web page.
Similar to running with Web UI, the Rest API server is hosted by Pecan as
well. So refer to :ref:`above section <run_kloudbuster_with_web_ui>` for
detailed documentations on how to start the Pecan server.
.. _start_kloudbuster_server:
KloudBuster integrates a Python based web server
`Pecan <http://www.pecanpy.org/>`_ to host both the KloudBuster Rest API
server and the KloudBuster front-end website, which listens to
localhost:8080 by default.
From the root of the KloudBuster repository, go to kb_server directory.
If this is the first time to start the server, run below command once
to setup the environment::
$ python setup.py develop
Then start the server by doing::
$ pecan serve config.py
Idealy, you should see a message like below, which indicates the server
is up running::
Starting server in PID 26431
serving on 0.0.0.0:8080, view at http://127.0.0.1:8080
Once the server is started, you can use different HTTP methods
(GET/PUT/POST/DELETE) to interactive with KloudBuster.
KloudBuster Standard Profiling
------------------------------
KloudBuster is able to perform the scale testing using different cominations
of configurations. There are multiple factors which can impact the final
results (VM count, number of connections per VM, number of requests per
seconds per VM, timeout, etc.). So KloudBuster is defining a specific set of
configurations among all cominations as a standard run.
In the standard run, the number of connections per VM will be set to 1000,
the number of requests per seconds per VM is set to 1000, the HTTP request
timeout is set to 5 seconds. The stop limit for progression runs will be error
packets greater than 50. Above configurations are all set by default.
In order to perform the standard run, set the max VM counts for the tests,
and enable the rogression runs. KloudBuster will start the iteration until
reaching the stop limit or the max scale. Eventually, once the KloudBuster run
is finished, the cloud performance can be told by looking at how many VMs
KloudBuster can run to.

11
kb_web/README.rst
View File

@ -4,20 +4,19 @@ KloudBuster Web UI
KloudBuster integrates a Python based web server which is able to host both
RestAPI server and KloudBuster front-end website. Normally, KloudBuster has
the front-end website pre-built and integrated into the KloudBuster image,
so you don't need to do anything to access the web UI.
so you don’t need to do anything to access the web UI.
Steps below are documented for development purposes, in the case if you want
to enhance the web UI.
to enhance the web UI. For regular users, the pre-built KloudBuster image
will satisfy most of the needs.
Setup Development Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The web UI is based on AngularJS, developped from Mac OS X (Yosemite), and
verified on Ubuntu 14.04.
Simply to say, below packages need to be installed for dependencies: NodeJS,
npm, grunt and bower.
verified on Ubuntu 14.04. Simply to say, below packages need to be installed
in order to do developments: NodeJS, npm, grunt and bower.
NodeJS & npm