Image
2 practical ways to use filters to manipulate data in Ansible
Ansible filters are a powerful feature that lets you assign values to variables, convert variable data types, and more.
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:
- Assign a default value to a variable if the content was not explicitly provided.
- Convert the data type of a variable.
- Handle internet protocol (IP) addresses and networks.
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.
1. Assign a value to a variable when it was not provided
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.
2. Convert the data type of a variable
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:
- TASK A shows the data types for the variables (
int
andAnsibleUnicode
). For this scenario, consider it the same as a string. - TASK B converts the data types using Jinja filters.
- TASK C shows the converted data types. (Surprise! Both show up as
str
because the Jinja assignment results in strings.) - TASK D shows the message because I am using the variable
my_orig_1
directly in thewhen
condition without converting it with a Jinja filter. - TASK E is skipped because the pure data type
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.
Wrap up
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.
Image
Although YAML is considered easy to understand, its syntax can be quite confusing. Use this guide to the basics.
Image
Get your infrastructure running quickly and reliably by automating your configuration using Jinja2 templates for Ansible.
Image
Learn how to use variables on the command line to pass data into your Ansible playbook at runtime.
Image
Learn to use a Jinja2 plugin to handle network configurations in server-provisioning playbooks.
Topics:
Ansible
Automation
Roberto Nozaki
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