summaryrefslogtreecommitdiffstats
path: root/docs/testing/user/installation.rst
blob: b3f0e91d9cd6825ad940d0a1986438e588661938 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) OPNFV, Dell EMC and others.

===========================
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:

.. code-block:: bash

    # Put an Ubuntu Image in glance
    wget -q https://cloud-images.ubuntu.com/releases/16.04/release/ubuntu-16.04-server-cloudimg-amd64-disk1.img
    openstack image create "Ubuntu 16.04 x86_64" --disk-format qcow2 --public \
        --container-format bare --file ubuntu-16.04-server-cloudimg-amd64-disk1.img

    # Create StorPerf flavor
    openstack flavor create storperf \
        --id auto \
        --ram 8192 \
        --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 series of Docker containers managed by
docker-compose.  There are two possible methods for installation:

#. Run the containers on bare metal
#. Run the containers in a VM

Requirements:

* 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
* 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
directory and set its permissions so that StorPerf can write to it:

.. code-block:: console

    mkdir -p ./carbon
    sudo chown 33:33 ./carbon


.. _sudo: https://docs.docker.com/engine/reference/run/#general-form

Ports
=====

The following ports are exposed if you use the supplied docker-compose.yaml
file:

* 5000 for StorPerf ReST API and Swagger UI

Note: Port 8000 is no longer exposed and graphite can be accesed via
http://storperf:5000/graphite

Running StorPerf Container
==========================

**As of Euphrates (development) 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
services that make up the full StorPerf application.  This file can be:

* Manually created
* Downloaded from the StorPerf git repo, or
* Create via a helper script from the StorPerf git repo

Manual creation involves taking the sample in the StorPerf git repo and typing
in the contents by hand on your target system.

Downloading From Git Repo
=========================

.. code-block:: console

     wget https://raw.githubusercontent.com/opnfv/storperf/master/docker-compose/docker-compose.yaml
     sha256sum docker-compose.yaml

which should result in:

.. code-block:: console

    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.
* TAG, which specified the Docker tag for the build (ie: latest, danube.3.0, etc).

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

StorPerf is now available at http://docker-host:5000/


Downloading Helper Tool
=======================

A tool to help you get started with the docker-compose.yaml can be downloaded
from:

.. code-block:: console

     wget https://raw.githubusercontent.com/opnfv/storperf/master/docker-compose/create-compose.py
     sha256sum create-compose.py

which should result in:

.. code-block:: console

     327cad2a7b3a3ca37910978005c743799313c2b90709e4a3f142286a06e53f57  create-compose.py

Note: The script will run fine on python3. Install python future package to avoid error on python2.

.. code-block:: console

     pip install future


Docker Exec
~~~~~~~~~~~

If needed, any StorPerf container can be entered with docker exec.  This is not normally
required.

.. code-block:: console

    docker exec -it storperf-master /bin/bash



Pulling StorPerf Containers
===========================

The tags for StorPerf can be found here: https://hub.docker.com/r/opnfv/storperf-master/tags/

Master (latest)
~~~~~~~~~~~~~~~

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.

Documentation for latest can be found using the latest label at:

http://docs.opnfv.org/en/latest/submodules/storperf/docs/testing/user/index.html

For x86_64 based systems, use:

.. code-block:: console

    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

For 64 bit ARM based systems, use:

.. code-block:: console

    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


Release (stable)
~~~~~~~~~~~~~~~~

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:

https://jira.opnfv.org/secure/RapidBoard.jspa?rapidView=3

For x86_64 based systems, use:

.. code-block:: console

    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

For 64 bit ARM based systems, use:

.. code-block:: console

    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

    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