x/vmtp
Code Issues Proposed changes

Update documentation

Browse Source 
Change-Id: Ifb30f857e4a12d55c3a3d24b84685fd3dc8a9ee6
This commit is contained in:
ahothan 2016-07-04 15:14:16 -07:00
parent 6cfbc4d5e8
commit 595f152611
8 changed files with 1168 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.rst
View File

@ -32,6 +32,10 @@ For VM-related flows, VMTP will automatically create the necessary OpenStack res
See the usage page for the description of all the command line arguments supported by VMTP.
Online Documentation
--------------------
The complete documentation for VMTP including installation and usage guide is available at http://vmtp.readthedocs.io/en/latest
Pre-requisite
-------------
@ -212,7 +216,7 @@ Sections 1 and 2 above provided that you also do one of the following:
Links
-----
* Documentation: http://vmtp.readthedocs.org/en/latest
* Documentation: http://vmtp.readthedocs.io/en/latest
* Source: http://git.openstack.org/cgit/openstack/vmtp
* Supports/Bugs: https://launchpad.net/vmtp
* Mailing List: vmtp-core@lists.launchpad.net

26
doc/source/contributing.rst
View File

@ -69,33 +69,39 @@ Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/vmtp
Build VMTP Docker Image
-----------------------
Build the VMTP Docker Image
---------------------------
The VMTP Docker images are published in the DockerHub berrypatch repository:
`<https://hub.docker.com/r/berrypatch/vmtp/>`_
Two files are used to build the Docker image: *Dockerfile* and *.dockerignore*. The former provides all the build instructions while the latter provides the list of files/directories that should not be copied to the Docker image.
In order to make the Docker image clean, remove all auto generated files from the root of your workspace first. It is strongly recommeneded to simply pull a new one from GitHub/StackForge. Specify the image name and the tag, and feed them to docker build. Examples to build the image with name "$USER/vmtp", tag "2.0.0" and "latest"::
In order to make the Docker image clean, remove all auto generated files from the root of your workspace first. It is strongly recommeneded to simply pull a new one from GitHub/OPenStack. Specify the image name and the tag, and feed them to docker build.
The tag should be an existing git tag for the vmtp repository.
To build the image with tag "2.0.0" and "latest"::
$ cd <vmtp-ws-root>
$ sudo docker build --tag=$USER/vmtp:2.0.0 .
$ sudo docker build --tag=$USER/vmtp:latest .
$ sudo docker build --tag=berrypatch/vmtp:2.0.0 .
$ sudo docker build --tag=berrypatch/vmtp:latest .
The images should be available for use::
$ sudo docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
ahothan/vmtp 2.0.0 9f08056496d7 27 hours ago 494.6 MB
ahothan/vmtp latest 9f08056496d7 27 hours ago 494.6 MB
berrypatch/vmtp 2.0.0 9f08056496d7 27 hours ago 494.6 MB
berrypatch/vmtp latest 9f08056496d7 27 hours ago 494.6 MB
For exchanging purposes, the image could be saved to a tar archive. You can distribute the VMTP Docker image among your servers easily with this feature::
$ sudo docker save -o <IMAGE_FILE> <IMAGE_ID>
To publish the image to Docker Hub::
To publish you need to be a member of the berrypatch vmtp team. After the login (requires your DockerHub username and password), push the appropriate version to berrypatch::
$ sudo docker login
$ sudo docker push $USER/vmtp:2.0.0
$ sudo docker push $USER/vmtp:latest
$ sudo docker push berrypatch/vmtp:2.0.0
$ sudo docker push berrypatch/vmtp:latest
.. _developer_guide_of_openstack:

4
doc/source/index.rst
View File

@ -3,8 +3,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to vmtp's documentation!
================================
Welcome to the VMTP documentation!
==================================
Contents:

141
doc/source/installation.rst
View File

@ -1,128 +1,29 @@
============
Installation
============
===================================
Installation and Quick Start Guides
===================================
There are two ways to install and run VMTP tool. Users of VMTP should use regular PyPI based installation, while developers of VMTP should use GitHub/StackForge Repository based installation. Normally, PyPI based installation will satisfy most of use cases, and it is the recommended way for running VMTP 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 VMTP.
VMTP can be installed on any server that has access to the OpenStack API.
There are 3 ways to install and run the VMTP tool:
.. note:: Installation from PyPI will only have the latest stable version.
- Docker container
- PyPI package
- Git
The Git installation is required for VMTP developers and can be used for users who want to have access to the VMTP source code.
Otherwise, most users should select the Docker container installation (if already using Docker containers) or the more "pythonic" method with PyPI packages/pip.
PyPI based Installation
-----------------------
.. toctree::
:maxdepth: 2
PyPI (The Python Package Index) is the official repository for software in Python. It holds lots of packages, and the installation is relatively easy in only 2 steps.
quickstart_docker
quickstart_pip
quickstart_git
Step 1
^^^^^^
Installation and Quick Start Guides:
Install required development libraries. Run the command based on your distro.
- :ref:`VMTP Docker Container Installation and Quick Start Guide <docker_installation>`
- :ref:`VMTP PyPI Installation and Quick Start Guide <pip_installation>`
- :ref:`VMTP Git Installation and Quick Start Guide <git_installation>`
Ubuntu/Debian based:
.. code-block:: bash
$ sudo apt-get install build-essential python-dev python-pip python-virtualenv git git-review
$ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev
RHEL/CentOS based:
.. code-block:: bash
$ sudo yum install gcc python-devel python-pip python-virtualenv git
$ sudo yum install libxml2-devel libxslt-devel libffi-devel libyaml-devel openssl-devel
MacOSX:
.. code-block:: bash
$ # Download the XCode command line tools from Apple App Store
$ xcode-select --install
$ sudo easy_install pip
$ sudo pip install virtualenv
Step 2
^^^^^^
Create a virtual environment for Python, and install VMTP:
.. code-block:: bash
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ pip install vmtp
$ vmtp -h
.. 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::
$ sudo pip install vmtp
instead if isolation among multiple Python projects is not needed.
.. _git_installation:
GitHub/OpenStack Repository based Installation
----------------------------------------------
It is recommended to run VMTP inside a virtual environment. However, it can be skipped if installed in a dedicated VM.
Super quick installation on Ubuntu/Debian
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
$ sudo apt-get install build-essential python-dev python-pip python-virtualenv git git-review
$ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev
$ # create a virtual environment
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ git clone git://git.openstack.org/openstack/vmtp
$ cd vmtp
$ pip install -r requirements-dev.txt
$ cd vmtp
$ python vmtp.py -h
Super quick installation on RHEL/CentOS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
$ sudo yum install gcc python-devel python-pip python-virtualenv git
$ sudo yum install libxml2-devel libxslt-devel libffi-devel libyaml-devel openssl-devel
$ sudo pip install git-review
$ # create a virtual environment
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ git clone git://git.openstack.org/openstack/vmtp
$ cd vmtp
$ pip install -r requirements-dev.txt
$ cd vmtp
$ python vmtp.py -h
Super quick installation on MacOSX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
VMTP 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:
.. code-block:: bash
$ # Download the XCode command line tools
$ xcode-select --install
$ # Install pip
$ sudo easy_install pip
$ # Install python virtualenv
$ sudo pip install virtualenv
$ # create a virtual environment
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ git clone git://git.openstack.org/openstack/vmtp
$ cd vmtp
$ pip install -r requirements-dev.txt
$ cd vmtp
$ python vmtp.py -h
.. note:: Installation from Docker container or PyPI will only have the latest stable version.

