New module - meraki_firewalled_services (#57289)

* Initial commit for module
- Module can query or modify network services on Meraki gear
- Check mode supported
- Integration tests included

* Small change to examples

* Move mutual exclusive to build in approach

* Sanity err

* Split integration tests into two files to avoid delegate_to

* Add the integration tests, woops
This commit is contained in:
Kevin Breit 2019-07-26 10:39:20 -05:00 committed by Paul Belanger
parent 4e8df9a4b8
commit db783eb2b9
4 changed files with 445 additions and 0 deletions

View file

@ -0,0 +1,241 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2019, Kevin Breit (@kbreit) <kevin.breit@kevinbreit.net>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'
}
DOCUMENTATION = r'''
---
module: meraki_firewalled_services
short_description: Edit firewall policies for administrative network services
version_added: "2.9"
description:
- Allows for setting policy firewalled services for Meraki network devices.
options:
auth_key:
description:
- Authentication key provided by the dashboard. Required if environmental variable MERAKI_KEY is not set.
type: str
net_name:
description:
- Name of a network.
aliases: [ network ]
type: str
net_id:
description:
- ID number of a network.
type: str
org_name:
description:
- Name of organization associated to a network.
type: str
org_id:
description:
- ID of organization associated to a network.
type: str
state:
description:
- States that a policy should be created or modified.
choices: [present, query]
default: present
type: str
service:
description:
- Network service to query or modify.
choices: [ICMP, SNMP, web]
type: str
access:
description:
- Network service to query or modify.
choices: [blocked, restricted, unrestricted]
type: str
allowed_ips:
description:
- List of IP addresses allowed to access a service.
- Only used when C(access) is set to restricted.
type: list
author:
- Kevin Breit (@kbreit)
extends_documentation_fragment: meraki
'''
EXAMPLES = r'''
- name: Set icmp service to blocked
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: ICMP
access: blocked
delegate_to: localhost
- name: Set icmp service to restricted
meraki_firewalled_services:
auth_key: abc123
state: present
org_name: YourOrg
net_name: YourNet
service: web
access: restricted
allowed_ips:
- 192.0.1.1
- 192.0.1.2
delegate_to: localhost
- name: Query appliance services
meraki_firewalled_services:
auth_key: abc123
state: query
org_name: YourOrg
net_name: YourNet
delegate_to: localhost
- name: Query services
meraki_firewalled_services:
auth_key: abc123
state: query
org_name: YourOrg
net_name: YourNet
service: ICMP
delegate_to: localhost
'''
RETURN = r'''
data:
description: List of network services.
returned: info
type: complex
contains:
access:
description: Access assigned to a service type.
returned: success
type: str
sample: unrestricted
service:
description: Service to apply policy to.
returned: success
type: str
sample: ICMP
allowed_ips:
description: List of IP addresses to have access to service.
returned: success
type: str
sample: 192.0.1.0
'''
import os
from ansible.module_utils.basic import AnsibleModule, json, env_fallback
from ansible.module_utils.urls import fetch_url
from ansible.module_utils._text import to_native
from ansible.module_utils.common.dict_transformations import recursive_diff
from ansible.module_utils.network.meraki.meraki import MerakiModule, meraki_argument_spec
def main():
# define the available arguments/parameters that a user can pass to
# the module
argument_spec = meraki_argument_spec()
argument_spec.update(
net_id=dict(type='str'),
net_name=dict(type='str', aliases=['network']),
state=dict(type='str', default='present', choices=['query', 'present']),
service=dict(type='str', default=None, choices=['ICMP', 'SNMP', 'web']),
access=dict(type='str', choices=['blocked', 'restricted', 'unrestricted']),
allowed_ips=dict(type='list', element='str'),
)
mutually_exclusive = [('net_name', 'net_id')]
# the AnsibleModule object will be our abstraction working with Ansible
# this includes instantiation, a couple of common attr would be the
# args/params passed to the execution, as well as if the module
# supports check mode
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
mutually_exclusive=mutually_exclusive
)
meraki = MerakiModule(module, function='firewalled_services')
module.params['follow_redirects'] = 'all'
net_services_urls = {'firewalled_services': '/networks/{net_id}/firewalledServices'}
services_urls = {'firewalled_services': '/networks/{net_id}/firewalledServices/{service}'}
meraki.url_catalog['network_services'] = net_services_urls
meraki.url_catalog['service'] = services_urls
# manipulate or modify the state as needed (this is going to be the
# part where your module will do what it needs to do)
org_id = meraki.params['org_id']
if not org_id:
org_id = meraki.get_org_id(meraki.params['org_name'])
net_id = None
if net_id is None:
nets = meraki.get_nets(org_id=org_id)
net_id = meraki.get_net_id(org_id, meraki.params['net_name'], data=nets)
if meraki.params['state'] == 'present':
if meraki.params['access'] != 'restricted' and meraki.params['allowed_ips'] is not None:
meraki.fail_json(msg="allowed_ips is only allowed when access is restricted.")
payload = {'access': meraki.params['access']}
if meraki.params['access'] == 'restricted':
payload['allowedIps'] = meraki.params['allowed_ips']
if meraki.params['state'] == 'query':
if meraki.params['service'] is None:
path = meraki.construct_path('network_services', net_id=net_id)
response = meraki.request(path, method='GET')
meraki.result['data'] = response
meraki.exit_json(**meraki.result)
else:
path = meraki.construct_path('service', net_id=net_id, custom={'service': meraki.params['service']})
response = meraki.request(path, method='GET')
meraki.result['data'] = response
meraki.exit_json(**meraki.result)
elif meraki.params['state'] == 'present':
path = meraki.construct_path('service', net_id=net_id, custom={'service': meraki.params['service']})
original = meraki.request(path, method='GET')
if meraki.is_update_required(original, payload, optional_ignore=['service']):
if meraki.check_mode is True:
diff_payload = {'service': meraki.params['service']} # Need to add service as it's not in payload
diff_payload.update(payload)
diff = recursive_diff(original, diff_payload)
original.update(payload)
meraki.result['diff'] = {'before': diff[0],
'after': diff[1]}
meraki.result['data'] = original
meraki.result['changed'] = True
meraki.exit_json(**meraki.result)
path = meraki.construct_path('service', net_id=net_id, custom={'service': meraki.params['service']})
response = meraki.request(path, method='PUT', payload=json.dumps(payload))
if meraki.status == 200:
diff = recursive_diff(original, response)
meraki.result['diff'] = {'before': diff[0],
'after': diff[1]}
meraki.result['data'] = response
meraki.result['changed'] = True
else:
meraki.result['data'] = original
# in the event of a successful module execution, you will want to
# simple AnsibleModule.exit_json(), passing the key/value results
meraki.exit_json(**meraki.result)
if __name__ == '__main__':
main()

