Templates and Filters

Templates

• Use template module to dploy a jinja2 template file

- name: Make sure sshd_config is customized
  template:
    src: sshd_config.j2
    dest: /etc/ssh/sshd_config
    owner: root
    group: root
    mode: "0600"
    setype: etc_t

Jinja2 Templates and Facts

• Ansible facts are special variables that contain information unique to the managed host

• By default, they are set by an implied task at the start of the play (Gathering Facts)

• You can also collect facts at any time by running the setup module

• These facts are stored in a special variable, ansible_facts, structured as a dictionary

• They include network addresses, hostnames, storage configuration, operating system, and many other things

# displays all facts for the managed host, and then just the fact that has the list of IPv4 addresses for the managed host
- name: Display some facts
  hosts: all
  
  tasks:
    - name: Display all facts
      debug:
        var: ansible_facts
    - name: Display a list of all IPv4 addresses
      debug:
        var: ansible_facts['all_ipv4_addresses']

Some other facts

• ansible_facts['fqdn']

• ansible_facts['default_ipv4']['address']

Template Syntax

Comment

• {# Comment #}

For loop

• The for statement provides a way to loop over a set of items

• groups['all'] is a special variable that lists all the members of group all

• The following example Jinja2 template file uses a for statement to set the variable host to each item in the groups['all'] list, in turn

• hostvars['host'] is another special variable contains the facts for the current value of host

# Create a file in /etc/hosts format containing the IPv4 address and FQDN of every host in the inventory

<div data-gb-custom-block data-tag="for" data-0='all' data-1='all' data-2='all' data-3='all'>

{{ hostvars['host']['ansible_facts']['default_ipv4']['address'] }} {{ hostvars['host']['ansible_facts']['fqdn'] }}

</div>

- name: Get switches in stack
  set_fact:
    stackmembers: "

<div data-gb-custom-block data-tag="for" data-0='0' data-1='0' data-2='0' data-3='0' data-4='0' data-5='0' data-6='0' data-7='0' data-8='0' data-9='0' data-10='0' data-11='0' data-12='0' data-13='0' data-14='0' data-15='0' data-16='0' data-17='0' data-18='0' data-19='0' data-20='0' data-21='0' data-22='0' data-23='0' data-24='0' data-25='0' data-26='0' data-27='0'><div data-gb-custom-block data-tag="if" data-0='^[ *][0-9]' data-1='^[ *][0-9]' data-2='0' data-3='-9'>present<div data-gb-custom-block data-tag="if">,</div></div></div>"

Conditionals

• Jinja2 templates use the syntax

for expressions or logic.

• You can use these expressions in template files but you should not use them in Ansible Playbooks.

• The if/endif statements allow you to put content in a deployed file based on whether another variable is set.

# The value of the result variable is placed in the deployed file only if the Boolean value of the finished variable is True.
{# Only included if finished is True #}

<div data-gb-custom-block data-tag="if">

{{ result }}

</div>

Filters

• Filters are used to modify or process the value from the variable

• Some filters are provided by the Jinja2 language itself

• Others are extensions included with Ansible as plug-ins.

• It is also possible to create custom filters

• Information about the filters that are available is at: https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html

• Filters can be incredibly useful to prepare data for use in your playbook or template

• To apply a filter to a variable:

  • Reference the variable, but follow its name with a pipe character

  • After the pipe character, add the name of the filter you want to apply

  • Some filters might require additional arguments or options in parentheses

  • You can chain multiple filters in a pipeline

• For example, the capitalize filter capitalizes the first letter of a string

# Assume the value of myname is james, James will be the result of the Jinja2 expansion.
{{ myname | capitalize }}

List intersect filter

- set_fact:
    intersectlist: "{{ list1 | intersect(list2)}}"

Processing Variables with Jinja2 Filters

• Filters do not change the value stored in the variable.

• The Jinja2 expression processes that value and uses the result without changing the variable itself.

• Learn more by reviewing the documentation at: https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html

Multiple Filters

- name: Multiple filter example
  hosts: localhost
  vars:
    mylist:
      - 3
      - 9
      - 1
      - 7
      - 9
  tasks:
    - name: Display sorted list of unique items
      debug:
        msg: "{{ mylist | unique | sort }}"

# Result will be: -1, -3, -7, -9

Other Filters

ipaddr Filter

• If passed a single IP address, it will return True if it is in the right format and False if it is not

• If passed a list of IP addresses, it will return a list of the ones that are valid

- name: Multiple filter example
  hosts: localhost
  vars:
    mylist:
      - 192.0.2.1
      - 10.0.0.1
      - 304.252.1.200
  tasks:
    - name: Display list of valid addresses
      debug:
        - 192.0.2.1 msg: "{{ mylist | ipaddr }}"

# Result will be: 192.0.2.1 and 10.0.0.1

- name: Multiple filter example
  hosts: localhost
  vars:
    mylist:
      - 192.0.2.1/255.255.255.0
      - 10.0.0.1/255.255.255.128
      - 10.0.0.200/255.255.255.128
  tasks:
    - name: Display list of CIDR networks
      debug:
        msg: "{{ mylist | ipaddr('network/prefix')}}"

# Result will be: 192.0.2.0/24, 10.0.0.0/25, 10.0.0.128/25

list of filters

• mandatory

• default

• int/float

• min/max/sum

• first/last/length

• unique

• union

• intersect

• difference

• combine

• dict2items

• items2dict

• lower/upper

• capitalize

• random

• reverse

• sort

• flatten

Templating External Data with Lookup Plugins

• A lookup plugin is an Ansible extension to the Jinja2 templating language

• They import and format data from external sources for use in variables and templates

• Allows you to use the contents of a file as a value for a variable

• Allows you to look up information from other sources and put them in a template

• ansible-doc -t lookup -l will list all available lookup plugins

• ansible-doc -t lookup file will display documentation for the file lookup plugin

Lookup and Query

• There are two ways to call a lookup plugin:

  • lookup returns a string of comma-separated items

  • query returns an actual YAML list of items

• query is often easier to use without further processing

Dig Lookup Plugin

• use the dig lookup plugin to look up the DNS MX records for gmail.com and returns a list where each item is one record. It then prints the list one item at a time

- name: Example of a lookup plugin in use
  hosts: all
  vars:
    mxvar: "{{ query('dig', 'gmail.com', 'qtype=MX') }}"
  tasks:
    - name: List each MX record for gmail.com
      debug:
        msg: An MX record is: {{ item }}
      loop: "{{ mxvar }}"

File Lookup Plugin

• The file lookup plugin can be used to load the contents of a file into a variable

• If a relative path is provided, the plugin looks for files in the playbook's files directory

• use the authorized_key module to copy the contents of files/naoko.key.pub into the ~naoko/.ssh/authorized_keys file for user naoko on each managed host.

• lookup plugin is used because the value of key must be her actual public key, not a file name

- name: Add authorized keys
  hosts: all
  vars:
    users:
      - naoko
  tasks:
    - name: Add authorized keys
      authorized_key:
        user: "{{ item }}"
        key: "{{ lookup('file', item + '.key.pub') }}"
      loop: "{{ users }}"

Lines Lookup Plugin

• The lines lookup plugin will read output from a command, making each line an item in the list

• This can be useful in conjunction with filters

• Uses lines to build a list consisting of the lines in the /etc/passwd file.

• It then loops over that list, using the debug module and the regex_replace filter to print out the name of each user account listed in that file.

- name: Print the name of each account in /etc/passwd
  debug:
    msg: A user is {{ item | regex_replace(':.*$') }}
  loop: "{{ query('lines', 'cat /etc/passwd') }}"

Template Lookup Plugin

• The template lookup plugin will take a Jinja2 template and evaluate that when setting the value.

• If a relative path is passed to the template, Ansible will look in the playbook's templates directory.

• Content of templates/my.template.j2: Hello {{ my_name }}!

- name: Print "Hello class!"
  hosts: all
  vars:
    my_name: class
  tasks:
    - name: Demonstrate template lookup plugin
      debug:
        msg: "{{ lookup('template', 'my.template.j2') }}"

# Result printed: Hello class!

URL Lookups

• The url lookup plugin is useful to grab the content of a web page or the output of an API

• This example talks to an Amazon API and prints the IPv4 and IPv6 networks used by AWS

- name: test url lookups
  hosts: localhost
  become: no
  vars:
    amazon_ip_ranges: "{{ lookup('url', 'https://ip-ranges.amazonaws.com/ip-ranges.json', split_lines=False) }}"
  
  tasks:
    - name: display IPv4 ranges
      debug:
        msg: "{{ item['ip_prefix'] }}"
      loop: "{{ amazon_ip_ranges['prefixes'] }}"
    - name: display IPv6 ranges
      debug:
        msg: "{{ item['ipv6_prefix'] }}"
      loop: "{{ amazon_ip_ranges['ipv6_prefixes'] }}"

Resource

• Jinja2 Tutorial