Update doc for web service and other

Change-Id: I1d0ddf812f0252bff395b0eae0cedd7df9d7d59e
This commit is contained in:
ahothan 2016-01-12 08:56:14 -08:00
parent b15484d929
commit 041a6e6177
3 changed files with 93 additions and 75 deletions

View File

@ -44,7 +44,9 @@ Features
* Manual cleanup script * Manual cleanup script
* Server mode and REST interface: * Web Server mode with Web UI to drive scale test from your browser
* Web Server mode with REST interface:
* Allows KloudBuster to be driven by other programs * Allows KloudBuster to be driven by other programs
* Swagger 2.0 YAML description of the REST interface * Swagger 2.0 YAML description of the REST interface

View File

@ -2,21 +2,25 @@
Installation Installation
============ ============
There are two ways to install and run KloudBuster tool. Users of KloudBuster KloudBuster is already pre-installed as a web service in the KloudBuster VM image
should use regular PyPI based installation, while developers of KloudBuster available from the `OpenStack Community App Catalog <https://apps.openstack.org>`_
should use GitHub/OpenStack Repository based installation. Normally, PyPI
based installation will satisfy most of use cases, and it is the recommended There are two alternative ways to install and run KloudBuster tool.
way for running KloudBuster under production environments, or through an Users of KloudBuster who prefers to use the CLI should use regular PyPI based installation.
automated or scheduled job. A git repository based installation gives more Developers of KloudBuster should use the GitHub/OpenStack Repository based installation.
flexibility, and it is a must for developers of KloudBuster.
Web Service and PyPI based installation will satisfy most use cases
and are the 2 recommended ways for running KloudBuster under production environments, or through an
automated or scheduled job.
The git repository based installation is targeted at developers of KloudBuster.
.. note:: Installation from PyPI will only have the latest stable version. .. note:: Installation from PyPI will only have the latest stable version.
PyPI based Installation PyPI based Installation
----------------------- -----------------------
This is the recommended way to install KloudBuster for non-development use, This is the recommended way to install KloudBuster for non-development use if CLI is required.
and KloudBuster is available in the Python Package Index (PyPI): KloudBuster is available in the Python Package Index (PyPI):
`KloudBuster PyPI <https://pypi.python.org/pypi/KloudBuster>`_ `KloudBuster PyPI <https://pypi.python.org/pypi/KloudBuster>`_
Step 1 Step 1
@ -154,11 +158,12 @@ Upload KloudBuster Image
.. note:: .. note::
If your OpenStack Glance is able to access the Internet, and you don't 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 need to access the KloudBuster Web UI from the pre-built image, you can skip
this section and you are done with the installation. this section and you are done with the installation.
KloudBuster needs one "universal" test VM image (referred to as "KloudBuster In the cloud under test, KloudBuster needs one "universal" test VM image
image") that contains the necessary test software. The KloudBuster image is (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 then instantiated in potentially large number of VMs by the KloudBuster
application using the appropriate role (HTTP server, HTTP traffic generator, application using the appropriate role (HTTP server, HTTP traffic generator,
etc.). etc.).
@ -169,17 +174,26 @@ 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 re-built from MacOSX using Vagrant or from any Linux server. See
:ref:`here <build_vm_image>` for more details. :ref:`here <build_vm_image>` for more details.
.. note::
The same KloudBuster VM image can be instantiated for running the test functions
(HTTP servers and HTTP traffic generators) and for running KloudBuster as a web service.
Manual upload of the KloudBuster VM image Manual upload of the KloudBuster VM image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to upload the KloudBuster Image to the cloud under test, the image 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, must be downloaded from the OpenStack App Catalog either directly from
e.g. the jump host which has the access to both Internet and the cloud under the OpenStack App Catalog (if you have direct access to the Internet)
test, then uploaded to Glance using either a Glance CLI command or via Horizon or through an intermediate location such as a jump host (a jump host has access
dashboard. to both Internet and the cloud under
test and can be used to download the image from the App Catalog
and upload to Glance using either a Glance CLI command or via Horizon
dashboard).
KloudBuster VM images are qcow2 images named "kloudbuster_v<version>.qcow2" KloudBuster VM images are qcow2 images named "kloudbuster_v<version>.qcow2"
(e.g. "kloudbuster_v3.qcow2"). The image can be downloaded from (e.g. "kloudbuster_v6.qcow2"). The image can be downloaded from
`<http://apps.openstack.org/#tab=glance-images>`_. Look for an image named `<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. with the "kloudbuster_v" prefix and download the latest version from the list.
@ -189,4 +203,4 @@ a local copy of that image:
.. code-block:: bash .. code-block:: bash
$ glance image-create --file kloudbuster_v3.qcow2 --disk-format qcow2 --container-format bare --is-public True --name kloudbuster_v3 $ glance image-create --file kloudbuster_v6.qcow2 --disk-format qcow2 --container-format bare --is-public True --name kloudbuster_v6

View File

@ -2,13 +2,13 @@
Usage Usage
===== =====
There are total of three ways of running KloudBuster, and the easiest way There are three ways for running KloudBuster, the easiest
to start is using the **Web UI**. It offers the most friendly interface, and being the **Web UI**. It offers the most user friendly interface and
also needs the least learning to get started. **CLI** is the traditional way needs the least learning to get started. **CLI** is the traditional way
to run applications. It has the most comprehensive feature sets when compared to run applications. It has the most comprehensive feature sets when compared
to the other two ways, and also it is pretty much the only choice if you don't to the other two ways. **Rest API** gives another way to access
have a GUI enabled environment. **Rest API** gives another way to access and control KloudBuster from another application.
and control KloudBuster. All APIs provided are well documented, and the All APIs provided are well documented, and the
built-in web UI is fully implemented on top of these APIs. built-in web UI is fully implemented on top of these APIs.
The default scale settings of KloudBuster is at minimal scale, which is The default scale settings of KloudBuster is at minimal scale, which is
@ -20,9 +20,37 @@ to run KloudBuster:
* 3 available floating IPs * 3 available floating IPs
Running KloudBuster with Web UI Running KloudBuster as a Web Server
------------------------------- -----------------------------------
The easiest way to use KloudBuster is to run it as a web server application.
The KloudBuster qcow2 image has the Web server built-in and is ready to use once up running.
To get the KloudBuster Web serverI running from scratch:
1. Follow the steps :ref:`here <upload_kb_image>` to upload the KloudBuster
image to the openstack cloud that will host your kloudbuster web server
(note that this could be the same as the cloud under test or could be a different cloud)
2. If necessary, and as for any web server bringup, create and configure the Neutron router and network
where the KloudBuster web server VM instance will be attached
3. Create or reuse a security group which allows the ingress TCP traffic on
port 8080
4. Launch an instance using the KloudBuster imagewith the proper security group
and connect to the appropriate network. Leave the
Key Pair as blank, as we don't need the SSH access to this VM
5. Associate a floating IP to the newly created VM instance so that it can be accessible from
an external browser
6. Open your browser, and type the below address to get started::
http://<floating_ip>:8080/ui/index.html
Alternatively, you could also run KloudBuster as a local web server from a clone
of the KloudBuster git repository.
The Web UI is developed using AngularJS framework, which needs to be built 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 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 build it from source, and start the KloudBuster server. Refer to
@ -30,30 +58,6 @@ build it from source, and start the KloudBuster server. Refer to
:ref:`below section <start_kloudbuster_server>` for the steps to start the :ref:`below section <start_kloudbuster_server>` for the steps to start the
KloudBuster server. KloudBuster server.
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:
1. Follow the steps :ref:`here <upload_kb_image>` to upload the KloudBuster
image to the cloud uder test;
2. Create and configure the Routers, Networks for holding a new VM;
3. Create a new security group, which allows the ingress TCP traffic on
port 8080;
4. Launch an instance using the KloudBuster imagewith 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;
5. Associate a floating IP to the newly created VM;
6. Open your browser, and type the below address to get started::
http://<floating_ip>:8080/ui/index.html
Running KloudBuster with CLI Running KloudBuster with CLI
---------------------------- ----------------------------
@ -326,11 +330,6 @@ for more options.
Running with Rest API 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 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 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 kb_server/kloudbuster-swagger.yaml, and paste into the left panel of
@ -364,35 +363,38 @@ Once the server is started, you can use different HTTP methods
(GET/PUT/POST/DELETE) to interactive with KloudBuster. (GET/PUT/POST/DELETE) to interactive with KloudBuster.
KloudBuster Standard Profiling KloudBuster Standard Scale Profile
------------------------------ ----------------------------------
KloudBuster is able to perform the scale testing using different cominations Multiple factors can impact data plane scale numbers measured by KloudBuster:
of configurations. There are multiple factors which can impact the final VM count, number of connections per VM, number of requests per
results (VM count, number of connections per VM, number of requests per seconds per VM, timeout, etc...
seconds per VM, timeout, etc.). So KloudBuster is defining a specific set of To help obtaining quick and easy results without having to tweak too many parameters,
configurations among all cominations as a standard run. KloudBuster defines an off the shelf *default scale profile*.
In the standard run, the number of connections per VM will be set to 1000, In the default scale profile:
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. The size of the HTML page in the server VMs will be
32768 Bytes. Above configurations are all set by default.
In order to perform the standard run, set the max VM counts for the tests, - the number of connections per VM will be set to 1000,
and enable the rogression runs. KloudBuster will start the iteration until - 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.
- The size of the HTML page in the server VMs will be 32768 Bytes.
In order to perform a run using the default scale profile, set the max VM counts for the test,
enable progression run and leave everything else with their default values.
KloudBuster will start the iteration until
reaching the stop limit or the max scale. Eventually, once the KloudBuster 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 run is finished, the cloud performance can be told by looking at how many VMs
KloudBuster can run to. KloudBuster can run to and by looking at the latency charts.
As a reference, for a Kilo OpenStack deployment (LinuxBridge + VLAN) with As a reference, KloudBuster can run approximately 21 VMs (with 21,000 connections and 21,000 HTTP requests/sec)
Packstack, using an 10GE NIC card for data plane traffic, KloudBuster can run and achieve approximately 5 Gbps of HTTP throughput on
apprximately 21 VMs and achieve approximately 5 GBps throughput. a typical multi-node Kilo OpenStack deployment (LinuxBridge + VLAN, 10GE NIC card).
How-to How-to
^^^^^^ ^^^^^^
In order to run KloudBuster Standard Profiling, you have to set up below In order to run KloudBuster Standard Scale Profile, you have to set up below
configurations: configurations:
1. Enable progression runs: 1. Enable progression runs: