Add ipwrap filter plugin (#118)

Add ipwrap filter plugin

SUMMARY


ISSUE TYPE


New Module Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

Reviewed-by: Priyam Sahoo <None>
Reviewed-by: Sagar Paul <sagpaul@redhat.com>
Reviewed-by: None <None>

README.md

@@ -25,6 +25,7 @@ Name | Description
 [ansible.utils.from_xml](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.from_xml_filter.rst)|Convert given XML string to native python dictionary.
 [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_filter.rst)|Retrieve the value in a variable using a path
 [ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_filter.rst)|Find the indices of items in a list matching some criteria
+[ansible.utils.ipwrap](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipwrap_filter.rst)|This filter is designed to Wrap IPv6 addresses in [ ] brackets.
 [ansible.utils.network_in_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_usable_filter.rst)|The network_in_usable filter returns whether an address passed as an argument is usable in a network.
 [ansible.utils.network_in_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_network_filter.rst)|This filter returns whether an address or a network passed as argument is in a network.
 [ansible.utils.next_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.next_nth_usable_filter.rst)|This filter returns the next nth usable ip within a network described by value.

changelogs/fragments/add_ipwrap_filter_plugin.yaml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - Add ipwrap filter plugin.

docs/ansible.utils.ipwrap_filter.rst

@@ -0,0 +1,198 @@
+.. _ansible.utils.ipwrap_filter:
+
+
+********************
+ansible.utils.ipwrap
+********************
+
+**This filter is designed to Wrap IPv6 addresses in [ ] brackets.**
+
+
+Version added: 2.5.0
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- Some configuration files require IPv6 addresses to be "wrapped" in square brackets ([ ]).To accomplish that,
+- you can use the ipwrap() filter.It will wrap all IPv6 addresses and leave any other strings intact.
+
+
+
+
+Parameters
+----------
+
+.. raw:: html
+
+    <table  border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th colspan="1">Parameter</th>
+            <th>Choices/<font color="blue">Defaults</font></th>
+                <th>Configuration</th>
+            <th width="100%">Comments</th>
+        </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>query</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                    </div>
+                </td>
+                <td>
+                        <b>Default:</b><br/><div style="color: blue">""</div>
+                </td>
+                    <td>
+                    </td>
+                <td>
+                        <div>You can provide a single argument to each ipwrap() filter.</div>
+                        <div>The filter will then treat it as a query and return values modified by that query.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>value</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">list</span>
+                         / <span style="color: purple">elements=string</span>
+                         / <span style="color: red">required</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                    <td>
+                    </td>
+                <td>
+                        <div>list of subnets or individual address or any other values input. Example. [&#x27;192.24.2.1&#x27;, &#x27;host.fqdn&#x27;, &#x27;::1&#x27;, &#x27;192.168.32.0/24&#x27;, &#x27;fe80::100/10&#x27;, True, &#x27;&#x27;, &#x27;42540766412265424405338506004571095040/64&#x27;]</div>
+                </td>
+            </tr>
+    </table>
+    <br/>
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml
+
+    #### examples
+    # Ipwrap filter plugin o Wrap IPv6 addresses in [ ] brackets.
+    - name: Set value as input list
+      ansible.builtin.set_fact:
+        value:
+          - 192.24.2.1
+          - host.fqdn
+          - ::1
+          - ''
+          - 192.168.32.0/24
+          - fe80::100/10
+          - 42540766412265424405338506004571095040/64
+          - True
+    - debug:
+        msg: "{{ value|ansible.utils.ipwrap }}"
+
+    - name: |
+            ipwrap() did not filter out non-IP address values, which is usually what you want when for example
+            you are mixing IP addresses with hostnames. If you still want to filter out all non-IP address values,
+            you can chain both filters together.
+      debug:
+        msg: "{{ value|ansible.utils.ipaddr|ansible.utils.ipwrap  }}"
+
+    # PLAY [Ipwrap filter plugin o Wrap IPv6 addresses in [ ] brackets.] ***************************************************
+    # TASK [Set value as input list] ***************************************************************************************
+    # ok: [localhost] => {"ansible_facts": {"value": ["192.24.2.1", "host.fqdn", "::1", "", "192.168.32.0/24",
+    # "fe80::100/10", "42540766412265424405338506004571095040/64", true]}, "changed": false}
+    #
+    # TASK [debug] ********************************************************************************************************
+    # ok: [localhost] => {
+    #     "msg": [
+    #         "192.24.2.1",
+    #         "::1",
+    #         "192.168.32.0/24",
+    #         "fe80::100/10",
+    #         "2001:db8:32c:faad::/64"
+    #     ]
+    # }
+    #
+    # TASK [debug] ************************************************************************************************
+    # ok: [localhost] => {
+    #     "msg": [
+    #         "192.24.2.1",
+    #         "host.fqdn",
+    #         "[::1]",
+    #         "",
+    #         "192.168.32.0/24",
+    #         "[fe80::100]/10",
+    #         "[2001:db8:32c:faad::]/64",
+    #         "True"
+    #     ]
+    # }
+    #
+    # TASK [ipwrap() did not filter out non-IP address values, which is usually what you want when for example
+    # you are mixing IP addresses with hostnames. If you still want to filter out all non-IP address values,
+    # you can chain both filters together.] ***
+    # ok: [localhost] => {
+    #     "msg": [
+    #         "192.24.2.1",
+    #         "[::1]",
+    #         "192.168.32.0/24",
+    #         "[fe80::100]/10",
+    #         "[2001:db8:32c:faad::]/64"
+    #     ]
+    # }
+
+
+
+Return Values
+-------------
+Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this filter:
+
+.. raw:: html
+
+    <table border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th colspan="1">Key</th>
+            <th>Returned</th>
+            <th width="100%">Description</th>
+        </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="return-"></div>
+                    <b>data</b>
+                    <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
+                    <div style="font-size: small">
+                      <span style="color: purple">list</span>
+                       / <span style="color: purple">elements=string</span>
+                    </div>
+                </td>
+                <td></td>
+                <td>
+                            <div>Returns list with values valid for a particular query.</div>
+                    <br/>
+                </td>
+            </tr>
+    </table>
+    <br/><br/>
+
+
+Status
+------
+
+
+Authors
+~~~~~~~
+
+- Ashwini Mhatre (@amhatre)
+
+
+.. hint::
+    Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

plugins/filter/ipwrap.py

@@ -0,0 +1,199 @@
+# -*- coding: utf-8 -*-
+# Copyright 2021 Red Hat
+# GNU General Public License v3.0+
+# (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+filter plugin file for ipaddr filters: ipwrap
+"""
+from __future__ import absolute_import, division, print_function
+from functools import partial
+import types
+from ansible_collections.ansible.utils.plugins.plugin_utils.base.ipaddr_utils import (
+    ipaddr,
+    _need_netaddr,
+)
+from ansible.errors import AnsibleFilterError
+from ansible_collections.ansible.utils.plugins.module_utils.common.argspec_validate import (
+    AnsibleArgSpecValidator,
+)
+
+__metaclass__ = type
+
+
+try:
+    from jinja2.filters import pass_environment
+except ImportError:
+    from jinja2.filters import environmentfilter as pass_environment
+
+try:
+    import netaddr
+
+    HAS_NETADDR = True
+except ImportError:
+    # in this case, we'll make the filters return error messages (see bottom)
+    HAS_NETADDR = False
+else:
+
+    class mac_linux(netaddr.mac_unix):
+        pass
+
+    mac_linux.word_fmt = "%.2x"
+
+DOCUMENTATION = """
+    name: ipwrap
+    author: Ashwini Mhatre (@amhatre)
+    version_added: "2.5.0"
+    short_description: This filter is designed to Wrap IPv6 addresses in [ ] brackets.
+    description:
+    - Some configuration files require IPv6 addresses to be "wrapped" in square brackets ([ ]).To accomplish that,
+    - you can use the ipwrap() filter.It will wrap all IPv6 addresses and leave any other strings intact.
+    options:
+        value:
+            description:
+            - list of subnets or individual address or any other values input. Example. ['192.24.2.1', 'host.fqdn',
+              '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
+            type: list
+            elements: str
+            required: True
+        query:
+            description:
+            - You can provide a single argument to each ipwrap() filter.
+            - The filter will then treat it as a query and return values modified by that query.
+            type: str
+            default: ''
+    notes:
+"""
+
+EXAMPLES = r"""
+#### examples
+# Ipwrap filter plugin o Wrap IPv6 addresses in [ ] brackets.
+- name: Set value as input list
+  ansible.builtin.set_fact:
+    value:
+      - 192.24.2.1
+      - host.fqdn
+      - ::1
+      - ''
+      - 192.168.32.0/24
+      - fe80::100/10
+      - 42540766412265424405338506004571095040/64
+      - True
+- debug:
+    msg: "{{ value|ansible.utils.ipwrap }}"
+
+- name: |
+        ipwrap() did not filter out non-IP address values, which is usually what you want when for example
+        you are mixing IP addresses with hostnames. If you still want to filter out all non-IP address values,
+        you can chain both filters together.
+  debug:
+    msg: "{{ value|ansible.utils.ipaddr|ansible.utils.ipwrap  }}"
+
+# PLAY [Ipwrap filter plugin o Wrap IPv6 addresses in [ ] brackets.] ***************************************************
+# TASK [Set value as input list] ***************************************************************************************
+# ok: [localhost] => {"ansible_facts": {"value": ["192.24.2.1", "host.fqdn", "::1", "", "192.168.32.0/24",
+# "fe80::100/10", "42540766412265424405338506004571095040/64", true]}, "changed": false}
+#
+# TASK [debug] ********************************************************************************************************
+# ok: [localhost] => {
+#     "msg": [
+#         "192.24.2.1",
+#         "::1",
+#         "192.168.32.0/24",
+#         "fe80::100/10",
+#         "2001:db8:32c:faad::/64"
+#     ]
+# }
+#
+# TASK [debug] ************************************************************************************************
+# ok: [localhost] => {
+#     "msg": [
+#         "192.24.2.1",
+#         "host.fqdn",
+#         "[::1]",
+#         "",
+#         "192.168.32.0/24",
+#         "[fe80::100]/10",
+#         "[2001:db8:32c:faad::]/64",
+#         "True"
+#     ]
+# }
+#
+# TASK [ipwrap() did not filter out non-IP address values, which is usually what you want when for example
+# you are mixing IP addresses with hostnames. If you still want to filter out all non-IP address values,
+# you can chain both filters together.] ***
+# ok: [localhost] => {
+#     "msg": [
+#         "192.24.2.1",
+#         "[::1]",
+#         "192.168.32.0/24",
+#         "[fe80::100]/10",
+#         "[2001:db8:32c:faad::]/64"
+#     ]
+# }
+
+"""
+
+RETURN = """
+  data:
+    type: list
+    elements: str
+    description:
+      - Returns list with values valid for a particular query.
+"""
+
+
+@pass_environment
+def _ipwrap(*args, **kwargs):
+    """This filter is designed to Wrap IPv6 addresses in [ ] brackets."""
+    keys = ["value"]
+    data = dict(zip(keys, args[1:]))
+    data.update(kwargs)
+    aav = AnsibleArgSpecValidator(
+        data=data, schema=DOCUMENTATION, name="ipwrap"
+    )
+    valid, errors, updated_data = aav.validate()
+    if not valid:
+        raise AnsibleFilterError(errors)
+    return ipwrap(**updated_data)
+
+
+def ipwrap(value, query=""):
+    try:
+        if isinstance(value, (list, tuple, types.GeneratorType)):
+            _ret = []
+            for element in value:
+                if ipaddr(element, query, version=False, alias="ipwrap"):
+                    _ret.append(ipaddr(element, "wrap"))
+                else:
+                    _ret.append(element)
+
+            return _ret
+        else:
+            _ret = ipaddr(value, query, version=False, alias="ipwrap")
+            if _ret:
+                return ipaddr(_ret, "wrap")
+            else:
+                return value
+
+    except Exception:
+        return value
+
+
+class FilterModule(object):
+    """IP address and network manipulation filters
+    """
+
+    filter_map = {
+        # IP addresses and networks
+        "ipwrap": _ipwrap
+    }
+
+    def filters(self):
+        """ ipwrap filter """
+        if HAS_NETADDR:
+            return self.filter_map
+        else:
+            return dict(
+                (f, partial(_need_netaddr, f)) for f in self.filter_map
+            )

tests/integration/targets/utils_ipaddr_filter/tasks/ipwrap.yaml

@@ -0,0 +1,19 @@
+---
+- name: set ipaddress list
+  ansible.builtin.set_fact:
+    value:
+      - 192.24.2.1
+      - host.fqdn
+      - ::1
+      - 192.168.32.0/24
+      - fe80::100/10
+      - "42540766412265424405338506004571095040/64"
+      - True
+
+- name: ipwrap filter
+  ansible.builtin.set_fact:
+    result1: "{{ value|ansible.utils.ipwrap }}"
+
+- name: Assert result for ipwrap.
+  assert:
+    that: "{{ result1 == ipwrap_result1 }}"

tests/integration/targets/utils_ipaddr_filter/vars/main.yaml

@@ -12,6 +12,15 @@ result2_val:
 result3_val:
     - "192.24.2.1"
 
+ipwrap_result1:
+    - "192.24.2.1"
+    - "host.fqdn"
+    - "[::1]"
+    - "192.168.32.0/24"
+    - "[fe80::100]/10"
+    - "[2001:db8:32c:faad::]/64"
+    - "True"
+    
 ipv6_result1:
     - "::ffff:192.168.32.0/120"
     - "::ffff:192.24.2.1/128"

tests/unit/plugins/filter/test_ipwrap.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+# Copyright 2021 Red Hat
+# GNU General Public License v3.0+
+# (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+Unit test file for ipwrap filter plugin
+"""
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+import unittest
+from ansible_collections.ansible.utils.plugins.filter.ipwrap import _ipwrap
+
+
+VALID_DATA = [
+    "192.24.2.1",
+    "host.fqdn",
+    "::1",
+    "",
+    "192.168.32.0/24",
+    "fe80::100/10",
+    "42540766412265424405338506004571095040/64",
+    True,
+]
+
+
+VALID_OUTPUT = [
+    "192.24.2.1",
+    "host.fqdn",
+    "[::1]",
+    "",
+    "192.168.32.0/24",
+    "[fe80::100]/10",
+    "[2001:db8:32c:faad::]/64",
+    "True",
+]
+
+
+class TestIpWrap(unittest.TestCase):
+    def setUp(self):
+        pass
+
+    def test_valid_data_list(self):
+        """Check passing valid argspec(list)"""
+        args = ["", VALID_DATA, ""]
+        result = _ipwrap(*args)
+        print(result)
+        self.assertEqual(result, VALID_OUTPUT)
+
+    def test_valid_data_string(self):
+        """Check passing valid argspec(string)"""
+
+        args = ["", "::1", ""]
+        result = _ipwrap(*args)
+        self.assertEqual(result, ["[::1]"])