summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormbeierl <mark.beierl@emc.com>2016-09-05 08:13:28 -0400
committermbeierl <mark.beierl@emc.com>2016-09-16 16:14:05 -0400
commitcd7b2eeef24c910c14c980ac6746e1145314deba (patch)
tree34e5afb25ab340d03941f9c2cb63f471bccc1b8d
parent8e3587493d685745e08c97e25ec8b2b3a7bd3a00 (diff)
Installation Guide
Populate the installation guide Change-Id: I271ee6d5a38195aaf95a9c821bee8049470d674f JIRA: DOCS-124 Signed-off-by: mbeierl <mark.beierl@emc.com>
-rw-r--r--.gitignore2
-rwxr-xr-xdocs/index.rst26
-rw-r--r--docs/userguide/execution.rst82
-rw-r--r--docs/userguide/index.rst14
-rwxr-xr-xdocs/userguide/installation.rst117
5 files changed, 241 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
index c06ce0a..c433381 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,5 @@ coverage.xml
.settings
storperf.egg-info
*.db
+docs_build
+docs_output
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100755
index 0000000..fafa4c4
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,26 @@
+.. 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.
+
+.. OPNFV StorPerf Documentation master file.
+
+======
+StorPerf
+======
+
+
+
+* Project Wiki: https://wiki.opnfv.org/display/storperf
+* Project Repository: https://gerrit.opnfv.org/gerrit/#/q/storperf
+* Continuous Integration https://build.opnfv.org/ci/view/storperf/
+
+.. toctree::
+ :maxdepth: 3
+ :numbered: 5
+
+ ./userguide/index.rst
+
+Indices
+=======
+* :ref:`search`
+
diff --git a/docs/userguide/execution.rst b/docs/userguide/execution.rst
new file mode 100644
index 0000000..f01fe06
--- /dev/null
+++ b/docs/userguide/execution.rst
@@ -0,0 +1,82 @@
+.. 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 Test Execution Guide
+=============================
+
+Planning
+========
+
+There are some ports that the container can expose:
+
+ * 22 for SSHD. Username and password are root/storperf. This is used for CLI access only
+ * 5000 for StorPerf ReST API.
+ * 8000 for StorPerf's Graphite Web Server
+
+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:
+
+.. code-block:: console
+
+ OS_AUTH_URL=http://10.13.182.243:5000/v2.0
+ OS_TENANT_ID=e8e64985506a4a508957f931d1800aa9
+ OS_TENANT_NAME=admin
+ OS_PROJECT_NAME=admin
+ OS_USERNAME=admin
+ OS_PASSWORD=admin
+ OS_REGION_NAME=RegionOne
+
+Additionally, if you want your results published to the common OPNFV Test Results
+ DB, add the following:
+
+.. code-block:: console
+
+ TEST_DB_URL=http://testresults.opnfv.org/testapi
+
+Running StorPerf Container
+==========================
+
+You might want to have the local disk used for storage as the default size of the docker
+container is only 10g. This is done with the -v option, mounting under
+/opt/graphite/storage/whisper
+
+.. code-block:: console
+
+ 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.
+
+.. 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
+
+This will then permit ssh to localhost port 5022 for CLI access.
+
+Docker Exec
+~~~~~~~~~~~
+
+Instead of exposing port 5022 externally, you can use the exec method in docker. This
+provides a slightly more secure method of running StorPerf container without having to
+expose port 22.
+
+.. 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
+
+If needed, the container can be entered with docker exec. This is not normally required.
+
+.. code-block:: console
+
+ docker exec -it
+
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
new file mode 100644
index 0000000..dfbface
--- /dev/null
+++ b/docs/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, Intel Corporation, AT&T and others.
+
+******************************
+StorPerf User Guide
+******************************
+
+.. toctree::
+ :numbered:
+ :maxdepth: 3
+
+ installation.rst
+ execution.rst
diff --git a/docs/userguide/installation.rst b/docs/userguide/installation.rst
new file mode 100755
index 0000000..0cdd9ee
--- /dev/null
+++ b/docs/userguide/installation.rst
@@ -0,0 +1,117 @@
+.. 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 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.
+
+.. code-block:: console
+
+ # 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
+
+ # Or, if you have access to the StorPerf repository you may import the StorPerf key
+ nova keypair-add --pub_key storperf_rsa.pub StorPerf
+
+
+Planning
+===========================
+
+StorPerf is delivered as a `Docker container
+<https://hub.docker.com/r/opnfv/storperf/tags/>`__. There are two possible
+methods for installation in your environment:
+ 1. Run container on Jump Host
+ 2. Run container in a VM
+
+
+Running StorPerf on Jump Host
+=============================
+
+Requirements:
+
+ * Docker must be installed
+ * Jump Host must have access to the OpenStack Controller API
+ * Jump Host must have internet connectivity for downloading docker image
+ * Enough floating IPs must be available to match your agent count
+
+Running StorPerf in a VM
+========================
+
+Requirements:
+
+ * VM has docker installed
+ * VM has OpenStack Controller credentials and can communicate with the Controller API
+ * VM has internet connectivity for downloading the docker image
+ * Enough floating IPs must be available to match your agent count
+
+VM Creation
+~~~~~~~~~~~
+
+The following procedure will create the VM in your environment
+
+.. code-block:: console
+
+ # Create the StorPerf VM itself. Here we use the network ID generated by OPNFV FUEL.
+ ADMIN_NET_ID=`neutron net-list | grep 'admin_internal_net ' | awk '{print $2}'`
+
+ nova boot --nic net-id=$ADMIN_NET_ID --flavor m1.small --key-name=StorPerf --image 'Ubuntu 14.04' 'StorPerf Master'
+
+At this point, you may associate a floating IP with the StorPerf master VM.
+
+VM Docker Installation
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following procedure will install Docker on Ubuntu 14.04.
+
+.. code-block:: console
+
+ sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
+ cat << EOF | sudo tee /etc/apt/sources.list.d/docker.list
+ deb https://apt.dockerproject.org/repo ubuntu-trusty main
+ EOF
+
+ sudo apt-get update
+ sudo apt-get install -y docker-engine
+ sudo usermod -aG docker ubuntu
+
+Pulling StorPerf Container
+==========================
+
+Colorado
+~~~~~~~~
+
+The tag for the latest stable Colorado release is:
+
+.. code-block: console
+
+ docker pull opnfv/storperf:colorado.0.1
+
+Brahmaputra
+~~~~~~~~~~~
+
+The tag for the latest stable Brahmaputra release is:
+
+.. code-block: console
+
+ docker pull opnfv/storperf:brahmaputra.1.2
+
+Development
+~~~~~~~~~~~
+
+The tag for the latest development version is:
+
+.. code-block: console
+
+ docker pull opnfv/storperf:master
+
+