358
doc/source/quickstart_docker.rst Normal file
View File

@ -0,0 +1,358 @@
========================================================
VMTP Docker Container Installation and Quick Start Guide
========================================================
.. _docker_installation:
Using the VMTP Docker container is the simplest and fastest method if you are already using Docker.
1. Installation
---------------
VMTP is available as a container in Docker Hub at
`berrypatch/vmtp <https://hub.docker.com/r/berrypatch/vmtp/>`_
To pull the latest vmtp container image (you may not need to run these commands with "sudo" if you have root permission):
.. code-block:: bash
sudo docker pull berrypatch/vmtp
To test vmtp is working:
.. code-block:: bash
sudo docker run --rm berrypatch/vmtp vmtp -h
2. Key Pair
-----------
VMTP requires a key pair to use to ssh to the test VMs that it will launch in OpenStack.
You can use the current user's key pair (located in $HOME/.ssh on the host where you run the container) if they exist:
.. code-block:: bash
$ ls -l ~/.ssh/id*
-rw------- 1 localadmin localadmin 1679 Mar 9 2015 /home/localadmin/.ssh/id_rsa
-rw-r--r-- 1 localadmin localadmin 400 Mar 9 2015 /home/localadmin/.ssh/id_rsa.pub
Otherwise you need to create a key pair on your host:
.. code-block:: bash
ssh-keygen -t rsa
3. Download RC file
-------------------
VMTP requires downloading an "openrc" file from the OpenStack Dashboard (Project|Acces&Security!Api Access|Download OpenStack RC File). That RC file is required to connect to OpenStack using the OpenStack API.
This file should be passed to VMTP using the *-r* option or should be sourced prior to invoking VMTP.
Because VMTP runs in a Docker container, the RC file must be accessible from the container.
The simplest is to download the RC file on the Docker host and make the (host) directory directly accessible to the container using the -v option.
For example if the RC file is downloaded as "admin-openrc.sh" in the current directory, that file is accessible from the container by mapping the current host directory ($PWD) to the "/tmp/vmtp" directory in the container and using the "/tmp/vmtp/admin-openrc.sh" pathname (in the below example, the container command just lists the rc file before exiting)
.. code-block:: bash
sudo docker run --rm -v $PWD:/tmp/vmtp berrypatch/vmtp ls /tmp/vmtp/admin-openrc.sh
4. Preparation steps with OpenStack
-----------------------------------
Now that the RC file is available from the container, you can run any OpenStack CLI command in the container (since the container will have all standard OpenStack client packages installed along with VMTP). Run the container in interactive mode, get to its shell prompt and source the RC file:
.. code-block:: bash
sudo docker run --rm -it -v $PWD:/tmp/vmtp berrypatch/vmtp bash
root@af7cedc3866f:/# source /tmp/vmtp/admin-openrc.sh
4.1. Verify flavor names
^^^^^^^^^^^^^^^^^^^^^^^^
We will check the flavor names available as we will have to select one flavor that VMTP should use to launch VM instances.
List the flavors (results may be different):
.. code-block:: bash
root@af7cedc3866f:/# nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
root@af7cedc3866f:/# exit
exit
localadmin@GG27-16:~/wsvmtp$
4.2. Upload any Linux VM image to OpenStack
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
VMTP requires a standard Linux VM image to run its tests in OpenStack.
You can skip this step if you already have a standard Linux VM image in your OpenStack (Ubuntu, Fedora, RHEL...).
Otherwise, you can upload any Linux VM image using the glance CLI or using the Horizon dashboard.
In the example below we will upload the Ubuntu 14.04 cloud image available from the uec-images.ubuntu.com web site using the glance CLI and we will name it "Ubuntu Server 14.04".
If your OpenStack can access directly the Internet:
.. code-block:: bash
root@af7cedc3866f:/# glance --os-image-api-version 1 image-create --copy-from http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu Server 14.04'
The glance command will return immediately but it will take some time for the file to get transferred. You will need to check for the status of the image before you can use it (will "queued", then "saving" then "active" if there is no issue).
If you prefer to make a local copy of the image, from another terminal window on the host:
.. code-block:: bash
wget http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img
Then copy it to OpenStack using the glance CLI (from the container prompt):
.. code-block:: bash
root@af7cedc3866f:/# glance --os-image-api-version 1 image-create --file /tmp/vmtp/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu 14.04'
Then list the images to verify and exit the container:
.. code-block:: bash
root@af7cedc3866f:/# glance image-list
+--------------------------------------+---------------------+
| ID | Name |
+--------------------------------------+---------------------+
| 5d7899d9-811c-483f-82b3-282a9bf143bf | cirros |
| 443ee290-b714-4bfe-9acb-b996ed6cc118 | Ubuntu 14.04 |
+--------------------------------------+---------------------+
root@af7cedc3866f:/# glance image-show 443ee290-b714-4bfe-9acb-b996ed6cc118
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| checksum | 479a314d90cefc163fdcfb875a070cd8 |
| container_format | bare |
| created_at | 2016-07-04T17:53:20Z |
| disk_format | qcow2 |
| id | 443ee290-b714-4bfe-9acb-b996ed6cc118 |
| min_disk | 0 |
| min_ram | 0 |
| name | Ubuntu 14.04 |
| owner | 5d912149f7474804824a463464874a21 |
| protected | False |
| size | 268829184 |
| status | active |
| tags | [] |
| updated_at | 2016-07-04T18:06:38Z |
| virtual_size | None |
| visibility | private |
+------------------+--------------------------------------+
root@af7cedc3866f:/# exit
5. Create your VMTP config file
-------------------------------
Get a copy of the default VMTP configuration file and save it in the local directory:
.. code-block:: bash
sudo docker run --rm -v $PWD:/tmp/vmtp berrypatch/vmtp vmtp -s > vmtp.cfg
Edit the vmtp.cfg file and make sure the following parameters are set properly:
- "image_name" must be the image name to use by VMTP ('Ubuntu Server 14.04' in the above example)
- "ssh_vm_username" must be a valid user name for the Linux image ("ubuntu" for Ubuntu images)
- "flavor_type" must be an appropriate flavor name (step 4.1 above)
- "public_key_file" must point to your public key (see below)
- "private_key_file" must point to your private key (see below)
To access the key pairs from the container, the simplest is to map the $HOME/.ssh directory to /tmp/ssh in the container (for example):
.. code-block:: bash
sudo docker run --rm -v $HOME/.ssh:/tmp/ssh berrypatch/vmtp ls -l /tmp/ssh/id_rsa
With this mapping, the key pair parameters in the config file should be set to:
.. code-block:: bash
public_key_file: /tmp/ssh/id_rsa.pub
private_key_file: /tmp/ssh/id_rsa
6. Run VMTP
-----------
Docker options used:
* --rm : remove the container instance after execution
* -it : interactive mode + use a terminal
* -v $PWD:/tmp/vmtp : map the host current directory to /tmp/vmtp in the container
* -v $HOME/.ssh:/tmp/ssh : map the host $HOME/.ssh directory to /tmp/ssh in the container
VMTP options used:
* -d : debug mode (more verbose)
* -c /tmp/vmtp/vmtp.cfg : specify the config file to use
* -r /tmp/vmtp/admin-openrc.sh : specify the RC file to use
* -p secret : specify the OpenStack password to use (replace with your own password)
* --protocol T : only do TCP throughput test (shorter time)
* --json /tmp/vmtp/test.json : save results in json format to a file
.. code-block:: bash
sudo docker run --rm -it -v $PWD:/tmp/vmtp -v $HOME/.ssh:/tmp/ssh berrypatch/vmtp vmtp -d -c /tmp/vmtp/vmtp.cfg -r /tmp/vmtp/admin-openrc.sh -p secret --protocol T --json /tmp/vmtp/test.json
This should produce an output similar to this (a complete run with the above options should take around 15 minutes but may vary based on the control plane speed of your OpenStack cloud):
.. code-block:: bash
Using http://172.29.86.28:5000/v2.0
VM public key: /tmp/ssh/id_rsa.pub
VM private key: /tmp/ssh/id_rsa
Found image Ubuntu Server 14.04 to launch VM, will continue
Using external network: ext-net
Found external router: demo-router
Created internal network: pns-internal-net
Created internal network: pns-internal-net2
Ext router associated to pns-internal-net
Ext router associated to pns-internal-net2
OpenStack agent: Open vSwitch agent
OpenStack network type: vlan
[TestServer1] Creating server VM...
[TestServer1] Starting on zone nova:compute-server-2
[TestServer1] VM status=BUILD, retrying 1 of 50...
[TestServer1] VM status=BUILD, retrying 2 of 50...
...
[TestServer1] Floating IP 10.23.220.45 created
[TestServer1] Started - associating floating IP 10.23.220.45
[TestServer1] Internal network IP: 192.168.1.3
[TestServer1] SSH IP: 10.23.220.45
[TestServer1] Setup SSH for ubuntu@10.23.220.45
[TestServer1] Installing nuttcp-7.3.2...
[TestServer1] Copying nuttcp-7.3.2 to target...
[TestServer1] Starting nuttcp-7.3.2 server...
[TestServer1]
[TestClient1] Creating client VM...
[TestClient1] Starting on zone nova:compute-server-2
[TestClient1] VM status=BUILD, retrying 1 of 50...
[TestClient1] VM status=BUILD, retrying 2 of 50...
...
[TestClient1] Floating IP 10.23.220.46 created
[TestClient1] Started - associating floating IP 10.23.220.46
[TestClient1] Internal network IP: 192.168.1.4
[TestClient1] SSH IP: 10.23.220.46
[TestClient1] Setup SSH for ubuntu@10.23.220.46
[TestClient1] Installing nuttcp-7.3.2...
[TestClient1] Copying nuttcp-7.3.2 to target...
============================================================
Flow 1: VM to VM same network fixed IP (intra-node)
[TestClient1] Measuring TCP Throughput (packet size=65536)...
[TestClient1] /tmp/nuttcp-7.3.2 -T10 -l65536 -p5001 -P5002 -fparse 192.168.1.3
[TestClient1] megabytes=20329.1875 real_seconds=10.00 rate_Mbps=17049.6212 tx_cpu=92 rx_cpu=53 retrans=0 rtt_ms=0.47
...
{ 'az_from': u'nova:compute-server-2',
'az_to': u'nova:compute-server-2',
'desc': 'VM to VM same network fixed IP (intra-node)',
'distro_id': 'Ubuntu',
'distro_version': '14.04',
'ip_from': u'192.168.1.4',
'ip_to': u'192.168.1.3',
'results': [ { 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.47,
'throughput_kbps': 17458812,
'tool': 'nuttcp-7.3.2'},
{ 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.19,
'throughput_kbps': 13832383,
'tool': 'nuttcp-7.3.2'},
{ 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.21,
'throughput_kbps': 17130867,
'tool': 'nuttcp-7.3.2'}]}
[TestClient1] Floating IP 10.23.220.46 deleted
[TestClient1] Instance deleted
[TestClient2] Creating client VM...
[TestClient2] Starting on zone nova:compute-server-2
[TestClient2] VM status=BUILD, retrying 1 of 50...
[TestClient2] VM status=BUILD, retrying 2 of 50...
...
---- Cleanup ----
[TestServer1] Terminating nuttcp-7.3.2
[TestServer1] Floating IP 10.23.220.45 deleted
[TestServer1] Instance deleted
Network pns-internal-net deleted
Network pns-internal-net2 deleted
Removed public key pns_public_key
Deleting security group
Summary of results
==================
Total Scenarios: 22
Passed Scenarios: 5 [100.00%]
Failed Scenarios: 0 [0.00%]
Skipped Scenarios: 17
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| Scenario | Scenario Name | Functional Status | Data |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| 1.1 | Same Network, Fixed IP, Intra-node, TCP | PASSED | {'tp_kbps': '16140687', 'rtt_ms': '0.29'} |
| 1.2 | Same Network, Fixed IP, Intra-node, UDP | SKIPPED | {} |
| 1.3 | Same Network, Fixed IP, Intra-node, ICMP | SKIPPED | {} |
| 2.1 | Same Network, Fixed IP, Inter-node, TCP | PASSED | {'tp_kbps': '4082749', 'rtt_ms': '0.5'} |
| 2.2 | Same Network, Fixed IP, Inter-node, UDP | SKIPPED | {} |
| 2.3 | Same Network, Fixed IP, Inter-node, ICMP | SKIPPED | {} |
| 3.1 | Different Network, Fixed IP, Intra-node, TCP | PASSED | {'tp_kbps': '2371753', 'rtt_ms': '0.386667'} |
| 3.2 | Different Network, Fixed IP, Intra-node, UDP | SKIPPED | {} |
| 3.3 | Different Network, Fixed IP, Intra-node, ICMP | SKIPPED | {} |
| 4.1 | Different Network, Fixed IP, Inter-node, TCP | PASSED | {'tp_kbps': '2036303', 'rtt_ms': '0.623333'} |
| 4.2 | Different Network, Fixed IP, Inter-node, UDP | SKIPPED | {} |
| 4.3 | Different Network, Fixed IP, Inter-node, ICMP | SKIPPED | {} |
| 5.1 | Different Network, Floating IP, Intra-node, TCP | PASSED | {'tp_kbps': '2260145', 'rtt_ms': '0.476667'} |
| 5.2 | Different Network, Floating IP, Intra-node, UDP | SKIPPED | {} |
| 5.3 | Different Network, Floating IP, Intra-node, ICMP | SKIPPED | {} |
| 6.1 | Different Network, Floating IP, Inter-node, TCP | PASSED | {'tp_kbps': '2134303', 'rtt_ms': '0.543333'} |
| 6.2 | Different Network, Floating IP, Inter-node, UDP | SKIPPED | {} |
| 6.3 | Different Network, Floating IP, Inter-node, ICMP | SKIPPED | {} |
| 7.1 | Native Throughput, TCP | SKIPPED | {} |
| 7.2 | Native Throughput, UDP | SKIPPED | {} |
| 7.3 | Native Throughput, ICMP | SKIPPED | {} |
| 8.1 | VM to Host Uploading | SKIPPED | {} |
| 8.2 | VM to Host Downloading | SKIPPED | {} |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
Saving results in json file: /tmp/vmtp/test.json...
8. Generate the results chart from the JSON result file
-------------------------------------------------------
Assuming the json result file is saved by the container run the vmtp_genchart container command from the host current directory:
.. code-block:: bash
$ sudo docker run --rm -v $PWD:/tmp/vmtp berrypatch/vmtp vmtp_genchart -c /tmp/vmtp/test.html /tmp/vmtp/test.json
Generating chart drawing code to /tmp/vmtp/test.html...
$
vmtp_genchart options:
* -c /tmp/vmtp/test.html : save the generated html file to the mapped directory
* /tmp/vmtp/test.json : the json file that contains the results of the VMTP run
The fie is available in the current directory and can be viewed with any browser:
.. code-block:: bash
$ ls -l test.html
-rw-r--r-- 1 root root 1557 Jul 4 14:10 test.html

