docs/testing/user/userguide/03-installation.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, Intel Corporation and others.
   5
   6 SampleVNF Installation
   7 ======================
   8
   9 Abstract
  10 --------
  11 The installation procedures described below will result in the deployment of
  12 all SW components needed to run the benchmarking procedures as defined in ETSI
  13 GS NFV-TST009 on top of an NFVI instance that is the subject of this characterization.
  14 Xtesting in combination with the rapid scripts and the PROX tool will be used to achieve this.
  15
  16 The steps needed to run the benchmarking are:
  17   1) Identify a machine on which you will install the containers to support the testing
  18   2) Clone the samplevnf project on that machine
  19   3) Deploy the testing VMs (hosting PROX tool) (Or containers)
  20   4) Deploy your own Xtesting toolchain.
  21   5) Build the test container that will drive the TST009 testing
  22   6) Publish your container on your local repository
  23   7) Execute the testing
  24
  25 In this chapter, we will cover the first 6 installation steps.
  26
  27 Prerequisites
  28 -------------
  29
  30 Supported Test setup
  31 ^^^^^^^^^^^^^^^^^^^^^
  32 The device under test (DUT) is an NFVI instance on which we can deploy PROX instances.
  33 A PROX instance is a machine that
  34   * has a management interface that can be reached from the test container
  35   * has one or more data plane interfaces on a dataplane network.
  36   * can be a container, a VM or a bare metal machine. We just need to be able to ssh into the
  37     PROX machine from the test container.
  38   * is optimized for data plane traffic.
  39   * will measure the throughput that is offered through its dataplane interface(s)
  40 There are no requirements on the NFVI instance itself. Of course, the measured throughput will
  41 depend heavily on the NFVI characteristics.
  42 In this release, we are supporting an automated deployment of the PROX instance on an NFVI that
  43 provides the OpenStack Heat interface. You could also deploy the PROX instances using other
  44 mechanisms. As long as you provide the necessary files describing these instances, the execution
  45 of the test can also be done automatically (steps 4-7) and hence be executed on different DUTs,
  46 e.g. VMWare, K8s, bare metal, ...
  47
  48 Below is the basic picture of the deployment needed for the testing.
  49
  50 .. image:: images/rapid.png
  51    :width: 800px
  52    :alt: supported topology
  53
  54 Different test scenario's can now be executed by deploying the PROX machines on different systems:
  55   * The generator machine could be deployed on a well defined compute node, that has network access
  56     to the other nodes through the TOR. The generated traffic is very similar to external traffic.
  57   * The Generator and the Swap instance could be on the same compute node to test E-W traffic between
  58     2 instance on the same compute node
  59   * The Generator and the Swap instance could be on a different compute node
  60
  61 Many VMs can be deployed before the test is running: each test case can then use different pairs of
  62 PROX instances to test all the above scenarios
  63
  64 Hardware & Software Ingredients
  65 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  66
  67 The only requirement is to have the PROX instances running. There are no stringent requirements to be able
  68 to run the test. Of course, the dataplane performance will heavily depend on the underlying NFVI HW & SW
  69
  70 Installation Steps
  71 ------------------
  72
  73 Step 1: Identify a machine on which you will install the containers
  74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  75 This machine will needs enough resource to install the Xtesting framework and needs to be enabled
  76 for containers.
  77 From a network point of view, it will need to have access to the PROX instances: That means it will need
  78 to be able to ssh into these machines and that the network also needs to allow for TCP port 8474 traffic.
  79
  80 When using the automation to create the VM through the Heat Stack API, this machine also needs to be able
  81 execute the OpenStack API. Alternatively, the creation of the VMs can be executed on another machine, but
  82 this will involve some manual file copying.
  83
  84 Step 2: Clone the samplevnf project on that machine
  85 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  86
  87 .. code-block:: console
  88
  89      git clone https://git.opnfv.org/samplevnf
  90
  91 Go to the relevant directory in this repository: samplevnf/VNFs/DPPD-PROX/helper-scripts/rapid/
  92
  93 Step 3: Deploy the testing VMs
  94 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  95 In this step, we will be deploying 2 or more instances that host the PROX tool. At the end of this step,
  96 the instances will be running and an environment file (default name: rapid.env) will be created. This file
  97 will have all information needed to run the actual test. You can do this step manually on all kinds of
  98 platforms (OpenStack, VMWare, K8s, bare metal, ...), but the automation tools described in the rest of this
  99 paragraph will using OpenStack Heat yaml files.
 100 First, a PROX qcow2 image needs to be downloaded.
 101
 102 .. code-block:: console
 103
 104      wget http://artifacts.opnfv.org/samplevnf/jerma/prox_jerma.qcow2
 105
 106 This image can also be created mannualy by following instructions in https://wiki.opnfv.org/display/SAM/Rapid+scripting,
 107 in the section "Creating an image"
 108 Now upload this image to Openstack:
 109
 110 .. code-block:: console
 111
 112      openstack image` create  --disk-format qcow2 --container-format bare --file prox_jerma.qcow2 rapidVM
 113
 114 Now run createrapid.sh to create the stack. This process takes the config_file as input. Details can be found in
 115 https://wiki.opnfv.org/display/SAM/Rapid+scripting, in the section "Deploying the VMs"
 116
 117 .. code-block:: console
 118
 119      ./createrapid.sh
 120
 121 At the end of this step, VMs should be running and the rapid.env and rapid_key.pem files should be available.
 122
 123 Step 4: Deploy your own Xtesting toolchain
 124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 125 Install Xtesting as described in https://xtesting.readthedocs.io/en/latest/
 126 First goto the xtesting directory in samplevnf/VNFs/DPPD-PROX/helper-scripts/rapid/xtesting (this was cloned
 127 in step 2)
 128
 129 .. code-block:: console
 130
 131      virtualenv xtesting
 132      . xtesting/bin/activate
 133      pip install ansible
 134      ansible-galaxy install collivier.xtesting
 135      ansible-playbook site.yaml
 136      deactivate
 137      rm -r xtesting
 138
 139 Step 5: Build the test container that will drive the TST009 testing
 140 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 141 Go to the directory samplevnf/VNFs/DPPD-PROX/helper-scripts/rapid/xtesting
 142 While building this container, some files will be copied into the container image. Two of these files
 143 are generated by Step 3: rapid.env and rapid_key.pem and reside in the samplevnf/VNFs/DPPD-PROX/helper-scripts/rapid/.
 144 Please copy them into the xtesting directory.
 145 The 3rd file that will be copied is testcases.yaml. You might want to modify this file according to the testing you would
 146 like to execute.
 147
 148 .. code-block:: console
 149
 150      docker build -t 127.0.0.1:5000/rapidxt .
 151
 152 Step 6: Publish your container on your local repository
 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 154
 155 .. code-block:: console
 156
 157      docker push  127.0.0.1:5000/rapidxt
 158
 159 You are now ready to execute the testing