Templates
"""""""""

Introduction into Jinja 2
=========================
* Jinja2 is a templating engine for python
* Ansible is using the Jinja2 templating system
* Loops, Filters and Conditionals are available in Jinja2

Benefits of templates
=====================
* Templates allow you to generate configuration files with different variable values
* conditionals and loops can also be used in templates
* you can store one template in source control that applies to many different environments
* some use-cases could be

    * different values for environments e.g ``test`` / ``prod``
    * different values for tiers e.g ``frontend`` / ``backend``


How to use templates
--------------------
* Create a ``templates`` folder in your role directory
* Place your file in the ``templates`` directory
* it's recommended to use the file extension ``.j2``
* in the template use variables with brackets ``{{ }}``

.. code-block:: yaml

    # file: templates/httpd.conf.j2
    This is a config file.
    My first variable is a fact.
    I'm a {{ ansible_os_family }} server!

* create a task and use the ``template`` module

.. code-block:: yaml

    - template:
        src: httpd.conf.j2
        dest: /etc/httpd.conf
        owner: root
        group: root
        mode: 0644


.. hint::

    The best way is to name your source file like destination file with the additional ``j2`` file extension -> ``httpd.conf.j2``


ansible_managed Header
----------------------
* a string that can be inserted into files written by Ansible’s config templating system
* the string can be changed in the Ansible configuration file
* should be used to tell users, that a file is managed by Ansible

.. code-block:: yaml
    
    ansible_managed = Ansible managed: {file} modified on %Y-%m-%d %H:%M:%S by {uid} on {host}


.. hint::

    Per default is a date in the string, so the template will be reported changed each time as the date is updated.

Loops and Conditionals
----------------------
* you can use loops and if statements in templates

.. code-block:: yaml

    # loop
    {% for user in sudo_users %}
    {{ user }} ALL=(ALL) NOPASSWD: ALL
    {% endfor %}

    # conditional
    {% if sudo_rsync %}
    {{ user }} ALL=(ALL) NOPASSWD: /bin/rsync
    {% endif %}

.. hint::

    Ansible allows Jinja2 loops and conditionals in templates, but not in playbooks. Ansible playbooks are pure machine-parseable YAML. 


Links
-----
* http://docs.ansible.com/ansible/playbooks_variables.html#using-variables-about-jinja2
* http://docs.ansible.com/ansible/playbooks_filters.html

copy vs template
================
* **copy** the file 1:1 on the managed host
* **template** module is evaluated by jinja2 -> variables, loops and conditionals can be used
* place the **ansible_managed** header into your templates


Jinja2 Filters
==============
* there are some useful filters available
* filters can be combined

    * ``{{ list | join(" ") }}`` (concenate lists)
    * ``{{ myvar | upper }}`` or ``lower``
    * ``{{ myvar | max }}`` or ``min``
    * ``{{ list | unique }}``
    * ``{{ list | random }}``
    * ``{{ myvar | checksum }}``
    * ``{{ path | basename }}``
    * ``{{ lvsize | default('0.25G') }}``
    * ``{{ ansible_managed | comment }}``

Links
-----
* http://docs.ansible.com/ansible/intro_configuration.html#ansible-managed
* http://docs.ansible.com/ansible/template_module.html
* http://docs.ansible.com/ansible/copy_module.html
* http://docs.ansible.com/ansible/playbooks_filters.html
* http://jinja.pocoo.org/docs