| | 1 | = Automated Tutorial Testing with Ansible = |
| | 2 | |
| | 3 | This page shows how to create an Ansible playbook to do automated testing. [http://groups.geni.net/geni/wiki/GENIExperimenter/Tutorials/RunHelloGENI HelloGeni tutorial] is used as an example to demonstrate how to perform automatd testing with Ansible. HelloGeni tutorial has a very simple topology with one server and one clients that are connected with a layer 2 link. We will demonstrate important factors in ansible script to start iperf server on server and then do iperf test from client to server. |
| | 4 | |
| | 5 | |
| | 6 | == 1. What are Ansible Playbook? == |
| | 7 | Ansible is a configuration management system that can be used to automate configuration tasks for distributed nodes. Ansible playbook is a way of sending commands in script format instead of using individual commands to remotely configure systems. Ansible playbooks are written in YAML format. |
| | 8 | |
| | 9 | == 2. Playbook Basics == |
| | 10 | * Play: Each playbook contains one or more 'plays' in a list. The play maps a groups of hosts to a series of tasks. Each play could contains a list of tasks which are executed. |
| | 11 | * Task: A task can be regarded as a configuration step in the remote system. We could add more than one task for a play. Tasks run from top to bottom. When a task fails, the host with the failed task are taken out of the entire playbook. Tasks belonging to other hosts will be executed normally. |
| | 12 | * Playbook: A playbook can contain multiple plays. For example, we could have a playbook that targets first the server, and then the client. The first play checks whether iperf server is running on server node using 'ps' command and then the second play starts the iperf client. |
| | 13 | |
| | 14 | {{{ |
| | 15 | - name: test server |
| | 16 | hosts: server |
| | 17 | sudo: True |
| | 18 | tasks: |
| | 19 | - name: check iperf running |
| | 20 | shell: ps aux | grep iperf |
| | 21 | register: iperf_running |
| | 22 | failed_when: "'iperf -s -i 10 &> /var/www/iperflogs/iperf-server.log' not in iperf_running.stdout" |
| | 23 | - debug: var=iperf_running.stdout_lines |
| | 24 | - name: test client |
| | 25 | hosts: client |
| | 26 | sudo: True |
| | 27 | tasks: |
| | 28 | - name: iperf test |
| | 29 | command: iperf -c server -P 2 |
| | 30 | register: iperf_test |
| | 31 | failed_when: "'failed' in iperf_test.stderr" |
| | 32 | async: 30 |
| | 33 | poll: 10 |
| | 34 | - debug: var=iperf_test.stdout_lines |
| | 35 | }}} |
| | 36 | |
| | 37 | |
| | 38 | == 3. Error Handling in Playbooks == |
| | 39 | Generally playbooks will stop executing any more tasks on a host that has a failure. If we want the playbook to ignore a task failure and continue executing, we could set the ignore_errors to 'yes'. |
| | 40 | Here's an example: |
| | 41 | {{{ |
| | 42 | - name: this will not be counted as a failure |
| | 43 | command: /bin/false |
| | 44 | ignore_errors: yes |
| | 45 | }}} |
| | 46 | Sometimes, the error code of a command cannot really tell if there is a failure and we need the output of the command to decide whether it is a failure. In this case, we should register the task to a variable and define the failure by command output. |
| | 47 | For example, 'failed' string in iperf test output means the test fails: |
| | 48 | {{{ |
| | 49 | - name: iperf test |
| | 50 | command: iperf -c server -P 2 |
| | 51 | register: iperf_test |
| | 52 | failed_when: "'failed' in iperf_test.stderr" |
| | 53 | }}} |
| | 54 | |
| | 55 | == 4. Print the command output == |
| | 56 | We could use 'debug' module to print command output during execution. This is useful for debugging. |
| | 57 | This example demonstrates how to print out the iperf test result: |
| | 58 | {{{ |
| | 59 | - name: iperf test |
| | 60 | command: iperf -c server -P 2 |
| | 61 | register: iperf_test |
| | 62 | - debug: var=iperf_test.stdout_lines |
| | 63 | }}} |
| | 64 | |
| | 65 | |
| | 66 | == 5. Set Task Timeout == |
| | 67 | Generally, tasks in playbooks are in blocking mode, which means the connection stay open until the task is done. This may not always be desirable for some failure: the connection will keep open until the SSH timeout. |
| | 68 | We could use asynchronous mode to set timeout for a task. 'async' sets the maximum runtime and 'poll' sets how frequently you would like to poll for status. |
| | 69 | For example, in our iperf test, we want to abort the task after 30s and polls the status every 10s, we could use the following script: |
| | 70 | {{{ |
| | 71 | - name: iperf test |
| | 72 | command: iperf -c server -P 2 |
| | 73 | register: iperf_test |
| | 74 | failed_when: "'failed' in iperf_test.stderr" |
| | 75 | async: 30 |
| | 76 | poll: 10 |
| | 77 | }}} |
| | 78 | |
| | 79 | == 6. Run Shell Script == |
| | 80 | The shell module takes the command name followed by a list of space-delimited arguments. It is almost exactly like the command module but runs the command through a shell (/bin/sh) on the remote node. |
| | 81 | Here's an example of checking whether a file exists on remote node. If the file does not exist, the task is regarded as failure: |
| | 82 | {{{ |
| | 83 | - name: test whether installed file exists or not |
| | 84 | shell: if [ -f /local/installed.txt ] ; then echo "yes" ; else echo "no" ; fi |
| | 85 | register: installation_test |
| | 86 | failed_when: "'no' in installation_test.stdout_lines" |
| | 87 | }}} |
| | 88 | |
| | 89 | == 7. Execute Tests == |
| | 90 | Run the playbook with the following command on the local machines: |
| | 91 | {{{ |
| | 92 | ansible-playbook <your_yml_file_directory> -i inventory |
| | 93 | }}} |
| | 94 | |
| | 95 | |
