Ansible Filters and Lookups
Raw data rarely arrives in the exact shape a task needs. A name may need capital letters, a list may need sorting, and a password may sit in a file on the control node. Filters reshape data, and lookups fetch data from outside the playbook. Picture a kitchen: a filter is the peeler that prepares a vegetable, and a lookup is the trip to the pantry that brings the vegetable to the counter.
Filters Transform Values
Ansible uses the Jinja2 filter syntax. A pipe symbol sends a value into a filter, and the filter returns a new value.
{{ value | filter_name }}
{{ value | filter_name(argument) }}
Diagram: The Filter Pipeline
" web-SERVER-01 "
│
▼ | trim
"web-SERVER-01"
│
▼ | lower
"web-server-01"
│
▼ | replace('-', '_')
"web_server_01"
- ansible.builtin.debug:
msg: "{{ ' web-SERVER-01 ' | trim | lower | replace('-', '_') }}"
Everyday Filters
| Filter | Example | Result |
|---|---|---|
| default | {{ port | default(80) }} | 80 when port is missing |
| upper / lower | {{ 'abc' | upper }} | ABC |
| length | {{ [1,2,3] | length }} | 3 |
| join | {{ ['a','b'] | join(',') }} | a,b |
| sort | {{ [3,1,2] | sort }} | [1, 2, 3] |
| unique | {{ [1,1,2] | unique }} | [1, 2] |
| int | {{ '42' | int }} | 42 |
| to_nice_yaml | {{ config | to_nice_yaml }} | Readable YAML text |
| basename | {{ '/etc/nginx/nginx.conf' | basename }} | nginx.conf |
The Default Filter Prevents Failures
An undefined variable stops a play with an error. The default filter supplies a fallback value.
- ansible.builtin.debug:
msg: "Listening on {{ http_port | default(8080) }}"
Use default(omit) inside a module option to skip that option entirely when the variable is undefined.
List and Dictionary Filters
vars:
servers:
- { name: web1, cpu: 4 }
- { name: web2, cpu: 8 }
- { name: db1, cpu: 16 }
tasks:
- ansible.builtin.debug:
msg: "{{ servers | map(attribute='name') | list }}"
- ansible.builtin.debug:
msg: "{{ servers | selectattr('cpu', 'gt', 4) | map(attribute='name') | list }}"
The first task prints ['web1', 'web2', 'db1']. The second prints ['web2', 'db1']. The map filter pulls one field from every item, and selectattr keeps only items that match a test.
Network and Security Filters
{{ '192.168.1.10/24' | ansible.utils.ipaddr('address') }}
{{ 'MySecret' | password_hash('sha512') }}
{{ 'hello' | b64encode }}
{{ 'hello' | hash('sha256') }}
Lookups Fetch Outside Data
A lookup runs on the control node and returns data to the playbook. Use the lookup function with a plugin name and arguments.
| Plugin | Purpose | Example |
|---|---|---|
| file | Read a file | lookup('file', '~/.ssh/id_rsa.pub') |
| env | Read an environment variable | lookup('env', 'HOME') |
| pipe | Run a command locally | lookup('pipe', 'date +%F') |
| password | Generate and store a password | lookup('password', 'creds/db length=20') |
| url | Fetch a web address | lookup('url', 'https://example.com/data.txt') |
| fileglob | List files by pattern | lookup('fileglob', 'files/*.conf') |
- name: Add a public key to a user
ansible.posix.authorized_key:
user: deploy
key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
Lookup Versus Query
The lookup function returns a comma separated string by default. The query function always returns a list, which suits loops.
loop: "{{ query('fileglob', 'files/*.conf') }}"
Try This
Create a variable holding a list of three dictionaries with name and size fields. Print only the names of items larger than a chosen number. Add a lookup that reads today's date through the pipe plugin and join it into the output sentence.
Summary
Filters reshape values inside a template or task, and a pipe chains several filters in sequence. The default filter guards against missing variables. Lookups read files, environment variables, command output, and web data from the control node. Use query instead of lookup when a loop expects a list.
