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