diff options
Diffstat (limited to 'docs/testing/user/installation.rst')
| -rwxr-xr-x | docs/testing/user/installation.rst | 176 |
1 files changed, 117 insertions, 59 deletions
diff --git a/docs/testing/user/installation.rst b/docs/testing/user/installation.rst index 046da42..7f56244 100755 --- a/docs/testing/user/installation.rst +++ b/docs/testing/user/installation.rst @@ -8,11 +8,20 @@ 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. +StorPerf can be instructed to use OpenStack APIs in order to manage a +Heat stack of virtual machines and Cinder volumes, or it can be run in +stackless mode, where it does not need to know anything about OpenStack. + +When running in OpenStack mode, there will need to be an external network +with floating IPs available to assign to the VMs, as well as a Glance image +that can be used to boot the VMs. This can be almost any Linux based +image, as long as it can either accept OpenStack metadata for injecting +the SSH key, or it has known SSH credentials as part of the base image. + +The flavor for the image should provide enough disk space for the initial +boot, along with additional space if profiling of the Glance backing is +desired. It should also provide at least 8 GB RAM to support FIO's memory +mapping of written data blocks. There are scripts in storperf/ci directory to assist, or you can use the follow code snippets: @@ -34,9 +43,10 @@ code snippets: 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: +Unless running in stackless mode, the OpenStack Controller environment +variables must be 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 @@ -78,8 +88,8 @@ Planning StorPerf is delivered as a series of Docker containers managed by docker-compose. There are two possible methods for installation: -#. Run container on bare metal -#. Run container in a VM +#. Run the containers on bare metal +#. Run the containers in a VM Requirements: @@ -89,7 +99,7 @@ Requirements: * 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 -* A local directory for holding the Carbon DB Whisper files +* Optionally, a local directory for holding the Carbon DB Whisper files 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 @@ -117,7 +127,7 @@ http://storperf:5000/graphite Running StorPerf Container ========================== -**As of Euphrates (development) release (June 2017), StorPerf has +**As of Euphrates release (June 2017), StorPerf has changed to use docker-compose in order to start its services.** Docker compose requires a local file to be created in order to define the @@ -142,12 +152,16 @@ which should result in: .. code-block:: console - 968c0c2d7c0e24f6777c33b37d9b4fd885575155069fb760405ec8214b2eb672 docker-compose.yaml + 69856e9788bec36308a25303ec9154ed68562e126788a47d54641d68ad22c8b9 docker-compose.yaml To run, you must specify two environment variables: -* ENV_FILE, which points to your OpenStack admin.rc as noted above. -* CARBON_DIR, which points to a directory that will be mounted to store the raw metrics. +* ENV_FILE, which points to your OpenStack admin.rc as noted above. If running + in stackless mode only, it is possible to remove the ENV_FILE reference from + the docker-compose.yaml file. +* CARBON_DIR, which points to a directory that will be mounted to store the + raw metrics. If desired, the CARBON_DIR can be removed from the + docker-compose.yaml file, causing metrics to be kept in the container only. * TAG, which specified the Docker tag for the build (ie: latest, danube.3.0, etc). The following command will start all the StorPerf services: @@ -175,7 +189,7 @@ which should result in: .. code-block:: console - 00649e02237d27bf0b40d1a66160a68a56c9f5e1ceb78d7858e30715cf4350e3 create-compose.py + 327cad2a7b3a3ca37910978005c743799313c2b90709e4a3f142286a06e53f57 create-compose.py Note: The script will run fine on python3. Install python future package to avoid error on python2. @@ -187,79 +201,123 @@ Note: The script will run fine on python3. Install python future package to avoi Docker Exec ~~~~~~~~~~~ -If needed, the container can be entered with docker exec. This is not normally +If needed, any StorPerf container can be entered with docker exec. This is not normally required. .. code-block:: console - docker exec -it storperf-master bash + docker exec -it storperf-master /bin/bash -Pulling StorPerf Container -========================== +Pulling StorPerf Containers +=========================== -Master (Euphrates) -~~~~~~~~~~~~~~~~~~ +The tags for StorPerf can be found here: https://hub.docker.com/r/opnfv/storperf-master/tags/ -StorPerf has switched to docker-compose in the latest version. The tag for -pulling the latest master Euphrates container is: +Master (latest) +~~~~~~~~~~~~~~~ -.. code-block:: bash +This tag represents StorPerf at its most current state of development. While +self-tests have been run, there is not a guarantee that all features will be +functional, or there may be bugs. - docker pull opnfv/storperf-master:latest - docker pull opnfv/storperf-reporting:latest - docker pull opnfv/storperf-httpfrontend:latest - docker pull opnfv/storperf-swaggerui:latest - docker pull opnfv/storperf-graphite:latest +Documentation for latest can be found using the latest label at: -However, by itself, this will no longer provide full functionality. Full -instructions are provided in the Running StorPerf Container section of this -document. +:ref:`User Guide <storperf-userguide>` +For x86_64 based systems, use: -Danube -~~~~~~ +.. code-block:: console -The tag for the latest stable Danube is be: + TAG=x86_64-latest ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=x86_64-latest ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d -.. code-block:: bash +For 64 bit ARM based systems, use: - docker pull opnfv/storperf:danube.3.0 +.. code-block:: console -Colorado -~~~~~~~~ + TAG=aarch64-latest ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=aarch64-latest ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d -The tag for the latest stable Colorado release is: -.. code-block:: bash +Release (stable) +~~~~~~~~~~~~~~~~ - docker pull opnfv/storperf:colorado.0.1 +This tag represents StorPerf at its most recent stable release. There are +no known bugs and known issues and workarounds are documented in the release +notes. Issues found here should be reported in JIRA: -Brahmaputra -~~~~~~~~~~~ +https://jira.opnfv.org/secure/RapidBoard.jspa?rapidView=3 -The tag for the latest stable Brahmaputra release is: +For x86_64 based systems, use: -.. code-block:: bash +.. code-block:: console - docker pull opnfv/storperf:brahmaputra.1.2 + TAG=x86_64-stable ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=x86_64-stable ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d -StorPerf on ARM Processors -========================== +For 64 bit ARM based systems, use: -StorPerf now supports docker images on ARM processors as well. However, at the moment -there is no upstream image on DockerHub. The user needs to manually build it. Firstly, -clone StorPerf repository from GitHub +.. code-block:: console -.. code-block:: bash + TAG=aarch64-stable ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=aarch64-stable ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d + + + +Fraser (opnfv-6.0.0) +~~~~~~~~~~~~~~~~~~ + +This tag represents the 6th OPNFV release and the 5th StorPerf release. There +are no known bugs and known issues and workarounds are documented in the release +notes. Documentation can be found under the Fraser label at: + +http://docs.opnfv.org/en/stable-fraser/submodules/storperf/docs/testing/user/index.html + +Issues found here should be reported against release 6.0.0 in JIRA: + +https://jira.opnfv.org/secure/RapidBoard.jspa?rapidView=3 + +For x86_64 based systems, use: + +.. code-block:: console + + TAG=x86_64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=x86_64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d + +For 64 bit ARM based systems, use: + +.. code-block:: console + + TAG=aarch64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=aarch64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d + + + +Euphrates (opnfv-5.0.0) +~~~~~~~~~~~~~~~~~ + +This tag represents the 5th OPNFV release and the 4th StorPerf release. There +are no known bugs and known issues and workarounds are documented in the release +notes. Documentation can be found under the Euphrates label at: + +http://docs.opnfv.org/en/stable-euphrates/submodules/storperf/docs/testing/user/index.html + +Issues found here should be reported against release 6.0.0 in JIRA: + +https://jira.opnfv.org/secure/RapidBoard.jspa?rapidView=3 + +For x86_64 based systems, use: + +.. code-block:: console - git clone https://git.opnfv.org/storperf - cd storperf/docker/ + TAG=x86_64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=x86_64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d -Next, build and setup the docker images +For 64 bit ARM based systems, use: .. code-block:: console - TAG=aarch64 ENV_FILE=./admin.rc CARBON_DIR=./carbon docker-compose -f local-docker-compose.yaml build - TAG=aarch64 ENV_FILE=./admin.rc CARBON_DIR=./carbon docker-compose -f local-docker-compose.yaml up -d + TAG=aarch64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose pull + TAG=aarch64-opnfv-6.0.0 ENV_FILE=./admin.rc CARBON_DIR=./carbon/ docker-compose up -d |