Image
![IT Automation ebook](/sysadmin/sites/default/files/styles/image_cta/public/2021-07/automation-expert-e-book-medium.jpg?itok=X_OfbjdH)
Photo by Marcos Paulo Prado on Unsplash
Filters are a very powerful feature in Ansible that allow you to manipulate data in many different ways.
[ Download now: A system administrator's guide to IT automation. ]
Using filters, you can do things such as:
Filters also allow you to manage other settings. I will cover some of them in future articles, like converting from lists to dictionaries and vice-versa, converting data to and from JSON and YAML, and more.
This article looks at some practical ways you can use filters.
For this example, I will use the following simple Ansible playbook:
---
- name: Basic filters
hosts: localhost
gather_facts: False
tasks:
- name: Validate argument
ansible.builtin.set_fact:
my_var: "{{ my_var | default('N/A') }}"
- name: Demonstrate a basic filter
ansible.builtin.debug:
msg:
- "1. Environment variable provided: {{ my_var }}"
- "2. Variable type................: {{ my_var | type_debug }}"
If I execute it without any parameters, I see this output:
ansible-playbook 01_basic_filter.yml
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
PLAY [Basic filters] ***************************************************************
TASK [Validate argument] ***********************************************************
ok: [localhost]
TASK [Demonstrate a basic filter] **************************************************
ok: [localhost] => {
"msg": [
"1. Environment variable provided: N/A",
"2. Variable type................: str"
]
}
PLAY RECAP ***************************************************************
localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
I use the filter to assign the string N/A
when the parameter is not provided and later use the type_debug
filter to show that the data type is str
.
[ Get started with IT automation with the Ansible Automation Platform beginner's guide. ]
Now I'll execute it again, this time providing extra-var
as the parameter:
ansible-playbook 01_basic_filter.yml -e my_var=ABC
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
PLAY [Basic filters] ***************************************************************
TASK [Validate argument] ***********************************************************
ok: [localhost]
TASK [Demonstrate a basic filter] **************************************************
ok: [localhost] => {
"msg": [
"1. Environment variable provided: ABC",
"2. Variable type................: str"
]
}
PLAY RECAP ***************************************************************
localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
The expected ABC
value is displayed, and not surprisingly the variable type is str
.
Something less intuitive happens when I pass a numeric value as the argument. It's beyond the scope of this article to discuss the reasons for this, but a numeric extra-var
also has the type str
. Be aware of this if your variable must be treated as an integer type.
In the previous example, I mentioned a situation where a certain variable does not have the data type you might expect.
[ Download now: A sysadmin's guide to Bash scripting. ]
This one is only a theoretical exercise to discuss data types and conversions, not an example of Ansible coding:
---
- name: Convert to int
hosts: localhost
gather_facts: False
vars:
my_orig_1: 101
my_orig_2: '102'
tasks:
- name: A - Show original data types
ansible.builtin.debug:
msg:
- "1. my_orig_1: {{ my_orig_1 }} is type {{ my_orig_1 | type_debug }}"
- "2. my_orig_2: {{ my_orig_2 }} is type {{ my_orig_2 | type_debug }}"
- name: B - Convert data types
ansible.builtin.set_fact:
my_conv_1: "{{ my_orig_1 | int }}"
my_conv_2: "{{ my_orig_2 | int }}"
- name: C - Show converted data types
ansible.builtin.debug:
msg:
- "1. my_conv_1: {{ my_conv_1 }} is type {{ my_conv_1 | type_debug }}"
- "2. my_conv_2: {{ my_conv_2 }} is type {{ my_conv_2 | type_debug }}"
- name: D - Use original value 1 in a when condition
ansible.builtin.debug:
msg: "The data type is int for my_orig_1"
when: (my_orig_1 | type_debug) == 'int'
- name: E - Use original value 2 in a when condition
ansible.builtin.debug:
msg: "The data type is int for my_orig_2"
when: (my_orig_2 | type_debug) == 'int'
...
The output looks like this:
ansible-playbook 02_convert_to_int.yml
PLAY [Convert to int] ***************************************************************
TASK [A - Show original data types] ***************************************************************
ok: [localhost] => {
"msg": [
"1. my_orig_1: 101 is type int",
"2. my_orig_2: 102 is type AnsibleUnicode"
]
}
TASK [B - Convert data types] ***************************************************************
ok: [localhost]
TASK [C - Show converted data types] ***************************************************************
ok: [localhost] => {
"msg": [
"1. my_conv_1: 101 is type str",
"2. my_conv_2: 102 is type str"
]
}
TASK [D - Use original value 1 in a when condition] **************************************************************
ok: [localhost] => {
"msg": "The data type is int for my_orig_1"
}
TASK [E - Use original value 2 in a when condition] **************************************************************
skipping: [localhost]
PLAY RECAP
**************************************************************
localhost : ok=4 changed=0 unreachable=0 failed=0 skipped=1 rescued=0 ignored=0
In this output:
int
and AnsibleUnicode
). For this scenario, consider it the same as a string.str
because the Jinja assignment results in strings.)my_orig_1
directly in the when
condition without converting it with a Jinja filter.my_orig_2
is a string.This is tricky, but the lesson here is that if I need to use a real data type in a variable, I must apply the filter directly. In this case, it was in the when
condition, but the idea is the same if I am doing a math operation such as:
---
- name: Simple math
hosts: localhost
gather_facts: False
vars:
my_var_received_as_str: '40' # Suppose I received this as a str (from a role, filter etc)
tasks:
- name:
ansible.builtin.debug:
msg: "{{ (my_var_received_as_str | int) + 2 }}"
This is a simple example that assumes I receive a variable from a source, I cannot control its data type, and it is a string.
[ Learn more about automation at the edge. ]
For the addition done in the last line, I must first convert it to int
, then add the number.
This is okay if I only want to show the result. But if I had to assign the result to another variable using the set_fact
module, then the result's data type would be a string.
This means that if I can't control or guarantee a variable's data type, I may need to convert it in every math calculation or conditionals using that variable.
I've just scratched the surface of what the Jinja filter in Ansible can do. Once you know how the filter works, you'll probably find yourself thinking, "there must have a filter to do this data transformation for me," and usually there is. Stay tuned for my next article, about handling network configuration with Ansible filters.
Roberto Nozaki (RHCSA/RHCE/RHCA) is an Automation Principal Consultant at Red Hat Canada where he specializes in IT automation with Ansible. More about me