Sometimes you end up with a complex data structure in JSON format and you need to extract only a small set of data within it. The **json_query** filter lets you query a complex JSON structure and iterate over it using a loop structure.
..note::
This filter has migrated to the `community.general <https://galaxy.ansible.com/community/general>`_ collection. Follow the installation instructions to install that collection.
..note:: This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples <http://jmespath.org/examples.html>`_.
Consider this data structure::
@ -703,21 +708,21 @@ To extract all clusters from this structure, you can use the following query::
When you need a randomly generated value, use one of these filters.
.._random_mac_filter:
Random MAC addresses
@ -764,9 +770,13 @@ Random MAC addresses
This filter can be used to generate a random MAC address from a string prefix.
..note::
This filter has migrated to the `community.general <https://galaxy.ansible.com/community/general>`_ collection. Follow the installation instructions to install that collection.
To get a random MAC address from a string prefix starting with '52:54:00'::
"{{ '52:54:00' | random_mac }}"
"{{ '52:54:00' | community.general.random_mac }}"
# => '52:54:00:ef:1c:03'
Note that if anything is wrong with the prefix string, the filter will issue an error.
@ -775,7 +785,7 @@ Note that if anything is wrong with the prefix string, the filter will issue an
As of Ansible version 2.9, you can also initialize the random number generator from a seed. This way, you can create random-but-idempotent MAC addresses::
These filters have migrated to the `ansible.netcommon <https://galaxy.ansible.com/ansible/netcommon>`_ collection. Follow the installation instructions to install that collection.
.._ipaddr_filter:
IP address filters
@ -932,17 +946,17 @@ IP address filters
To test if a string is a valid IP address::
{{ myvar | ipaddr }}
{{ myvar | ansible.netcommon.ipaddr }}
You can also require a specific IP protocol version::
{{ myvar | ipv4 }}
{{ myvar | ipv6 }}
{{ myvar | ansible.netcommon.ipv4 }}
{{ myvar | ansible.netcommon.ipv6 }}
IP address filter can also be used to extract specific information from an IP
address. For example, to get the IP address itself from a CIDR, you can use::
The ``parse_xml`` filter will load the spec file and pass the command output
through formatted as JSON.
@ -1143,7 +1157,8 @@ is an XPath expression used to get the attributes of the ``vlan`` tag in output
</configuration>
</rpc-reply>
..note:: For more information on supported XPath expressions, see `<https://docs.python.org/2/library/xml.etree.elementtree.html#xpath-support>`_.
..note::
For more information on supported XPath expressions, see `XPath Support <https://docs.python.org/2/library/xml.etree.elementtree.html#xpath-support>`_.
Network VLAN filters
--------------------
@ -1160,7 +1175,7 @@ sorted string list of integers according to IOS-like VLAN list rules. This list
@ -1584,10 +1599,14 @@ To format a date using a string (like with the shell date command), use the "str
Kubernetes filters
==================
..note::
These filters have migrated to the `community.kubernetes <https://galaxy.ansible.com/community/kubernetes>`_ collection. Follow the installation instructions to install that collection.
Use the "k8s_config_resource_name" filter to obtain the name of a Kubernetes ConfigMap or Secret,
@ -14,6 +14,10 @@ the input data to extract requested information. ``ipaddr()`` works with both
IPv4 and IPv6 addresses in various forms. There are also additional functions
available to manipulate IP subnets and MAC addresses.
..note::
The ``ipaddr()`` filter migrated to the `ansible.netcommon <https://galaxy.ansible.com/ansible/netcommon>`_ collection. Follow the installation instructions to install that collection.
To use this filter in Ansible, you need to install the `netaddr`_ Python library on
a computer on which you use Ansible (it is not required on remote hosts).
It can usually be installed with either your system package manager or using
@ -37,11 +41,11 @@ filters. To use the filter, pass a string to it:
..code-block:: none
{{ '192.0.2.0' | ipaddr }}
{{ '192.0.2.0' | ansible.netcommon.ipaddr }}
You can also pass the values as variables::
{{ myvar | ipaddr }}
{{ myvar | ansible.netcommon.ipaddr }}
Here are some example test results of various input strings::
@ -66,11 +70,11 @@ type, ``ipaddr()`` filter has two "aliases", ``ipv4()`` and ``ipv6()``.
Example use of an IPv4 filter::
{{ myvar | ipv4 }}
{{ myvar | ansible.netcommon.ipv4 }}
A similar example of an IPv6 filter::
{{ myvar | ipv6 }}
{{ myvar | ansible.netcommon.ipv6 }}
Here's some example test results to look for IPv4 addresses::
@ -98,13 +102,13 @@ valid for a particular query::
In Debian-based systems, the network configuration stored in the ``/etc/network/interfaces`` file uses a combination of IP address, network address, netmask and broadcast address to configure an IPv4 network interface. We can get these values from a single 'host/prefix' combination:
@ -251,12 +255,12 @@ In Debian-based systems, the network configuration stored in the ``/etc/network/
..code-block:: jinja
# Jinja2 template
{% set ipv4_host = host_prefix | unique | ipv4('host/prefix') | first %}
{% set ipv4_host = host_prefix | unique | ansible.netcommon.ipv4('host/prefix') | first %}