Closes #651 and #652 - Wireless modules (#678)

* Add module for Wireless LAN
* Add module for Wireless LAN Group
* Add module for Wireless link
* Add tests for wireless modules
* Add initial wireless links for CI

Author: rodvand

plugins/module_utils/netbox_utils.py

@@ -91,6 +91,7 @@
     secrets=[],
     tenancy=["tenants", "tenant_groups", "contacts", "contact_groups", "contact_roles"],
     virtualization=["cluster_groups", "cluster_types", "clusters", "virtual_machines"],
+    wireless=["wireless_lans", "wireless_lan_groups", "wireless_links"],
 )
 
 # Used to normalize data for the respective query types used to find endpoints
@@ -120,6 +121,7 @@
     parent_region="slug",
     parent_site_group="slug",
     parent_tenant_group="slug",
+    parent_wireless_lan_group="slug",
     power_panel="name",
     power_port="name",
     power_port_template="name",
@@ -151,6 +153,8 @@
     vlan_group="slug",
     vlan_role="name",
     vrf="name",
+    wireless_lan="ssid",
+    wireless_lan_group="slug",
 )
 
 # Specifies keys within data that need to be converted to ID and the endpoint to be used when queried
@@ -183,6 +187,8 @@
     "import_targets": "route_targets",
     "installed_device": "devices",
     "interface": "interfaces",
+    "interface_a": "interfaces",
+    "interface_b": "interfaces",
     "interface_template": "interface_templates",
     "ip_addresses": "ip_addresses",
     "ipaddresses": "ip_addresses",
@@ -200,6 +206,7 @@
     "parent_region": "regions",
     "parent_site_group": "site_groups",
     "parent_tenant_group": "tenant_groups",
+    "parent_wireless_lan_group": "wireless_lan_groups",
     "platforms": "platforms",
     "power_panel": "power_panels",
     "power_port": "power_ports",
@@ -242,6 +249,9 @@
     "vlan_group": "vlan_groups",
     "vlan_role": "roles",
     "vrf": "vrfs",
+    "wireless_lan": "wireless_lans",
+    "wireless_lan_group": "wireless_lan_groups",
+    "wireless_link": "wireless_links",
 }
 
 ENDPOINT_NAME_MAPPING = {
@@ -304,6 +314,9 @@
     "vlans": "vlan",
     "vlan_groups": "vlan_group",
     "vrfs": "vrf",
+    "wireless_lans": "wireless_lan",
+    "wireless_lan_groups": "wireless_lan_group",
+    "wireless_links": "wireless_link",
 }
 
 ALLOWED_QUERY_PARAMS = {
@@ -355,6 +368,8 @@
     "front_port_template": set(["name", "device_type", "rear_port"]),
     "installed_device": set(["name"]),
     "interface": set(["name", "device", "virtual_machine"]),
+    "interface_a": set(["name", "device"]),
+    "interface_b": set(["name", "device"]),
     "interface_template": set(["name", "device_type"]),
     "inventory_item": set(["name", "device"]),
     "ip_address": set(["address", "vrf", "device", "interface", "assigned_object"]),
@@ -408,6 +423,9 @@
     "vlan": set(["group", "name", "site", "tenant", "vid", "vlan_group"]),
     "vlan_group": set(["slug", "site", "scope"]),
     "vrf": set(["name", "tenant"]),
+    "wireless_lan": set(["ssid"]),
+    "wireless_lan_group": set(["name"]),
+    "wireless_link": set(["interface_a", "interface_b"]),
 }
 
 QUERY_PARAMS_IDS = set(
@@ -472,6 +490,7 @@
     "parent_region": "parent",
     "parent_site_group": "parent",
     "parent_tenant_group": "parent",
+    "parent_wireless_lan_group": "parent",
     "power_port_template": "power_port",
     "prefix_role": "role",
     "rack_group": "group",
@@ -485,6 +504,7 @@
     "virtual_machine_role": "role",
     "vlan_role": "role",
     "vlan_group": "group",
+    "wireless_lan_group": "group",
 }
 
 # This is used to dynamically convert name to slug on endpoints requiring a slug
