a-c-m
/
ansible.utils
mirror of https://github.com/ansible-collections/ansible.utils.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
ansible.utils/docs/ansible.utils.ipsubnet_filt...

290 lines
12 KiB
ReStructuredText
Raw Normal View History

Add ipsubnet filter plugin (#122) Add ipsubnet filter plugin SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nathaniel Case <this.is@nathanielca.se> Reviewed-by: None <None>
2022-01-20 15:03:54 +00:00
.. _ansible.utils.ipsubnet_filter:
**********************
ansible.utils.ipsubnet
**********************
**This filter can be used to manipulate network subnets in several ways.**
Version added: 2.5.0
.. contents::
:local:
:depth: 1
Synopsis
--------
- This filter can be used to manipulate network subnets in several ways.
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>index</b>
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
<div style="font-size: small">
Switch To Calculating Networking Information Directly For Performance (#146) * Add Unit Tests To Capture Failures From 'subnet' Generator The netaddr library returns a generator for the 'subnet' call. This works great until you use larger networks. While it is uncommon to encounter it in IPv4 usage it is trivial to hit it in IPv6. * Switch To Calculating Networking Information Directly For Performance This replaces the inefficient generator for 'subnet' and uses math to determine the result directly. Since a list is not returned directly to the client in the implemented cases this works great and is fast. A further optimization at least on the logic of this might be to break the different cases implemented by the filter out into unique functions. I did not do this yet because I wanted to get feedback on this direction. * Changelog Fragment For PR / Bugfix Adding changelog fragment that references source issue. * Dropping Python 3.7 Bypass Removes Need For 'sys' Module A test for ipsubnet was bypassed under 3.7 because of an inconsistent return value w/3.6 and 2.7. I removed the bypass and changed the behavior of the filter to raise an AnsibleFilterError in all versions of Python. * Add A Pair of Integration Tests These demonstrate the issue with the current implementation and would normally stall out while building the list of possible subnets from the generator. * Address Changelog Feedback I kept the performance item as a bugfix but bumped the typing to a minor change. * Add 'netaddr' To Integration Test 'requirements.txt' * The `ansible-test integration --docker` requires this line in requirements.txt to pass the 'netaddr' related tests * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Replace str -> to_text * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Kate Case <this.is@katherineca.se>
2022-08-31 16:09:35 +00:00
<span style="color: purple">integer</span>
Add ipsubnet filter plugin (#122) Add ipsubnet filter plugin SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nathaniel Case <this.is@nathanielca.se> Reviewed-by: None <None>
2022-01-20 15:03:54 +00:00
</div>
</td>
<td>
</td>
<td>
</td>
<td>
<div>The second argument of the ipsubnet() filter is an index number; by specifying it you can get a new subnet
with the specified index.</div>
</td>
</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 query as 1st argument.
To check if a given string is a subnet, pass it through the filter without any arguments. If the given
string is an IP address, it will be converted into a subnet.
If you specify a subnet size as the first parameter of the ipsubnet() filter, and the subnet size is
smaller than the current one, you will get the number of subnets a given subnet can be split into.</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">string</span>
/ <span style="color: red">required</span>
</div>
</td>
<td>
</td>
<td>
</td>
<td>
<div>subnets or individual address or any other values input for ipsubnet plugin</div>
</td>
</tr>
</table>
<br/>
Examples
--------
.. code-block:: yaml
#### examples
# Ipsubnet filter plugin with different queries.
vars:
fact_diff filter plugin (#310) * Add fact_diff filter plugin * Add integration and unit tests * Add changelog * Add argspect test * Add examples * Fix lint * Fix ansible-lint * REvert changes * Fix sanity * Address review comments * Delete tests/integration/inventory --------- Co-authored-by: Ashwini Mhatre <amhatre@amhatre-thinkpadt14sgen2i.pnq.csb>
2023-11-13 05:58:43 +00:00
address: 192.168.144.5
subnet: 192.168.0.0/16
ipv6_address: '2001:4860:4860::8888'
ipv6_subnet: '2600:1f1c:1b3:8f00::/56'
Add ipsubnet filter plugin (#122) Add ipsubnet filter plugin SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nathaniel Case <this.is@nathanielca.se> Reviewed-by: None <None>
2022-01-20 15:03:54 +00:00
tasks:
fact_diff filter plugin (#310) * Add fact_diff filter plugin * Add integration and unit tests * Add changelog * Add argspect test * Add examples * Fix lint * Fix ansible-lint * REvert changes * Fix sanity * Address review comments * Delete tests/integration/inventory --------- Co-authored-by: Ashwini Mhatre <amhatre@amhatre-thinkpadt14sgen2i.pnq.csb>
2023-11-13 05:58:43 +00:00
- name: convert IP address to subnet
debug:
msg: '{{ address | ansible.utils.ipsubnet }}'
- name: check if a given string is a subnet
debug:
msg: '{{ subnet | ansible.utils.ipsubnet }}'
- name: Get the number of subnets a given subnet can be split into.
debug:
msg: '{{ subnet | ansible.utils.ipsubnet(20) }}'
- name: Get a 1st subnet
debug:
msg: '{{ subnet | ansible.utils.ipsubnet(20, 0) }}'
- name: Get a last subnet
debug:
msg: '{{ subnet | ansible.utils.ipsubnet(20, -1) }}'
- name: Get first IPv6 subnet that has prefix length /120
debug:
msg: '{{ ipv6_subnet | ansible.utils.ipsubnet(120, 0) }}'
- name: Get last subnet that has prefix length /120
debug:
msg: '{{ ipv6_subnet | ansible.utils.ipsubnet(120, -1) }}'
- name: Get biggest subnet that contains that given IP address.
debug:
msg: '{{ address | ansible.utils.ipsubnet(20) }}'
- name: Get 1st smaller subnet by specifying 0 as index number
debug:
msg: '{{ address | ansible.utils.ipsubnet(18, 0) }}'
- name: Get last subnet
debug:
msg: '{{ address | ansible.utils.ipsubnet(18, -1) }}'
- name: >-
The rank of the IP in the subnet (the IP is the 36870nth /32 of the
subnet)
debug:
msg: '{{ address | ansible.utils.ipsubnet(subnet) }}'
- name: The rank in the /24 that contain the address
debug:
msg: '{{ address | ansible.utils.ipsubnet(''192.168.144.0/24'') }}'
- name: An IP with the subnet in the first /30 in a /24
debug:
msg: '{{ ''192.168.144.1/30'' | ansible.utils.ipsubnet(''192.168.144.0/24'') }}'
- name: The fifth subnet /30 in a /24
debug:
msg: '{{ ''192.168.144.16/30'' | ansible.utils.ipsubnet(''192.168.144.0/24'') }}'
Add ipsubnet filter plugin (#122) Add ipsubnet filter plugin SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nathaniel Case <this.is@nathanielca.se> Reviewed-by: None <None>
2022-01-20 15:03:54 +00:00
# PLAY [Ipsubnet filter plugin with different queries.] ****************************************************************
# TASK [convert IP address to subnet] *************************************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:10
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.144.5/32"
# }
#
# TASK [check if a given string is a subnet] ******************************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:15
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.0.0/16"
# }
#
# TASK [Get the number of subnets a given subnet can be split into.] ******************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:20
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "16"
# }
#
# TASK [Get a 1st subnet] *************************************************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:25
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.0.0/20"
# }
#
# TASK [Get a last subnet] ************************************************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:30
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.240.0/20"
# }
#
# TASK [Get biggest subnet that contains that given IP address.] **********************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:35
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.144.0/20"
# }
#
# TASK [Get 1st smaller subnet by specifying 0 as index number] ***********************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:40
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.128.0/18"
# }
#
# TASK [Get last subnet] **************************************************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:45
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "192.168.144.4/31"
# }
#
# TASK [The rank of the IP in the subnet (the IP is the 36870nth /32 of the subnet)] **************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:50
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "36870"
# }
#
# TASK [The rank in the /24 that contain the address] *********************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:55
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "6"
# }
#
# TASK [An IP with the subnet in the first /30 in a /24] ******************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:60
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "1"
# }
#
# TASK [he fifth subnet /30 in a /24] *************************************************************************
# task path: /Users/amhatre/ansible-collections/playbooks/test_ipsubnet.yaml:65
# Loading collection ansible.utils from /Users/amhatre/ansible-collections/collections/ansible_collections/ansible/utils
# ok: [localhost] => {
# "msg": "5"
# }
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">
Fix bugs in Ipaddr filters (#149) Fix bugs in Ipaddr filters SUMMARY ipaddr - Fix input validation issues in ipaddr,ipv4,ipv6,ipwrap filters. ipaddr - Add valid network for link-local fixes: #148 fixes: ansible-collections/ansible.netcommon#375 fixes: ansible-collections/ansible.netcommon#350 ISSUE TYPE Bugfix Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nilashish Chakraborty <nilashishchakraborty8@gmail.com> Reviewed-by: Sagar Paul <sagpaul@redhat.com>
2022-03-04 11:43:59 +00:00
<span style="color: purple">raw</span>
Add ipsubnet filter plugin (#122) Add ipsubnet filter plugin SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nathaniel Case <this.is@nathanielca.se> Reviewed-by: None <None>
2022-01-20 15:03:54 +00:00
</div>
</td>
<td></td>
<td>
Fix bugs in Ipaddr filters (#149) Fix bugs in Ipaddr filters SUMMARY ipaddr - Fix input validation issues in ipaddr,ipv4,ipv6,ipwrap filters. ipaddr - Add valid network for link-local fixes: #148 fixes: ansible-collections/ansible.netcommon#375 fixes: ansible-collections/ansible.netcommon#350 ISSUE TYPE Bugfix Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nilashish Chakraborty <nilashishchakraborty8@gmail.com> Reviewed-by: Sagar Paul <sagpaul@redhat.com>
2022-03-04 11:43:59 +00:00
<div>Returns values valid for a particular query.</div>
Add ipsubnet filter plugin (#122) Add ipsubnet filter plugin SUMMARY ISSUE TYPE New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Nathaniel Case <this.is@nathanielca.se> Reviewed-by: None <None>
2022-01-20 15:03:54 +00:00
<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.