```````````````````````````````````````````````
Tutorial: Hello Ansible on iMinds Virtual Wall
```````````````````````````````````````````````

In this tutorial, you will learn how you can use the open source configuration
managment tool "Ansible" to ease the development, scaling and reproducability
of your next experiment.


1. Design the experiment
========================

In this exercise we will convert the install script below into an Ansible playbook.

This install script does the following:

* Install `apache2` and `iperf`

On the server:

* Configure the default site on Apache
* Copy some files to /var/www
* Start the apache service

On the client:

* Start a wget client script
* Start an iperf client script

.. literalinclude:: helloansible_installscript.sh
   :language: bash
   :linenos:


2. Establish the Environment
============================

a. To run this exercise, you will need an account and two pieces of software.

  #. `Have a Fed4FIRE or GENI account <../getanaccount.html>`_
  #. jFed Experimenter GUI *BETA*: use the **Quickstart Experimenter GUI BETA**-button on  <http://jfed.iminds.be/>
  #. Have Ansible installed:

     a. On Linux and Mac: `find the instructions for your package manager here <http://docs.ansible.com/intro_installation.html#latest-releases-via-apt-ubuntu>`_
     b. On Windows: Ansible has no support for Windows on the control machine. You can swap in a Linux VM to overcome this issue (Use :download:`ansible_controller.rspec <ansible_controller.rspec>` for a readily configured machine).

b. Download the webpages and scripts needed for the exercise.

Use `wget` to download the :download:`tarball <helloansible-install.tar.gz>` of files onto your local machine and use tar to uncompress it::

  wget http://doc.ilabt.iminds.be/jfed-documentation/_downloads/helloansible-install.tar.gz
  tar zxvf helloansible-install.tar.gz

.. note:: Windows users should download and unpack this on their Ansible controller testbed-node.

3. Obtain resources
===================

Reserve :download:`helloansible.rspec <helloansible.rspec>` in jFed in an
experiment named `ansblXX` where XX is your initials.

4. Configure and Initialize
===========================

jFed can export the login information of your nodes into several formats for
configuration management systems.
An Ansible inventory is one of the supported formats. This is a flat file format
which tells Ansible the name and login information for your nodes.

To export these files:

* Go to the "RSpec Viewer" tab on the top of your screen
* Choose "Save Experiment" -> "Export Configuration Management Settings"
* Save the ZIP-file in a convenient place
* Unpack the ZIP-file in your working directory

.. NOTE::	Windows users should copy and unpack their zip-file onto their ansible controller. You can use `WinSCP <https://winscp.net/>`_ to copy the resources to your testbed node.

.. image:: export-configuration-management-settings.png
     :align: center

The exported ZIP-file contains several files:

* **id_rsa**
* id_rsa.pub
* ssh-config
* **ansible-hosts**
* **ansible.cfg**
* fabfile.py
* README.txt

The `README.txt`-file contains an comprehensive introduction for each of these files.
In this tutorial, we will be using  the files mentioned in bold.

An example of the content of these files can be found below:

ansible-hosts::

  # Sample commands:
  # ansible nodes -m ping
  # ansible nodes -m shell -a "uptime"

  [nodes]
  client 	ansible_ssh_host=n091-vm26-10.wall2.ilabt.iminds.be	ansible_ssh_port=22	ansible_ssh_user=twalcari
  server 	ansible_ssh_host=n091-vm26-11.wall2.ilabt.iminds.be	ansible_ssh_port=22	ansible_ssh_user=twalcari

ansible.cfg::

  [defaults]
  private_key_file = ./id_rsa
  host_key_checking = false
  inventory = ansible-hosts


.. WARNING:: Before continuing, you need to properly secure the private key `id_rsa`.
   Otherwise, all commands will fail. To do this, execute::

      $ chmod 600 id_rsa

Check to see if your nodes are up and ready.
This command uses the ping module to ping all the servers from the `nodes`-group (in which jFed stores all servers by default) listed in the inventory file::

  $ ansible nodes -m ping

Example output showing all of the nodes responding to ping::

  $ ansible -i ansible-hosts nodes -m ping
  client | success >> {
      "changed": false,
      "ping": "pong"
  }

  server | success >> {
      "changed": false,
      "ping": "pong"
  }