370
doc/source/quickstart_git.rst Normal file
View File

@ -0,0 +1,370 @@
===========================================
VMTP Git Installation and Quick Start Guide
===========================================
.. _git_installation:
1. GitHub/OpenStack Repository based Installation
-------------------------------------------------
It is recommended to run VMTP inside a virtual environment (this can be skipped if installed in a dedicated VM).
Installation on Ubuntu/Debian
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
$ sudo apt-get install build-essential python-dev python-pip python-virtualenv git git-review
$ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev
$ # create a virtual environment
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ git clone git://git.openstack.org/openstack/vmtp
$ cd vmtp
$ pip install -r requirements-dev.txt
$ cd vmtp
$ python vmtp.py -h
Installation on RHEL/CentOS
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
$ sudo yum install gcc python-devel python-pip python-virtualenv git
$ sudo yum install libxml2-devel libxslt-devel libffi-devel libyaml-devel openssl-devel
$ sudo pip install git-review
$ # create a virtual environment
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ git clone git://git.openstack.org/openstack/vmtp
$ cd vmtp
$ pip install -r requirements-dev.txt
$ cd vmtp
$ python vmtp.py -h
Installation on MacOSX
^^^^^^^^^^^^^^^^^^^^^^
VMTP 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:
.. code-block:: bash
$ # Download the XCode command line tools
$ xcode-select --install
$ # Install pip
$ sudo easy_install pip
$ # Install python virtualenv
$ sudo pip install virtualenv
$ # create a virtual environment
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ git clone git://git.openstack.org/openstack/vmtp
$ cd vmtp
$ pip install -r requirements-dev.txt
$ cd vmtp
$ python vmtp.py -h
2. Key Pair
-----------
VMTP requires a key pair to use to ssh to the test VMs that it will launch in OpenStack.
You can use the current user's key pair (located in $HOME/.ssh on the host where you run the container) if they exist:
.. code-block:: bash
$ ls -l ~/.ssh/id*
-rw------- 1 localadmin localadmin 1679 Mar 9 2015 /home/localadmin/.ssh/id_rsa
-rw-r--r-- 1 localadmin localadmin 400 Mar 9 2015 /home/localadmin/.ssh/id_rsa.pub
Otherwise you need to create a key pair on your host:
.. code-block:: bash
ssh-keygen -t rsa
3. Download RC file
-------------------
VMTP requires downloading an "openrc" file from the OpenStack Dashboard (Project|Acces&Security!Api Access|Download OpenStack RC File). That RC file is required to connect to OpenStack using the OpenStack API.
This file should be passed to VMTP using the *-r* option or should be sourced prior to invoking VMTP.
In this example we assume the RC file is saved in the current directory under the name "admin-openrc.sh".
4. Preparation steps with OpenStack
-----------------------------------
In the VMTP virtual environment, you can run any OpenStack CLI command (since the virtual environment will have all standard OpenStack client packages installed along with VMTP). Source the RC file so we can execute the CLI commands:
.. code-block:: bash
source admin-openrc.sh
4.1. Verify flavor names
^^^^^^^^^^^^^^^^^^^^^^^^
We will check the flavor names available as we will have to select one flavor that VMTP should use to launch VM instances.
List the flavors (results may be different):
.. code-block:: bash
$ nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
$
4.2. Upload any Linux VM image to OpenStack
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
VMTP requires a standard Linux VM image to run its tests in OpenStack.
You can skip this step if you already have a standard Linux VM image in your OpenStack (Ubuntu, Fedora, RHEL...).
Otherwise, you can upload any Linux VM image using the glance CLI or using the Horizon dashboard.
In the example below we will upload the Ubuntu 14.04 cloud image available from the uec-images.ubuntu.com web site using the glance CLI and we will name it "Ubuntu Server 14.04".
If your OpenStack can access directly the Internet:
.. code-block:: bash
glance --os-image-api-version 1 image-create --copy-from http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu Server 14.04'
The glance command will return immediately but it will take some time for the file to get transferred. You will need to check for the status of the image before you can use it (will "queued", then "saving" then "active" if there is no issue).
If you prefer to make a local copy of the image:
.. code-block:: bash
wget http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img
Then copy it to OpenStack using the glance CLI:
.. code-block:: bash
glance --os-image-api-version 1 image-create --file /tmp/vmtp/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu 14.04'
Then list the images to verify:
.. code-block:: bash
$ glance image-list
+--------------------------------------+---------------------+
| ID | Name |
+--------------------------------------+---------------------+
| 5d7899d9-811c-483f-82b3-282a9bf143bf | cirros |
| 443ee290-b714-4bfe-9acb-b996ed6cc118 | Ubuntu 14.04 |
+--------------------------------------+---------------------+
$ glance image-show 443ee290-b714-4bfe-9acb-b996ed6cc118
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| checksum | 479a314d90cefc163fdcfb875a070cd8 |
| container_format | bare |
| created_at | 2016-07-04T17:53:20Z |
| disk_format | qcow2 |
| id | 443ee290-b714-4bfe-9acb-b996ed6cc118 |
| min_disk | 0 |
| min_ram | 0 |
| name | Ubuntu 14.04 |
| owner | 5d912149f7474804824a463464874a21 |
| protected | False |
| size | 268829184 |
| status | active |
| tags | [] |
| updated_at | 2016-07-04T18:06:38Z |
| virtual_size | None |
| visibility | private |
+------------------+--------------------------------------+
$
5. Create your VMTP config file
-------------------------------
Get a copy of the default VMTP configuration file and save it in the local directory as "vmtp.cfg":
.. code-block:: bash
cp cfg.default.yaml vmtp.cfg
Edit the vmtp.cfg file and make sure the following parameters are set properly:
- "image_name" must be the image name to use by VMTP ('Ubuntu Server 14.04' in the above example)
- "ssh_vm_username" must be a valid user name for the Linux image ("ubuntu" for Ubuntu images)
- "flavor_type" must be an appropriate flavor name (step 4.1 above)
6. Run VMTP
-----------
VMTP options used:
* -d : debug mode (more verbose)
* -c vmtp.cfg : specify the config file to use
* -r admin-openrc.sh : specify the RC file to use
* -p secret : specify the OpenStack password to use (replace with your own password)
* --protocol T : only do TCP throughput test (shorter time)
* --json test.json : save results in json format to a file
.. code-block:: bash
python vmtp.py -d -c vmtp.cfg -r admin-openrc.sh -p secret --protocol T --json test.json
This should produce an output similar to this (a complete run with the above options should take around 15 minutes but may vary based on the control plane speed of your OpenStack cloud):
.. code-block:: bash
Using http://172.29.86.28:5000/v2.0
VM public key: /home/localadmin/.ssh/id_rsa.pub
VM private key: /home/localadmin/.ssh/id_rsa
Found image Ubuntu Server 14.04 to launch VM, will continue
Using external network: ext-net
Found external router: demo-router
Created internal network: pns-internal-net
Created internal network: pns-internal-net2
Ext router associated to pns-internal-net
Ext router associated to pns-internal-net2
OpenStack agent: Open vSwitch agent
OpenStack network type: vlan
[TestServer1] Creating server VM...
[TestServer1] Starting on zone nova:compute-server-2
[TestServer1] VM status=BUILD, retrying 1 of 50...
[TestServer1] VM status=BUILD, retrying 2 of 50...
...
[TestServer1] Floating IP 10.23.220.45 created
[TestServer1] Started - associating floating IP 10.23.220.45
[TestServer1] Internal network IP: 192.168.1.3
[TestServer1] SSH IP: 10.23.220.45
[TestServer1] Setup SSH for ubuntu@10.23.220.45
[TestServer1] Installing nuttcp-7.3.2...
[TestServer1] Copying nuttcp-7.3.2 to target...
[TestServer1] Starting nuttcp-7.3.2 server...
[TestServer1]
[TestClient1] Creating client VM...
[TestClient1] Starting on zone nova:compute-server-2
[TestClient1] VM status=BUILD, retrying 1 of 50...
[TestClient1] VM status=BUILD, retrying 2 of 50...
...
[TestClient1] Floating IP 10.23.220.46 created
[TestClient1] Started - associating floating IP 10.23.220.46
[TestClient1] Internal network IP: 192.168.1.4
[TestClient1] SSH IP: 10.23.220.46
[TestClient1] Setup SSH for ubuntu@10.23.220.46
[TestClient1] Installing nuttcp-7.3.2...
[TestClient1] Copying nuttcp-7.3.2 to target...
============================================================
Flow 1: VM to VM same network fixed IP (intra-node)
[TestClient1] Measuring TCP Throughput (packet size=65536)...
[TestClient1] /tmp/nuttcp-7.3.2 -T10 -l65536 -p5001 -P5002 -fparse 192.168.1.3
[TestClient1] megabytes=20329.1875 real_seconds=10.00 rate_Mbps=17049.6212 tx_cpu=92 rx_cpu=53 retrans=0 rtt_ms=0.47
...
{ 'az_from': u'nova:compute-server-2',
'az_to': u'nova:compute-server-2',
'desc': 'VM to VM same network fixed IP (intra-node)',
'distro_id': 'Ubuntu',
'distro_version': '14.04',
'ip_from': u'192.168.1.4',
'ip_to': u'192.168.1.3',
'results': [ { 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.47,
'throughput_kbps': 17458812,
'tool': 'nuttcp-7.3.2'},
{ 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.19,
'throughput_kbps': 13832383,
'tool': 'nuttcp-7.3.2'},
{ 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.21,
'throughput_kbps': 17130867,
'tool': 'nuttcp-7.3.2'}]}
[TestClient1] Floating IP 10.23.220.46 deleted
[TestClient1] Instance deleted
[TestClient2] Creating client VM...
[TestClient2] Starting on zone nova:compute-server-2
[TestClient2] VM status=BUILD, retrying 1 of 50...
[TestClient2] VM status=BUILD, retrying 2 of 50...
...
---- Cleanup ----
[TestServer1] Terminating nuttcp-7.3.2
[TestServer1] Floating IP 10.23.220.45 deleted
[TestServer1] Instance deleted
Network pns-internal-net deleted
Network pns-internal-net2 deleted
Removed public key pns_public_key
Deleting security group
Summary of results
==================
Total Scenarios: 22
Passed Scenarios: 5 [100.00%]
Failed Scenarios: 0 [0.00%]
Skipped Scenarios: 17
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| Scenario | Scenario Name | Functional Status | Data |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| 1.1 | Same Network, Fixed IP, Intra-node, TCP | PASSED | {'tp_kbps': '16140687', 'rtt_ms': '0.29'} |
| 1.2 | Same Network, Fixed IP, Intra-node, UDP | SKIPPED | {} |
| 1.3 | Same Network, Fixed IP, Intra-node, ICMP | SKIPPED | {} |
| 2.1 | Same Network, Fixed IP, Inter-node, TCP | PASSED | {'tp_kbps': '4082749', 'rtt_ms': '0.5'} |
| 2.2 | Same Network, Fixed IP, Inter-node, UDP | SKIPPED | {} |
| 2.3 | Same Network, Fixed IP, Inter-node, ICMP | SKIPPED | {} |
| 3.1 | Different Network, Fixed IP, Intra-node, TCP | PASSED | {'tp_kbps': '2371753', 'rtt_ms': '0.386667'} |
| 3.2 | Different Network, Fixed IP, Intra-node, UDP | SKIPPED | {} |
| 3.3 | Different Network, Fixed IP, Intra-node, ICMP | SKIPPED | {} |
| 4.1 | Different Network, Fixed IP, Inter-node, TCP | PASSED | {'tp_kbps': '2036303', 'rtt_ms': '0.623333'} |
| 4.2 | Different Network, Fixed IP, Inter-node, UDP | SKIPPED | {} |
| 4.3 | Different Network, Fixed IP, Inter-node, ICMP | SKIPPED | {} |
| 5.1 | Different Network, Floating IP, Intra-node, TCP | PASSED | {'tp_kbps': '2260145', 'rtt_ms': '0.476667'} |
| 5.2 | Different Network, Floating IP, Intra-node, UDP | SKIPPED | {} |
| 5.3 | Different Network, Floating IP, Intra-node, ICMP | SKIPPED | {} |
| 6.1 | Different Network, Floating IP, Inter-node, TCP | PASSED | {'tp_kbps': '2134303', 'rtt_ms': '0.543333'} |
| 6.2 | Different Network, Floating IP, Inter-node, UDP | SKIPPED | {} |
| 6.3 | Different Network, Floating IP, Inter-node, ICMP | SKIPPED | {} |
| 7.1 | Native Throughput, TCP | SKIPPED | {} |
| 7.2 | Native Throughput, UDP | SKIPPED | {} |
| 7.3 | Native Throughput, ICMP | SKIPPED | {} |
| 8.1 | VM to Host Uploading | SKIPPED | {} |
| 8.2 | VM to Host Downloading | SKIPPED | {} |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
Saving results in json file: test.json...
8. Generate the results chart from the JSON result file
-------------------------------------------------------
Assuming the json result file is saved by the container run the vmtp_genchart container command from the host current directory:
.. code-block:: bash
$ python vmtp_genchart.py -c test.html test.json
Generating chart drawing code to /tmp/vmtp/test.html...
$
vmtp_genchart options:
* -c test.html : save the generated html file to the mapped directory
* test.json : the json file that contains the results of the VMTP run
The fie is available in the current directory and can be viewed with any browser:
.. code-block:: bash
$ ls -l test.html
-rw-r--r-- 1 root root 1557 Jul 4 14:10 test.html

