summaryrefslogtreecommitdiffstats
path: root/docs/testing/developer/devguide/ansible.rst
blob: ab2cb55c65a7c95f4d5d5b8575dc3efd94a0fd34 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0


****************
Run with Ansible
****************

QTIP benchmarking tasks are built upon `Ansible`_ playbooks and roles. If you are familiar with Ansible, it is possible
to run it with ``ansible-playbook`` command. And it is useful during development of ansible modules or testing roles.

.. _Ansible: https://www.ansible.com/

Create workspace
================

There is a playbook in ``resources/ansible_roles/qtip-workspace`` used for creating a new workspace::

    cd resources/ansible_roles/qtip-workspace
    ansible-playbook create.yml

NOTE: if this playbook is moved to other directory, configuration in ``ansible.cfg`` needs to be updated accordingly.
The ansible roles from QTIP, i.e. ``<path_of_qtip>/resources/ansible_roles`` must be added to ``roles_path`` in
`Ansible configuration file`_. For example::

    roles_path = ~/qtip/resources/ansible_roles

.. _Ansible configuration file:

Executing benchmark
===================

Before executing the setup playbook, make sure `~/.ssh/config` has been configured properly so that you can login the
**master node** "directly". Skip next section, if you can login with ``ssh <master-host>`` from localhost,

SSH access to master node
-------------------------

It is common that the master node is behind some jump host. In this case, ssh option ``ProxyCommand`` and ``ssh-agent``
shall be required.

Assume that you need to login to deploy server, then login to the master node from there. An example configuration is
as following::

    Host fuel-deploy
      HostName 172.50.0.250
      User root

    Host fuel-master
      HostName 192.168.122.63
      User root
      ProxyCommand ssh -o 'ForwardAgent yes' apex-deploy 'ssh-add && nc %h %p'

If several jumps are required to reach the master node, we may chain the jump hosts like below::

    Host jumphost
      HostName 10.62.105.31
      User zte
      Port 22

    Host fuel-deploy
      HostName 172.50.0.250
      User root
      ProxyJump jumphost

    Host fuel-master
      HostName 192.168.122.63
      User root
      ProxyCommand ssh -o 'ForwardAgent yes' apex-deploy 'ssh-add && nc %h %p'

NOTE: ``ProxyJump`` is equivalent to the long ``ProxyCommand`` option, but it is only available since OpenSSH 7.3

Automatic setup
---------------

#. Modify ``<workspace>/group_vars/all.yml`` to set installer information correctly
#. Modify ``<workspace>/hosts`` file to set installer master host correctly
#. Run the setup playbook to generate ansible inventory of system under test by querying the slave nodes from the installer
master::

    cd workspace
    ansible-playbook setup.yml

.. _apex: https://wiki.opnfv.org/display/apex
.. _fuel: https://wiki.opnfv.org/display/fuel

It will update the ``hosts`` and ``ssh.cfg``

Currently, QTIP supports automatic discovery from `apex`_ and `fuel`_.

Manual setup
------------

If your installer is not supported or you are
testing hosts not managed by installer, you may add them manually in ``[compute]`` group in ``<workspace>/hosts``::

    [compute:vars]
    ansible_ssh_common_args=-F ./ssh.cfg

    [compute]
    node-2
    node-4
    node-6
    node-7

And ``ssh.cfg`` for ssh connection configuration::

    Host node-5
      HostName 10.20.5.12
      User root

Run the tests
-------------

Run the benchmarks with the following command::

    ansible-playbook run.yml

CAVEAT: QTIP will install required packages in system under test.

Inspect the results
-------------------

The test results and calculated output are stored in ``results``::

    current/
        node-2/
            arithmetic/
                metric.json
                report
                unixbench.log
            dpi/
            ...
        node-4/
        ...
        qtip-pod-qpi.json
    qtip-pod-20170425-1710/
    qtip-pod-20170425-1914/
    ...

The folders are named as ``<pod_name>-<start_time>/`` and the results are organized by *hosts* under test. Inside each
host, the test data are organized by metrics as defined in QPI specification.

For each metrics, it usually includes the following content

* log file generated by the performance testing tool
* metrics collected from the log files
* reported rendered with the metrics collected

Teardown the test environment
-----------------------------

QTIP will create temporary files for testing in system under test. Execute the teardown playbook to clean it up::

    ansible-playbook teardown.yml