VNFs/DPPD-PROX/helper-scripts/rapid/README

   1 ##
   2 ## Copyright (c) 2010-2020 Intel Corporation
   3 ##
   4 ## Licensed under the Apache License, Version 2.0 (the "License");
   5 ## you may not use this file except in compliance with the License.
   6 ## You may obtain a copy of the License at
   7 ##
   8 ##     http://www.apache.org/licenses/LICENSE-2.0
   9 ##
  10 ## Unless required by applicable law or agreed to in writing, software
  11 ## distributed under the License is distributed on an "AS IS" BASIS,
  12 ## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 ## See the License for the specific language governing permissions and
  14 ## limitations under the License.
  15 ##
  16
  17 rapid (Rapid Automated Performance Indication for Dataplane)
  18 ************************************************************
  19
  20 rapid is a set of files offering an easy way to do a sanity check of the
  21 dataplane performance of an OpenStack or container environment.
  22
  23 Most of the information below is now available on wiki.opnfv.org/display/SAM/Rapid+scripting
  24
  25 In case of OpenStack, copy the files in a directory on a machine that can run the OpenStack CLI
  26 commands and that can reach the networks to connect to the VMs.
  27
  28 You will need an image that has the PROX tool installed.
  29 A good way to do this is to use the packer tool to build an image for a target of your choice.
  30 You can also build this image manually by executing all the commands described in the deploycentostools.sh.
  31 The default name of the qcow2 file is rapidVM.qcow2
  32
  33 When using the packer tool, the first step is to upload an
  34 existing CentOS cloud image from the internet into OpenStack.
  35 Check out: https://cloud.centos.org/centos/7/images/
  36 You should now create proper clouds.yaml file so Packer can connect to your OpenStack.
  37 Sample clouds.yaml could look like this:
  38
  39 client:
  40   force_ipv4: true
  41 clouds:
  42   overcloud:
  43     verify:    False
  44     interface: "public"
  45     auth:
  46       username:         "admin"
  47       password:         "your_password"
  48       project_name:     "admin"
  49       tenant_name:      "admin"
  50       auth_url:         "https://192.168.1.1:5000/v3"
  51       user_domain_name: "Default"
  52       domain_name:      "Default"
  53     identity_api_version: "3"
  54
  55 Packer could be run from docker image, you will need to create following alias:
  56
  57 alias packer='docker run -it --env OS_CLOUD=$OS_CLOUD -v "$PWD":/root/project -w /root/project hashicorp/packer:light $@'
  58 and make sure the OS_CLOUD variable is set to the correct cloud: in the clouds.yaml example above, you would first
  59 export OS_CLOUD=overcloud
  60
  61 There are 2 files: centos.json and deploycentostools.sh, allowing you to create
  62 an image automatically. Run
  63   # packer build centos.json
  64 Edit centos.json to reflect the settings of your environment: The following fields need to populated
  65 with the values of your system:
  66   - "source_image_name": Needs to be the name of the Centos cloud image
  67   - "flavor": Needs to be the ID or name of the flavor existing in your OpenStack environment that will be used
  68     to start the VM in which we will install all tools
  69   - "network_discovery_cidrs": Should contain the CIDR of the network you want to use e.g. "10.6.6.0/24"
  70   - "floating_ip_network": ID or name of the floating ip network in case floating ip are being used
  71   - "security_groups": ID or name of the security group being used
  72
  73 Refer to Packer docs for more details:
  74 https://www.packer.io/docs/builders/openstack.html
  75
  76 Note that this procedure is not only installing the necessary tools to run PROX,
  77 but also does some system optimizations (tuned). Check deploycentostools.sh for more details.
  78
  79 Now you need to create a stack, that will deploy the PROX VMs using the PROX
  80 image built in the previous step. The stack needs to have an ouput section
  81 with the following outputs:
  82 outputs:
  83   number_of_servers:
  84     value:
  85       - <NUMBER_OF_SERVERS>   # A list of <NUMBER_OF_SERVERS>
  86   server_name:
  87     value:
  88       - - <SERVER_NAME>       # A list containing a list of <SERVER_NAME>
  89   data_plane_ips:
  90     value:
  91       - - <DATA_PLANE_IPS>    # A list containing a list of <DATA_PLANE_IPS>
  92   data_plane_macs:
  93     value:
  94       - - <DATA_PLANE_MACS>   # A list containing a list of <DATA_PLANE_MACS>
  95   mngmt_ips:
  96     value:
  97       - - <MNGMT_IP>          # A list containing a list of <MNGMT_IP>
  98 where
  99     * <NUMBER_OF_SERVERS> is an int
 100     * <SERVER_NAME> is a string
 101     * <DATA_PLANE_IPS> is a list of strings
 102     * <DATA_PLANE_MACS> is a list of strings
 103     * <MNGMT_IP> is a string
 104
 105 createrapid.py will take the input from config_file, to create an ssh keypair
 106 and stack (if not already existing). The tool will use the yaml files as
 107 specified in the config_file and create a <STACK>.env file, containing
 108 input used for runrapid.py.
 109
 110 Now you can run the runrapid.py file. Use help for more info on the usage:
 111   # ./runrapid.py --help
 112 The script will connect to all machines that have been instantiated and it will launch
 113 PROX in all machines. This will be done through the admin IP assigned to the machines.
 114 Once that is done it will connect to the PROX tcp socket and start sending
 115 commands to run the actual test.
 116 Make sure the security groups allow for tcp access (ssh & prox port).
 117 It will print test results on the screen while running.
 118 The actual test that is running is described in <TEST>.test.
 119
 120 Notes about prox_user_data.sh script:
 121 - The script contains commands that will be executed using cloud-init at
 122   startup of the VMs.
 123 - huge pages are allocated for DPDK on node 0 (hard-coded) in the VM.
 124
 125 Note on using SRIOV ports:
 126 Before running createrapid, make sure the network, subnet and ports are already created
 127 This can be done as follows (change the parameters to your needs):
 128 openstack network create --share --external --provider-network-type flat --provider-physical-network physnet2 fast-network
 129 openstack subnet create --network  fast-network  --subnet-range 20.20.20.0/24 --gateway none fast-subnet
 130 openstack port create --network fast-network --vnic-type direct --fixed-ip subnet=fast-subnet Port1
 131 openstack port create --network fast-network --vnic-type direct --fixed-ip subnet=fast-subnet Port2
 132 openstack port create --network fast-network --vnic-type direct --fixed-ip subnet=fast-subnet Port3
 133
 134 Note when doing tests using the gateway functionality on OVS:
 135 When a GW VM is sending packets on behalf of another VM (e.g. the generator), we need to make sure the OVS
 136 will allow those packets to go through. Therefore you need to the IP address of the generator in the
 137 "allowed address pairs" of the GW VM.
 138
 139 Note when doing tests using encryption on OVS:
 140 Your OVS configuration might block encrypted packets. To allow packets to go through,
 141 you can disable port_security. You can do this by using the following commands
 142 neutron port-update xxxxxx --no-security-groups
 143 neutron port-update xxxxxx --port_security_enabled=False
 144
 145 An example of the env file generated by createrapid.py can be found below.
 146 Note that this file can be created manually in case the stack is created in a
 147 different way than what is described in this text. This can be useful in case
 148 you are not using OpenStack as a VIM or when using special configurations that
 149 cannot be achieved using createrapid.py. Fields needed for runrapid are:
 150 * all info in the [Mx] sections
 151 * the key information in the [ssh] section
 152 * the total_number_of_vms information in the [rapid] section
 153
 154 [rapid]
 155 loglevel = DEBUG
 156 version = 19.6.30
 157 total_number_of_machines = 3
 158
 159 [M1]
 160 name = rapid-VM1
 161 admin_ip = 10.25.1.109
 162 dp_ip1 = 10.10.10.4
 163 dp_mac1 = fa:16:3e:25:be:25
 164
 165 [M2]
 166 name = rapid-VM2
 167 admin_ip = 10.25.1.110
 168 dp_ip1 = 10.10.10.7
 169 dp_mac1 = fa:16:3e:72:bf:e8
 170
 171 [M3]
 172 name = rapid-VM3
 173 admin_ip = 10.25.1.125
 174 dp_ip1 = 10.10.10.15
 175 dp_mac1 = fa:16:3e:69:f3:e7
 176
 177 [ssh]
 178 key = prox.pem
 179 user = centos
 180
 181 [Varia]
 182 vim = OpenStack
 183 stack = rapid