2 practical ways to use filters to manipulate data in Ansible

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 and AnsibleUnicode). 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 the when 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.