View file

@ -0,0 +1 @@
unsupported

View file

@ -0,0 +1,7 @@
# Test code for the Meraki Firewalled Services module
# Copyright: (c) 2018, Kevin Breit (@kbreit)
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
---
- name: Run test cases
include: tests.yml ansible_connection=local

View file

@ -0,0 +1,196 @@
# Test code for the Meraki modules
# Copyright: (c) 2019, Kevin Breit (@kbreit)
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
---
- block:
- name: Create network
meraki_network:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
type: appliance
register: create
- set_fact:
net_id: create.data.id
- name: Set icmp service to blocked with check mode
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: ICMP
access: blocked
register: icmp_blocked_check
check_mode: yes
- debug:
var: icmp_blocked_check
- assert:
that:
- icmp_blocked_check.data is defined
- icmp_blocked_check is changed
- name: Set icmp service to blocked
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: ICMP
access: blocked
register: icmp_blocked
- debug:
var: icmp_blocked
- assert:
that:
- icmp_blocked.data is defined
- icmp_blocked is changed
- name: Set icmp service to blocked with idempotency
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: ICMP
access: blocked
register: icmp_blocked_idempotent
- debug:
var: icmp_blocked_idempotent
- assert:
that:
- icmp_blocked_idempotent.data is defined
- icmp_blocked_idempotent is not changed
- name: Set icmp service to restricted with check mode
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: web
access: restricted
allowed_ips:
- 192.0.1.1
- 192.0.1.2
check_mode: yes
register: web_restricted_check
- debug:
var: web_restricted_check
- assert:
that:
- web_restricted_check.data is defined
- web_restricted_check is changed
- name: Set icmp service to restricted
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: web
access: restricted
allowed_ips:
- 192.0.1.1
- 192.0.1.2
register: web_restricted
- debug:
var: web_restricted
- assert:
that:
- web_restricted.data is defined
- web_restricted is changed
- name: Set icmp service to restricted with idempotency
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: web
access: restricted
allowed_ips:
- 192.0.1.1
- 192.0.1.2
register: web_restricted_idempotent
- debug:
var: web_restricted_idempotent
- assert:
that:
- web_restricted_idempotent.data is defined
- web_restricted_idempotent is not changed
- name: Test error for access restricted and allowed_ips
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: present
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: web
access: unrestricted
allowed_ips:
- 192.0.1.1
- 192.0.1.2
register: access_error
ignore_errors: yes
- assert:
that:
- 'access_error.msg == "allowed_ips is only allowed when access is restricted."'
- name: Query appliance services
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: query
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
register: query_appliance
- debug:
var: query_appliance
- assert:
that:
- query_appliance.data is defined
- name: Query services
meraki_firewalled_services:
auth_key: '{{ auth_key }}'
state: query
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance
service: ICMP
register: query_service
- debug:
var: query_service
- assert:
that:
- query_service.data is defined
#############################################################################
# Tear down starts here
#############################################################################
always:
- name: Delete all networks
meraki_network:
auth_key: '{{ auth_key }}'
state: absent
org_name: '{{test_org_name}}'
net_name: IntTestNetworkAppliance