1 .. SPDX-License-Identifier: CC-BY-4.0
6 This section gives some guidelines about how to troubleshoot the test cases
9 **IMPORTANT**: As in the previous section, the steps defined below must be
10 executed inside the Functest Docker container and after sourcing the OpenStack
17 source /home/opnfv/functest/conf/env_file
22 This section covers the test cases related to the VIM (healthcheck, vping_ssh,
23 vping_userdata, tempest_smoke_serial, tempest_full_parallel, rally_sanity,
28 For both vPing test cases (**vPing_ssh**, and **vPing_userdata**), the first
33 * Create Security Group
36 After these actions, the test cases differ and will be explained in their
39 These test cases can be run inside the container, using new Functest CLI as
42 $ functest testcase run vping_ssh
43 $ functest testcase run vping_userdata
45 The Functest CLI is designed to route a call to the corresponding internal
46 python scripts, located in paths::
48 /usr/lib/python2.7/site-packages/functest/opnfv_tests/openstack/vping/vping_ssh.py
49 /usr/lib/python2.7/site-packages/functest/opnfv_tests/openstack/vping/vping_userdata.py
53 #. There is one difference, between the Functest CLI based test case
54 execution compared to the earlier used Bash shell script, which is
55 relevant to point out in troubleshooting scenarios:
57 The Functest CLI does **not yet** support the option to suppress
58 clean-up of the generated OpenStack resources, following the execution
61 Explanation: After finishing the test execution, the corresponding
62 script will remove, by default, all created resources in OpenStack
63 (image, instances, network and security group). When troubleshooting,
64 it is advisable sometimes to keep those resources in case the test
65 fails and a manual testing is needed.
67 It is actually still possible to invoke test execution, with suppression
68 of OpenStack resource cleanup, however this requires invocation of a
69 **specific Python script:** 'run_tests'.
70 The `OPNFV Functest Developer Guide`_ provides guidance on the use of that
71 Python script in such troubleshooting cases.
73 Some of the common errors that can appear in this test case are::
75 vPing_ssh- ERROR - There has been a problem when creating the neutron network....
77 This means that there has been some problems with Neutron, even before creating
78 the instances. Try to create manually a Neutron network and a Subnet to see if
79 that works. The debug messages will also help to see when it failed (subnet and
80 router creation). Example of Neutron commands (using 10.6.0.0/24 range for
83 neutron net-create net-test
84 neutron subnet-create --name subnet-test --allocation-pool start=10.6.0.2,end=10.6.0.100 \
85 --gateway 10.6.0.254 net-test 10.6.0.0/24
86 neutron router-create test_router
87 neutron router-interface-add <ROUTER_ID> test_subnet
88 neutron router-gateway-set <ROUTER_ID> <EXT_NET_NAME>
90 Another related error can occur while creating the Security Groups for the
93 vPing_ssh- ERROR - Failed to create the security group...
95 In this case, proceed to create it manually. These are some hints::
97 neutron security-group-create sg-test
98 neutron security-group-rule-create sg-test --direction ingress --protocol icmp \
99 --remote-ip-prefix 0.0.0.0/0
100 neutron security-group-rule-create sg-test --direction ingress --ethertype IPv4 \
101 --protocol tcp --port-range-min 80 --port-range-max 80 --remote-ip-prefix 0.0.0.0/0
102 neutron security-group-rule-create sg-test --direction egress --ethertype IPv4 \
103 --protocol tcp --port-range-min 80 --port-range-max 80 --remote-ip-prefix 0.0.0.0/0
105 The next step is to create the instances. The image used is located in
106 */home/opnfv/functest/data/cirros-0.4.0-x86_64-disk.img* and a Glance image is
107 created with the name **functest-vping**. If booting the instances fails (i.e.
108 the status is not **ACTIVE**), you can check why it failed by doing::
111 nova show <INSTANCE_ID>
113 It might show some messages about the booting failure. To try that manually::
115 nova boot --flavor m1.small --image functest-vping --nic net-id=<NET_ID> nova-test
117 This will spawn a VM using the network created previously manually.
118 In all the OPNFV tested scenarios from CI, it never has been a problem with the
119 previous actions. Further possible problems are explained in the following
125 This test case creates a floating IP on the external network and assigns it to
126 the second instance **opnfv-vping-2**. The purpose of this is to establish
127 a SSH connection to that instance and SCP a script that will ping the first
128 instance. This script is located in the repository under
129 /usr/lib/python2.7/site-packages/functest/opnfv_tests/openstack/vping/ping.sh
130 and takes an IP as a parameter. When the SCP is completed, the test will do a
131 SSH call to that script inside the second instance. Some problems can happen
134 vPing_ssh- ERROR - Cannot establish connection to IP xxx.xxx.xxx.xxx. Aborting
136 If this is displayed, stop the test or wait for it to finish, if you have used
137 the special method of test invocation with specific supression of OpenStack
138 resource clean-up, as explained earler. It means that the Container can not
139 reach the Public/External IP assigned to the instance **opnfv-vping-2**. There
140 are many possible reasons, and they really depend on the chosen scenario. For
141 most of the ODL-L3 and ONOS scenarios this has been noticed and it is a known
144 First, make sure that the instance **opnfv-vping-2** succeeded to get an IP
145 from the DHCP agent. It can be checked by doing::
147 nova console-log opnfv-vping-2
149 If the message *Sending discover* and *No lease, failing* is shown, it probably
150 means that the Neutron dhcp-agent failed to assign an IP or even that it was
151 not responding. At this point it does not make sense to try to ping the
154 If the instance got an IP properly, try to ping manually the VM from the
161 If the ping does not return anything, try to ping from the Host where the
162 Docker container is running. If that solves the problem, check the iptable
163 rules because there might be some rules rejecting ICMP or TCP traffic
164 coming/going from/to the container.
166 At this point, if the ping does not work either, try to reproduce the test
167 manually with the steps described above in the vPing common section with the
170 neutron floatingip-create <EXT_NET_NAME>
171 nova floating-ip-associate nova-test <FLOATING_IP>
174 Further troubleshooting is out of scope of this document, as it might be due to
175 problems with the SDN controller. Contact the installer team members or send an
176 email to the corresponding OPNFV mailing list for more information.
182 This test case does not create any floating IP neither establishes an SSH
183 connection. Instead, it uses nova-metadata service when creating an instance
184 to pass the same script as before (ping.sh) but as 1-line text. This script
185 will be executed automatically when the second instance **opnfv-vping-2** is
188 The only known problem here for this test to fail is mainly the lack of support
189 of cloud-init (nova-metadata service). Check the console of the instance::
191 nova console-log opnfv-vping-2
193 If this text or similar is shown::
195 checking http://169.254.169.254/2009-04-04/instance-id
196 failed 1/20: up 1.13. request failed
197 failed 2/20: up 13.18. request failed
198 failed 3/20: up 25.20. request failed
199 failed 4/20: up 37.23. request failed
200 failed 5/20: up 49.25. request failed
201 failed 6/20: up 61.27. request failed
202 failed 7/20: up 73.29. request failed
203 failed 8/20: up 85.32. request failed
204 failed 9/20: up 97.34. request failed
205 failed 10/20: up 109.36. request failed
206 failed 11/20: up 121.38. request failed
207 failed 12/20: up 133.40. request failed
208 failed 13/20: up 145.43. request failed
209 failed 14/20: up 157.45. request failed
210 failed 15/20: up 169.48. request failed
211 failed 16/20: up 181.50. request failed
212 failed 17/20: up 193.52. request failed
213 failed 18/20: up 205.54. request failed
214 failed 19/20: up 217.56. request failed
215 failed 20/20: up 229.58. request failed
216 failed to read iid from metadata. tried 20
218 it means that the instance failed to read from the metadata service. Contact
219 the Functest or installer teams for more information.
225 In the upstream OpenStack CI all the Tempest test cases are supposed to pass.
226 If some test cases fail in an OPNFV deployment, the reason is very probably one
229 +----------------------------+------------------------------------------------+
231 +============================+================================================+
232 | Resources required for | Such resources could be e.g. an external |
233 | testcase execution are | network and access to the management subnet |
234 | missing | (adminURL) from the Functest docker container. |
235 +----------------------------+------------------------------------------------+
236 | OpenStack components or | Check running services in the controller and |
237 | services are missing or | compute nodes (e.g. with "systemctl" or |
238 | not configured properly | "service" commands). |
239 | | Configuration parameters can be verified from |
240 | | the related .conf files located under |
241 | | '/etc/<component>' directories. |
242 +----------------------------+------------------------------------------------+
243 | Some resources required | The tempest.conf file, automatically generated |
244 | for execution test cases | by Rally in Functest, does not contain all the |
245 | are missing | needed parameters or some parameters are not |
247 | | The tempest.conf file is located in directory |
248 | | 'root/.rally/verification/verifier-<UUID> |
249 | | /for-deployment-<UUID>' |
250 | | in the Functest Docker container. Use the |
251 | | "rally deployment list" command in order to |
252 | | check the UUID of the current deployment. |
253 +----------------------------+------------------------------------------------+
256 When some Tempest test case fails, captured traceback and possibly also the
257 related REST API requests/responses are output to the console. More detailed
258 debug information can be found from tempest.log file stored into related Rally
261 Functest offers a possibility to test a customized list of Tempest test cases.
262 To enable that, add a new entry in docker/components/testcases.yaml on the
263 "components" container with the following content::
266 case_name: tempest_custom
267 project_name: functest
271 The test case allows running a customized list of tempest
277 module: 'functest.opnfv_tests.openstack.tempest.tempest'
278 class: 'TempestCustom'
280 Also, a list of the Tempest test cases must be provided to the container or
281 modify the existing one in
282 /usr/lib/python2.7/site-packages/functest/opnfv_tests/openstack/tempest/custom_tests/test_list.txt
284 Example of custom list of tests 'my-custom-tempest-tests.txt'::
286 tempest.scenario.test_server_basic_ops.TestServerBasicOps.test_server_basic_ops[compute,id-7fff3fb3-91d8-4fd0-bd7d-0204f1f180ba,network,smoke]
287 tempest.scenario.test_network_basic_ops.TestNetworkBasicOps.test_network_basic_ops[compute,id-f323b3ba-82f8-4db7-8ea6-6a895869ec49,network,smoke]
289 This is an example of running a customized list of Tempest tests in Functest::
291 sudo docker run --env-file env \
292 -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
293 -v $(pwd)/images:/home/opnfv/functest/images \
294 -v $(pwd)/my-custom-testcases.yaml:/usr/lib/python2.7/site-packages/functest/ci/testcases.yaml \
295 -v $(pwd)/my-custom-tempest-tests.txt:/usr/lib/python2.7/site-packages/functest/opnfv_tests/openstack/tempest/custom_tests/test_list.txt \
296 opnfv/functest-components run_tests -t tempest_custom
302 The same error causes which were mentioned above for Tempest test cases, may
303 also lead to errors in Rally as well.
305 Possible scenarios are:
317 To know more about what those scenarios are doing, they are defined in
319 /usr/lib/python2.7/site-packages/functest/opnfv_tests/openstack/rally/scenario
320 For more info about Rally scenario definition please refer to the Rally
321 official documentation. `[3]`_
323 To check any possible problems with Rally, the logs are stored under
324 */home/opnfv/functest/results/rally/* in the Functest Docker container.
326 .. _`[3]`: https://rally.readthedocs.org/en/latest/index.html
334 If the Basic Restconf test suite fails, check that the ODL controller is
335 reachable and its Restconf module has been installed.
337 If the Neutron Reachability test fails, verify that the modules
338 implementing Neutron requirements have been properly installed.
340 If any of the other test cases fails, check that Neutron and ODL have
341 been correctly configured to work together. Check Neutron configuration
342 files, accounts, IP addresses etc.).
348 Please refer to the dedicated feature user guides for details.
356 vIMS deployment may fail for several reasons, the most frequent ones are
357 described in the following table:
359 +-----------------------------------+------------------------------------+
361 +===================================+====================================+
362 | Keystone admin API not reachable | Impossible to create vIMS user and |
364 +-----------------------------------+------------------------------------+
365 | Impossible to retrieve admin role | Impossible to create vIMS user and |
367 +-----------------------------------+------------------------------------+
368 | Error when uploading image from | impossible to deploy VNF |
369 | OpenStack to glance | |
370 +-----------------------------------+------------------------------------+
371 | Cinder quota cannot be updated | Default quotas not sufficient, they|
372 | | are adapted in the script |
373 +-----------------------------------+------------------------------------+
374 | Impossible to create a volume | VNF cannot be deployed |
375 +-----------------------------------+------------------------------------+
376 | SSH connection issue between the | if vPing test fails, vIMS test will|
377 | Test Docker container and the VM | fail... |
378 +-----------------------------------+------------------------------------+
379 | No Internet access from the VM | the VMs of the VNF must have an |
380 | | external access to Internet |
381 +-----------------------------------+------------------------------------+
382 | No access to OpenStack API from | Orchestrator can be installed but |
383 | the VM | the vIMS VNF installation fails |
384 +-----------------------------------+------------------------------------+
386 Please note that this test case requires resources (8 VM (2Go) + 1 VM (4Go)),
387 it is there fore not recommended to run it on a light configuration.
389 .. _`OPNFV Functest Developer Guide`: http://artifacts.opnfv.org/functest/docs/testing_developer_devguide/index.html#