summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authormbeierl <mark.beierl@dell.com>2017-02-21 13:23:42 -0500
committermbeierl <mark.beierl@dell.com>2017-02-23 13:20:02 -0500
commit176b0ff44e6e5b8e3133a5b2fc652fa3850779d8 (patch)
treebd4d4f10d8a1df9ec3a7e5c84f8c89cb13fd3957 /docs
parent2994748e8112feccf870ff9db923040346dfee60 (diff)
Documentation Update
Adds documentation for Danube. Change-Id: I2755cb00b769cd0668e5c956d0b70c33d328d882 JIRA: STORPERF-81 Signed-off-by: mbeierl <mark.beierl@dell.com>
Diffstat (limited to 'docs')
-rw-r--r--[-rwxr-xr-x]docs/index.rst37
-rw-r--r--docs/release/installation/index.rst13
-rwxr-xr-xdocs/release/installation/installation.rst (renamed from docs/userguide/installation.rst)46
-rw-r--r--docs/release/userguide/index.rst14
-rw-r--r--docs/release/userguide/introduction.rst (renamed from docs/userguide/execution.rst)49
-rw-r--r--docs/release/userguide/test-usage.rst248
-rw-r--r--docs/userguide/index.rst14
7 files changed, 365 insertions, 56 deletions
diff --git a/docs/index.rst b/docs/index.rst
index fafa4c4..60e9c21 100755..100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,26 +1,43 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, Intel Corporation, AT&T and others.
+.. (c) OPNFV, Dell EMC and others.
-.. OPNFV StorPerf Documentation master file.
-
-======
+========
StorPerf
-======
-
+========
+StorPerf is an OPNFV testing project aimed to measure the performance
+of the Cinder subsystem.
* Project Wiki: https://wiki.opnfv.org/display/storperf
-* Project Repository: https://gerrit.opnfv.org/gerrit/#/q/storperf
+* Project Repository: https://git.opnfv.org/storperf
+* Project Artifacts: https://hub.docker.com/r/opnfv/storperf/
* Continuous Integration https://build.opnfv.org/ci/view/storperf/
+******************************
+StorPerf Installation Guide
+******************************
+
+.. toctree::
+ :caption: StorPerf Installation Guide
+ :maxdepth: 5
+ :numbered: 5
+
+ ./release/installation/installation.rst
+
+******************************
+StorPerf User Guide
+******************************
+
.. toctree::
- :maxdepth: 3
+ :caption: StorPerf User Guide
+ :maxdepth: 5
:numbered: 5
- ./userguide/index.rst
+ ./release/userguide/introduction.rst
+ ./release/userguide/test-usage.rst
+
Indices
=======
* :ref:`search`
-
diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst
new file mode 100644
index 0000000..78ce1a5
--- /dev/null
+++ b/docs/release/installation/index.rst
@@ -0,0 +1,13 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Dell EMC and others.
+
+======================
+StorPerf Installation Guide
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ installation.rst
diff --git a/docs/userguide/installation.rst b/docs/release/installation/installation.rst
index 0cdd9ee..ae3b3f8 100755
--- a/docs/userguide/installation.rst
+++ b/docs/release/installation/installation.rst
@@ -1,6 +1,6 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, Intel Corporation, AT&T and others.
+.. (c) OPNFV, Dell EMC and others.
===========================
StorPerf Installation Guide
@@ -8,20 +8,23 @@ StorPerf Installation Guide
OpenStack Prerequisites
===========================
-If you do not have an Ubuntu 14.04 image in Glance, you will need to add one.
-A key pair for launching agents is also required.
+If you do not have an Ubuntu 16.04 image in Glance, you will need to add one.
+There are scripts in storperf/ci directory to assist, or you can use the follow
+code snippets:
-.. code-block:: console
+.. code-block:: bash
# Put an Ubuntu Image in glance
- wget https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img
- glance image-create --name 'Ubuntu 14.04' --visibility public --disk-format=qcow2 --container-format=bare --file=trusty-server-cloudimg-amd64-disk1.img
-
- # Create a key pair for the agents.
- nova keypair-add StorPerf > StorPerf.pem
+ wget -q https://cloud-images.ubuntu.com/releases/16.04/release/ubuntu-16.04-server-cloudimg-amd64-disk1.img
+ openstack image create "Ubuntu 16.04 x86_64" --disk-format qcow2 --public \
+ --container-format bare --file ubuntu-16.04-server-cloudimg-amd64-disk1.img
- # Or, if you have access to the StorPerf repository you may import the StorPerf key
- nova keypair-add --pub_key storperf_rsa.pub StorPerf
+ # Create StorPerf flavor
+ openstack flavor create storperf \
+ --id auto \
+ --ram 8192 \
+ --disk 4 \
+ --vcpus 2
Planning
@@ -87,31 +90,40 @@ The following procedure will install Docker on Ubuntu 14.04.
Pulling StorPerf Container
==========================
+Danube
+~~~~~~
+
+The tag for the latest stable Danube will be:
+
+.. code-block:: bash
+
+ docker pull opnfv/storperf:danube.0.1
+
Colorado
~~~~~~~~
The tag for the latest stable Colorado release is:
-.. code-block: console
+.. code-block:: bash
- docker pull opnfv/storperf:colorado.0.1
+ docker pull opnfv/storperf:colorado.0.1
Brahmaputra
~~~~~~~~~~~
The tag for the latest stable Brahmaputra release is:
-.. code-block: console
+.. code-block:: bash
- docker pull opnfv/storperf:brahmaputra.1.2
+ docker pull opnfv/storperf:brahmaputra.1.2
Development
~~~~~~~~~~~
The tag for the latest development version is:
-.. code-block: console
+.. code-block:: bash
- docker pull opnfv/storperf:master
+ docker pull opnfv/storperf:master
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
new file mode 100644
index 0000000..64475e4
--- /dev/null
+++ b/docs/release/userguide/index.rst
@@ -0,0 +1,14 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Dell EMC and others.
+
+======================
+StorPerf User Guide
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction.rst
+ test-usage.rst
diff --git a/docs/userguide/execution.rst b/docs/release/userguide/introduction.rst
index f01fe06..a40750f 100644
--- a/docs/userguide/execution.rst
+++ b/docs/release/userguide/introduction.rst
@@ -1,10 +1,10 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, Intel Corporation, AT&T and others.
+.. (c) OPNFV, Dell EMC and others.
-=============================
-StorPerf Test Execution Guide
-=============================
+==================================
+StorPerf Container Execution Guide
+==================================
Planning
========
@@ -20,7 +20,7 @@ OpenStack Credentials
You must have your OpenStack Controller environment variables defined and passed to
the StorPerf container. The easiest way to do this is to put the rc file contents
-into a clean file the looks similar to this:
+into a clean file the looks similar to this for V2 authentication:
.. code-block:: console
@@ -32,6 +32,20 @@ into a clean file the looks similar to this:
OS_PASSWORD=admin
OS_REGION_NAME=RegionOne
+For V3 authentication, use the following:
+
+.. code-block:: console
+
+ OS_AUTH_URL=http://10.13.182.243:5000/v3
+ OS_PROJECT_ID=32ae78a844bc4f108b359dd7320463e5
+ OS_PROJECT_NAME=admin
+ OS_USER_DOMAIN_NAME=Default
+ OS_USERNAME=admin
+ OS_PASSWORD=admin
+ OS_REGION_NAME=RegionOne
+ OS_INTERFACE=public
+ OS_IDENTITY_API_VERSION=3
+
Additionally, if you want your results published to the common OPNFV Test Results
DB, add the following:
@@ -51,17 +65,14 @@ container is only 10g. This is done with the -v option, mounting under
mkdir -p ~/carbon
sudo chown 33:33 ~/carbon
-Container with SSH
-~~~~~~~~~~~~~~~~~~
-
-Running the StorPerf Container with all ports open and a local disk for the result
-storage. This is not recommended as the SSH port is open.
+The recommended method of running StorPerf is to expose only the ReST and Graphite
+ports. The command line below shows how to run the container with local disk for
+the carbon database.
.. code-block:: console
- docker run -t --env-file admin-rc -p 5022:22 -p 5000:5000 -p 8000:8000 -v ~/carbon:/opt/graphite/storage/whisper --name storperf opnfv/storperf
+ docker run -t --env-file admin-rc -p 5000:5000 -p 8000:8000 -v ~/carbon:/opt/graphite/storage/whisper --name storperf opnfv/storperf
-This will then permit ssh to localhost port 5022 for CLI access.
Docker Exec
~~~~~~~~~~~
@@ -70,13 +81,21 @@ Instead of exposing port 5022 externally, you can use the exec method in docker.
provides a slightly more secure method of running StorPerf container without having to
expose port 22.
+If needed, the container can be entered with docker exec. This is not normally required.
+
.. code-block:: console
- docker run -t --env-file admin-rc -p 5000:5000 -p 8000:8000 -v ~/carbon:/opt/graphite/storage/whisper --name storperf opnfv/storperf
+ docker exec -it storperf bash
-If needed, the container can be entered with docker exec. This is not normally required.
+Container with SSH
+~~~~~~~~~~~~~~~~~~
+
+Running the StorPerf Container with all ports open and a local disk for the result
+storage. This is not recommended as the SSH port is open.
.. code-block:: console
- docker exec -it
+ docker run -t --env-file admin-rc -p 5022:22 -p 5000:5000 -p 8000:8000 -v ~/carbon:/opt/graphite/storage/whisper --name storperf opnfv/storperf
+
+This will then permit ssh to localhost port 5022 for CLI access.
diff --git a/docs/release/userguide/test-usage.rst b/docs/release/userguide/test-usage.rst
new file mode 100644
index 0000000..339fb28
--- /dev/null
+++ b/docs/release/userguide/test-usage.rst
@@ -0,0 +1,248 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Dell EMC and others.
+
+=============================
+StorPerf Test Execution Guide
+=============================
+
+Prerequisites
+=============
+
+This guide requires StorPerf to be running and have its ReST API accessible. If
+the ReST API is not running on port 5000, adjust the commands provided here as
+needed.
+
+Interacting With StorPerf
+=========================
+
+Once the StorPerf container has been started and the ReST API exposed, you can
+interact directly with it using the ReST API. StorPerf comes with a Swagger
+interface that is accessible through the exposed port at:
+
+.. code-block:: console
+
+ http://StorPerf:5000/swagger/index.html
+
+The typical test execution follows this pattern:
+
+#. Configure the environment
+#. Initialize the cinder volumes
+#. Execute one or more performance runs
+#. Delete the environment
+
+Configure The Environment
+=========================
+
+The following pieces of information are required to prepare the environment:
+
+- The number of VMs/Cinder volumes to create
+- The Glance image that holds the VM operating system to use. StorPerf has
+ only been tested with Ubuntu 16.04
+- The name of the public network that agents will use
+- The size, in gigabytes, of the Cinder volumes to create
+
+The ReST API is a POST to http://StorPerf:5000/api/v1.0/configurations and
+takes a JSON payload as follows.
+
+.. code-block:: json
+
+ {
+ "agent_count": int,
+ "agent_image": string,
+ "public_network": string,
+ "volume_size": int
+ }
+
+This call will block until the stack is created, at which point it will return
+the OpenStack heat stack id.
+
+Initialize the Cinder Volumes
+=============================
+Before executing a test run for the purpose of measuring performance, it is
+necessary to fill the Cinder volume with random data. Failure to execute this
+step can result in meaningless numbers, especially for read performance. Most
+Cinder drivers are smart enough to know what blocks contain data, and which do
+not. Uninitialized blocks return "0" immediately without actually reading from
+the volume.
+
+Initiating the data fill looks the same as a regular performance test, but uses
+the special workload called "_warm_up". StorPerf will never push _warm_up
+data to the OPNFV Test Results DB, nor will it terminate the run on steady state.
+It is guaranteed to run to completion, which fills 100% of the volume with
+random data.
+
+The ReST API is a POST to http://StorPerf:5000/api/v1.0/jobs and
+takes a JSON payload as follows.
+
+.. code-block:: json
+
+ {
+ "nowarm": "false",
+ "nossd": "false",
+ "workload": "_warm_up"
+ }
+
+This will return a job ID as follows.
+
+.. code-block:: json
+
+ {
+ "job_id": "edafa97e-457e-4d3d-9db4-1d6c0fc03f98"
+ }
+
+This job ID can be used to query the state to determine when it has completed.
+See the section on querying jobs for more information.
+
+Execute a Performance Run
+=========================
+Performance runs can execute either a single workload, or iterate over a matrix
+of workload types, block sizes and queue depths.
+
+Workload Types
+~~~~~~~~~~~~~~
+rr
+ Read, Random. 100% read of random blocks
+rs
+ Read, Sequential. 100% read of sequential blocks of data
+rw
+ Read / Write Mix, Random. 70% random read, 30% random write
+wr
+ Write, Random. 100% write of random blocks
+ws
+ Write, Sequential. 100% write of sequential blocks.
+
+Block Sizes
+~~~~~~~~~~~
+A comma delimited list of the different block sizes to use when reading and
+writing data. Note: Some Cinder drivers (such as Ceph) cannot support block
+sizes larger than 16k (16384).
+
+Queue Depths
+~~~~~~~~~~~~
+A comma delimited list of the different queue depths to use when reading and
+writing data. The queue depth parameter causes FIO to keep this many I/O
+requests outstanding at one time. It is used to simulate traffic patterns
+on the system. For example, a queue depth of 4 would simulate 4 processes
+constantly creating I/O requests.
+
+Deadline
+~~~~~~~~
+The deadline is the maximum amount of time in minutes for a workload to run. If
+steady state has not been reached by the deadline, the workload will terminate
+and that particular run will be marked as not having reached steady state. Any
+remaining workloads will continue to execute in order.
+
+.. code-block:: json
+
+ {
+ "block_sizes": "2048,16384,
+ "nowarm": "false",
+ "nossd": "false",
+ "deadline": 20,
+ "queue_depths": "2,4",
+ "workload": "wr,rr,rw",
+ }
+
+Metadata
+~~~~~~~~
+A job can have metadata associated with it for tagging. The following metadata
+is required in order to push results to the OPNFV Test Results DB:
+
+.. code-block:: json
+
+ "metadata": {
+ "disk_type": "HDD or SDD",
+ "pod_name": "OPNFV Pod Name",
+ "scenario_name": string,
+ "storage_node_count": int,
+ "version": string,
+ "build_tag": string,
+ "test_case": "snia_steady_state"
+ }
+
+
+
+Query Jobs Information
+======================
+
+By issuing a GET to the job API http://StorPerf:5000/api/v1.0/jobs?job_id=<ID>,
+you can fetch information about the job as follows:
+
+- &type=status: to report on the status of the job.
+- &type=metrics: to report on the collected metrics.
+- &type=metadata: to report back any metadata sent with the job ReST API
+
+Status
+~~~~~~
+The Status field can be:
+- Running to indicate the job is still in progress, or
+- Completed to indicate the job is done. This could be either normal completion
+ or manually terminated via HTTP DELETE call.
+
+Workloads can have a value of:
+- Pending to indicate the workload has not yet started,
+- Running to indicate this is the active workload, or
+- Completed to indicate this workload has completed.
+
+This is an example of a type=status call.
+
+.. code-block:: json
+
+ {
+ "Status": "Running",
+ "TestResultURL": null,
+ "Workloads": {
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.1.block-size.16384": "Pending",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.1.block-size.4096": "Pending",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.1.block-size.512": "Pending",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.4.block-size.16384": "Running",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.4.block-size.4096": "Pending",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.4.block-size.512": "Pending",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.8.block-size.16384": "Completed",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.8.block-size.4096": "Pending",
+ "eeb2e587-5274-4d2f-ad95-5c85102d055e.ws.queue-depth.8.block-size.512": "Pending"
+ }
+ }
+
+Metrics
+~~~~~~~
+Metrics can be queried at any time during or after the completion of a run.
+Note that the metrics show up only after the first interval has passed, and
+are subject to change until the job completes.
+
+This is a sample of a type=metrics call.
+
+.. code-block:: json
+
+ {
+ "rw.queue-depth.1.block-size.512.read.bw": 52.8,
+ "rw.queue-depth.1.block-size.512.read.iops": 106.76199999999999,
+ "rw.queue-depth.1.block-size.512.read.lat.mean": 93.176,
+ "rw.queue-depth.1.block-size.512.write.bw": 22.5,
+ "rw.queue-depth.1.block-size.512.write.iops": 45.760000000000005,
+ "rw.queue-depth.1.block-size.512.write.lat.mean": 21764.184999999998
+ }
+
+Abort a Job
+===========
+Issuing an HTTP DELETE to the job api http://StorPerf:5000/api/v1.0/jobs will
+force the termination of the whole job, regardless of how many workloads
+remain to be executed.
+
+.. code-block:: bash
+
+ curl -X DELETE --header 'Accept: application/json' http://StorPerf:5000/api/v1.0/jobs
+
+Delete the Environment
+======================
+After you are done testing, you can have StorPerf delete the Heat stack by
+issuing an HTTP DELETE to the configurations API.
+
+.. code-block:: bash
+
+ curl -X DELETE --header 'Accept: application/json' http://StorPerf:5000/api/v1.0/configurations
+
+You may also want to delete an environment, and then create a new one with a
+different number of VMs/Cinder volumes to test the impact of the number of VMs
+in your environment.
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
deleted file mode 100644
index dfbface..0000000
--- a/docs/userguide/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, Intel Corporation, AT&T and others.
-
-******************************
-StorPerf User Guide
-******************************
-
-.. toctree::
- :numbered:
- :maxdepth: 3
-
- installation.rst
- execution.rst