Fix the link issue in Documents

Change-Id: Id33cc16811897b449dc564232328957e7f3b43f2
This commit is contained in:
Yichen Wang 2016-05-13 15:32:54 -07:00
parent 1c9d14743b
commit 691a8883e7
6 changed files with 122 additions and 98 deletions

View File

@ -30,8 +30,7 @@ The default storage scale test will use the following settings:
* Create 1 private network
* Create 1 VM and attach a 10 GB Cinder volume to it
* Perform the default storage workload sequence:
* random access 4KB block size, IO depth 4, 100 IOPs for 30 seconds each
* random access 4KB block size, IO depth 4, 100 IOPs for 30 seconds
* 100% read
* 100% write
* 70% read, 30% write
@ -67,11 +66,11 @@ that are documented using yaml comments.
in the configuration file that you do not intend to change
Once modified, you can pass the configuration file to KloudBuster using the
--config option.
*--config* option.
General Configuration Options
-----------------------------
"""""""""""""""""""""""""""""
Each item in the configuration file is well documented. Below is
just a quick-start on some important config items that need to be paid more

View File

@ -1,22 +1,22 @@
==============================================
KloudBuster Docker Container Quick Start Guide
KloudBuster Docker Container Quick Start Guide
==============================================
The KloudBuster Docker container provides a quick way to use KloudBuster
if you are already familiar with Docker.
The KloudBuster Docker container provides a quick way to use KloudBuster if you
are already familiar with Docker.
Prerequisites
-------------
This quick start guide assumes you have already installed Docker.
All command line examples below are based on Linux (which could be
either native or in a VM) and require Internet access to Docker Hub.
This quick start guide assumes you have already installed Docker. All command
line examples below are based on Linux (which could be either native or in a
VM) and require Internet access to Docker Hub.
1. Pull latest Docker container image
-------------------------------------
KloudBuster is available as a container in Docker Hub at
KloudBuster is available as a container in Docker Hub at
`berrypatch/kloudbuster <https://hub.docker.com/r/berrypatch/kloudbuster/>`_
.. code-block:: bash
@ -26,37 +26,44 @@ KloudBuster is available as a container in Docker Hub at
2. Get the openrc file from your OpenStack Horizon dashboard
------------------------------------------------------------
Using the Horizon dashboard, download the openrc file (Project|Compute|API Access then click on "Download OpenStack RC File").
It is best to use the admin user to run KloudBuster as much as possible (otherwise there are restrictions on what you can do).
Instructions below assume a copy of that file is saved under the local directory with the name "admin-openrc.sh"
Using the Horizon dashboard, download the openrc file (Project|Compute|API
Access then click on "Download OpenStack RC File"). It is best to use the
admin user to run KloudBuster as much as possible (otherwise there are
restrictions on what you can do). Instructions below assume a copy of that
file is saved under the local directory with the name "admin-openrc.sh"
3. Upload the KloudBuster VM image to the cloud under test
----------------------------------------------------------
If your OpenStack cloud has full access to the Internet, you can skip this step as KloudBuster will
instruct Glance to download the KloudBuster VM inage directly from the OpenStack (skip to next step).
Otherwise, :ref:`download the latest kloudbuster image <upload_kb_image>` from the OpenStack App Catalog.
If your OpenStack cloud has full access to the Internet, you can skip this step
as KloudBuster will instruct Glance to download the KloudBuster VM inage
directly from the OpenStack (skip to next step).
In addition to the method described to upload the image using the Horizon dashboard or the glance CLI,
you can also use the glance CLI that is already available in the KloudBuster container.
Start a bash shell in the container and map the local directory to '/opt/kb' in the container
so that you have access to the image and the RC file:
Otherwise, :ref:`download the latest kloudbuster image <upload_kb_image>` from
the OpenStack App Catalog.
In addition to the method described to upload the image using the Horizon
dashboard or the glance CLI, you can also use the glance CLI that is already
available in the KloudBuster container. Start a bash shell in the container
and map the local directory to '/opt/kb' in the container so that you have
access to the image and the RC file:
.. code-block:: bash
docker run -v $PWD:/opt/kb --rm -it berrypatch/kloudbuster bash
Then from inside the container bash prompt, source the openrc file, invoke the glance
CLI to upload the VM image (should take a few minutes) then exit and terminate the container:
Then from inside the container bash prompt, source the openrc file, invoke the
glance CLI to upload the VM image (should take a few minutes) then exit and
terminate the container:
.. code-block:: bash
source /opt/kb/admin-openrc.sh
glance image-create --name "kloudbuster_v6" --visibility public --disk-format qcow2 --container-format bare --file /opt/kb/kloudbuster_v6.qcow2
exit
glance image-create --name "kloudbuster_v6" --visibility public --disk-format qcow2 --container-format bare --file /opt/kb/kloudbuster_v6.qcow2
Now you should be back to the host and should see the kloudbuster image in the current directory.
Now you should be back to the host and should see the kloudbuster image in the
current directory.
4. Running the KloudBuster CLI
------------------------------
@ -69,14 +76,15 @@ KloudBuster scale test straight from CLI in the container.
docker run -v $PWD:/opt/kb --rm -t berrypatch/kloudbuster kloudbuster -h
We assume in the below example that you have an openrc file available called "admin-openrc.sh" in the local directory
and that the corresponding OpenStack password is "admin"
We assume in the below example that you have an openrc file available called
"admin-openrc.sh" in the local directory and that the corresponding OpenStack
password is "admin".
Run the default HTTP data plane scale test
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default HTTP scale test is described :ref:`here <default_http_scale>`
The default HTTP scale test is described :ref:`here <default_http_scale>`.
.. code-block:: bash
@ -85,7 +93,7 @@ The default HTTP scale test is described :ref:`here <default_http_scale>`
Run the default storage scale test
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default storage scale test is described :ref:`here <default_storage_scale>`
The default storage scale test is described :ref:`here <default_storage_scale>`.
.. code-block:: bash
@ -95,15 +103,17 @@ The default storage scale test is described :ref:`here <default_storage_scale>`
Run KloudBuster with a custom configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To get a copy of the default KloudBuster configuration and store it to a file called "kb.cfg"::
To get a copy of the default KloudBuster configuration and store it to a file
called "kb.cfg":
.. code-block:: bash
docker run --rm berrypatch/kloudbuster kloudbuster --show-config >/opt/kb/kb.cfg
less kb.cfg
You can then edit kb.cfg and modify it appropriately. To run KloudBuster with the custom configuration, simply pass it to container after mapping the host local directory to "/opt/kb" (for example)::
You can then edit kb.cfg and modify it appropriately. To run KloudBuster with
the custom configuration, simply pass it to container after mapping the host
local directory to "/opt/kb" (for example):
.. code-block:: bash
@ -112,13 +122,18 @@ You can then edit kb.cfg and modify it appropriately. To run KloudBuster with th
5. Running KloudBuster as a WebUI/REST Server
---------------------------------------------
By default KloudbBuster will listen on port 8080 in the container. This port must be mapped to a host level port using the -p argument. For example, to use the same port number at the host level:
By default KloudbBuster will listen on port 8080 in the container. This port
must be mapped to a host level port using the -p argument. For example, to use
the same port number at the host level:
.. code-block:: bash
docker run -p 8080:8080 --rm berrypatch/kloudbuster kb_start_server&
The first port number is the host listen port (any port of your choice) while the second one after the column is the container listen port (always 8080 for KloudBuster). For example, to use port 9090 on the host and map it to the KloudBuster port in the container, you would use -p 9090:8080
The first port number is the host listen port (any port of your choice) while
the second one after the column is the container listen port (always 8080 for
KloudBuster). For example, to use port 9090 on the host and map it to the
KloudBuster port in the container, you would use -p 9090:8080
To stop the KloudBuster container, you can use the "docker kill <id>" command.
@ -130,6 +145,7 @@ The KloudBuster REST base URL is the above URL with "/api" appended::
http://<host_ip>:8080/api
ref:`How to use the Web UI <webui_usage>`
ref:`How to use the REST interface <rest_usage>`
:ref:`How to use the Web UI <webui_usage>`
:ref:`How to use the REST interface <rest_usage>`

View File

@ -65,7 +65,6 @@ If you need to run the KloudBuster Web UI you need to install coreutils
.. code-block:: bash
$
$ # If you need to run KloudBuster Web UI,
$ # coreutils needs to be installed using Homebrew.
$ # Refer here for the steps to install Homebrew on Mac:
@ -104,8 +103,6 @@ If you need to run the KloudBuster Web UI you need to install coreutils
Full documentation at: <http://www.gnu.org/software/coreutils/stdbuf>
or available locally via: info '(coreutils) stdbuf invocation'
Verify installation
^^^^^^^^^^^^^^^^^^^
@ -123,10 +120,13 @@ to the OpenStack cloud under test.
3. Download the openrc file
---------------------------
Using the Horizon dashboard, download the openrc file (Project|Compute|API Access then click on "Download OpenStack RC File").
It is best to use the admin user to run KloudBuster as much as possible (otherwise there are restrictions on what you can do).
The examples below assume the openrc file is saved at the root of the kloudbuster git repository with the name "admin-openrc.sh"
and the password is "admin".
Using the Horizon dashboard, download the openrc file (Project|Compute|API
Access then click on "Download OpenStack RC File"). It is best to use the
admin user to run KloudBuster as much as possible (otherwise there are
restrictions on what you can do). The examples below assume the openrc file is
saved at the root of the kloudbuster git repository with the name
"admin-openrc.sh" and the password is "admin".
4. Running the KloudBuster CLI
------------------------------
@ -134,7 +134,7 @@ and the password is "admin".
Run the default HTTP data plane scale test
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default HTTP scale test is described :ref:`here <default_http_scale>`
The default HTTP scale test is described :ref:`here <default_http_scale>`.
.. code-block:: bash
@ -143,7 +143,7 @@ The default HTTP scale test is described :ref:`here <default_http_scale>`
Run the default storage scale test
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default storage scale test is described :ref:`here <default_storage_scale>`
The default storage scale test is described :ref:`here <default_storage_scale>`.
.. code-block:: bash
@ -152,13 +152,15 @@ The default storage scale test is described :ref:`here <default_storage_scale>`
Run KloudBuster with a custom configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default KloudBuster configuration file is in cfg.scale.yaml. You can make a copy of it in "kb.cfg"::
The default KloudBuster configuration file is in cfg.scale.yaml. You can make a
copy of it in "kb.cfg":
.. code-block:: bash
cp kloudbuster/cfg.scale.yaml kb.cfg
You can then edit kb.cfg and modify it appropriately. To run KloudBuster with the custom configuration::
You can then edit kb.cfg and modify it appropriately. To run KloudBuster with
the custom configuration:
.. code-block:: bash
@ -179,8 +181,9 @@ is up running::
By default KloudbBuster will listen on port 8080.
ref:`How to use the Web UI <webui_usage>`
ref:`How to use the REST interface <rest_usage>`
:ref:`How to use the Web UI <webui_usage>`
:ref:`How to use the REST interface <rest_usage>`
To terminate the server, simply use the kill command on the server pid.

View File

@ -108,13 +108,15 @@ To verify kloudbuster is installed properly, just type::
3. Upload the KloudBuster VM image
----------------------------------
Follow the :ref:`steps <upload_kb_image>` to upload the KloudBuster VM image
to the OpenStack cloud under test.
Follow the :ref:`steps <upload_kb_image>` to upload the KloudBuster VM image to
the OpenStack cloud under test.
4. Download the openrc file
---------------------------
Using the Horizon dashboard, download the openrc file (Project|Compute|API Access then click on "Download OpenStack RC File").
It is best to use the admin user to run KloudBuster as much as possible (otherwise there are restrictions on what you can do).
Using the Horizon dashboard, download the openrc file (Project|Compute|API
Access then click on "Download OpenStack RC File"). It is best to use the
admin user to run KloudBuster as much as possible (otherwise there are
restrictions on what you can do).
5. Running the KloudBuster CLI
@ -123,7 +125,7 @@ It is best to use the admin user to run KloudBuster as much as possible (otherwi
Run the default HTTP data plane scale test
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default HTTP scale test is described :ref:`here <default_http_scale>`
The default HTTP scale test is described :ref:`here <default_http_scale>`.
.. code-block:: bash
@ -133,7 +135,7 @@ The default HTTP scale test is described :ref:`here <default_http_scale>`
Run the default storage scale test
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default storage scale test is described :ref:`here <default_storage_scale>`
The default storage scale test is described :ref:`here <default_storage_scale>`.
.. code-block:: bash
@ -142,14 +144,16 @@ The default storage scale test is described :ref:`here <default_storage_scale>`
Run KloudBuster with a custom configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To get a copy of the default KloudBuster configuration and store it to a file called "kb.cfg"::
To get a copy of the default KloudBuster configuration and store it to a file
called "kb.cfg":
.. code-block:: bash
kloudbuster --show-config >kb.cfg
less kb.cfg
You can then edit kb.cfg and modify it appropriately. To run KloudBuster with the custom configuration::
You can then edit kb.cfg and modify it appropriately. To run KloudBuster with
the custom configuration:
.. code-block:: bash
@ -177,6 +181,7 @@ The KloudBuster REST base URL is the above URL with "/api" appended::
http://<host_ip>:8080/api
ref:`How to use the Web UI <webui_usage>`
ref:`How to use the REST interface <rest_usage>`
:ref:`How to use the Web UI <webui_usage>`
:ref:`How to use the REST interface <rest_usage>`

View File

@ -26,21 +26,25 @@ You can also reuse an existing tenant network and router.
3. Create a Security Group
--------------------------
Create or reuse a security group which allows ingress TCP traffic on port 8080
Create or reuse a security group which allows ingress TCP traffic on port 8080.
4. Launch the KloudBuster VM Application
----------------------------------------
Launch an instance using the KloudBuster image with 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
Launch an instance using the KloudBuster image with 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
--------------------------
Associate a floating IP to the newly created VM instance so that it can be
accessible from an external browser
6. Connect to the web UI with a browser
---------------------------------------
The Web UI URL to use from any browser is::
http://<floating_ip>:8080
@ -51,17 +55,14 @@ The base URL to use for REST access is::
7. Download the openrc file
---------------------------
Using the Horizon dashboard, download the openrc file (Project|Compute|API Access then click on "Download OpenStack RC File").
It is best to use the admin user to run KloudBuster as much as possible (otherwise there are restrictions on what you can do).
Using the Horizon dashboard, download the openrc file (Project|Compute|API
Access then click on "Download OpenStack RC File"). It is best to use the
admin user to run KloudBuster as much as possible (otherwise there are
restrictions on what you can do).
8. Login to KloudBuster
-----------------------
Follow ref:`instructions <webui_usage>` on how to use the web UI.
Follow :ref:`instructions <webui_usage>` on how to use the web UI.

View File

@ -19,7 +19,7 @@ OpenStack cloud pre-requisites to run KloudBuster:
* Neutron networking
* Admin access to the cloud under test (non-admin might work with some
tweaks and limitations)
* 3 available floating IPs if running the HTTP data plane scale test,
* 3 available floating IPs if running the HTTP data plane scale test
* 2 available floating IPs if running the Storage scale test
KloudBuster Installation Options
@ -37,7 +37,7 @@ locally on their workstation or laptop can use the PyPI based installation
(pip install) or the Docker container.
Docker container, Web Service and PyPI based installation will satisfy most use cases
and are the recommended ways for running KloudBuster under production environments
and are the recommended ways for running KloudBuster under production environments
or through an automated or scheduled job.
@ -56,19 +56,20 @@ Quick Start Guides
Using the KloudBuster Web UI
----------------------------
Using any browser, point to the provided URL. You will get a Login page where you will need to enter:
Using any browser, point to the provided URL. You will get a Login page where
you will need to enter:
* The type of scale test (HTTP data plane or storage)
* The location of the openrc file for the cloud under test and the corresponding
OpenStack password
You could modify the scale test configuration options or simply start the scale test with the default scale configuration.
Click on Stage button to instruct KloudBuster to stage all the OpenStack resources. This can take time
depending on how many VMs are requested and how fast is the cloud under test.
You could modify the scale test configuration options or simply start the scale
test with the default scale configuration. Click on Stage button to instruct
KloudBuster to stage all the OpenStack resources. This can take time depending
on how many VMs are requested and how fast is the cloud under test.
Once staging is done, click on the Run button to run the scale test.
.. _rest_usage:
Interacting with the KloudBuster REST Interface
@ -93,15 +94,14 @@ KloudBuster VM Image Upload
---------------------------
Before you can use KloudBuster you must upload the KloudBuster VM image to your
OpenStack cloud under test.
KloudBuster needs one "universal" test VM image
OpenStack cloud under test. KloudBuster needs one "universal" test VM image
(referred to as "KloudBuster image") that contains the necessary test software.
The KloudBuster image is then instantiated by the KloudBuster application
in potentially large number of VMs using the appropriate role (HTTP server,
HTTP traffic generator...).
The KloudBuster image is then instantiated by the KloudBuster application in
potentially large number of VMs using the appropriate role (HTTP server, HTTP
traffic generator...).
Pre-built VM images are available for download from the
`OpenStack App Catalog <http://apps.openstack.org/#tab=glance-images>`_.
`OpenStack App Catalog <http://apps.openstack.org/#tab=glance-images>`_.
.. note::
@ -118,13 +118,13 @@ Pre-built VM images are available for download from the
Download the KloudBuster VM image to the local directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You must download a local copy if your OpenStack cloud does not have dirct access
to the Internet.
Download the latest image directly from `OpenStack App Catalog <http://apps.openstack.org/#tab=glance-images>`_
using your favorite browser (search for "kloudbuster") or using wget.
KloudBuster VM images are qcow2 images named "kloudbuster_v<version>.qcow2"
(e.g. "kloudbuster_v6.qcow2"). Look for an image named
with the "kloudbuster_v" prefix and download the latest version from the list.
You must download a local copy if your OpenStack cloud does not have dirct
access to the Internet. Download the latest image directly from
`OpenStack App Catalog <http://apps.openstack.org/#tab=glance-images>`_ using
your favorite browser (search for "kloudbuster") or using wget. KloudBuster VM
images are qcow2 images named "kloudbuster_v<version>.qcow2" (e.g.
"kloudbuster_v6.qcow2"). Look for an image named with the "kloudbuster_v"
prefix and download the latest version from the list.
Example for downloading the v6 image using wget:
@ -132,14 +132,13 @@ Example for downloading the v6 image using wget:
wget http://storage.apps.openstack.org/images/kloudbuster_v6.qcow2
Upload the KloudBuster VM image using the Horizon Dashboard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From the dashboard, create a new image and select either "Image File" if you want to
uplaod from the local copy of the image or "Image Location" if you want to
upload directly from the OpenStack App Catalog (you will need the complete URL of the image).
From the dashboard, create a new image and select either "Image File" if you
want to uplaod from the local copy of the image or "Image Location" if you want
to upload directly from the OpenStack App Catalog (you will need the complete
URL of the image).
The name of the image in Glance *must* match exactly the image name in the App
Catalog (without the .qcow2 extension, e.g. "kloudbuster_v6").
@ -149,6 +148,7 @@ Upload the KloudBuster VM image using the Glance CLI
This assumes that you have installed the OpenStack Glance API and have sourced
the appropriate openrc file.
To upload the image from a local copy of that image using the Glance CLI:
.. code-block:: bash