Tasks
"""""

Before we can start with **Tasks**, we need to know **YAML**.

YAML is your friend
===================
* yaml stores structured data as text
* Ansible uses YAML because it's easy to read and write
* nearly every YAML file starts with a list
* an item in the list is a list of key / value pairs
* the key / value pairs are commonly called ``hash`` or ``dictionary``
* a YAML file begins with ``---``
* YAML cares about **whitespaces** and refuses tab character
* the amount of whitespaces is free, often are 2 whitespaces used

String / Numeric value
----------------------
* string values don't need quotes, but recommended (to avoid spaces)
* simple key/value pairs

.. code-block:: yaml

    username: 'foo'
    gid: 55


List
----
* ordered sequence
* can be nested
* all members of a list begins with ``-`` (dash and space)

.. code-block:: yaml

    # a list named userlist with two items
    userlist:
      - foo
      - bar

Dictionary
----------
* a dictionary is represented in a ``key: value`` form (space is needed)
* unordered group of key/value pairs
* indentation is needed
* can be nested

.. code-block:: yaml

    # a dictionary named user with two key/values (string)
    user:
      username: foo
      home: /home/foo


Nested
------
* more complicated data structures are possible
* dictionaries and lists can be nested
* indentation is used for nesting

* example
    * a list with 2 items
    * dictionaries whose values are lists
    * a mix of both

.. code-block:: yaml

    ---
    - pascal:                        <- 1st list item with a dictionary item
        name: Pascal Stauffer        <- key / value pair
        series:                      <- list with 3 items (indentation!)
          - suits
          - house of cards
          - dexter
    - domi:                          <- 2nd list item with a dictionary item
        name: Domi Barton            <- key / value pair
        series:                      <- list with 3 items (indentation!)
          - breaking bad
          - happy endings
          - last man on earth

    # dict.name / dict['name'] = string
    # dict.series / dict['series'] = list

.. hint::

    A list always containts a dash ``-``, so you can differate between a list and a dictionary.


* Dictionaries and lists can also be represented in a short form

.. code-block:: yaml

    # dictionary short form
    martin: {name: Martin D'vloper, job: Developer, skill: Elite}
    
    # list short form
    fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

.. hint::

    Don't use the short form. It can be difficult to read and is hard to compare with a SCM tool.


Multiple lines
--------------
* values can span multiple lines using ``|`` or ``>``
* ``|`` will include the newlines
* ``>`` will ignore newlines

.. code-block:: yaml

    include_newlines: |
                exactly as you see
                will appear these three
                lines of poetry

    ignore_newlines: >
                this is really a
                single line of text
                despite appearances


Links
-----
* http://docs.ansible.com/ansible/YAMLSyntax.html


What's a Task
=============
* a task defines a state
* tasks are written in YAML syntax
* calls a module with parameters
* tasks are executed in order
* tasks can be written on one or more lines
* tasks run parallel on servers (default 5)
* order of the hosts depends on the response time
* the next task will started, if it run on every server
* if a task fails, the following tasks will be skipped on this server 

.. code-block:: yaml

    # recommended form
    - name: install httpd package    <- documentation
      yum:                           <- module
        name: httpd                  <- arguments
        state: present

    # short form
    - apt: name=apache2 state=present


.. hint::

    Don't use the short form. With a lots of arguments, the line will be too long. And it's difficutlt to compare with a SCM tool.


Run a ad-hoc task/command
-------------------------
* a task can be run with the `ansible` binary.

.. code-block:: bash

    ansible -m apt -a "name=apache2 state=latest" web1.pascal.lab