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