diff options
Diffstat (limited to 'docs/testing/user/installation.rst')
| -rwxr-xr-x | docs/testing/user/installation.rst | 228 |
1 files changed, 179 insertions, 49 deletions
diff --git a/docs/testing/user/installation.rst b/docs/testing/user/installation.rst index 0effb2f..6098360 100755 --- a/docs/testing/user/installation.rst +++ b/docs/testing/user/installation.rst @@ -9,6 +9,11 @@ StorPerf Installation Guide OpenStack Prerequisites =========================== If you do not have an Ubuntu 16.04 image in Glance, you will need to add one. +You also need to create the StorPerf flavor, or choose one that closely +matches. For Ubuntu 16.04, it must have a minimum of a 4 GB disk. It should +also have about 8 GB RAM to support FIO's memory mapping of written data blocks +to ensure 100% coverage of the volume under test. + There are scripts in storperf/ci directory to assist, or you can use the follow code snippets: @@ -26,78 +31,214 @@ code snippets: --disk 4 \ --vcpus 2 +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 called admin.rc that looks similar to this for V2 authentication: + +.. code-block:: console + + cat << 'EOF' > admin.rc + 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 + EOF + +For V3 authentication, at a minimum, use the following: + +.. code-block:: console + + cat << 'EOF' > admin.rc + OS_AUTH_URL=http://10.10.243.14:5000/v3 + OS_USERNAME=admin + OS_PASSWORD=admin + OS_PROJECT_DOMAIN_NAME=Default + OS_PROJECT_NAME=admin + OS_USER_DOMAIN_NAME=Default + EOF + + +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 + 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 +StorPerf is delivered as a series of Docker containers managed by +docker-compose. There are two possible methods for installation: - -Running StorPerf on Jump Host -============================= +#. Run container on bare metal +#. Run container in a VM 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 +* Docker and docker-compose must be installed + * (note: sudo_ may be required if user is not part of docker group) +* OpenStack Controller credentials are available +* Host has access to the OpenStack Controller API +* Host must have internet connectivity for downloading docker image +* Enough OpenStack floating IPs must be available to match your agent count -Running StorPerf in a VM -======================== +.. _sudo: https://docs.docker.com/engine/reference/run/#general-form -Requirements: +Ports +===== - * 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 +The following ports are exposed if you use the supplied docker-compose.yaml +file: -VM Creation -~~~~~~~~~~~ +* 5000 for StorPerf ReST API and Swagger UI +* 8000 for StorPerf's Graphite Web Server -The following procedure will create the VM in your environment -.. code-block:: console +Running StorPerf Container +========================== + +**As of Euphrates (development) release (June 2017), StorPerf has +changed to use docker-compose in order to start its services.** - # 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}'` +Two files are needed in order +to start StorPerf: - nova boot --nic net-id=$ADMIN_NET_ID --flavor m1.small --key-name=StorPerf --image 'Ubuntu 14.04' 'StorPerf Master' +#. docker-compose.yaml +#. nginx.conf -At this point, you may associate a floating IP with the StorPerf master VM. +Copy and paste the following into a terminal to create the docker-compose.yaml -VM Docker Installation -~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: console -The following procedure will install Docker on Ubuntu 14.04. + cat << 'EOF' > docker-compose.yaml + version: '2' + services: + storperf: + container_name: "storperf" + image: "opnfv/storperf:${TAG}" + ports: + - "8000:8000" + env_file: ${ENV_FILE} + volumes: + - ${CARBON_DIR}:/opt/graphite/storage/whisper + swagger-ui: + container_name: "swagger-ui" + image: "schickling/swagger-ui" + http-front-end: + container_name: "http-front-end" + image: nginx:stable-alpine + ports: + - "5000:5000" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro + links: + - storperf + - swagger-ui + EOF + +Copy and paste the following into a terminal to create the nginx.conf .. 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 + cat << 'EOF' > nginx.conf + http { + include mime.types; + default_type application/octet-stream; + sendfile on; + keepalive_timeout 65; + proxy_send_timeout 600; + proxy_read_timeout 600; + send_timeout 600; + map $args $containsurl { + default 0; + "~(^|&)url=[^&]+($|&)" 1; + } + server { + listen 5000; + location /api/ { + proxy_pass http://storperf:5000; + proxy_set_header Host $host:$proxy_port; + } + location /swagger/ { + if ($containsurl = 0) { + return 302 $scheme://$host:$server_port$uri?url=http://$host:$server_port/api/spec.json$args; + } + proxy_pass http://swagger-ui:80/; + } + } + } + events { + worker_connections 1024; + } EOF - sudo apt-get update - sudo apt-get install -y docker-engine - sudo usermod -aG docker ubuntu +Local disk used for the Carbon DB storage as the default size of the docker +container is only 10g. Here is an example of how to create a local storage +directory and set its permissions so that StorPerf can write to it: + +.. code-block:: console + + mkdir -p ./carbon + sudo chown 33:33 ./carbon + + +The following command will start all the StorPerf services: + +.. code-block:: console + + TAG=latest ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=latest ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d + +You can now view the StorPerf SwaggerUI at: + +``http://127.0.0.1:5000/swagger`` + + +Docker Exec +~~~~~~~~~~~ + +If needed, the container can be entered with docker exec. This is not normally +required. + +.. code-block:: console + + docker exec -it storperf bash + + Pulling StorPerf Container ========================== +Master (Euphrates) +~~~~~~~~~~~~~~~~~~ + +StorPerf has switched to docker-compose in the latest version. The tag for +pulling the latest master Euphrates container is: + +.. code-block:: bash + + docker pull opnfv/storperf:master + +However, by itself, this will no longer provide full functionality. Full +instructions are provided in the Introduction document. + + Danube ~~~~~~ -The tag for the latest stable Danube will be: +The tag for the latest stable Danube is be: .. code-block:: bash - docker pull opnfv/storperf:danube.1.0 + docker pull opnfv/storperf:danube.2.0 Colorado ~~~~~~~~ @@ -116,14 +257,3 @@ The tag for the latest stable Brahmaputra release is: .. code-block:: bash docker pull opnfv/storperf:brahmaputra.1.2 - -Development -~~~~~~~~~~~ - -The tag for the latest development version is: - -.. code-block:: bash - - docker pull opnfv/storperf:master - - |