Try using the ping module in Ansible to only ping server or client by replacing
`all` in the above with `server` or `client`.

5. Using Ansible Ad Hoc
=======================

The following are some example Ansible Ad Hoc commands.
You can run these commands one at a time from the machine where you have Ansible
installed. `-s` tells Ansible to use `sudo` when executing the command.
All modules are described in the `Ansible Documentation <http://docs.ansible.com/modules_by_category.html>`_.


`apt <http://docs.ansible.com/apt_module.html>`_ module is used to install
packages using the apt package manager::

  ansible [nodes/server/client] -s -m apt -a "name=apache2 update_cache=yes"

`command <http://docs.ansible.com/command_module.html>`_ module is used to
execute an arbitrary command on the remote node::

  ansible [nodes/server/client]  -s -m command -a "/usr/sbin/a2enmod status"

`file <http://docs.ansible.com/file_module.html>`_ module is used to set
attributes of files::

  ansible [nodes/server/client] -s -m file -a "path=/var/www/html state=absent"

`synchronize <http://docs.ansible.com/synchronize_module.html>`_ module is an
implementation of rsync and is used to efficiently synchronize files between
your local machine and a remote node::

  ansible [nodes/server/client] -s  -m synchronize \
      -a "src=website/index.html dest=/var/www"

`lineinfile <http://docs.ansible.com/lineinfile_module.html>`_ module is used to see if an arbitrary line exists in a file::

  ansible [nodes/server/client] -s  -m lineinfile \
     -a "line='ExtendedStatus On' dest=/etc/apache2/conf.d/extendedstatus create=yes state=present"

`service <http://docs.ansible.com/service_module.html>`_ module is used to start/stop/restart/etc services::

  ansible [nodes/server/client] -s  -m service -a "name=apache2 state=restarted"

Use it!
-------
Using the above Ad Hoc Ansible commands configure the client node by doing the following:

* on both client and server, install `apache2` and `iperf`
* copy the scripts directory into `/local` on the client node with permissions 755.

.. solution can be found in playbook below

Verify that the above items have been done, by logging into the client node and running::

  $ apache2 -v
  $ iperf -v
  $ ls /local/scripts

6. Using Ansible Playbooks
==========================
Ansible commands can be collected into files called Playbooks.
Playbooks are in a configuration file format called YAML which is very
straightforward. In particular, Ansible Ad Hoc commands easily map to commands
used in an Ansible Playbook.

Use the `name` construct to leave a comment describing the Ansible command you are running.

The Playbook to configure the client node as in the install script is as follows:

.. literalinclude:: hello-client.yml
   :language: yaml


Do these commands look like the Ad Hoc commands you came up with in the previous step?

Put the above content in a file called :download:`hello-client.yml`.

Run the playbook with the following command on the local machine::

  ansible-playbook -i ansible-hosts hello-client.yml

Use it!
-------
Using the above Ansible modules, configure the server node by reproducing the
steps in the HelloGENI install script for the server node.
As you find a command that works, use it to construct a `hello-server.yml`
playbook. (See the `solution <helloansible-solution.html>`_ or  :download:`hello-server.yml`)

Here is a template you can fill in  to create the `hello-server.yml`-file:

.. literalinclude:: hello-server-template.yml
   :language: yaml
   :linenos:

* Run both the client and server playbooks on your nodes.

* Browse to the server node

7. Advanced Ansible
===================

* You may have noticed that the server playbook and the client playbook
  contained duplicate commands. This is because both nodes need to have apache
  installed so that they can act as webservers.
  As you might have guessed, there is a way to modularize this configuration.
  In Ansible this is done with "roles".
* Explore some of the intermediate features of Ansible such as roles, variables,
  and handlers.

8. Teardown Experiment
======================
* Reload the OS of your client and server,
  and test your playbooks from scratch in the new experiment.
  Do you get the same behavior?
* When you are done, delete the resources in your experiment.

9. Archive Experiment
=====================

If this was a real experiment, you would commit your Ansible playbook to a
version control system like `git` as you go.


Acknowledgements
================
This tutorial is an adaptation of the GENI-tutorial
`"Converting the Hello GENI Install Script to Ansible" <http://groups.geni.net/geni/wiki/GENIExperimenter/Tutorials/AnsibleHelloGENI>`_