.. 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

Running StorPerf Container
^^^^^^^^^^^^^^^^^^^^^^^^^^

You must have your OpenStack Controller environment variables defined and passatd 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

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

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

..
    Revision: 4e5909587bcbb8dac8cc5dea19d6bf9592753678
    Build date: 2016-09-05