docs/userguide/troubleshooting.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Troubleshooting
   5 ===============
   6
   7 This section gives some guidelines about how to troubleshoot the test cases
   8 owned by Functest.
   9
  10 IMPORTANT: The steps defined below must be executed inside the Functest Docker
  11 container and after sourcing the OpenStack credentials::
  12
  13     . $creds
  14
  15 or::
  16
  17     source /home/opnfv/functest/conf/openstack.creds
  18
  19
  20
  21 VIM
  22 ---
  23
  24 vPing common
  25 ^^^^^^^^^^^^
  26 For both vPing test cases (vPing_SSH, and vPing_userdata), the first steps are
  27 similar:
  28  * Create Glance image
  29  * Create Network
  30  * Create Security Group
  31  * Create instances
  32
  33 After these actions, the test cases differ and will be explained in their section.
  34
  35 This test cases can be run inside the container as follows::
  36
  37     $repos_dir/functest/docker/run_tests.sh -t vping_ssh
  38     $repos_dir/functest/docker/run_tests.sh -t vping_userdata
  39
  40 The *run_tests.sh* script is calling internally the vPing scripts, located in
  41 *$repos_dir/functest/testcases/vPing/CI/libraries/vPing_ssh.py* or
  42 *$repos_dir/functest/testcases/vPing/CI/libraries/vPing_userdata.py* with the
  43 appropriate flags.
  44
  45 After finishing the test execution, the corresponding script will remove all
  46 created resources in OpenStack (image, instances, network and security group).
  47 When troubleshooting, it is handy sometimes to keep those resources in case the
  48 test fails and a manual testing is needed. This can be achieved by adding the flag *-n*::
  49
  50     $repos_dir/functest/docker/run_tests.sh -n -t vping_ssh
  51     $repos_dir/functest/docker/run_tests.sh -n -t vping_userdata
  52
  53
  54 Some of the common errors that can appear in this test case are::
  55
  56     vPing_ssh- ERROR - There has been a problem when creating the neutron network....
  57
  58 This means that there has been some problems with Neutron, even before creating the
  59 instances. Try to create manually a Neutron network and a Subnet to see if that works.
  60 The debug messages will also help to see when it failed (subnet and router creation).
  61 Example of Neutron commands (using 10.6.0.0/24 range for example)::
  62
  63     neutron net-create net-test
  64     neutron subnet-create --name subnet-test --allocation-pool start=10.6.0.2,end=10.6.0.100 --gateway 10.6.0.254 net-test 10.6.0.0/24
  65     neutron router-create test_router
  66     neutron router-interface-add <ROUTER_ID> test_subnet
  67     neutron router-gateway-set <ROUTER_ID> <EXT_NET_NAME>
  68
  69 Another related error can occur while creating the Security Groups for the instances::
  70
  71     vPing_ssh- ERROR - Failed to create the security group...
  72
  73 In this case, proceed to create it manually. These are some hints::
  74
  75     neutron security-group-create sg-test
  76     neutron security-group-rule-create sg-test --direction ingress --protocol icmp --remote-ip-prefix 0.0.0.0/0
  77     neutron security-group-rule-create sg-test --direction ingress --ethertype IPv4 --protocol tcp --port-range-min 80 --port-range-max 80 --remote-ip-prefix 0.0.0.0/0
  78     neutron security-group-rule-create sg-test --direction egress --ethertype IPv4 --protocol tcp --port-range-min 80 --port-range-max 80 --remote-ip-prefix 0.0.0.0/0
  79
  80 The next step is to create the instances. The image used is located in
  81 */home/opnfv/functest/data/cirros-0.3.4-x86_64-disk.img* and a glance image is created
  82 with the name *functest-vping*. If booting the instances fails (i.e. the status
  83 is not **ACTIVE**), you can check why it failed by doing::
  84
  85     nova list
  86     nova show <INSTANCE_ID>
  87
  88 It might show some messages about the booting failure. To try that manually::
  89
  90     net_id=$(neutron net-list | grep net-test | awk '{print $2}')
  91     nova boot --flavor 2 --image functest-vping --nic net-id=$net_id nova-test
  92
  93 This will spawn a VM using the network created previously manually. If you want to use
  94 the existing vPing network, just replace *net-test* by *vping-net*.
  95 In all the OPNFV tested scenarios from CI, it never has been a problem with the
  96 previous actions. Further possible problems are explained in the following sections.
  97
  98
  99 vPing_SSH
 100 ^^^^^^^^^
 101 This test case creates a floating IP on the external network and assigns it to
 102 the second instance with name *opnfv-vping-2*. The purpose of this is to establish
 103 a SSH connection to that instance to SCP a script that will ping the first insntace.
 104 This script is located in the repository under
 105 *$repos_dir/functest/testcases/vPing/CI/libraries/ping.sh* and takes an IP as
 106 a parameter. When the SCP is completed, the test will do an SSH call to that script
 107 inside the second instance. Some problems can happen here::
 108
 109     vPing_ssh- ERROR - Cannot establish connection to IP xxx.xxx.xxx.xxx. Aborting
 110
 111 If this is displayed, stop the test or wait for it to finish (if you have used the flag
 112 *-n* in *run_tests.sh* explained previously) so that the test does not clean
 113 the OpenStack resources. It means that the Container can not reach the public
 114 IP assigned to the instance *opnfv-vping-2*. There are many possible reasons, and
 115 they really depend on the chosen scenario. For most of the ODL-L3 and ONOS scenarios
 116 this has been noticed and it is a known limitation.
 117
 118 First, make sure that the instance *opnfv-vping-2* managed to get an IP from
 119 the DHCP agent. It can be checked by doing::
 120
 121     nova console-log opnfv-vping-2
 122
 123 If the message *Sending discover* and *No lease, failing* is shown, it probably
 124 means that the Neutron dhcp-agent failed to assign an IP or even that it was not
 125 responding. At this point it does not make sense to try to ping the floating IP.
 126
 127 If the instance got an IP properly, try to ping manually the VM from the container::
 128
 129     nova list
 130     <grab the public IP>
 131     ping <public IP>
 132
 133 If the ping does not return anything, try to ping from the Host where the Docker
 134 container is running. If that solves the problem, check the iptable rules because
 135 there might be some rules rejecting ICMP or TCP traffic coming/going from/to the container.
 136
 137 At this point, if the ping does not work either, try to reproduce the test
 138 manually with the steps described above in the vPing common section with the addition::
 139
 140     neutron floatingip-create <EXT_NET_NAME>
 141     nova floating-ip-associate nova-test <FLOATING_IP>
 142
 143
 144 Further troubleshooting is out of scope of this document, as it might be due to
 145 problems with the SDN controller. Contact the installer team members.
 146
 147
 148
 149 vPing_userdata
 150 ^^^^^^^^^^^^^^
 151 This test case does not create any floating IP neither establishes an SSH
 152 connection. Instead, it uses nova-metadata service when creating an instance
 153 to pass the same script as before (ping.sh) but as 1-line text. This script
 154 will be executed automatically when the second instance *opnfv-vping-2* is booted.
 155
 156 The only known problem here for this test to fail is mainly the lack of support
 157 of cloud-init (nova-metadata service). Check the console of the instance::
 158
 159     nova console-log opnfv-vping-2
 160
 161 If this text or similar is showed::
 162
 163     checking http://169.254.169.254/2009-04-04/instance-id
 164     failed 1/20: up 1.13. request failed
 165     failed 2/20: up 13.18. request failed
 166     failed 3/20: up 25.20. request failed
 167     failed 4/20: up 37.23. request failed
 168     failed 5/20: up 49.25. request failed
 169     failed 6/20: up 61.27. request failed
 170     failed 7/20: up 73.29. request failed
 171     failed 8/20: up 85.32. request failed
 172     failed 9/20: up 97.34. request failed
 173     failed 10/20: up 109.36. request failed
 174     failed 11/20: up 121.38. request failed
 175     failed 12/20: up 133.40. request failed
 176     failed 13/20: up 145.43. request failed
 177     failed 14/20: up 157.45. request failed
 178     failed 15/20: up 169.48. request failed
 179     failed 16/20: up 181.50. request failed
 180     failed 17/20: up 193.52. request failed
 181     failed 18/20: up 205.54. request failed
 182     failed 19/20: up 217.56. request failed
 183     failed 20/20: up 229.58. request failed
 184     failed to read iid from metadata. tried 20
 185
 186 it means that the instance failed to read from the metadata service. Contact
 187 the installer team members for more information.
 188
 189 Cloud-init in not supported on scenario dealing with ONOS and the tests have been
 190 excluded from CI in those scenarios.
 191
 192
 193 Tempest
 194 ^^^^^^^
 195
 196 In the upstream OpenStack CI all the Tempest test cases are supposed to pass.
 197 If some test cases fail in an OPNFV deployment, the reason is very probably one
 198 of the following::
 199
 200  +-----------------------------+------------------------------------------------+
 201  | Error                       | Details                                        |
 202  +=============================+================================================+
 203  | Resources required for test | Such resources could be e.g. an external       |
 204  | case execution are missing  | network and access to the management subnet    |
 205  |                             | (adminURL) from the Functest docker container. |
 206  +-----------------------------+------------------------------------------------+
 207  | OpenStack components or     | Check running services in the controller and   |
 208  | services are missing or not | compute nodes (e.g. with "systemctl" or        |
 209  | configured properly         | "service" commands). Configuration parameters  |
 210  |                             | can be verified from related .conf files       |
 211  |                             | located under /etc/<component> directories.    |
 212  +-----------------------------+------------------------------------------------+
 213  | Some resources required for | The tempest.conf file, automatically generated |
 214  | execution test cases are    | by Rally in Functest, does not contain all the |
 215  | missing                     | needed parameters or some parameters are not   |
 216  |                             | set properly.                                  |
 217  |                             | The tempest.conf file is located in /home/opnfv|
 218  |                             | /.rally/tempest/for-deployment-<UUID> in       |
 219  |                             | Functest container                             |
 220  |                             | Use "rally deployment list" command in order to|
 221  |                             | check UUID of current deployment.              |
 222  +-----------------------------+------------------------------------------------+
 223
 224
 225 When some Tempest test case fails, captured traceback and possibly also related
 226 REST API requests/responses are output to the console.
 227 More detailed debug information can be found from tempest.log file stored into
 228 related Rally deployment folder.
 229
 230
 231 Rally
 232 ^^^^^
 233
 234 Same error causes than for Tempest mentioned above may lead to error in Rally.
 235
 236 Controllers
 237 -----------
 238
 239 ODL
 240 ^^^
 241 2 versions are supported in Brahmaputra depending on the scenario:
 242  * Lithium
 243  * Berylium
 244
 245 The upstream test suites have not been adapted, so you may get 18 or 15 tests
 246 passed on 18 depending on your configuration. The 3 testcases are partly failed
 247 due to wrong return code.
 248
 249 ONOS
 250 ^^^^
 251
 252 TODO
 253
 254 OpenContrail
 255 ^^^^^^^^^^^^
 256
 257 Feature
 258 -------
 259
 260 vIMS
 261 ^^^^
 262 vIMS deployment may fail for several reasons, the most frequent ones are
 263 described in the following table:
 264
 265 +===================================+====================================+
 266 | Error                             |  Comments                          |
 267 +-----------------------------------+------------------------------------+
 268 | Keystone admin API  not reachable | Impossible to create vIMS user and |
 269 |                                   | tenant                             |
 270 +-----------------------------------+------------------------------------+
 271 | Impossible to retrieve admin role | Impossible to create vIMS user and |
 272 | id                                | tenant                             |
 273 +-----------------------------------+------------------------------------+
 274 | Error when uploading image from   | impossible to deploy VNF           |
 275 | OpenStack to glance               |                                    |
 276 +-----------------------------------+------------------------------------+
 277 | Cinder quota cannot be updated    | Default quotas not sufficient, they|
 278 |                                   | are adapted in the script          |
 279 +-----------------------------------+------------------------------------+
 280 | Impossible to create a volume     | VNF cannot be deployed             |
 281 +-----------------------------------+------------------------------------+
 282 | SSH connection issue between the  | if vPing test fails, vIMS test will|
 283 | Test container and the VM         | fail...                            |
 284 +-----------------------------------+------------------------------------+
 285 | No Internet access from a VM      | the VMs of the VNF must have an    |
 286 |                                   | external access to Internet        |
 287 +-----------------------------------+------------------------------------+
 288
 289
 290 Promise
 291 ^^^^^^^
 292
 293 TODO