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.
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>`_.
..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::
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.
When you need a randomly generated value, use one of these filters.
.._random_mac_filter:
.._random_mac_filter:
Random MAC addresses
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.
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'::
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'
# => '52:54:00:ef:1c:03'
Note that if anything is wrong with the prefix string, the filter will issue an error.
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::
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:
.._ipaddr_filter:
IP address filters
IP address filters
@ -932,17 +946,17 @@ IP address filters
To test if a string is a valid IP address::
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::
You can also require a specific IP protocol version::
{{ myvar | ipv4 }}
{{ myvar | ansible.netcommon.ipv4 }}
{{ myvar | ipv6 }}
{{ myvar | ansible.netcommon.ipv6 }}
IP address filter can also be used to extract specific information from an IP
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::
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
The ``parse_xml`` filter will load the spec file and pass the command output
through formatted as JSON.
through formatted as JSON.
@ -1143,7 +1157,8 @@ is an XPath expression used to get the attributes of the ``vlan`` tag in output
</configuration>
</configuration>
</rpc-reply>
</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
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
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,
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
IPv4 and IPv6 addresses in various forms. There are also additional functions
available to manipulate IP subnets and MAC addresses.
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
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).
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
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
..code-block:: none
{{ '192.0.2.0' | ipaddr }}
{{ '192.0.2.0' | ansible.netcommon.ipaddr }}
You can also pass the values as variables::
You can also pass the values as variables::
{{ myvar | ipaddr }}
{{ myvar | ansible.netcommon.ipaddr }}
Here are some example test results of various input strings::
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::
Example use of an IPv4 filter::
{{ myvar | ipv4 }}
{{ myvar | ansible.netcommon.ipv4 }}
A similar example of an IPv6 filter::
A similar example of an IPv6 filter::
{{ myvar | ipv6 }}
{{ myvar | ansible.netcommon.ipv6 }}
Here's some example test results to look for IPv4 addresses::
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:
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
..code-block:: jinja
# Jinja2 template
# Jinja2 template
{% set ipv4_host = host_prefix | unique | ipv4('host/prefix') | first %}
{% set ipv4_host = host_prefix | unique | ansible.netcommon.ipv4('host/prefix') | first %}