360
doc/source/quickstart_pip.rst Normal file
View File

@ -0,0 +1,360 @@
============================================
VMTP PyPI Installation and Quick Start Guide
============================================
.. _pip_installation:
1. Installation
---------------
PyPI (The Python Package Index) is the most popular distribution repository for software in Python.
The latest stable version of VMTP can be installed from PyPI using pip.
Step 1
^^^^^^
Install required libraries. Run the command based on your distro.
Ubuntu/Debian based:
.. code-block:: bash
$ sudo apt-get install build-essential python-dev python-pip python-virtualenv git git-review
$ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev
RHEL/CentOS based:
.. code-block:: bash
$ sudo yum install gcc python-devel python-pip python-virtualenv git
$ sudo yum install libxml2-devel libxslt-devel libffi-devel libyaml-devel openssl-devel
MacOSX:
.. code-block:: bash
$ # Download the XCode command line tools from Apple App Store
$ xcode-select --install
$ sudo easy_install pip
$ sudo pip install virtualenv
Step 2
^^^^^^
Create a virtual environment for Python, and install VMTP:
.. code-block:: bash
$ virtualenv ./vmtpenv
$ source ./vmtpenv/bin/activate
$ pip install vmtp
$ vmtp -h
.. 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. If isolation among multiple Python projects is not needed, we could use instead::
$ sudo pip install vmtp
2. Key Pair
-----------
VMTP requires a key pair to use to ssh to the test VMs that it will launch in OpenStack.
You can use the current user's key pair (located in $HOME/.ssh on the host where you run the container) if they exist:
.. code-block:: bash
$ ls -l ~/.ssh/id*
-rw------- 1 localadmin localadmin 1679 Mar 9 2015 /home/localadmin/.ssh/id_rsa
-rw-r--r-- 1 localadmin localadmin 400 Mar 9 2015 /home/localadmin/.ssh/id_rsa.pub
Otherwise you need to create a key pair on your host:
.. code-block:: bash
ssh-keygen -t rsa
3. Download RC file
-------------------
VMTP requires downloading an "openrc" file from the OpenStack Dashboard (Project|Acces&Security!Api Access|Download OpenStack RC File). That RC file is required to connect to OpenStack using the OpenStack API.
This file should be passed to VMTP using the *-r* option or should be sourced prior to invoking VMTP.
In this example we assume the RC file is saved in the current directory under the name "admin-openrc.sh".
4. Preparation steps with OpenStack
-----------------------------------
In the VMTP virtual environment, you can run any OpenStack CLI command (since the virtual environment will have all standard OpenStack client packages installed along with VMTP). Source the RC file so we can execute the CLI commands:
.. code-block:: bash
source admin-openrc.sh
4.1. Verify flavor names
^^^^^^^^^^^^^^^^^^^^^^^^
We will check the flavor names available as we will have to select one flavor that VMTP should use to launch VM instances.
List the flavors (results may be different):
.. code-block:: bash
$ nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
$
4.2. Upload any Linux VM image to OpenStack
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
VMTP requires a standard Linux VM image to run its tests in OpenStack.
You can skip this step if you already have a standard Linux VM image in your OpenStack (Ubuntu, Fedora, RHEL...).
Otherwise, you can upload any Linux VM image using the glance CLI or using the Horizon dashboard.
In the example below we will upload the Ubuntu 14.04 cloud image available from the uec-images.ubuntu.com web site using the glance CLI and we will name it "Ubuntu Server 14.04".
If your OpenStack can access directly the Internet:
.. code-block:: bash
glance --os-image-api-version 1 image-create --copy-from http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu Server 14.04'
The glance command will return immediately but it will take some time for the file to get transferred. You will need to check for the status of the image before you can use it (will "queued", then "saving" then "active" if there is no issue).
If you prefer to make a local copy of the image:
.. code-block:: bash
wget http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img
Then copy it to OpenStack using the glance CLI:
.. code-block:: bash
glance --os-image-api-version 1 image-create --file /tmp/vmtp/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu 14.04'
Then list the images to verify:
.. code-block:: bash
$ glance image-list
+--------------------------------------+---------------------+
| ID | Name |
+--------------------------------------+---------------------+
| 5d7899d9-811c-483f-82b3-282a9bf143bf | cirros |
| 443ee290-b714-4bfe-9acb-b996ed6cc118 | Ubuntu 14.04 |
+--------------------------------------+---------------------+
$ glance image-show 443ee290-b714-4bfe-9acb-b996ed6cc118
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| checksum | 479a314d90cefc163fdcfb875a070cd8 |
| container_format | bare |
| created_at | 2016-07-04T17:53:20Z |
| disk_format | qcow2 |
| id | 443ee290-b714-4bfe-9acb-b996ed6cc118 |
| min_disk | 0 |
| min_ram | 0 |
| name | Ubuntu 14.04 |
| owner | 5d912149f7474804824a463464874a21 |
| protected | False |
| size | 268829184 |
| status | active |
| tags | [] |
| updated_at | 2016-07-04T18:06:38Z |
| virtual_size | None |
| visibility | private |
+------------------+--------------------------------------+
$
5. Create your VMTP config file
-------------------------------
Get a copy of the default VMTP configuration file and save it in the local directory:
.. code-block:: bash
vmtp -s > vmtp.cfg
Edit the vmtp.cfg file and make sure the following parameters are set properly:
- "image_name" must be the image name to use by VMTP ('Ubuntu Server 14.04' in the above example)
- "ssh_vm_username" must be a valid user name for the Linux image ("ubuntu" for Ubuntu images)
- "flavor_type" must be an appropriate flavor name (step 4.1 above)
6. Run VMTP
-----------
VMTP options used:
* -d : debug mode (more verbose)
* -c vmtp.cfg : specify the config file to use
* -r admin-openrc.sh : specify the RC file to use
* -p secret : specify the OpenStack password to use (replace with your own password)
* --protocol T : only do TCP throughput test (shorter time)
* --json test.json : save results in json format to a file
.. code-block:: bash
vmtp -d -c vmtp.cfg -r admin-openrc.sh -p secret --protocol T --json test.json
This should produce an output similar to this (a complete run with the above options should take around 15 minutes but may vary based on the control plane speed of your OpenStack cloud):
.. code-block:: bash
Using http://172.29.86.28:5000/v2.0
VM public key: /home/localadmin/.ssh/id_rsa.pub
VM private key: /home/localadmin/.ssh/id_rsa
Found image Ubuntu Server 14.04 to launch VM, will continue
Using external network: ext-net
Found external router: demo-router
Created internal network: pns-internal-net
Created internal network: pns-internal-net2
Ext router associated to pns-internal-net
Ext router associated to pns-internal-net2
OpenStack agent: Open vSwitch agent
OpenStack network type: vlan
[TestServer1] Creating server VM...
[TestServer1] Starting on zone nova:compute-server-2
[TestServer1] VM status=BUILD, retrying 1 of 50...
[TestServer1] VM status=BUILD, retrying 2 of 50...
...
[TestServer1] Floating IP 10.23.220.45 created
[TestServer1] Started - associating floating IP 10.23.220.45
[TestServer1] Internal network IP: 192.168.1.3
[TestServer1] SSH IP: 10.23.220.45
[TestServer1] Setup SSH for ubuntu@10.23.220.45
[TestServer1] Installing nuttcp-7.3.2...
[TestServer1] Copying nuttcp-7.3.2 to target...
[TestServer1] Starting nuttcp-7.3.2 server...
[TestServer1]
[TestClient1] Creating client VM...
[TestClient1] Starting on zone nova:compute-server-2
[TestClient1] VM status=BUILD, retrying 1 of 50...
[TestClient1] VM status=BUILD, retrying 2 of 50...
...
[TestClient1] Floating IP 10.23.220.46 created
[TestClient1] Started - associating floating IP 10.23.220.46
[TestClient1] Internal network IP: 192.168.1.4
[TestClient1] SSH IP: 10.23.220.46
[TestClient1] Setup SSH for ubuntu@10.23.220.46
[TestClient1] Installing nuttcp-7.3.2...
[TestClient1] Copying nuttcp-7.3.2 to target...
============================================================
Flow 1: VM to VM same network fixed IP (intra-node)
[TestClient1] Measuring TCP Throughput (packet size=65536)...
[TestClient1] /tmp/nuttcp-7.3.2 -T10 -l65536 -p5001 -P5002 -fparse 192.168.1.3
[TestClient1] megabytes=20329.1875 real_seconds=10.00 rate_Mbps=17049.6212 tx_cpu=92 rx_cpu=53 retrans=0 rtt_ms=0.47
...
{ 'az_from': u'nova:compute-server-2',
'az_to': u'nova:compute-server-2',
'desc': 'VM to VM same network fixed IP (intra-node)',
'distro_id': 'Ubuntu',
'distro_version': '14.04',
'ip_from': u'192.168.1.4',
'ip_to': u'192.168.1.3',
'results': [ { 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.47,
'throughput_kbps': 17458812,
'tool': 'nuttcp-7.3.2'},
{ 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.19,
'throughput_kbps': 13832383,
'tool': 'nuttcp-7.3.2'},
{ 'pkt_size': 65536,
'protocol': 'TCP',
'rtt_ms': 0.21,
'throughput_kbps': 17130867,
'tool': 'nuttcp-7.3.2'}]}
[TestClient1] Floating IP 10.23.220.46 deleted
[TestClient1] Instance deleted
[TestClient2] Creating client VM...
[TestClient2] Starting on zone nova:compute-server-2
[TestClient2] VM status=BUILD, retrying 1 of 50...
[TestClient2] VM status=BUILD, retrying 2 of 50...
...
---- Cleanup ----
[TestServer1] Terminating nuttcp-7.3.2
[TestServer1] Floating IP 10.23.220.45 deleted
[TestServer1] Instance deleted
Network pns-internal-net deleted
Network pns-internal-net2 deleted
Removed public key pns_public_key
Deleting security group
Summary of results
==================
Total Scenarios: 22
Passed Scenarios: 5 [100.00%]
Failed Scenarios: 0 [0.00%]
Skipped Scenarios: 17
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| Scenario | Scenario Name | Functional Status | Data |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| 1.1 | Same Network, Fixed IP, Intra-node, TCP | PASSED | {'tp_kbps': '16140687', 'rtt_ms': '0.29'} |
| 1.2 | Same Network, Fixed IP, Intra-node, UDP | SKIPPED | {} |
| 1.3 | Same Network, Fixed IP, Intra-node, ICMP | SKIPPED | {} |
| 2.1 | Same Network, Fixed IP, Inter-node, TCP | PASSED | {'tp_kbps': '4082749', 'rtt_ms': '0.5'} |
| 2.2 | Same Network, Fixed IP, Inter-node, UDP | SKIPPED | {} |
| 2.3 | Same Network, Fixed IP, Inter-node, ICMP | SKIPPED | {} |
| 3.1 | Different Network, Fixed IP, Intra-node, TCP | PASSED | {'tp_kbps': '2371753', 'rtt_ms': '0.386667'} |
| 3.2 | Different Network, Fixed IP, Intra-node, UDP | SKIPPED | {} |
| 3.3 | Different Network, Fixed IP, Intra-node, ICMP | SKIPPED | {} |
| 4.1 | Different Network, Fixed IP, Inter-node, TCP | PASSED | {'tp_kbps': '2036303', 'rtt_ms': '0.623333'} |
| 4.2 | Different Network, Fixed IP, Inter-node, UDP | SKIPPED | {} |
| 4.3 | Different Network, Fixed IP, Inter-node, ICMP | SKIPPED | {} |
| 5.1 | Different Network, Floating IP, Intra-node, TCP | PASSED | {'tp_kbps': '2260145', 'rtt_ms': '0.476667'} |
| 5.2 | Different Network, Floating IP, Intra-node, UDP | SKIPPED | {} |
| 5.3 | Different Network, Floating IP, Intra-node, ICMP | SKIPPED | {} |
| 6.1 | Different Network, Floating IP, Inter-node, TCP | PASSED | {'tp_kbps': '2134303', 'rtt_ms': '0.543333'} |
| 6.2 | Different Network, Floating IP, Inter-node, UDP | SKIPPED | {} |
| 6.3 | Different Network, Floating IP, Inter-node, ICMP | SKIPPED | {} |
| 7.1 | Native Throughput, TCP | SKIPPED | {} |
| 7.2 | Native Throughput, UDP | SKIPPED | {} |
| 7.3 | Native Throughput, ICMP | SKIPPED | {} |
| 8.1 | VM to Host Uploading | SKIPPED | {} |
| 8.2 | VM to Host Downloading | SKIPPED | {} |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
Saving results in json file: test.json...
8. Generate the results chart from the JSON result file
-------------------------------------------------------
Assuming the json result file is saved by the container run the vmtp_genchart container command from the host current directory:
.. code-block:: bash
$ vmtp_genchart -c test.html test.json
Generating chart drawing code to /tmp/vmtp/test.html...
$
vmtp_genchart options:
* -c test.html : save the generated html file to the mapped directory
* test.json : the json file that contains the results of the VMTP run
The fie is available in the current directory and can be viewed with any browser:
.. code-block:: bash
$ ls -l test.html
-rw-r--r-- 1 root root 1557 Jul 4 14:10 test.html

