ansible.utils.to_paths – Flatten a complex object into a dictionary of paths and values

Note

This plugin is part of the ansible.utils collection (version 2.4.3).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.utils.

To use it in a playbook, specify: ansible.utils.to_paths.

New in version 1.0.0: of ansible.utils

Synopsis

  • Flatten a complex object into a dictionary of paths and values.

  • Paths are dot delimited whenever possible.

  • Brackets are used for list indices and keys that contain special characters.

  • to_paths is also available as a filter plugin.

  • Using the parameters below- lookup('ansible.utils.to_paths', var, prepend, wantlist)

Parameters

Parameter Choices/Defaults Configuration Comments
prepend
string
Prepend each path entry. Useful to add the initial var name.
var
raw / required
The value of var will be used.
wantlist
boolean
    Choices:
  • no
  • yes
If set to True, the return value will always be a list. This can also be accomplished using query or q instead of lookup. https://docs.ansible.com/ansible/latest/plugins/lookup.html

Examples

#### Simple examples

- ansible.builtin.set_fact:
    a:
      b:
        c:
          d:
          - 0
          - 1
          e:
          - True
          - False

- ansible.builtin.set_fact:
    paths: "{{ lookup('ansible.utils.to_paths', a) }}"

# TASK [ansible.builtin.set_fact] ********************************************
# ok: [nxos101] => changed=false
#   ansible_facts:
#     paths:
#       b.c.d[0]: 0
#       b.c.d[1]: 1
#       b.c.e[0]: True
#       b.c.e[1]: False

- name: Use prepend to add the initial variable name
  ansible.builtin.set_fact:
    paths: "{{ lookup('ansible.utils.to_paths', a, prepend='a') }}"

# TASK [Use prepend to add the initial variable name] **************************
# ok: [nxos101] => changed=false
#   ansible_facts:
#     paths:
#       a.b.c.d[0]: 0
#       a.b.c.d[1]: 1
#       a.b.c.e[0]: True
#       a.b.c.e[1]: False


#### Using a complex object

- name: Make an API call
  ansible.builtin.uri:
    url: "https://nxos101/restconf/data/openconfig-interfaces:interfaces"
    headers:
      accept: "application/yang.data+json"
    url_password: password
    url_username: admin
    validate_certs: False
  register: result
  delegate_to: localhost

- name: Flatten the complex object
  ansible.builtin.set_fact:
    paths: "{{ lookup('ansible.utils.to_paths', result.json) }}"

# TASK [Flatten the complex object] ******************************************
# ok: [nxos101] => changed=false
#   ansible_facts:
#     paths:
#       interfaces.interface[0].config.enabled: 'true'
#       interfaces.interface[0].config.mtu: '1500'
#       interfaces.interface[0].config.name: eth1/71
#       interfaces.interface[0].config.type: ethernetCsmacd
#       interfaces.interface[0].ethernet.config['auto-negotiate']: 'true'
#       interfaces.interface[0].ethernet.state.counters['in-crc-errors']: '0'
#       interfaces.interface[0].ethernet.state.counters['in-fragment-frames']: '0'
#       interfaces.interface[0].ethernet.state.counters['in-jabber-frames']: '0'
#       interfaces.interface[0].ethernet.state.counters['in-mac-control-frames']: '0'
#       <...>

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
string
success
A dictionary of key value pairs.
The key is the path.
The value is the value.



Authors

  • Bradley Thornton (@cidrblock)