docs/testing/user/configguide/configguide.rst

   1 .. SPDX-License-Identifier: CC-BY-4.0
   2
   3 Installation and configuration
   4 ==============================
   5
   6 Alpine containers have been introduced in Euphrates.
   7 Alpine allows Functest testing in several very light containers and thanks to
   8 the refactoring on dependency management should allow the creation of light and
   9 fully customized docker images.
  10
  11
  12 Functest Dockers for OpenStack deployment
  13 -----------------------------------------
  14 Docker images are available on the dockerhub:
  15
  16   * opnfv/functest-healthcheck
  17   * opnfv/functest-smoke
  18   * opnfv/functest-smoke-cntt
  19   * opnfv/functest-benchmarking
  20   * opnfv/functest-benchmarking-cntt
  21   * opnfv/functest-vnf
  22
  23
  24 Preparing your environment
  25 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  26
  27 cat env::
  28
  29   DEPLOY_SCENARIO=XXX  # if not os-nosdn-nofeature-noha scenario
  30   NAMESERVER=XXX  # if not 8.8.8.8
  31   EXTERNAL_NETWORK=XXX # if not first network with router:external=True
  32   DASHBOARD_URL=XXX  # else tempest_horizon will be skipped
  33   NEW_USER_ROLE=XXX # if not member
  34   SDN_CONTROLLER_IP=XXX  # if odl scenario
  35   VOLUME_DEVICE_NAME=XXX  # if not vdb
  36   FLAVOR_EXTRA_SPECS=hw:mem_page_size:large    # if fdio scenarios
  37
  38 See section on environment variables for details.
  39
  40 cat env_file::
  41
  42   export OS_AUTH_URL=XXX
  43   export OS_USER_DOMAIN_NAME=XXX
  44   export OS_PROJECT_DOMAIN_NAME=XXX
  45   export OS_USERNAME=XXX
  46   export OS_PROJECT_NAME=XXX
  47   export OS_PASSWORD=XXX
  48   export OS_IDENTITY_API_VERSION=3
  49   export OS_REGION_NAME=XXX
  50
  51 See section on OpenStack credentials for details.
  52
  53 Create a directory for the different images (attached as a Docker volume)::
  54
  55   mkdir -p images && wget -q -O- https://git.opnfv.org/functest/plain/functest/ci/download_images.sh | sh -s -- images && ls -1 images/*
  56
  57   images/cirros-0.5.1-aarch64-disk.img
  58   images/cirros-0.5.1-x86_64-disk.img
  59   images/cloudify-docker-manager-community-19.01.24.tar
  60   images/Fedora-Cloud-Base-30-1.2.x86_64.qcow2
  61   images/shaker-image-1.3.0+stretch.qcow2
  62   images/ubuntu-14.04-server-cloudimg-amd64-disk1.img
  63   images/ubuntu-14.04-server-cloudimg-arm64-uefi1.img
  64   images/ubuntu-16.04-server-cloudimg-amd64-disk1.img
  65   images/vyos-1.1.8-amd64.qcow2
  66
  67 Testing healthcheck suite
  68 ^^^^^^^^^^^^^^^^^^^^^^^^^
  69
  70 Run healthcheck suite::
  71
  72   sudo docker run --env-file env \
  73       -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
  74       -v $(pwd)/images:/home/opnfv/functest/images \
  75       opnfv/functest-healthcheck
  76
  77 Results shall be displayed as follows::
  78
  79   +--------------------------+------------------+---------------------+------------------+----------------+
  80   |        TEST CASE         |     PROJECT      |         TIER        |     DURATION     |     RESULT     |
  81   +--------------------------+------------------+---------------------+------------------+----------------+
  82   |     connection_check     |     functest     |     healthcheck     |      00:03       |      PASS      |
  83   |      tenantnetwork1      |     functest     |     healthcheck     |      00:05       |      PASS      |
  84   |      tenantnetwork2      |     functest     |     healthcheck     |      00:06       |      PASS      |
  85   |         vmready1         |     functest     |     healthcheck     |      00:06       |      PASS      |
  86   |         vmready2         |     functest     |     healthcheck     |      00:08       |      PASS      |
  87   |        singlevm1         |     functest     |     healthcheck     |      00:32       |      PASS      |
  88   |        singlevm2         |     functest     |     healthcheck     |      00:37       |      PASS      |
  89   |        vping_ssh         |     functest     |     healthcheck     |      00:46       |      PASS      |
  90   |      vping_userdata      |     functest     |     healthcheck     |      00:39       |      PASS      |
  91   |       cinder_test        |     functest     |     healthcheck     |      01:05       |      PASS      |
  92   |      tempest_smoke       |     functest     |     healthcheck     |      05:39       |      PASS      |
  93   |     tempest_horizon      |     functest     |     healthcheck     |      01:05       |      PASS      |
  94   |           odl            |     functest     |     healthcheck     |      00:00       |      SKIP      |
  95   +--------------------------+------------------+---------------------+------------------+----------------+
  96
  97 NOTE: the duration is a reference and it might vary depending on your SUT.
  98
  99 Testing smoke suite
 100 ^^^^^^^^^^^^^^^^^^^
 101
 102 Run smoke suite::
 103
 104   sudo docker run --env-file env \
 105       -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
 106       -v $(pwd)/images:/home/opnfv/functest/images \
 107       opnfv/functest-smoke
 108
 109 Results shall be displayed as follows::
 110
 111   +---------------------------+------------------+---------------+------------------+----------------+
 112   |         TEST CASE         |     PROJECT      |      TIER     |     DURATION     |     RESULT     |
 113   +---------------------------+------------------+---------------+------------------+----------------+
 114   |      tempest_neutron      |     functest     |     smoke     |      15:30       |      PASS      |
 115   |       tempest_cinder      |     functest     |     smoke     |      02:01       |      PASS      |
 116   |      tempest_keystone     |     functest     |     smoke     |      01:17       |      PASS      |
 117   |        tempest_heat       |     functest     |     smoke     |      22:14       |      PASS      |
 118   |     tempest_telemetry     |     functest     |     smoke     |      00:00       |      SKIP      |
 119   |        rally_sanity       |     functest     |     smoke     |      17:24       |      PASS      |
 120   |      refstack_compute     |     functest     |     smoke     |      07:03       |      PASS      |
 121   |      refstack_object      |     functest     |     smoke     |      02:09       |      PASS      |
 122   |     refstack_platform     |     functest     |     smoke     |      07:31       |      PASS      |
 123   |        tempest_full       |     functest     |     smoke     |      41:52       |      PASS      |
 124   |      tempest_scenario     |     functest     |     smoke     |      08:42       |      PASS      |
 125   |        tempest_slow       |     functest     |     smoke     |      43:42       |      PASS      |
 126   |       patrole_admin       |     functest     |     smoke     |      21:06       |      PASS      |
 127   |       patrole_member      |     functest     |     smoke     |      21:23       |      PASS      |
 128   |       patrole_reader      |     functest     |     smoke     |      21:56       |      PASS      |
 129   |      tempest_barbican     |     functest     |     smoke     |      02:30       |      PASS      |
 130   |      tempest_octavia      |     functest     |     smoke     |      00:00       |      SKIP      |
 131   |       tempest_cyborg      |     functest     |     smoke     |      00:00       |      SKIP      |
 132   +---------------------------+------------------+---------------+------------------+----------------+
 133
 134 Note: if the scenario does not support some tests, they are indicated as SKIP.
 135 See User guide for details.
 136
 137 Testing smoke CNTT suite
 138 ^^^^^^^^^^^^^^^^^^^^^^^^
 139
 140 Run smoke-cntt suite::
 141
 142   sudo docker run --env-file env \
 143       -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
 144       -v $(pwd)/images:/home/opnfv/functest/images \
 145       opnfv/functest-smoke-cntt
 146
 147 Results shall be displayed as follows::
 148
 149   +-------------------------------+------------------+---------------+------------------+----------------+
 150   |           TEST CASE           |     PROJECT      |      TIER     |     DURATION     |     RESULT     |
 151   +-------------------------------+------------------+---------------+------------------+----------------+
 152   |      tempest_neutron_cntt     |     functest     |     smoke     |      11:35       |      PASS      |
 153   |      tempest_cinder_cntt      |     functest     |     smoke     |      01:58       |      PASS      |
 154   |     tempest_keystone_cntt     |     functest     |     smoke     |      01:13       |      PASS      |
 155   |       tempest_heat_cntt       |     functest     |     smoke     |      22:32       |      PASS      |
 156   |       rally_sanity_cntt       |     functest     |     smoke     |      17:16       |      PASS      |
 157   |       tempest_full_cntt       |     functest     |     smoke     |      41:13       |      PASS      |
 158   |     tempest_scenario_cntt     |     functest     |     smoke     |      08:57       |      PASS      |
 159   |       tempest_slow_cntt       |     functest     |     smoke     |      35:58       |      PASS      |
 160   +-------------------------------+------------------+---------------+------------------+----------------+
 161
 162 Testing benchmarking suite
 163 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 164
 165 Run benchmarking suite::
 166
 167   sudo docker run --env-file env \
 168       -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
 169       -v $(pwd)/images:/home/opnfv/functest/images \
 170       opnfv/functest-benchmarking
 171
 172 Results shall be displayed as follows::
 173
 174   +--------------------+------------------+----------------------+------------------+----------------+
 175   |     TEST CASE      |     PROJECT      |         TIER         |     DURATION     |     RESULT     |
 176   +--------------------+------------------+----------------------+------------------+----------------+
 177   |     rally_full     |     functest     |     benchmarking     |      93:03       |      PASS      |
 178   |     rally_jobs     |     functest     |     benchmarking     |      27:05       |      PASS      |
 179   |        vmtp        |     functest     |     benchmarking     |      17:56       |      PASS      |
 180   |       shaker       |     functest     |     benchmarking     |      24:02       |      PASS      |
 181   +--------------------+------------------+----------------------+------------------+----------------+
 182
 183 Note: if the scenario does not support some tests, they are indicated as SKIP.
 184 See User guide for details.
 185
 186 Testing benchmarking CNTT suite
 187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 188
 189 Run benchmarking-cntt suite::
 190
 191   sudo docker run --env-file env \
 192       -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
 193       -v $(pwd)/images:/home/opnfv/functest/images \
 194       opnfv/functest-benchmarking-cntt
 195
 196 Results shall be displayed as follows::
 197
 198   +-------------------------+------------------+----------------------+------------------+----------------+
 199   |        TEST CASE        |     PROJECT      |         TIER         |     DURATION     |     RESULT     |
 200   +-------------------------+------------------+----------------------+------------------+----------------+
 201   |     rally_full_cntt     |     functest     |     benchmarking     |      89:52       |      PASS      |
 202   |     rally_jobs_cntt     |     functest     |     benchmarking     |      19:39       |      PASS      |
 203   |           vmtp          |     functest     |     benchmarking     |      16:59       |      PASS      |
 204   |          shaker         |     functest     |     benchmarking     |      23:43       |      PASS      |
 205   +-------------------------+------------------+----------------------+------------------+----------------+
 206
 207 Testing vnf suite
 208 ^^^^^^^^^^^^^^^^^
 209
 210 Run vnf suite::
 211
 212   sudo docker run --env-file env \
 213       -v $(pwd)/openstack.creds:/home/opnfv/functest/conf/env_file \
 214       -v $(pwd)/images:/home/opnfv/functest/images \
 215       opnfv/functest-vnf
 216
 217 Results shall be displayed as follows::
 218
 219   +----------------------+------------------+--------------+------------------+----------------+
 220   |      TEST CASE       |     PROJECT      |     TIER     |     DURATION     |     RESULT     |
 221   +----------------------+------------------+--------------+------------------+----------------+
 222   |       cloudify       |     functest     |     vnf      |      05:08       |      PASS      |
 223   |     cloudify_ims     |     functest     |     vnf      |      24:46       |      PASS      |
 224   |       heat_ims       |     functest     |     vnf      |      33:12       |      PASS      |
 225   |     vyos_vrouter     |     functest     |     vnf      |      15:53       |      PASS      |
 226   |       juju_epc       |     functest     |     vnf      |      27:52       |      PASS      |
 227   +----------------------+------------------+--------------+------------------+----------------+
 228
 229 Functest Dockers for Kubernetes deployment
 230 ------------------------------------------
 231 Docker images are available on the dockerhub:
 232
 233   * opnfv/functest-kubernetes-healthcheck
 234   * opnfv/functest-kubernetes-smoke
 235   * opnfv/functest-kubernetes-security
 236   * opnfv/functest-kubernetes-benchmarking
 237   * opnfv/functest-kubernetes-cnf
 238
 239 Preparing your environment
 240 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 241
 242 cat env::
 243
 244   DEPLOY_SCENARIO=k8s-XXX
 245
 246 Testing healthcheck suite
 247 ^^^^^^^^^^^^^^^^^^^^^^^^^
 248
 249 Run healthcheck suite::
 250
 251   sudo docker run -it --env-file env \
 252       -v $(pwd)/config:/root/.kube/config \
 253       opnfv/functest-kubernetes-healthcheck
 254
 255 A config file in the current dir 'config' is also required, which should be
 256 volume mapped to ~/.kube/config inside kubernetes container.
 257
 258 Results shall be displayed as follows::
 259
 260   +-------------------+------------------+---------------------+------------------+----------------+
 261   |     TEST CASE     |     PROJECT      |         TIER        |     DURATION     |     RESULT     |
 262   +-------------------+------------------+---------------------+------------------+----------------+
 263   |     k8s_quick     |     functest     |     healthcheck     |      00:18       |      PASS      |
 264   |     k8s_smoke     |     functest     |     healthcheck     |      01:14       |      PASS      |
 265   +-------------------+------------------+---------------------+------------------+----------------+
 266
 267 Testing smoke suite
 268 ^^^^^^^^^^^^^^^^^^^
 269
 270 Run smoke suite::
 271
 272   sudo docker run -it --env-file env \
 273       -v $(pwd)/config:/root/.kube/config \
 274       opnfv/functest-kubernetes-smoke
 275
 276 Results shall be displayed as follows::
 277
 278   +---------------------------+------------------+---------------+------------------+----------------+
 279   |         TEST CASE         |     PROJECT      |      TIER     |     DURATION     |     RESULT     |
 280   +---------------------------+------------------+---------------+------------------+----------------+
 281   |      k8s_conformance      |     functest     |     smoke     |      94:26       |      PASS      |
 282   |     xrally_kubernetes     |     functest     |     smoke     |      13:05       |      PASS      |
 283   +---------------------------+------------------+---------------+------------------+----------------+
 284
 285 Testing security suite
 286 ^^^^^^^^^^^^^^^^^^^^^^
 287
 288 Run smoke suite::
 289
 290   sudo docker run -it --env-file env \
 291       -v $(pwd)/config:/root/.kube/config \
 292       opnfv/functest-kubernetes-security
 293
 294 Results shall be displayed as follows::
 295
 296   +---------------------------+------------------+------------------+------------------+----------------+
 297   |         TEST CASE         |     PROJECT      |       TIER       |     DURATION     |     RESULT     |
 298   +---------------------------+------------------+------------------+------------------+----------------+
 299   |        kube_hunter        |     functest     |     security     |      00:19       |      PASS      |
 300   |     kube_bench_master     |     functest     |     security     |      00:02       |      PASS      |
 301   |      kube_bench_node      |     functest     |     security     |      00:01       |      PASS      |
 302   +---------------------------+------------------+------------------+------------------+----------------+
 303
 304 Testing benchmarking suite
 305 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 306
 307 Run benchmarking suite::
 308
 309   sudo docker run -it --env-file env \
 310       -v $(pwd)/config:/root/.kube/config \
 311       opnfv/functest-kubernetes-benchmarking
 312
 313 Results shall be displayed as follows::
 314
 315   +--------------------------------+------------------+----------------------+------------------+----------------+
 316   |           TEST CASE            |     PROJECT      |         TIER         |     DURATION     |     RESULT     |
 317   +--------------------------------+------------------+----------------------+------------------+----------------+
 318   |     xrally_kubernetes_full     |     functest     |     benchmarking     |      34:16       |      PASS      |
 319   +--------------------------------+------------------+----------------------+------------------+----------------+
 320
 321 Testing cnf suite
 322 ^^^^^^^^^^^^^^^^^
 323
 324 Run cnf suite::
 325
 326   sudo docker run -it --env-file env \
 327       -v $(pwd)/config:/root/.kube/config \
 328       opnfv/functest-kubernetes-cnf
 329
 330 Results shall be displayed as follows::
 331
 332   +-------------------------+------------------+--------------+------------------+----------------+
 333   |        TEST CASE        |     PROJECT      |     TIER     |     DURATION     |     RESULT     |
 334   +-------------------------+------------------+--------------+------------------+----------------+
 335   |         k8s_vims        |     functest     |     cnf      |      09:06       |      PASS      |
 336   |        helm_vims        |     functest     |     cnf      |      08:54       |      PASS      |
 337   |     cnf_conformance     |     functest     |     cnf      |      02:00       |      PASS      |
 338   +-------------------------+------------------+--------------+------------------+----------------+
 339
 340 Environment variables
 341 =====================
 342
 343 Several environment variables may be specified:
 344
 345   * INSTALLER_IP=<Specific IP Address>
 346   * DEPLOY_SCENARIO=<vim>-<controller>-<nfv_feature>-<ha_mode>
 347   * NAMESERVER=XXX  # if not 8.8.8.8
 348   * VOLUME_DEVICE_NAME=XXX  # if not vdb
 349   * EXTERNAL_NETWORK=XXX # if not first network with router:external=True
 350   * NEW_USER_ROLE=XXX # if not member
 351
 352 INSTALLER_IP is required by Barometer in order to access the installer node and
 353 the deployment.
 354
 355 The format for the DEPLOY_SCENARIO env variable can be described as follows:
 356   * vim: (os|k8s) = OpenStack or Kubernetes
 357   * controller is one of ( nosdn | odl )
 358   * nfv_feature is one or more of ( ovs | kvm | sfc | bgpvpn | nofeature )
 359   * ha_mode (high availability) is one of ( ha | noha )
 360
 361 If several features are pertinent then use the underscore character '_' to
 362 separate each feature (e.g. ovs_kvm). 'nofeature' indicates that no OPNFV
 363 feature is deployed.
 364
 365 The list of supported scenarios per release/installer is indicated in the
 366 release note.
 367
 368 **NOTE:** The scenario name is mainly used to automatically detect
 369 if a test suite is runnable or not (e.g. it will prevent ODL test suite to be
 370 run on 'nosdn' scenarios). If not set, Functest will try to run the default
 371 test cases that might not include SDN controller or a specific feature.
 372
 373 **NOTE:** An HA scenario means that 3 OpenStack controller nodes are
 374 deployed. It does not necessarily mean that the whole system is HA. See
 375 installer release notes for details.
 376
 377 Finally, three additional environment variables can also be passed in
 378 to the Functest Docker Container, using the -e
 379 "<EnvironmentVariable>=<Value>" mechanism. The first two parameters are
 380 only relevant to Jenkins CI invoked testing and **should not be used**
 381 when performing manual test scenarios:
 382
 383   * INSTALLER_TYPE=(apex|compass|daisy|fuel)
 384   * NODE_NAME=<Test POD Name>
 385   * BUILD_TAG=<Jenkins Build Tag>
 386
 387 where:
 388
 389   * <Test POD Name> = Symbolic name of the POD where the tests are run.
 390                       Visible in test results files, which are stored
 391                       to the database. This option is only used when
 392                       tests are activated under Jenkins CI control.
 393                       It indicates the POD/hardware where the test has
 394                       been run. If not specified, then the POD name is
 395                       defined as "Unknown" by default.
 396                       DO NOT USE THIS OPTION IN MANUAL TEST SCENARIOS.
 397   * <Jenkins Build tag> = Symbolic name of the Jenkins Build Job.
 398                          Visible in test results files, which are stored
 399                          to the database. This option is only set when
 400                          tests are activated under Jenkins CI control.
 401                          It enables the correlation of test results,
 402                          which are independently pushed to the results database
 403                          from different Jenkins jobs.
 404                          DO NOT USE THIS OPTION IN MANUAL TEST SCENARIOS.
 405
 406
 407 Openstack credentials
 408 =====================
 409 OpenStack credentials are mandatory and must be provided to Functest.
 410 When running the command "functest env prepare", the framework  will
 411 automatically look for the Openstack credentials file
 412 "/home/opnfv/functest/conf/env_file" and will exit with
 413 error if it is not present or is empty.
 414
 415 There are 2 ways to provide that file:
 416
 417   * by using a Docker volume with -v option when creating the Docker container.
 418     This is referred to in docker documentation as "Bind Mounting".
 419     See the usage of this parameter in the following chapter.
 420   * or creating manually the file '/home/opnfv/functest/conf/env_file'
 421     inside the running container and pasting the credentials in it. Consult
 422     your installer guide for further details. This is however not
 423     instructed in this document.
 424
 425 In proxified environment you may need to change the credentials file.
 426 There are some tips in chapter: `Proxy support`_
 427
 428 SSL Support
 429 -----------
 430 If you need to connect to a server that is TLS-enabled (the auth URL
 431 begins with "https") and it uses a certificate from a private CA or a
 432 self-signed certificate, then you will need to specify the path to an
 433 appropriate CA certificate to use, to validate the server certificate
 434 with the environment variable OS_CACERT::
 435
 436   echo $OS_CACERT
 437   /etc/ssl/certs/ca.crt
 438
 439 However, this certificate does not exist in the container by default.
 440 It has to be copied manually from the OpenStack deployment. This can be
 441 done in 2 ways:
 442
 443   #. Create manually that file and copy the contents from the OpenStack
 444      controller.
 445   #. (Recommended) Add the file using a Docker volume when starting the
 446      container::
 447
 448        -v <path_to_your_cert_file>:/etc/ssl/certs/ca.cert
 449
 450 You might need to export OS_CACERT environment variable inside the
 451 credentials file::
 452
 453   export OS_CACERT=/etc/ssl/certs/ca.crt
 454
 455 Certificate verification can be turned off using OS_INSECURE=true. For
 456 example, Fuel uses self-signed cacerts by default, so an pre step would
 457 be::
 458
 459   export OS_INSECURE=true
 460
 461
 462 Logs
 463 ====
 464 By default all the logs are put un /home/opnfv/functest/results/functest.log.
 465 If you want to have more logs in console, you may edit the logging.ini file
 466 manually.
 467 Connect on the docker then edit the file located in
 468 /usr/lib/python3.8/site-packages/xtesting/ci/logging.ini
 469
 470 Change wconsole to console in the desired module to get more traces.
 471
 472
 473 Configuration
 474 =============
 475
 476 You may also directly modify the python code or the configuration file (e.g.
 477 testcases.yaml used to declare test constraints) under
 478 /usr/lib/python3.8/site-packages/xtesting and
 479 /usr/lib/python3.8/site-packages/functest
 480
 481
 482 Tips
 483 ====
 484
 485 Docker
 486 ------
 487 When typing **exit** in the container prompt, this will cause exiting
 488 the container and probably stopping it. When stopping a running Docker
 489 container all the changes will be lost, there is a keyboard shortcut
 490 to quit the container without stopping it: <CTRL>-P + <CTRL>-Q. To
 491 reconnect to the running container **DO NOT** use the *run* command
 492 again (since it will create a new container), use the *exec* or *attach*
 493 command instead::
 494
 495   docker ps  # <check the container ID from the output>
 496   docker exec -ti <CONTAINER_ID> /bin/bash
 497
 498 There are other useful Docker commands that might be needed to manage possible
 499 issues with the containers.
 500
 501 List the running containers::
 502
 503   docker ps
 504
 505 List all the containers including the stopped ones::
 506
 507   docker ps -a
 508
 509 Start a stopped container named "FunTest"::
 510
 511   docker start FunTest
 512
 513 Attach to a running container named "StrikeTwo"::
 514
 515   docker attach StrikeTwo
 516
 517 It is useful sometimes to remove a container if there are some problems::
 518
 519   docker rm <CONTAINER_ID>
 520
 521 Use the *-f* option if the container is still running, it will force to
 522 destroy it::
 523
 524   docker rm -f <CONTAINER_ID>
 525
 526 Check the Docker documentation [`dockerdocs`_] for more information.
 527
 528
 529 Checking Openstack and credentials
 530 ----------------------------------
 531 It is recommended and fairly straightforward to check that Openstack
 532 and credentials are working as expected.
 533
 534 Once the credentials are there inside the container, they should be
 535 sourced before running any Openstack commands::
 536
 537   source /home/opnfv/functest/conf/env_file
 538
 539 After this, try to run any OpenStack command to see if you get any
 540 output, for instance::
 541
 542   openstack user list
 543
 544 This will return a list of the actual users in the OpenStack
 545 deployment. In any other case, check that the credentials are sourced::
 546
 547   env|grep OS_
 548
 549 This command must show a set of environment variables starting with
 550 *OS_*, for example::
 551
 552   OS_REGION_NAME=RegionOne
 553   OS_USER_DOMAIN_NAME=Default
 554   OS_PROJECT_NAME=admin
 555   OS_AUTH_VERSION=3
 556   OS_IDENTITY_API_VERSION=3
 557   OS_PASSWORD=da54c27ae0d10dfae5297e6f0d6be54ebdb9f58d0f9dfc
 558   OS_AUTH_URL=http://10.1.0.9:5000/v3
 559   OS_USERNAME=admin
 560   OS_TENANT_NAME=admin
 561   OS_ENDPOINT_TYPE=internalURL
 562   OS_INTERFACE=internalURL
 563   OS_NO_CACHE=1
 564   OS_PROJECT_DOMAIN_NAME=Default
 565
 566
 567 If the OpenStack command still does not show anything or complains
 568 about connectivity issues, it could be due to an incorrect url given to
 569 the OS_AUTH_URL environment variable. Check the deployment settings.
 570
 571 .. _`Proxy support`:
 572
 573 Proxy support
 574 -------------
 575 If your Jumphost node is operating behind a http proxy, then there are
 576 2 places where some special actions may be needed to make operations
 577 succeed:
 578
 579   #. Initial installation of docker engine First, try following the
 580      official Docker documentation for Proxy settings. Some issues were
 581      experienced on CentOS 7 based Jumphost. Some tips are documented
 582      in section: :ref:`Docker Installation on CentOS behind http proxy`
 583      below.
 584
 585 If that is the case, make sure the resolv.conf and the needed
 586 http_proxy and https_proxy environment variables, as well as the
 587 'no_proxy' environment variable are set correctly::
 588
 589   # Make double sure that the 'no_proxy=...' line in the
 590   # 'env_file' file is commented out first. Otherwise, the
 591   # values set into the 'no_proxy' environment variable below will
 592   # be ovewrwritten, each time the command
 593   # 'source ~/functest/conf/env_file' is issued.
 594
 595   cd ~/functest/conf/
 596   sed -i 's/export no_proxy/#export no_proxy/' env_file
 597   source ./env_file
 598
 599   # Next calculate some IP addresses for which http_proxy
 600   # usage should be excluded:
 601
 602   publicURL_IP=$(echo $OS_AUTH_URL | grep -Eo "([0-9]+\.){3}[0-9]+")
 603
 604   adminURL_IP=$(openstack catalog show identity | \
 605   grep adminURL | grep -Eo "([0-9]+\.){3}[0-9]+")
 606
 607   export http_proxy="<your http proxy settings>"
 608   export https_proxy="<your https proxy settings>"
 609   export no_proxy="127.0.0.1,localhost,$publicURL_IP,$adminURL_IP"
 610
 611   # Ensure that "git" uses the http_proxy
 612   # This may be needed if your firewall forbids SSL based git fetch
 613   git config --global http.sslVerify True
 614   git config --global http.proxy <Your http proxy settings>
 615
 616 For example, try to use the **nc** command from inside the functest
 617 docker container::
 618
 619   nc -v opnfv.org 80
 620   Connection to opnfv.org 80 port [tcp/http] succeeded!
 621
 622   nc -v opnfv.org 443
 623   Connection to opnfv.org 443 port [tcp/https] succeeded!
 624
 625 Note: In a Jumphost node based on the CentOS family OS, the **nc**
 626 commands might not work. You can use the **curl** command instead.
 627
 628   curl https://www.opnfv.org/
 629
 630   <HTML><HEAD><meta http-equiv="content-type"
 631   .
 632   .
 633   </BODY></HTML>
 634
 635   curl https://www.opnfv.org:443
 636
 637   <HTML><HEAD><meta http-equiv="content-type"
 638   .
 639   .
 640   </BODY></HTML>
 641
 642   (Ignore the content. If command returns a valid HTML page, it proves
 643   the connection.)
 644
 645 .. _`Docker Installation on CentOS behind http proxy`:
 646
 647 Docker Installation on CentOS behind http proxy
 648 -----------------------------------------------
 649 This section is applicable for CentOS family OS on Jumphost which
 650 itself is behind a proxy server. In that case, the instructions below
 651 should be followed **before** installing the docker engine::
 652
 653   1) # Make a directory '/etc/systemd/system/docker.service.d'
 654      # if it does not exist
 655      sudo mkdir /etc/systemd/system/docker.service.d
 656
 657   2) # Create a file called 'env.conf' in that directory with
 658      # the following contents:
 659      [Service]
 660      EnvironmentFile=-/etc/sysconfig/docker
 661
 662   3) # Set up a file called 'docker' in directory '/etc/sysconfig'
 663      # with the following contents:
 664      HTTP_PROXY="<Your http proxy settings>"
 665      HTTPS_PROXY="<Your https proxy settings>"
 666      http_proxy="${HTTP_PROXY}"
 667      https_proxy="${HTTPS_PROXY}"
 668
 669   4) # Reload the daemon
 670      systemctl daemon-reload
 671
 672   5) # Sanity check - check the following docker settings:
 673      systemctl show docker | grep -i env
 674
 675      Expected result:
 676      ----------------
 677      EnvironmentFile=/etc/sysconfig/docker (ignore_errors=yes)
 678      DropInPaths=/etc/systemd/system/docker.service.d/env.conf
 679
 680 Now follow the instructions in [`Install Docker on CentOS`_] to download
 681 and install the **docker-engine**. The instructions conclude with a
 682 "test pull" of a sample "Hello World" docker container. This should now
 683 work with the above pre-requisite actions.
 684
 685
 686 .. _`dockerdocs`: https://docs.docker.com/
 687 .. _`Proxy`: https://docs.docker.com/engine/admin/systemd/#http-proxy
 688 .. _`Install Docker on CentOS`: https://docs.docker.com/engine/installation/linux/centos/
 689 .. _`Functest User Guide`: http://docs.opnfv.org/en/stable-danube/submodules/functest/docs/testing/user/userguide/index.html
 690 .. _`images/CentOS-7-x86_64-GenericCloud.qcow2`: https://cloud.centos.org/centos/7/images/CentOS-7-x86_64-GenericCloud.qcow2
 691 .. _`images/cirros-0.5.1-x86_64-disk.img`: http://download.cirros-cloud.net/0.5.1/cirros-0.5.1-x86_64-disk.img
 692 .. _`images/ubuntu-14.04-server-cloudimg-amd64-disk1.img`: https://cloud-images.ubuntu.com/releases/14.04/release/ubuntu-14.04-server-cloudimg-amd64-disk1.img