Ansible Fundamentals

Using Jinja2 Templates and Filters

1
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Deploying Files with Jinja2 Templates

2
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Objectives

● Use Jinja2 templates to deploy customized files to managed hosts.

3
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Deploying Files to Managed hosts

● There are a number of Ansible modules that can be used to deploy files, including:
○ copy to copy a file to the managed hosts
○ file to make sure a file, directory, or link exists (or does not) and has certain settings
○ synchronize to copy entire directories of content
● You can also edit files in place with Ansible modules
○ lineinfile to make sure a certain line exists in a file, for example

● However, what if a file you want to deploy needs to be customized for each managed host?
○ Use Jinja2 template files and the template module

4
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Jinja2 Template Files

● Jinja2 template files allow you to deploy a

template that contains Jinja2 variables like
an Ansible Playbook
Port {{ ssh_port }}

● Those variables are replaced with their values #AddressFamily any

when the template is deployed #ListenAddress 0.0.0.0
#ListenAddress ::

● One use case: have a complex configuration HostKey /etc/ssh/ssh_host_rsa_key

file that is customized with values set by host HostKey /etc/ssh/ssh_host_ecdsa_key
HostKey /etc/ssh/ssh_host_ed25519_key
or group-specific inventory variables
...example truncated...
● At right is a piece of a Jinja2 template file for
/etc/ssh/sshd_config based on the value in
the inventory variable ssh_port for the host

5
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Deploying Jinja2 Templates

● Use the template module to deploy a