@@ -512,6 +532,7 @@
     "platforms",
     "providers",
     "vlan_groups",
+    "wireless_lan_groups",
 }
 
 SCOPE_TO_ENDPOINT = {
@@ -954,6 +975,7 @@ def _find_app(self, endpoint):
         for k, v in API_APPS_ENDPOINTS.items():
             if endpoint in v:
                 nb_app = k
+
         return nb_app
 
     def _find_ids(self, data, user_query_params):

plugins/module_utils/netbox_wireless.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2021, Martin Rødvand (@rodvand) <mikhail.yohman@gmail.com>
+# 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
+
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_utils import (
+    NetboxModule,
+    ENDPOINT_NAME_MAPPING,
+    SLUG_REQUIRED,
+)
+
+
+NB_WIRELESS_LANS = "wireless_lans"
+NB_WIRELESS_LAN_GROUPS = "wireless_lan_groups"
+NB_WIRELESS_LINKS = "wireless_links"
+
+
+class NetboxWirelessModule(NetboxModule):
+    def __init__(self, module, endpoint):
+        super().__init__(module, endpoint)
+
+    def run(self):
+        """
+        This function should have all necessary code for endpoints within the application
+        to create/update/delete the endpoint objects
+        Supported endpoints:
+        - wireless LAN
+        - wireless LAN Group
+        - wireless link
+        """
+        # Used to dynamically set key when returning results
+        endpoint_name = ENDPOINT_NAME_MAPPING[self.endpoint]
+
+        self.result = {"changed": False}
+
+        application = self._find_app(self.endpoint)
+        nb_app = getattr(self.nb, application)
+        nb_endpoint = getattr(nb_app, self.endpoint)
+        user_query_params = self.module.params.get("query_params")
+
+        data = self.data
+
+        # Used for msg output
+        if data.get("name"):
+            name = data["name"]
+        elif data.get("slug"):
+            name = data["slug"]
+        elif data.get("ssid"):
+            name = data["ssid"]
+
+        if data.get("interface_a") and data.get("interface_b"):
+            interface_a_name = self.module.params["data"]["interface_a"].get("name")
+            interface_a_device = self.module.params["data"]["interface_a"].get("device")
+            interface_b_name = self.module.params["data"]["interface_b"].get("name")
+            interface_b_device = self.module.params["data"]["interface_b"].get("device")
+            name = f"{interface_a_device} {interface_a_name} <> {interface_b_device} {interface_b_name}"
+
+        if self.endpoint in SLUG_REQUIRED:
+            if not data.get("slug"):
+                data["slug"] = self._to_slug(name)
+
+        object_query_params = self._build_query_params(
+            endpoint_name, data, user_query_params
+        )
+        self.nb_object = self._nb_endpoint_get(nb_endpoint, object_query_params, name)
+
+        if self.state == "present":
+            self._ensure_object_exists(nb_endpoint, endpoint_name, name, data)
+        elif self.state == "absent":
+            self._ensure_object_absent(endpoint_name, name)
+
+        try:
+            serialized_object = self.nb_object.serialize()
+        except AttributeError:
+            serialized_object = self.nb_object
+
+        self.result.update({endpoint_name: serialized_object})
+
+        self.module.exit_json(**self.result)

plugins/modules/netbox_wireless_lan.py

@@ -0,0 +1,192 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2021, Martin Rødvand (@rodvand)
+# 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
+
+DOCUMENTATION = r"""
+---
+module: netbox_wireless_lan
+short_description: Creates or removes Wireless LANs from NetBox
+description:
+  - Creates or removes wireless LANs from NetBox
+notes:  
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Martin Rødvand (@rodvand)
+requirements:
+  - pynetbox
+version_added: "3.5.0"
+extends_documentation_fragment:
+  - netbox.netbox.common
+options:
+  data:
+    type: dict
+    description:
+      - Defines the contact configuration
+    suboptions:
+      ssid:
+        description:
+          - Name of the SSID to be created
+        required: true
+        type: str
+      description:
+        description:
+          - The description of the Wireless LAN
+        required: false
+        type: str
+      wireless_lan_group:
+        description:
+          - The wireless LAN group
+        required: false
+        type: raw
+      vlan:
+        description:
+          - The VLAN of the Wireless LAN
+        required: false
+        type: raw
+      auth_type:
+        description:
+          - The authentication type of the Wireless LAN
+        choices:
+          - open
+          - wep
+          - wpa-personal
+          - wpa-enterprise
+        required: false
+        type: str
+      auth_cipher:
+        description:
+          - The authentication cipher of the Wireless LAN
+        choices:
+          - auto
+          - tkip
+          - aes
+        required: false
+        type: str
+      auth_psk:
+        description:
+          - The PSK of the Wireless LAN
+        required: false
+        type: str    
+      tags:
+        description:
+          - Any tags that the Wireless LAN may need to be associated with
+        required: false
+        type: list
+        elements: raw
+      custom_fields:
+        description:
+          - must exist in NetBox
+        required: false
+        type: dict    
+    required: true
+"""
+
+EXAMPLES = r"""
+- name: "Test NetBox module"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+  tasks:
+    - name: Create Wireless LAN within NetBox with only required information
+      netbox_wireless_lan:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          ssid: Wireless Network One
+        state: present
+
+    - name: Delete Wireless LAN within netbox
+      netbox_wireless_lan:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          ssid: Wireless Network One
+        state: absent
+
+    - name: Create Wireless LAN with all parameters
+      netbox_wireless_lan:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          ssid: Wireless Network One          
+          description: Cool Wireless Network
+          auth_type: wpa-enterprise
+          auth_cipher: aes
+          auth_psk: psk123456                    
+          tags:
+            - tagA
+            - tagB
+            - tagC
+        state: present
+"""
+
+RETURN = r"""
+wireless_lan:
+  description: Serialized object as created or already existent within NetBox
+  returned: on creation
+  type: dict
+msg:
+  description: Message indicating failure or info about what has been achieved
+  returned: always
+  type: str
+"""
+
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_utils import (
+    NetboxAnsibleModule,
+    NETBOX_ARG_SPEC,
+)
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_wireless import (
+    NetboxWirelessModule,
+    NB_WIRELESS_LANS,
+)
+from copy import deepcopy
+
+
+def main():
+    """
+    Main entry point for module execution
+    """
+    argument_spec = deepcopy(NETBOX_ARG_SPEC)
+    argument_spec.update(
+        dict(
+            data=dict(
+                type="dict",
+                required=True,
+                options=dict(
+                    ssid=dict(required=True, type="str"),
+                    description=dict(required=False, type="str"),
+                    wireless_lan_group=dict(required=False, type="raw"),
+                    vlan=dict(required=False, type="raw"),
+                    auth_type=dict(
+                        required=False,
+                        choices=["open", "wep", "wpa-enterprise", "wpa-personal"],
+                        type="str",
+                    ),
+                    auth_cipher=dict(
+                        required=False, choices=["auto", "tkip", "aes"], type="str"
+                    ),
+                    auth_psk=dict(required=False, type="str"),
+                    tags=dict(required=False, type="list", elements="raw"),
+                    custom_fields=dict(required=False, type="dict"),
+                ),
+            ),
+        )
+    )
+
+    required_if = [("state", "present", ["ssid"]), ("state", "absent", ["ssid"])]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_wireless_lan = NetboxWirelessModule(module, NB_WIRELESS_LANS)
+    netbox_wireless_lan.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()