Updated June 14, 2023
Introduction to Ansible Filters
In Ansible, when we need data manipulation, processing, formatting and conversion. We have a set of filters, jinja2 template filters and custom filters created by users. In the background, filters in Ansible are from jinja2, so the input data is transformed inside a template expression. Also note that the templating happens on the Ansible controller node, not the target remote hosts. So, filters get executed on local data provided by the Ansible controller. This is helpful as in this way, the amount of data which needs to be transferred to remote hosts is lesser after processing locally, in most of the cases.
Explaining Ansible Filters
Ansible has a rich set of filters backed by jinja2 templating. We input some data into these templates and the jinja2 template engine process that data and provide the output accordingly. Filters mostly used for formatting or transforming the data. Then based on the output any other tasks are performed. Also, filtering is very useful in debugging. The list of built-in filters shipped by jinja2 can be checked from the below link, which is an official link for jinja2 template designer documentation.
The list of filters that are provided by Ansible can be checked from the below link, which is an official documentation link for Ansible playbook filters.
https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html
Templates when used with debug modules, add more verbosity and troubleshooting information to the output of a playbook. We will see these kinds of scenarios in the example section.
How does Ansible Filters Works?
We have a variety of filters in Ansible, we can use these filters in a task to transform some given data. Based on the output a decision making can be done, similarly, the output of after templating can work as input to other tasks. It’s Python in the background in which the data transformation is performed. If some templating is not supported by the Python function of python installed on the controller node, then templating will not provide the correct output.
Filtering syntax is like the below examples, where the left side is the input to templating and the right side is the filter provided by ansible. The output can be printed on-screen or can be registered in a variable.
{{ <input>| <filter> }}
Examples to Implement Ansible Filters
Now by using examples, we will try to learn about some of the popular filters, which you might have to use in day to day operations. We will take some examples, but before going there, we first understand our lab used for testing purposes. Here we have an Ansible control server named ansible-controller and two remotes hosts named host- one and host-two. We will create playbooks and run Ansible commands on the ansible-controller node and manage the users on remote hosts.
Example #1
Defaulting undefined variables is done by using filter default, which will assign the default value to a variable if this is not defined. To check this, we can make a playbook with content like below, here when we defined var_1 variable with value 5, then running it will give us the test_var variable value equal to 5
Code:
---
hosts: localhost vars:
var_1: 5 tasks:
set_fact:
test_var: "{{ var_1 | default(2) }}"
debug:
var: test_var
We will run this playbook as below:
Output:
ansible-playbook filter_mandatory.yaml
Example #2
If remove the definition of var_1 variable and make the playbook like below:
Code:
---
hosts: localhost tasks:
set_fact:
test_var: "{{ var_1 | default(2) }}"
debug:
var: test_var
Then executing it will give you the value of the test_var variable equal to 2, which is the default value.
Output:
ansible-playbook filter_mandatory.yaml
Example #3
There are some mathematics-related modules as well, like abs, int, pow, root. To check some of these, we can make a playbook with content like below:
Code:
---
hosts: localhost vars:
var_one: -2.5 tasks:
set_fact:
var_abs: "{{ var_one | abs }}" var_pow: "{{ var_one | pow(5) }}"
debug:
msg: Absolute value -2.5 is "{{ var_abs }}"
debug:
msg: Fifth power of -2.5 is "{{ var_pow }}"
Output:
ansible-playbook filter_math.yaml
Example #4
If we want to filter a list, we can use a select filter, this is used with a keyword Other filters like the list can be used along with it. To check this, we can make a playbook with content like below:
Code:
---
hosts: all tasks:
set_fact:
interfaces_list: "{{ ansible_interfaces | select('match', '^(eth|wlan)[0-9]+') | list
}}"
debug:
msg: The interface's list on "{{ ansible_hostname }}" is "{{ interfaces_list }}"
Output:
ansible-playbook filter_select_match.yaml
Example #5
To convert some string into upper or lower, we can use map To check this, we can make a playbook with content like below:
Code:
---
hosts: localhost vars:
var_one: Test-machine tasks:
debug:
msg: var_one is now {{ var_one | map('upper')| list}}
Output:
ansible-playbook filter_map.yaml
Example #6
Some filters can give you the hash of some string or data. To check this, we can make a playbook with content like below:
Code:
---
hosts: localhost vars:
var_one: apple tasks:
debug:
msg: Variable value is "{{ var_one | hash('sha1') }}"
Output:
ansible-playbook filter_hash.yaml
Similarly, there a lot of filters which can do basic string manipulation like:
To add a quote use like below
echo {{ string_value | quote }}
To use one value on true and others on false from a list of two.
{{ (name == "peter") | ternary('male’, ‘female') }}
To use one to true, another to false and third to null
{{ enabled | ternary('on’, ‘off', omit) }}
To get the last name of a file path like ‘test.ini’ from ‘/etc/test.ini’
{{ path | basename }}
There are some very useful filters like regex_search and regex_replace for searching and replacing a string from input. Also, some advance filters like k8s_config_resource_name which is useful in Kubernetes to get ConfigMap or Secret name from some input configuration or specification data. Similarly, many filters are there for handling data like a router, switch configuration. You can find some or many filters as per your needs. You just need to explore them.
Conclusion
Filters are important when you are debugging some issues with the playbook or you need to transform some data before using it on remote servers. Rich set of default filters and the ability to create one for your requirements makes the scope of usability wide enough.
Recommended Articles
This is a guide to Ansible Filters. Here we discuss an introduction to Ansible Filters, how does it work along with examples with code and output. You can also go through our other related articles to learn more –