- name: Make sure sshd_config is customized
Jinja2 template file. template:
src: sshd_config.j2
dest: /etc/ssh/sshd_config
● It takes most of the same arguments as owner: root
copy. group: root
mode: "0600"
setype: etc_t
● The example task at right templates the
sshd_config.j2 file from your playbook's
directory (or a templates directory in your
playbook's directory) to /etc/ssh/sshd_config
on the managed host, setting permissions
and file ownership

6
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 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, - name: Display some facts
ansible_facts, structured as a dictionary hosts: all
● They include network addresses, hostnames, tasks:
storage configuration, operating system, and - name: Display all facts
many other things debug:
var: ansible_facts
● The example play at right displays all facts
for the managed host, and then just the fact - name: Display a list of all IPv4 addresses
debug:
that has the list of IPv4 addresses for the var: ansible_facts['all_ipv4_addresses']
managed host

7
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: Jinja2 Templates and Facts
● At top right is a Jinja2 template, motd.j2, to be
This host is {{ ansible_facts['fqdn'] }}
deployed as /etc/motd on the managed hosts.
The fact ansible_facts['fqdn'] will be replaced Unauthorized access is prohibited.
with the fully-qualified DNS name of the host.

- name: Ensure /etc/motd is correct

● The /etc/motd file is templated with the task at template:
middle right. src: motd.j2
dest: /etc/motd

● The example at bottom right is what you will

This host is server1.example.com
see on the host server1.example.com after a
play containing that task runs. Unauthorized access is prohibited.

8
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example of a Comment

● You can use the syntax {# COMMENT #} for comments that should not appear in the final file.
● In the following example, the first line includes a comment that will not be included in the final file.
The variable references in the second line are replaced with the values of the system facts being
referenced.

{# /etc/hosts line #}
{{ ansible_facts['default_ipv4']['address'] }} {{ ansible_facts['fqdn'] }}

9
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Control Structures in Jinja2 Template Files

● 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

● The result of this template is to create a file in /etc/hosts format containing the IPv4 address and
FQDN of every host in the inventory

{% for host in groups['all'] %}

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

10
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Using Jinja2 Conditionals

● Jinja2 templates use the syntax {% EXPR %} 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.
● In the following example, 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 #}

{% if finished %}
{{ result }}
{% endif %}

11
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Processing Variables with Jinja2 Filters

12
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Objectives

● Use Jinja2 filters to process and reformat the values of variables.

13
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Jinja2 Filters

● Jinja2 expressions support 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, although that is beyond the scope of this course.

● 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.

14
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Processing Data with Jinja2 Filters
● 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, and you have the following Jinja2 statement:

{{ myname | capitalize }}

● James will be the result of the Jinja2 expansion.

15
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Multiple filters
● The next example shows multiple filters used together
● The unique filter gets a unique set of items in a list, removing duplicates
● The sort filter sorts a list of items
- name: Multiple filter example
hosts: localhost
● The play at right filters mylist through two vars:
filters, unique and sort mylist:
- 3
- 9
● The resulting output will be the list below: - 1
- 7
-1 - 9
-3 tasks:
-7 - name: Display sorted list of unique items
-9 debug:
msg: "{{ mylist | unique | sort }}"

16
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: The ipaddr Filter
● As an example, the ipaddr filter can perform a number of operations on IP addresses

● If passed a single IP address, it will return

- name: Multiple filter example
True if it is in the right format and False if
hosts: localhost
it is not vars:
mylist:
● If passed a list of IP addresses, it will return - 192.0.2.1
- 10.0.0.1
a list of the ones that are valid. - 304.252.1.200
● If you run the play at right, the results would tasks:
be: - name: Display list of valid addresses
debug:
msg: "{{ mylist | ipaddr }}"
- 192.0.2.1
- 10.0.0.1

17
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: The ipaddr Filter
● A more complex example actually uses ipaddr to reformat the output

● You can use an option in parentheses to

- name: Multiple filter example
tell the filter to convert a network and
hosts: localhost
netmask from host and VLSN notation vars:
to CIDR network and prefix notation mylist:
- 192.0.2.1/255.255.255.0
- 10.0.0.1/255.255.255.128
● If you run the play at right, the following - 10.0.0.200/255.255.255.128
output will result: tasks:
- name: Display list of CIDR networks
- 192.0.2.0/24 debug:
- 10.0.0.0/25 msg: "{{ mylist | ipaddr('network/prefix')
- 10.0.0.128/25 }}"

● Note that this actually changed the

format of the value displayed, not
just its order or which items appear
18
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Processing Variables with Jinja2 Filters

Important

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.

● There are a large number of filters available, both as standard filters from Jinja2 and as additional
filters provided by Ansible, too many to cover in a few minutes.

● A small selection of the filters you should investigate on your own include:

● Learn more by reviewing the documentation at

https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html
19
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Templating External Data with
Lookup Plugins

20
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Objectives

● Use lookup plugins to template external data within Jinja2 templates

21
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Using Lookup Plugins to Import Data

● 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

22
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 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:

The example at right will use - name: Example of a lookup plugin in use
the dig lookup plugin to look hosts: all
vars:
up the DNS MX records for mxvar: "{{ query('dig', 'gmail.com', 'qtype=MX') }}"
gmail.com and returns a list tasks:
where each item is one record. - name: List each MX record for gmail.com
debug:
msg: An MX record is: {{ item }}
It then prints the list one item loop: "{{ mxvar }}"
at a time.

23
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: File Lookups

● The file lookup plugin can be used to load the contents of a file into a variable
● If you provide a relative path, the plugin looks for files in the playbook's files directory

The play at right will look use the - name: Add authorized keys
authorized_key module to copy the hosts: all
contents of files/naoko.key.pub vars:
users:
into the ~naoko/.ssh/authorized_keys - naoko
file for user naoko on each managed tasks:
host. - name: Add authorized keys
authorized_key:
user: "{{ item }}"
We use the lookup plugin because the key: "{{ lookup('file', item + '.key.pub') }}"
value of key must be her actual public loop: "{{ users }}"
key, not a file name.

24
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: Command Output Lookups with Lines as Items

● 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

The example task at right uses - name: Print the name of each account in /etc/passwd
lines to build a list consisting of debug:
the lines in the /etc/passwd file. msg: A user is {{ item | regex_replace(':.*$') }}
loop: "{{ query('lines', 'cat /etc/passwd') }}"

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.

25
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: Template Lookups

● The template lookup plugin will take a Jinja2 template and evaluate that when setting the value.
● If you pass a relative path to the template, Ansible will look in the playbook's templates directory.

● For example, assume that templates/my.template.j2 has the content: Hello {{ my_name }}!

The example play on the right - name: Print "Hello class!"

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

26
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Example: 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'] }}"

27
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.
 Learning More about Lookup Plugins

● There are many more lookup plugins available.

● Remember to use ansible-doc -t lookup commands to find useful documentation.

● Lookup plugins are powerful, especially once you are skilled at using variables and filters

28
©2020 Red Hat, Inc., licensed to Pluralsight, LLC. All trademarks, service marks, and logos used herein are the property of their respective owners.