diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rwxr-xr-x | docs/index.rst | 26 | ||||
| -rw-r--r-- | docs/userguide/execution.rst | 82 | ||||
| -rw-r--r-- | docs/userguide/index.rst | 14 | ||||
| -rwxr-xr-x | docs/userguide/installation.rst | 117 |
5 files changed, 241 insertions, 0 deletions
@@ -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 + + |