docs/testing/user/userguide/06-yardstick-plugin.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others.
   5
   6 .. Convention for heading levels in Yardstick documentation:
   7
   8    =======  Heading 0 (reserved for the title in a document)
   9    -------  Heading 1
  10    ^^^^^^^  Heading 2
  11    +++++++  Heading 3
  12    '''''''  Heading 4
  13
  14    Avoid deeper levels because they do not render well.
  15
  16 ===================================
  17 Installing a plug-in into Yardstick
  18 ===================================
  19
  20
  21 Abstract
  22 --------
  23
  24 Yardstick provides a ``plugin`` CLI command to support integration with other
  25 OPNFV testing projects. Below is an example invocation of Yardstick plugin
  26 command and Storperf plug-in sample.
  27
  28
  29 Installing Storperf into Yardstick
  30 ----------------------------------
  31
  32 Storperf is delivered as a Docker container from
  33 https://hub.docker.com/r/opnfv/storperf/tags/.
  34
  35 There are two possible methods for installation in your environment:
  36
  37 * Run container on Jump Host
  38 * Run container in a VM
  39
  40 In this introduction we will install Storperf on Jump Host.
  41
  42
  43 Step 0: Environment preparation
  44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  45
  46 Running Storperf on Jump Host
  47 Requirements:
  48
  49 * Docker must be installed
  50 * Jump Host must have access to the OpenStack Controller API
  51 * Jump Host must have internet connectivity for downloading docker image
  52 * Enough floating IPs must be available to match your agent count
  53
  54 Before installing Storperf into yardstick you need to check your openstack
  55 environment and other dependencies:
  56
  57 1. Make sure docker is installed.
  58 2. Make sure Keystone, Nova, Neutron, Glance, Heat are installed correctly.
  59 3. Make sure Jump Host have access to the OpenStack Controller API.
  60 4. Make sure Jump Host must have internet connectivity for downloading docker
  61    image.
  62 5. You need to know where to get basic openstack Keystone authorization info,
  63    such as OS_PASSWORD, OS_PROJECT_NAME, OS_AUTH_URL, OS_USERNAME.
  64 6. To run a Storperf container, you need to have OpenStack Controller
  65    environment variables defined and passed to Storperf container. The best way
  66    to do this is to put environment variables in a "storperf_admin-rc" file.
  67    The storperf_admin-rc should include credential environment variables at
  68    least:
  69
  70    * OS_AUTH_URL
  71    * OS_USERNAME
  72    * OS_PASSWORD
  73    * OS_PROJECT_NAME
  74    * OS_PROJECT_ID
  75    * OS_USER_DOMAIN_ID
  76
  77 *Yardstick* has a ``prepare_storperf_admin-rc.sh`` script which can be used to
  78 generate the ``storperf_admin-rc`` file, this script is located at
  79 ``test/ci/prepare_storperf_admin-rc.sh``
  80
  81 ::
  82
  83   #!/bin/bash
  84   # Prepare storperf_admin-rc for StorPerf.
  85   AUTH_URL=${OS_AUTH_URL}
  86   USERNAME=${OS_USERNAME:-admin}
  87   PASSWORD=${OS_PASSWORD:-console}
  88
  89   # OS_TENANT_NAME is still present to keep backward compatibility with legacy
  90   # deployments, but should be replaced by OS_PROJECT_NAME.
  91   TENANT_NAME=${OS_TENANT_NAME:-admin}
  92   PROJECT_NAME=${OS_PROJECT_NAME:-$TENANT_NAME}
  93   PROJECT_ID=`openstack project show admin|grep '\bid\b' |awk -F '|' '{print $3}'|sed -e 's/^[[:space:]]*//'`
  94   USER_DOMAIN_ID=${OS_USER_DOMAIN_ID:-default}
  95
  96   rm -f ~/storperf_admin-rc
  97   touch ~/storperf_admin-rc
  98
  99   echo "OS_AUTH_URL="$AUTH_URL >> ~/storperf_admin-rc
 100   echo "OS_USERNAME="$USERNAME >> ~/storperf_admin-rc
 101   echo "OS_PASSWORD="$PASSWORD >> ~/storperf_admin-rc
 102   echo "OS_PROJECT_NAME="$PROJECT_NAME >> ~/storperf_admin-rc
 103   echo "OS_PROJECT_ID="$PROJECT_ID >> ~/storperf_admin-rc
 104   echo "OS_USER_DOMAIN_ID="$USER_DOMAIN_ID >> ~/storperf_admin-rc
 105
 106
 107 The generated ``storperf_admin-rc`` file will be stored in the root directory.
 108 If you installed *Yardstick* using Docker, this file will be located in the
 109 container. You may need to copy it to the root directory of the Storperf
 110 deployed host.
 111
 112 Step 1: Plug-in configuration file preparation
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 To install a plug-in, first you need to prepare a plug-in configuration file in
 116 YAML format and store it in the "plugin" directory. The plugin configration
 117 file work as the input of yardstick "plugin" command. Below is the Storperf
 118 plug-in configuration file sample:
 119 ::
 120
 121   ---
 122   # StorPerf plugin configuration file
 123   # Used for integration StorPerf into Yardstick as a plugin
 124   schema: "yardstick:plugin:0.1"
 125   plugins:
 126     name: storperf
 127   deployment:
 128     ip: 192.168.23.2
 129     user: root
 130     password: root
 131
 132 In the plug-in configuration file, you need to specify the plug-in name and the
 133 plug-in deployment info, including node ip, node login username and password.
 134 Here the Storperf will be installed on IP 192.168.23.2 which is the Jump Host
 135 in my local environment.
 136
 137 Step 2: Plug-in install/remove scripts preparation
 138 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 139
 140 In ``yardstick/resource/scripts`` directory, there are two folders: an
 141 ``install`` folder and a ``remove`` folder. You need to store the plug-in
 142 install/remove scripts in these two folders respectively.
 143
 144 The detailed installation or remove operation should de defined in these two
 145 scripts. The name of both install and remove scripts should match the plugin-in
 146 name that you specified in the plug-in configuration file.
 147
 148 For example, the install and remove scripts for Storperf are both named
 149 ``storperf.bash``.
 150
 151 Step 3: Install and remove Storperf
 152 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 153
 154 To install Storperf, simply execute the following command::
 155
 156   # Install Storperf
 157   yardstick plugin install plugin/storperf.yaml
 158
 159 Removing Storperf from Yardstick
 160 ++++++++++++++++++++++++++++++++
 161
 162 To remove Storperf, simply execute the following command::
 163
 164   # Remove Storperf
 165   yardstick plugin remove plugin/storperf.yaml
 166
 167 What yardstick plugin command does is using the username and password to log
 168 into the deployment target and then execute the corresponding install or remove
 169 script.