103
doc/source/usage.rst
View File

@ -7,24 +7,22 @@ VMTP Usage
.. code::
usage: vmtp.py [-h] [-c <config_file>] [-sc] [-r <openrc_file>]
[-m <gmond_ip>[:<port>]] [-p <password>] [-t <time>]
[--host <user>@<host_ssh_ip>[:<password>:<server-listen-if-name>]]
[--external-host <user>@<host_ssh_ip>[:password>]]
[--controller-node <user>@<host_ssh_ip>[:<password>]]
[--mongod-server <server ip>] [--json <file>]
[--tp-tool <nuttcp|iperf>]
[--availability_zone <availability_zone>] [--hypervisor [<az>:]
<hostname>] [--inter-node-only] [--same-network-only]
[--protocols <T|U|I>] [--multicast <multicast_address>]
[--bandwidth <bandwidth>]
[--tcpbuf <tcp_pkt_size1,...>] [--udpbuf <udp_pkt_size1,...>]
[--reuse_network_name <network_name>]
[--os-dataplane-network <network_name>]
[--delete-image-after-run] [--no-env]
[--vnic-type <direct|macvtap|normal>] [-d] [-v]
[--stop-on-error] [--vm-image-url <url_to_image>]
[--test-description <test_description>]
usage: vmtp [-h] [-c <config_file>] [-sc] [-r <openrc_file>]
[-m <gmond_ip>[:<port>]] [-p <password>] [-t <time>]
[--host <user>@<host_ssh_ip>[:<password>:<server-listen-if-name>]]
[--external-host <user>@<host_ssh_ip>[:password>]]
[--controller-node <user>@<host_ssh_ip>[:<password>]]
[--mongod-server <server ip>] [--json <file>]
[--tp-tool <nuttcp|iperf>]
[--availability_zone <availability_zone>] [--hypervisor [<az>:]
<hostname>] [--inter-node-only] [--same-network-only]
[--protocols <T|U|I>] [--bandwidth <bandwidth>]
[--tcpbuf <tcp_pkt_size1,...>] [--udpbuf <udp_pkt_size1,...>]
[--reuse_network_name <network_name>]
[--os-dataplane-network <network_name>] [--delete-image-after-run]
[--no-env] [--vnic-type <direct|macvtap|normal>] [-d] [-v]
[--stop-on-error] [--vm-image-url <url_to_image>]
[--test-description <test_description>]
optional arguments:
-h, --help show this help message and exit
@ -59,10 +57,7 @@ VMTP Usage
--inter-node-only only measure inter-node
--same-network-only only measure same network
--protocols <T|U|I> protocols T(TCP), U(UDP), I(ICMP) - default=TUI (all)
--multicast <multicast_address>
bind to multicast address. (implies
--protocols U, --tp-tool nuttcp)
--bandwidth <bandwidth>
--bandwidth <bandwidth>
the bandwidth limit for TCP/UDP flows in K/M/Gbps,
e.g. 128K/32M/5G. (default=no limit)
--tcpbuf <tcp_pkt_size1,...>
@ -88,7 +83,8 @@ VMTP Usage
manually)
--vm-image-url <url_to_image>
URL to a Linux image in qcow2 format that can be
downloaded from
downloaded fromor location of the image file with
prefix file://
--test-description <test_description>
The test description to be stored in JSON or MongoDB
@ -168,10 +164,10 @@ VMTP requires a Linux image available in Glance to spawn VMs. It could be upload
There is a candidate image defined in the default config already. It has been verified working, but of course it is OK to try other Linux distro as well.
VNIC Type
^^^^^^^^^
VNIC Type and SR-IOV Support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default test VMs will be created with ports that have a "normal" VNIC type. To create test VMs with ports that use PCI passthrough SRIOV, specify **--vnic_type direct**. This will assume that the host where the VM are instantiated have SRIOV capable NIC.
By default test VMs will be created with ports that have a "normal" VNIC type. To create test VMs with ports that use PCI passthrough SR-IOV, specify **--vnic_type direct**. This will assume that the host where the VM are instantiated have SR-IOV capable NIC.
An exception will be thrown if a test VM is lauched on a host that does not have SRIOV capable NIC or has not been configured to use such feature.
@ -186,40 +182,13 @@ VMTP supports to run on a provider network by supplying the provider network nam
Note that the fixed IP addresses assigned to the test VM on the provider network must be reachable from the host which VMTP application is running on.
Quick guide to run VMTP on an OpenStack Cloud
----------------------------------------------
Preparation
^^^^^^^^^^^
* Step 1)
Download the openrc file from OpenStack Dashboard, and saved it to your local file system. (In Horizon dashboard: Project|Acces&Security!Api Access|Download OpenStack RC File)
* Step 2)
Create one configuration file for your specific cloud and use the *-c* option to pass that file name to VMTP. Parameters that you are most certainly required to change are:
**image_name**: The name of the Linux image that will run the test VMs created by vmtp. It must be set to an existing image available in openstack (check the name with Horizon or using "nova image-list" from the shell). Any recent Ubuntu or CentOS/Fedora image should work -- if needed you will need to upload an image to OpenStack manually prior to running VMTP.
**ssh_vm_username**: VM SSH username to use (specific to the image)
**flavor_type**: The flavor name to use (often specific to each cloud)
* Step 3)
Upload the Linux image to the OpenStack controller node, so that OpenStack is able to spawning VMs. You will be prompted an error if the image defined in the config file is not available to use when running the tool. The image can be uploaded using either Horizon dashboard, or the command below::
python vmtp.py -r admin-openrc.sh -p admin --vm_image_url http://<url_to_the_image>
.. note:: Currently, VMTP only supports to load the image in qcow2 format.
Examples of running VMTP on an OpenStack Cloud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------------------
Examples below invoke VMTP using the python interpreter (suitable for git installation). For Docker container or pip installation, simply invoke vmtp directly (instead of "python vmtp.py").
Example 1: Typical Run
""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^
Run VMTP on an OpenStack cloud with the default configuration file, use "admin-openrc.sh" as the rc file, and "admin" as the password::
@ -241,7 +210,7 @@ This will tell VMTP to only collect ICMP and TCP measurements.
Example 2: Cloud upload/download performance measurement
""""""""""""""""""""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run VMTP on an OpenStack cloud with a specified configuration file (mycfg.yaml), and saved the result to a JSON file::
@ -252,10 +221,10 @@ If you do not have ssh password-less access to the external host (public key) yo
python vmtp.py -c mycfg.yaml -r admin-openrc.sh -p admin --external-host localadmin@172.29.87.29:secret --json res.json
Example 3: Store the OpenStack deployment details
"""""""""""""""""""""""""""""""""""""""""""""""""
Example 3: Retrieve the OpenStack deployment details
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run VMTP on an OpenStack cloud, fetch the defails of the deployment and store it to JSON file. Assume the controlloer node is on 192.168.12.34 with admin/admin::
Run VMTP on an OpenStack cloud, fetch the details of the deployment and store it to JSON file. Assume the controller node is on 192.168.12.34 with admin/admin::
python vmtp.py -r admin-openrc.sh -p admin --json res.json --controller-node root@192.168.12.34:admin
@ -271,7 +240,7 @@ Before storing info into MongoDB, some configurations are needed to change to fi
Example 4: Specify which compute nodes to spawn VMs
"""""""""""""""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run VMTP on an OpenStack cloud, spawn the test server VM on tme212, and the test client VM on tme210. Save the result, and perform the inter-node measurement only::
@ -279,7 +248,7 @@ Run VMTP on an OpenStack cloud, spawn the test server VM on tme212, and the test
Example 5: Collect native host performance data
"""""""""""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run VMTP to get native host throughput between 172.29.87.29 and 172.29.87.30 using the localadmin ssh username and run each tcp/udp test session for 120 seconds (instead of the default 10 seconds)::
@ -299,7 +268,7 @@ For example, to measure throughput between 2 hosts using the network attached to
Example 6: IPV6 throughput measurement
""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to use VMTP to measure throughput for IPv6.
@ -331,7 +300,7 @@ Generating charts from JSON results
.. code::
usage: genchart.py [-h] [-c <file>] [-b] [-p <all|tcp|udp>] [-v]
usage: vmtp_genchart.py [-h] [-c <file>] [-b] [-p <all|tcp|udp>] [-v]
<file> [<file> ...]
VMTP Chart Generator V0.0.1
@ -352,9 +321,9 @@ Examples of use:
Generate charts from the JSON results file "tb172.json", store resulting html to "tb172.html" and open that file in the browser::
python genchart.py --chart tb172.html --browser tb172.json
python vmtp_genchart.py --chart tb172.html --browser tb172.json
Same but only show UDP numbers::
python genchart.py --chart tb172.html --browser --protocol udp tb172.json
python vmtp_genchart.py --chart tb172.html --browser --protocol udp tb172.json