From 29608d3e5a01a0454b8a230b5549f60c9c701a0e Mon Sep 17 00:00:00 2001 From: Yujun Zhang Date: Thu, 11 May 2017 20:03:33 +0800 Subject: Update readme of running with native `ansible-playbook` command Change-Id: Idd021dd6301c7ced7658460622ba4961b071c3c2 Signed-off-by: Yujun Zhang --- docs/testing/developer/devguide/ansible.rst | 155 ++++++++++++++++++++++++++++ docs/testing/developer/devguide/index.rst | 1 + 2 files changed, 156 insertions(+) create mode 100644 docs/testing/developer/devguide/ansible.rst (limited to 'docs/testing/developer/devguide') diff --git a/docs/testing/developer/devguide/ansible.rst b/docs/testing/developer/devguide/ansible.rst new file mode 100644 index 00000000..ab2cb55c --- /dev/null +++ b/docs/testing/developer/devguide/ansible.rst @@ -0,0 +1,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. ``/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 `` 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 ``/group_vars/all.yml`` to set installer information correctly +#. Modify ``/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 ``/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 ``-/`` 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 diff --git a/docs/testing/developer/devguide/index.rst b/docs/testing/developer/devguide/index.rst index bd25a5b7..40baca9c 100644 --- a/docs/testing/developer/devguide/index.rst +++ b/docs/testing/developer/devguide/index.rst @@ -11,6 +11,7 @@ QTIP Developer Guide :maxdepth: 2 overview.rst + ansible.rst arch.rst framework.rst cli.rst -- cgit 1.2.3-korg