mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-07-02 14:40:19 -07:00
Module deprecation: docs, scheme and tests (#34100)
Enforce module deprecation.
After module has reached the end of it's deprecation cycle we will replace it with a docs stub.
* Replace deprecated modules with docs-only sub
* Use of deprecated past deprecation cycle gives meaningful message (see examples below)
* Enforce documentation.deprecation dict via `schema.py`
* Update `ansible-doc` and web docs to display documentation.deprecation
* Document that structure in `dev_guide`
* Ensure that all modules starting with `_` have a `deprecation:` block
* Ensure `deprecation:` block is only used on modules that start with `_`
* `removed_in` A string which represents when this module needs **deleting**
* CHANGELOG.md and porting_guide_2.5.rst list removed modules as well as alternatives
* CHANGELOG.md links to porting guide index
To ensure that meaningful messages are given to the user if they try to use a module at the end of it's deprecation cycle we enforce the module to contain:
```python
if __name__ == '__main__':
removed_module()
```
This commit is contained in:
John R Barker
GitHub
parent
7c83f006c0
commit
a23c95023b
66 changed files with 241 additions and 4438 deletions
|
|
@ -19,7 +19,10 @@ module: cl_bond
|
|||
version_added: "2.1"
|
||||
author: "Cumulus Networks (@CumulusNetworks)"
|
||||
short_description: Configures a bond port on Cumulus Linux
|
||||
deprecated: Deprecated in 2.3. Use M(nclu) instead.
|
||||
deprecated:
|
||||
removed_in: "2.5"
|
||||
why: The M(nclu) module is designed to be easier to use for individuals who are new to Cumulus Linux by exposing the NCLU interface in an automatable way.
|
||||
alternative: Use M(nclu) instead.
|
||||
description:
|
||||
- Configures a bond interface on Cumulus Linux To configure a bridge port
|
||||
use the cl_bridge module. To configure any other type of interface use the
|
||||
|
|
@ -209,281 +212,7 @@ msg:
|
|||
sample: "interface bond0 config updated"
|
||||
'''
|
||||
|
||||
import os
|
||||
import re
|
||||
import tempfile
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
# handy helper for calling system calls.
|
||||
# calls AnsibleModule.run_command and prints a more appropriate message
|
||||
# exec_path - path to file to execute, with all its arguments.
|
||||
# E.g "/sbin/ip -o link show"
|
||||
# failure_msg - what message to print on failure
|
||||
def run_cmd(module, exec_path):
|
||||
(_rc, out, _err) = module.run_command(exec_path)
|
||||
if _rc > 0:
|
||||
if re.search('cannot find interface', _err):
|
||||
return '[{}]'
|
||||
failure_msg = "Failed; %s Error: %s" % (exec_path, _err)
|
||||
module.fail_json(msg=failure_msg)
|
||||
else:
|
||||
return out
|
||||
|
||||
|
||||
def current_iface_config(module):
|
||||
# due to a bug in ifquery, have to check for presence of interface file
|
||||
# and not rely solely on ifquery. when bug is fixed, this check can be
|
||||
# removed
|
||||
_ifacename = module.params.get('name')
|
||||
_int_dir = module.params.get('location')
|
||||
module.custom_current_config = {}
|
||||
if os.path.exists(_int_dir + '/' + _ifacename):
|
||||
_cmd = "/sbin/ifquery -o json %s" % (module.params.get('name'))
|
||||
module.custom_current_config = module.from_json(
|
||||
run_cmd(module, _cmd))[0]
|
||||
|
||||
|
||||
def build_address(module):
|
||||
# if addr_method == 'dhcp', don't add IP address
|
||||
if module.params.get('addr_method') == 'dhcp':
|
||||
return
|
||||
_ipv4 = module.params.get('ipv4')
|
||||
_ipv6 = module.params.get('ipv6')
|
||||
_addresslist = []
|
||||
if _ipv4 and len(_ipv4) > 0:
|
||||
_addresslist += _ipv4
|
||||
|
||||
if _ipv6 and len(_ipv6) > 0:
|
||||
_addresslist += _ipv6
|
||||
if len(_addresslist) > 0:
|
||||
module.custom_desired_config['config']['address'] = ' '.join(
|
||||
_addresslist)
|
||||
|
||||
|
||||
def build_vids(module):
|
||||
_vids = module.params.get('vids')
|
||||
if _vids and len(_vids) > 0:
|
||||
module.custom_desired_config['config']['bridge-vids'] = ' '.join(_vids)
|
||||
|
||||
|
||||
def build_pvid(module):
|
||||
_pvid = module.params.get('pvid')
|
||||
if _pvid:
|
||||
module.custom_desired_config['config']['bridge-pvid'] = str(_pvid)
|
||||
|
||||
|
||||
def conv_bool_to_str(_value):
|
||||
if isinstance(_value, bool):
|
||||
if _value is True:
|
||||
return 'yes'
|
||||
else:
|
||||
return 'no'
|
||||
return _value
|
||||
|
||||
|
||||
def conv_array_to_str(_value):
|
||||
if isinstance(_value, list):
|
||||
return ' '.join(_value)
|
||||
return _value
|
||||
|
||||
|
||||
def build_generic_attr(module, _attr):
|
||||
_value = module.params.get(_attr)
|
||||
_value = conv_bool_to_str(_value)
|
||||
_value = conv_array_to_str(_value)
|
||||
if _value:
|
||||
module.custom_desired_config['config'][
|
||||
re.sub('_', '-', _attr)] = str(_value)
|
||||
|
||||
|
||||
def build_alias_name(module):
|
||||
alias_name = module.params.get('alias_name')
|
||||
if alias_name:
|
||||
module.custom_desired_config['config']['alias'] = alias_name
|
||||
|
||||
|
||||
def build_addr_method(module):
|
||||
_addr_method = module.params.get('addr_method')
|
||||
if _addr_method:
|
||||
module.custom_desired_config['addr_family'] = 'inet'
|
||||
module.custom_desired_config['addr_method'] = _addr_method
|
||||
|
||||
|
||||
def build_vrr(module):
|
||||
_virtual_ip = module.params.get('virtual_ip')
|
||||
_virtual_mac = module.params.get('virtual_mac')
|
||||
vrr_config = []
|
||||
if _virtual_ip:
|
||||
vrr_config.append(_virtual_mac)
|
||||
vrr_config.append(_virtual_ip)
|
||||
module.custom_desired_config.get('config')['address-virtual'] = \
|
||||
' '.join(vrr_config)
|
||||
|
||||
|
||||
def add_glob_to_array(_bondmems):
|
||||
"""
|
||||
goes through each bond member if it sees a dash add glob
|
||||
before it
|
||||
"""
|
||||
result = []
|
||||
if isinstance(_bondmems, list):
|
||||
for _entry in _bondmems:
|
||||
if re.search('-', _entry):
|
||||
_entry = 'glob ' + _entry
|
||||
result.append(_entry)
|
||||
return ' '.join(result)
|
||||
return _bondmems
|
||||
|
||||
|
||||
def build_bond_attr(module, _attr):
|
||||
_value = module.params.get(_attr)
|
||||
_value = conv_bool_to_str(_value)
|
||||
_value = add_glob_to_array(_value)
|
||||
if _value:
|
||||
module.custom_desired_config['config'][
|
||||
'bond-' + re.sub('_', '-', _attr)] = str(_value)
|
||||
|
||||
|
||||
def build_desired_iface_config(module):
|
||||
"""
|
||||
take parameters defined and build ifupdown2 compatible hash
|
||||
"""
|
||||
module.custom_desired_config = {
|
||||
'addr_family': None,
|
||||
'auto': True,
|
||||
'config': {},
|
||||
'name': module.params.get('name')
|
||||
}
|
||||
|
||||
for _attr in ['slaves', 'mode', 'xmit_hash_policy',
|
||||
'miimon', 'lacp_rate', 'lacp_bypass_allow',
|
||||
'lacp_bypass_period', 'lacp_bypass_all_active',
|
||||
'min_links']:
|
||||
build_bond_attr(module, _attr)
|
||||
|
||||
build_addr_method(module)
|
||||
build_address(module)
|
||||
build_vids(module)
|
||||
build_pvid(module)
|
||||
build_alias_name(module)
|
||||
build_vrr(module)
|
||||
|
||||
for _attr in ['mtu', 'mstpctl_portnetwork', 'mstpctl_portadminedge'
|
||||
'mstpctl_bpduguard', 'clag_id',
|
||||
'lacp_bypass_priority']:
|
||||
build_generic_attr(module, _attr)
|
||||
|
||||
|
||||
def config_dict_changed(module):
|
||||
"""
|
||||
return true if 'config' dict in hash is different
|
||||
between desired and current config
|
||||
"""
|
||||
current_config = module.custom_current_config.get('config')
|
||||
desired_config = module.custom_desired_config.get('config')
|
||||
return current_config != desired_config
|
||||
|
||||
|
||||
def config_changed(module):
|
||||
"""
|
||||
returns true if config has changed
|
||||
"""
|
||||
if config_dict_changed(module):
|
||||
return True
|
||||
# check if addr_method is changed
|
||||
return module.custom_desired_config.get('addr_method') != \
|
||||
module.custom_current_config.get('addr_method')
|
||||
|
||||
|
||||
def replace_config(module):
|
||||
temp = tempfile.NamedTemporaryFile()
|
||||
desired_config = module.custom_desired_config
|
||||
# by default it will be something like /etc/network/interfaces.d/swp1
|
||||
final_location = module.params.get('location') + '/' + \
|
||||
module.params.get('name')
|
||||
final_text = ''
|
||||
_fh = open(final_location, 'w')
|
||||
# make sure to put hash in array or else ifquery will fail
|
||||
# write to temp file
|
||||
try:
|
||||
temp.write(module.jsonify([desired_config]))
|
||||
# need to seek to 0 so that data is written to tempfile.
|
||||
temp.seek(0)
|
||||
_cmd = "/sbin/ifquery -a -i %s -t json" % (temp.name)
|
||||
final_text = run_cmd(module, _cmd)
|
||||
finally:
|
||||
temp.close()
|
||||
|
||||
try:
|
||||
_fh.write(final_text)
|
||||
finally:
|
||||
_fh.close()
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(
|
||||
slaves=dict(required=True, type='list'),
|
||||
name=dict(required=True, type='str'),
|
||||
ipv4=dict(type='list'),
|
||||
ipv6=dict(type='list'),
|
||||
alias_name=dict(type='str'),
|
||||
addr_method=dict(type='str',
|
||||
choices=['', 'dhcp']),
|
||||
mtu=dict(type='str'),
|
||||
virtual_ip=dict(type='str'),
|
||||
virtual_mac=dict(type='str'),
|
||||
vids=dict(type='list'),
|
||||
pvid=dict(type='str'),
|
||||
mstpctl_portnetwork=dict(type='bool'),
|
||||
mstpctl_portadminedge=dict(type='bool'),
|
||||
mstpctl_bpduguard=dict(type='bool'),
|
||||
clag_id=dict(type='str'),
|
||||
min_links=dict(type='int', default=1),
|
||||
mode=dict(type='str', default='802.3ad'),
|
||||
miimon=dict(type='int', default=100),
|
||||
xmit_hash_policy=dict(type='str', default='layer3+4'),
|
||||
lacp_rate=dict(type='int', default=1),
|
||||
lacp_bypass_allow=dict(type='int', choices=[0, 1]),
|
||||
lacp_bypass_all_active=dict(type='int', choices=[0, 1]),
|
||||
lacp_bypass_priority=dict(type='list'),
|
||||
lacp_bypass_period=dict(type='int'),
|
||||
location=dict(type='str',
|
||||
default='/etc/network/interfaces.d')
|
||||
),
|
||||
mutually_exclusive=[['lacp_bypass_priority', 'lacp_bypass_all_active']],
|
||||
required_together=[['virtual_ip', 'virtual_mac']]
|
||||
)
|
||||
|
||||
# if using the jinja default filter, this resolves to
|
||||
# create an list with an empty string ['']. The following
|
||||
# checks all lists and removes it, so that functions expecting
|
||||
# an empty list, get this result. May upstream this fix into
|
||||
# the AnsibleModule code to have it check for this.
|
||||
for k, _param in module.params.items():
|
||||
if isinstance(_param, list):
|
||||
module.params[k] = [x for x in _param if x]
|
||||
|
||||
_location = module.params.get('location')
|
||||
if not os.path.exists(_location):
|
||||
_msg = "%s does not exist." % (_location)
|
||||
module.fail_json(msg=_msg)
|
||||
return # for testing purposes only
|
||||
|
||||
ifacename = module.params.get('name')
|
||||
_changed = False
|
||||
_msg = "interface %s config not changed" % (ifacename)
|
||||
current_iface_config(module)
|
||||
build_desired_iface_config(module)
|
||||
if config_changed(module):
|
||||
replace_config(module)
|
||||
_msg = "interface %s config updated" % (ifacename)
|
||||
_changed = True
|
||||
|
||||
module.exit_json(changed=_changed, msg=_msg)
|
||||
|
||||
from ansible.module_utils.common.removed import removed_module
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
removed_module()
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue