docs/testing/user/userguide/10-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
  88 Step 1: Plug-in configuration file preparation
  89 ++++++++++++++++++++++++++++++++++++++++++++++
  90
  91 To install a plug-in, first you need to prepare a plug-in configuration file in
  92 YAML format and store it in the "plugin" directory. The plugin configration file
  93 work as the input of yardstick "plugin" command. Below is the Storperf plug-in
  94 configuration file sample:
  95 ::
  96
  97   ---
  98   # StorPerf plugin configuration file
  99   # Used for integration StorPerf into Yardstick as a plugin
 100   schema: "yardstick:plugin:0.1"
 101   plugins:
 102     name: storperf
 103   deployment:
 104     ip: 192.168.23.2
 105     user: root
 106     password: root
 107
 108 In the plug-in configuration file, you need to specify the plug-in name and the
 109 plug-in deployment info, including node ip, node login username and password.
 110 Here the Storperf will be installed on IP 192.168.23.2 which is the Jump Host
 111 in my local environment.
 112
 113 Step 2: Plug-in install/remove scripts preparation
 114 ++++++++++++++++++++++++++++++++++++++++++++++++++
 115
 116 Under "yardstick/resource/scripts directory", there are two folders: a "install"
 117 folder and a "remove" folder. You need to store the plug-in install/remove script
 118 in these two folders respectively.
 119
 120 The detailed installation or remove operation should de defined in these two scripts.
 121 The name of both install and remove scripts should match the plugin-in name that you
 122 specified in the plug-in configuration file.
 123 For example, the install and remove scripts for Storperf are both named to "storperf.bash".
 124
 125
 126 Step 3: Install and remove Storperf
 127 +++++++++++++++++++++++++++++++++++
 128
 129 To install Storperf, simply execute the following command
 130 ::
 131
 132   # Install Storperf
 133   yardstick plugin install plugin/storperf.yaml
 134
 135 removing Storperf from yardstick
 136 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 137
 138 To remove Storperf, simply execute the following command
 139 ::
 140
 141   # Remove Storperf
 142   yardstick plugin remove plugin/storperf.yaml
 143
 144 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.