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

FilterExampleResult
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.

PluginPurposeExample
fileRead a filelookup('file', '~/.ssh/id_rsa.pub')
envRead an environment variablelookup('env', 'HOME')
pipeRun a command locallylookup('pipe', 'date +%F')
passwordGenerate and store a passwordlookup('password', 'creds/db length=20')
urlFetch a web addresslookup('url', 'https://example.com/data.txt')
fileglobList files by patternlookup('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.