wbrawner/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

New module to install images on Cisco FTD devices (#53467)

Browse source 
* Add ftd_install module

* Remove shebangs

* Avoid using enum package

* Update module docs

* Update ftd_install docs

* Update PropertyMock import

* Fixing unit tests

* Move get_system_info and FtdOperations to module_utils

* Update dependency name

* Move Kick assertion to module_utils

* Add a note about Python interpreter for this module
This commit is contained in:
Anton Nikulin 2019-03-26 16:05:53 +02:00 committed by Sumit Jaiswal
parent bfc6a2a8d6
commit c231fc5a7c
6 changed files with 868 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
lib/ansible/module_utils/network/ftd/configuration.py
View file

@ -35,6 +35,8 @@ MULTIPLE_DUPLICATES_FOUND_ERROR = (
"Multiple objects returned according to filters being specified. "
"Please specify more specific filters which can find exact object that caused duplication error")
PATH_PARAMS_FOR_DEFAULT_OBJ = {'objId': 'default'}
class OperationNamePrefix:
ADD = 'add'

137
lib/ansible/module_utils/network/ftd/device.py Normal file
View file

@ -0,0 +1,137 @@
# Copyright (c) 2019 Cisco and/or its affiliates.
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
from ansible.module_utils.six.moves.urllib.parse import urlparse
try:
from kick.device2.ftd5500x.actions.ftd5500x import Ftd5500x
from kick.device2.kp.actions import Kp
HAS_KICK = True
except ImportError:
HAS_KICK = False
def assert_kick_is_installed(module):
if not HAS_KICK:
module.fail_json(msg='Firepower-kick library is required to run this module. '
'Please, install it with `pip install firepower-kick` command and run the playbook again.')
class FtdModel:
FTD_ASA5506_X = 'Cisco ASA5506-X Threat Defense'
FTD_ASA5508_X = 'Cisco ASA5508-X Threat Defense'
FTD_ASA5516_X = 'Cisco ASA5516-X Threat Defense'
FTD_2110 = 'Cisco Firepower 2110 Threat Defense'
FTD_2120 = 'Cisco Firepower 2120 Threat Defense'
FTD_2130 = 'Cisco Firepower 2130 Threat Defense'
FTD_2140 = 'Cisco Firepower 2140 Threat Defense'
@classmethod
def supported_models(cls):
return [getattr(cls, item) for item in dir(cls) if item.startswith('FTD_')]
class FtdPlatformFactory(object):
@staticmethod
def create(model, module_params):
for cls in AbstractFtdPlatform.__subclasses__():
if cls.supports_ftd_model(model):
return cls(module_params)
raise ValueError("FTD model '%s' is not supported by this module." % model)
class AbstractFtdPlatform(object):
PLATFORM_MODELS = []
def install_ftd_image(self, params):
raise NotImplementedError('The method should be overridden in subclass')
@classmethod
def supports_ftd_model(cls, model):
return model in cls.PLATFORM_MODELS
@staticmethod
def parse_rommon_file_location(rommon_file_location):
rommon_url = urlparse(rommon_file_location)
if rommon_url.scheme != 'tftp':
raise ValueError('The ROMMON image must be downloaded from TFTP server, other protocols are not supported.')
return rommon_url.netloc, rommon_url.path
class Ftd2100Platform(AbstractFtdPlatform):
PLATFORM_MODELS = [FtdModel.FTD_2110, FtdModel.FTD_2120, FtdModel.FTD_2130, FtdModel.FTD_2140]
def __init__(self, params):
self._ftd = Kp(hostname=params["device_hostname"],
login_username=params["device_username"],
login_password=params["device_password"],
sudo_password=params.get("device_sudo_password") or params["device_password"])
def install_ftd_image(self, params):
line = self._ftd.ssh_console(ip=params["console_ip"],
port=params["console_port"],
username=params["console_username"],
password=params["console_password"])
try:
rommon_server, rommon_path = self.parse_rommon_file_location(params["rommon_file_location"])
line.baseline_fp2k_ftd(tftp_server=rommon_server,
rommon_file=rommon_path,
uut_hostname=params["device_hostname"],
uut_username=params["device_username"],
uut_password=params.get("device_new_password") or params["device_password"],
uut_ip=params["device_ip"],
uut_netmask=params["device_netmask"],
uut_gateway=params["device_gateway"],
dns_servers=params["dns_server"],
search_domains=params["search_domains"],
fxos_url=params["image_file_location"],
ftd_version=params["image_version"])
finally:
line.disconnect()
class FtdAsa5500xPlatform(AbstractFtdPlatform):
PLATFORM_MODELS = [FtdModel.FTD_ASA5506_X, FtdModel.FTD_ASA5508_X, FtdModel.FTD_ASA5516_X]
def __init__(self, params):
self._ftd = Ftd5500x(hostname=params["device_hostname"],
login_password=params["device_password"],
sudo_password=params.get("device_sudo_password") or params["device_password"])
def install_ftd_image(self, params):
line = self._ftd.ssh_console(ip=params["console_ip"],
port=params["console_port"],
username=params["console_username"],
password=params["console_password"])
try:
rommon_server, rommon_path = self.parse_rommon_file_location(params["rommon_file_location"])
line.rommon_to_new_image(rommon_tftp_server=rommon_server,
rommon_image=rommon_path,
pkg_image=params["image_file_location"],
uut_ip=params["device_ip"],
uut_netmask=params["device_netmask"],
uut_gateway=params["device_gateway"],
dns_server=params["dns_server"],
search_domains=params["search_domains"],
hostname=params["device_hostname"])
finally:
line.disconnect()

41
lib/ansible/module_utils/network/ftd/operation.py Normal file
View file

@ -0,0 +1,41 @@
# Copyright (c) 2018 Cisco and/or its affiliates.
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
from ansible.module_utils.network.ftd.configuration import ParamName, PATH_PARAMS_FOR_DEFAULT_OBJ
class FtdOperations:
"""
Utility class for common operation names
"""
GET_SYSTEM_INFO = 'getSystemInformation'
GET_MANAGEMENT_IP_LIST = 'getManagementIPList'
GET_DNS_SETTING_LIST = 'getDeviceDNSSettingsList'
GET_DNS_SERVER_GROUP = 'getDNSServerGroup'
def get_system_info(resource):
"""
Executes `getSystemInformation` operation and returns information about the system.
:param resource: a BaseConfigurationResource object to connect to the device
:return: a dictionary with system information about the device and its software
"""
path_params = {ParamName.PATH_PARAMS: PATH_PARAMS_FOR_DEFAULT_OBJ}
system_info = resource.execute_operation(FtdOperations.GET_SYSTEM_INFO, path_params)
return system_info

295
lib/ansible/modules/network/ftd/ftd_install.py Normal file
View file

@ -0,0 +1,295 @@
#!/usr/bin/python
# Copyright (c) 2019 Cisco and/or its affiliates.
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = """
---
module: ftd_install
short_description: Installs FTD pkg image on the firewall
description:
- Provisioning module for FTD devices that installs ROMMON image (if needed) and
FTD pkg image on the firewall.
- Can be used with `httpapi` and `local` connection types. The `httpapi` is preferred,
the `local` connection should be used only when the device cannot be accessed via
REST API.
version_added: "2.8"
requirements: [ "python >= 3.5", "firepower-kick" ]
notes:
- Requires `firepower-kick` library that should be installed separately and requires Python >= 3.5.
- On localhost, Ansible can be still run with Python >= 2.7, but the interpreter for this particular module must be
Python >= 3.5.
- Python interpreter for the module can overwritten in `ansible_python_interpreter` variable.
author: "Cisco Systems, Inc. (@annikulin)"
options:
device_hostname:
description:
- Hostname of the device as appears in the prompt (e.g., 'firepower-5516').
required: true
type: str
device_username:
description:
- Username to login on the device.
- Defaulted to 'admin' if not specified.
required: false
type: str
default: admin
device_password:
description:
- Password to login on the device.
required: true
type: str
device_sudo_password:
description:
- Root password for the device. If not specified, `device_password` is used.
required: false
type: str
device_new_password:
description:
- New device password to set after image installation.
- If not specified, current password from `device_password` property is reused.
- Not applicable for ASA5500-X series devices.
required: false
type: str
device_ip:
description:
- Device IP address of management interface.
- If not specified and connection is 'httpapi`, the module tries to fetch the existing value via REST API.
- For 'local' connection type, this parameter is mandatory.
required: false
type: str
device_gateway:
description:
- Device gateway of management interface.
- If not specified and connection is 'httpapi`, the module tries to fetch the existing value via REST API.
- For 'local' connection type, this parameter is mandatory.
required: false
type: str
device_netmask:
description:
- Device netmask of management interface.
- If not specified and connection is 'httpapi`, the module tries to fetch the existing value via REST API.
- For 'local' connection type, this parameter is mandatory.
required: false
type: str
device_model:
description:
- Platform model of the device (e.g., 'Cisco ASA5506-X Threat Defense').
- If not specified and connection is 'httpapi`, the module tries to fetch the device model via REST API.
- For 'local' connection type, this parameter is mandatory.
required: false
type: str
choices:
- Cisco ASA5506-X Threat Defense
- Cisco ASA5508-X Threat Defense
- Cisco ASA5516-X Threat Defense
- Cisco Firepower 2110 Threat Defense
- Cisco Firepower 2120 Threat Defense
- Cisco Firepower 2130 Threat Defense
- Cisco Firepower 2140 Threat Defense
dns_server:
description:
- DNS IP address of management interface.
- If not specified and connection is 'httpapi`, the module tries to fetch the existing value via REST API.
- For 'local' connection type, this parameter is mandatory.
required: false
type: str
console_ip:
description:
- IP address of a terminal server.
- Used to set up an SSH connection with device's console port through the terminal server.
required: true
type: str
console_port:
description:
- Device's port on a terminal server.
required: true
type: str
console_username:
description:
- Username to login on a terminal server.
required: true
type: str
console_password:
description:
- Password to login on a terminal server.
required: true
type: str
rommon_file_location:
description:
- Path to the boot (ROMMON) image on TFTP server.
- Only TFTP is supported.
required: true
type: str
image_file_location:
description:
- Path to the FTD pkg image on the server to be downloaded.
- FTP, SCP, SFTP, TFTP, or HTTP protocols are usually supported, but may depend on the device model.
required: true
type: str
image_version:
description:
- Version of FTD image to be installed.
- Helps to compare target and current FTD versions to prevent unnecessary reinstalls.
required: true
type: str
force_install:
description:
- Forces the FTD image to be installed even when the same version is already installed on the firewall.
- By default, the module stops execution when the target version is installed in the device.
required: false
type: bool
default: false
search_domains:
description:
- Search domains delimited by comma.
- Defaulted to 'cisco.com' if not specified.
required: false
type: str
default: cisco.com
"""
EXAMPLES = """
- name: Install image v6.3.0 on FTD 5516
ftd_install:
device_hostname: firepower
device_password: pass
device_ip: 192.168.0.1
device_netmask: 255.255.255.0
device_gateway: 192.168.0.254
dns_server: 8.8.8.8
console_ip: 10.89.0.0
console_port: 2004
console_username: console_user
console_password: console_pass
rommon_file_location: 'tftp://10.89.0.11/installers/ftd-boot-9.10.1.3.lfbff'
image_file_location: 'https://10.89.0.11/installers/ftd-6.3.0-83.pkg'
image_version: 6.3.0-83
"""
RETURN = """
msg:
description: The message saying whether the image was installed or explaining why the installation failed.
returned: always
type: str
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.connection import Connection
from ansible.module_utils.six import iteritems
from ansible.module_utils.network.ftd.configuration import BaseConfigurationResource, ParamName
from ansible.module_utils.network.ftd.device import assert_kick_is_installed, FtdPlatformFactory, FtdModel
from ansible.module_utils.network.ftd.operation import FtdOperations, get_system_info
REQUIRED_PARAMS_FOR_LOCAL_CONNECTION = ['device_ip', 'device_netmask', 'device_gateway', 'device_model', 'dns_server']
def main():
fields = dict(
device_hostname=dict(type='str', required=True),
device_username=dict(type='str', required=False, default='admin'),
device_password=dict(type='str', required=True, no_log=True),
device_sudo_password=dict(type='str', required=False, no_log=True),
device_new_password=dict(type='str', required=False, no_log=True),
device_ip=dict(type='str', required=False),
device_netmask=dict(type='str', required=False),
device_gateway=dict(type='str', required=False),
device_model=dict(type='str', required=False, choices=FtdModel.supported_models()),
dns_server=dict(type='str', required=False),
search_domains=dict(type='str', required=False, default='cisco.com'),
console_ip=dict(type='str', required=True),
console_port=dict(type='str', required=True),
console_username=dict(type='str', required=True),
console_password=dict(type='str', required=True, no_log=True),
rommon_file_location=dict(type='str', required=True),
image_file_location=dict(type='str', required=True),
image_version=dict(type='str', required=True),
force_install=dict(type='bool', required=False, default=False)
)
module = AnsibleModule(argument_spec=fields)
assert_kick_is_installed(module)
use_local_connection = module._socket_path is None
if use_local_connection:
check_required_params_for_local_connection(module, module.params)
platform_model = module.params['device_model']
check_that_model_is_supported(module, platform_model)
else:
connection = Connection(module._socket_path)
resource = BaseConfigurationResource(connection, module.check_mode)
system_info = get_system_info(resource)
platform_model = module.params['device_model'] or system_info['platformModel']
check_that_model_is_supported(module, platform_model)
check_that_update_is_needed(module, system_info)
check_management_and_dns_params(resource, module.params)
ftd_platform = FtdPlatformFactory.create(platform_model, module.params)
ftd_platform.install_ftd_image(module.params)
module.exit_json(changed=True,
msg='Successfully installed FTD image %s on the firewall device.' % module.params["image_version"])
def check_required_params_for_local_connection(module, params):
missing_params = [k for k, v in iteritems(params) if k in REQUIRED_PARAMS_FOR_LOCAL_CONNECTION and v is None]
if missing_params:
message = "The following parameters are mandatory when the module is used with 'local' connection: %s." % \
', '.join(sorted(missing_params))
module.fail_json(msg=message)
def check_that_model_is_supported(module, platform_model):
if platform_model not in FtdModel.supported_models():
module.fail_json(msg="Platform model '%s' is not supported by this module." % platform_model)
def check_that_update_is_needed(module, system_info):
target_ftd_version = module.params["image_version"]
if not module.params["force_install"] and target_ftd_version == system_info['softwareVersion']:
module.exit_json(changed=False, msg="FTD already has %s version of software installed." % target_ftd_version)
def check_management_and_dns_params(resource, params):
if not all([params['device_ip'], params['device_netmask'], params['device_gateway']]):
management_ip = resource.execute_operation(FtdOperations.GET_MANAGEMENT_IP_LIST, {})['items'][0]
params['device_ip'] = params['device_ip'] or management_ip['ipv4Address']
params['device_netmask'] = params['device_netmask'] or management_ip['ipv4NetMask']
params['device_gateway'] = params['device_gateway'] or management_ip['ipv4Gateway']
if not params['dns_server']:
dns_setting = resource.execute_operation(FtdOperations.GET_DNS_SETTING_LIST, {})['items'][0]
dns_server_group_id = dns_setting['dnsServerGroup']['id']
dns_server_group = resource.execute_operation(FtdOperations.GET_DNS_SERVER_GROUP,
{ParamName.PATH_PARAMS: {'objId': dns_server_group_id}})
params['dns_server'] = dns_server_group['dnsServers'][0]['ipAddress']
if __name__ == '__main__':
main()

145
test/units/module_utils/network/ftd/test_device.py Normal file
View file

@ -0,0 +1,145 @@
# Copyright (c) 2019 Cisco and/or its affiliates.
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
import pytest
pytest.importorskip("kick")
from ansible.module_utils.network.ftd.device import FtdPlatformFactory, FtdModel, FtdAsa5500xPlatform, \
Ftd2100Platform, AbstractFtdPlatform
from units.modules.network.ftd.test_ftd_install import DEFAULT_MODULE_PARAMS
class TestFtdModel(object):
def test_has_value_should_return_true_for_existing_models(self):
assert FtdModel.FTD_2120 in FtdModel.supported_models()
assert FtdModel.FTD_ASA5516_X in FtdModel.supported_models()
def test_has_value_should_return_false_for_non_existing_models(self):
assert 'nonExistingModel' not in FtdModel.supported_models()
assert None not in FtdModel.supported_models()
class TestFtdPlatformFactory(object):
@pytest.fixture(autouse=True)
def mock_devices(self, mocker):
mocker.patch('ansible.module_utils.network.ftd.device.Kp')
mocker.patch('ansible.module_utils.network.ftd.device.Ftd5500x')
def test_factory_should_return_corresponding_platform(self):
ftd_platform = FtdPlatformFactory.create(FtdModel.FTD_ASA5508_X, dict(DEFAULT_MODULE_PARAMS))
assert type(ftd_platform) is FtdAsa5500xPlatform
ftd_platform = FtdPlatformFactory.create(FtdModel.FTD_2130, dict(DEFAULT_MODULE_PARAMS))
assert type(ftd_platform) is Ftd2100Platform
def test_factory_should_raise_error_with_not_supported_model(self):
with pytest.raises(ValueError) as ex:
FtdPlatformFactory.create('nonExistingModel', dict(DEFAULT_MODULE_PARAMS))
assert "FTD model 'nonExistingModel' is not supported by this module." == ex.value.args[0]
class TestAbstractFtdPlatform(object):
def test_install_ftd_image_raise_error_on_abstract_class(self):
with pytest.raises(NotImplementedError):
AbstractFtdPlatform().install_ftd_image(dict(DEFAULT_MODULE_PARAMS))
def test_supports_ftd_model_should_return_true_for_supported_models(self):
assert Ftd2100Platform.supports_ftd_model(FtdModel.FTD_2120)
assert FtdAsa5500xPlatform.supports_ftd_model(FtdModel.FTD_ASA5516_X)
def test_supports_ftd_model_should_return_false_for_non_supported_models(self):
assert not AbstractFtdPlatform.supports_ftd_model(FtdModel.FTD_2120)
assert not Ftd2100Platform.supports_ftd_model(FtdModel.FTD_ASA5508_X)
assert not FtdAsa5500xPlatform.supports_ftd_model(FtdModel.FTD_2120)
def test_parse_rommon_file_location(self):
server, path = AbstractFtdPlatform.parse_rommon_file_location('tftp://1.2.3.4/boot/rommon-boot.foo')
assert '1.2.3.4' == server
assert '/boot/rommon-boot.foo' == path
def test_parse_rommon_file_location_should_fail_for_non_tftp_protocol(self):
with pytest.raises(ValueError) as ex:
AbstractFtdPlatform.parse_rommon_file_location('http://1.2.3.4/boot/rommon-boot.foo')
assert 'The ROMMON image must be downloaded from TFTP server' in str(ex)
class TestFtd2100Platform(object):
@pytest.fixture
def kp_mock(self, mocker):
return mocker.patch('ansible.module_utils.network.ftd.device.Kp')
@pytest.fixture
def module_params(self):
return dict(DEFAULT_MODULE_PARAMS)
def test_install_ftd_image_should_call_kp_module(self, kp_mock, module_params):
ftd = FtdPlatformFactory.create(FtdModel.FTD_2110, module_params)
ftd.install_ftd_image(module_params)
assert kp_mock.called
assert kp_mock.return_value.ssh_console.called
ftd_line = kp_mock.return_value.ssh_console.return_value
assert ftd_line.baseline_fp2k_ftd.called
assert ftd_line.disconnect.called
def test_install_ftd_image_should_call_disconnect_when_install_fails(self, kp_mock, module_params):
ftd_line = kp_mock.return_value.ssh_console.return_value
ftd_line.baseline_fp2k_ftd.side_effect = Exception('Something went wrong')
ftd = FtdPlatformFactory.create(FtdModel.FTD_2120, module_params)
with pytest.raises(Exception):
ftd.install_ftd_image(module_params)
assert ftd_line.baseline_fp2k_ftd.called
assert ftd_line.disconnect.called
class TestFtdAsa5500xPlatform(object):
@pytest.fixture
def asa5500x_mock(self, mocker):
return mocker.patch('ansible.module_utils.network.ftd.device.Ftd5500x')
@pytest.fixture
def module_params(self):
return dict(DEFAULT_MODULE_PARAMS)
def test_install_ftd_image_should_call_kp_module(self, asa5500x_mock, module_params):
ftd = FtdPlatformFactory.create(FtdModel.FTD_ASA5508_X, module_params)
ftd.install_ftd_image(module_params)
assert asa5500x_mock.called
assert asa5500x_mock.return_value.ssh_console.called
ftd_line = asa5500x_mock.return_value.ssh_console.return_value
assert ftd_line.rommon_to_new_image.called
assert ftd_line.disconnect.called
def test_install_ftd_image_should_call_disconnect_when_install_fails(self, asa5500x_mock, module_params):
ftd_line = asa5500x_mock.return_value.ssh_console.return_value
ftd_line.rommon_to_new_image.side_effect = Exception('Something went wrong')
ftd = FtdPlatformFactory.create(FtdModel.FTD_ASA5516_X, module_params)
with pytest.raises(Exception):
ftd.install_ftd_image(module_params)
assert ftd_line.rommon_to_new_image.called
assert ftd_line.disconnect.called

248
test/units/modules/network/ftd/test_ftd_install.py Normal file
View file

@ -0,0 +1,248 @@
# Copyright (c) 2019 Cisco and/or its affiliates.
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
from __future__ import absolute_import
import pytest
from units.compat.mock import PropertyMock
from ansible.module_utils import basic
from units.modules.utils import set_module_args, exit_json, fail_json, AnsibleFailJson, AnsibleExitJson
from ansible.modules.network.ftd import ftd_install
from ansible.module_utils.network.ftd.device import FtdModel
DEFAULT_MODULE_PARAMS = dict(
device_hostname="firepower",
device_username="admin",
device_password="pass",
device_new_password="newpass",
device_sudo_password="sudopass",
device_ip="192.168.0.1",
device_netmask="255.255.255.0",
device_gateway="192.168.0.254",
device_model=FtdModel.FTD_ASA5516_X,
dns_server="8.8.8.8",
console_ip="10.89.0.0",
console_port="2004",
console_username="console_user",
console_password="console_pass",
rommon_file_location="tftp://10.0.0.1/boot/ftd-boot-1.9.2.0.lfbff",
image_file_location="http://10.0.0.1/Release/ftd-6.2.3-83.pkg",
image_version="6.2.3-83",
search_domains="cisco.com",
force_install=False
)
class TestFtdInstall(object):
module = ftd_install
@pytest.fixture(autouse=True)
def module_mock(self, mocker):
mocker.patch.multiple(basic.AnsibleModule, exit_json=exit_json, fail_json=fail_json)
mocker.patch.object(basic.AnsibleModule, '_socket_path', new_callable=PropertyMock, create=True,
return_value=mocker.MagicMock())
@pytest.fixture(autouse=True)
def connection_mock(self, mocker):
connection_class_mock = mocker.patch('ansible.modules.network.ftd.ftd_install.Connection')
return connection_class_mock.return_value
@pytest.fixture
def config_resource_mock(self, mocker):
resource_class_mock = mocker.patch('ansible.modules.network.ftd.ftd_install.BaseConfigurationResource')
return resource_class_mock.return_value
@pytest.fixture(autouse=True)
def ftd_factory_mock(self, mocker):
return mocker.patch('ansible.modules.network.ftd.ftd_install.FtdPlatformFactory')
@pytest.fixture(autouse=True)
def has_kick_mock(self, mocker):
return mocker.patch('ansible.module_utils.network.ftd.device.HAS_KICK', True)
def test_module_should_fail_when_kick_is_not_installed(self, mocker):
mocker.patch('ansible.module_utils.network.ftd.device.HAS_KICK', False)
set_module_args(dict(DEFAULT_MODULE_PARAMS))
with pytest.raises(AnsibleFailJson) as ex:
self.module.main()
result = ex.value.args[0]
assert result['failed']
assert "Firepower-kick library is required to run this module" in result['msg']
def test_module_should_fail_when_platform_is_not_supported(self, config_resource_mock):
config_resource_mock.execute_operation.return_value = {'platformModel': 'nonSupportedModel'}
module_params = dict(DEFAULT_MODULE_PARAMS)
del module_params['device_model']
set_module_args(module_params)
with pytest.raises(AnsibleFailJson) as ex:
self.module.main()
result = ex.value.args[0]
assert result['failed']
assert result['msg'] == "Platform model 'nonSupportedModel' is not supported by this module."
def test_module_should_fail_when_device_model_is_missing_with_local_connection(self, mocker):
mocker.patch.object(basic.AnsibleModule, '_socket_path', create=True, return_value=None)
module_params = dict(DEFAULT_MODULE_PARAMS)
del module_params['device_model']
set_module_args(module_params)
with pytest.raises(AnsibleFailJson) as ex:
self.module.main()
result = ex.value.args[0]
assert result['failed']
expected_msg = \
"The following parameters are mandatory when the module is used with 'local' connection: device_model."
assert expected_msg == result['msg']
def test_module_should_fail_when_management_ip_values_are_missing_with_local_connection(self, mocker):
mocker.patch.object(basic.AnsibleModule, '_socket_path', create=True, return_value=None)
module_params = dict(DEFAULT_MODULE_PARAMS)
del module_params['device_ip']
del module_params['device_netmask']
del module_params['device_gateway']
set_module_args(module_params)
with pytest.raises(AnsibleFailJson) as ex:
self.module.main()
result = ex.value.args[0]
assert result['failed']
expected_msg = "The following parameters are mandatory when the module is used with 'local' connection: " \
"device_gateway, device_ip, device_netmask."
assert expected_msg == result['msg']
def test_module_should_return_when_software_is_already_installed(self, config_resource_mock):
config_resource_mock.execute_operation.return_value = {
'softwareVersion': '6.3.0-11',
'platformModel': 'Cisco ASA5516-X Threat Defense'
}
module_params = dict(DEFAULT_MODULE_PARAMS)
module_params['image_version'] = '6.3.0-11'
set_module_args(module_params)
with pytest.raises(AnsibleExitJson) as ex:
self.module.main()
result = ex.value.args[0]
assert not result['changed']
assert result['msg'] == 'FTD already has 6.3.0-11 version of software installed.'
def test_module_should_proceed_if_software_is_already_installed_and_force_param_given(self, config_resource_mock):
config_resource_mock.execute_operation.return_value = {
'softwareVersion': '6.3.0-11',
'platformModel': 'Cisco ASA5516-X Threat Defense'
}
module_params = dict(DEFAULT_MODULE_PARAMS)
module_params['image_version'] = '6.3.0-11'
module_params['force_install'] = True
set_module_args(module_params)
with pytest.raises(AnsibleExitJson) as ex:
self.module.main()
result = ex.value.args[0]
assert result['changed']
assert result['msg'] == 'Successfully installed FTD image 6.3.0-11 on the firewall device.'
def test_module_should_install_ftd_image(self, config_resource_mock, ftd_factory_mock):
config_resource_mock.execute_operation.side_effect = [
{
'softwareVersion': '6.2.3-11',
'platformModel': 'Cisco ASA5516-X Threat Defense'
}
]
module_params = dict(DEFAULT_MODULE_PARAMS)
set_module_args(module_params)
with pytest.raises(AnsibleExitJson) as ex:
self.module.main()
result = ex.value.args[0]
assert result['changed']
assert result['msg'] == 'Successfully installed FTD image 6.2.3-83 on the firewall device.'
ftd_factory_mock.create.assert_called_once_with('Cisco ASA5516-X Threat Defense', DEFAULT_MODULE_PARAMS)
ftd_factory_mock.create.return_value.install_ftd_image.assert_called_once_with(DEFAULT_MODULE_PARAMS)
def test_module_should_fill_management_ip_values_when_missing(self, config_resource_mock, ftd_factory_mock):
config_resource_mock.execute_operation.side_effect = [
{
'softwareVersion': '6.3.0-11',
'platformModel': 'Cisco ASA5516-X Threat Defense'
},
{
'items': [{
'ipv4Address': '192.168.1.1',
'ipv4NetMask': '255.255.255.0',
'ipv4Gateway': '192.168.0.1'
}]
}
]
module_params = dict(DEFAULT_MODULE_PARAMS)
expected_module_params = dict(module_params)
del module_params['device_ip']
del module_params['device_netmask']
del module_params['device_gateway']
expected_module_params.update(
device_ip='192.168.1.1',
device_netmask='255.255.255.0',
device_gateway='192.168.0.1'
)
set_module_args(module_params)
with pytest.raises(AnsibleExitJson):
self.module.main()
ftd_factory_mock.create.assert_called_once_with('Cisco ASA5516-X Threat Defense', expected_module_params)
ftd_factory_mock.create.return_value.install_ftd_image.assert_called_once_with(expected_module_params)
def test_module_should_fill_dns_server_when_missing(self, config_resource_mock, ftd_factory_mock):
config_resource_mock.execute_operation.side_effect = [
{
'softwareVersion': '6.3.0-11',
'platformModel': 'Cisco ASA5516-X Threat Defense'
},
{
'items': [{
'dnsServerGroup': {
'id': '123'
}
}]
},
{
'dnsServers': [{
'ipAddress': '8.8.9.9'
}]
}
]
module_params = dict(DEFAULT_MODULE_PARAMS)
expected_module_params = dict(module_params)
del module_params['dns_server']
expected_module_params['dns_server'] = '8.8.9.9'
set_module_args(module_params)
with pytest.raises(AnsibleExitJson):
self.module.main()
ftd_factory_mock.create.assert_called_once_with('Cisco ASA5516-X Threat Defense', expected_module_params)
ftd_factory_mock.create.return_value.install_ftd_image.assert_called_once_with(expected_module_params)