New Modules: Add modules for front/rear port management (#237)

Author: toerb

README.md

@@ -34,6 +34,8 @@ To keep the code simple, we only officially support the two latest releases of N
 - netbox_device_role
 - netbox_device_type
 - netbox_device
+- netbox_front_port
+- netbox_front_port_template
 - netbox_inventory_item
 - netbox_ip_address
 - netbox_ipam_role
@@ -50,6 +52,8 @@ To keep the code simple, we only officially support the two latest releases of N
 - netbox_rack_group
 - netbox_rack_role
 - netbox_rack
+- netbox_rear_port
+- netbox_rear_port_template
 - netbox_region
 - netbox_rir
 - netbox_site

plugins/module_utils/netbox_dcim.py

@@ -24,6 +24,8 @@
 NB_DEVICES = "devices"
 NB_DEVICE_ROLES = "device_roles"
 NB_DEVICE_TYPES = "device_types"
+NB_FRONT_PORTS = "front_ports"
+NB_FRONT_PORT_TEMPLATES = "front_port_templates"
 NB_INTERFACES = "interfaces"
 NB_INVENTORY_ITEMS = "inventory_items"
 NB_MANUFACTURERS = "manufacturers"
@@ -37,6 +39,8 @@
 NB_RACKS = "racks"
 NB_RACK_ROLES = "rack_roles"
 NB_RACK_GROUPS = "rack_groups"
+NB_REAR_PORTS = "rear_ports"
+NB_REAR_PORT_TEMPLATES = "rear_port_templates"
 NB_REGIONS = "regions"
 NB_SITES = "sites"
 
@@ -58,6 +62,8 @@ def run(self):
         - devices
         - device_roles
         - device_types
+        - front_ports
+        - front_port_templates
         - interfaces
         - inventory_items
         - manufacturers
@@ -72,6 +78,8 @@ def run(self):
         - racks
         - rack_roles
         - rack_groups
+        - rear_ports
+        - rear_port_templates
         - regions
         """
         # Used to dynamically set key when returning results

plugins/module_utils/netbox_utils.py

@@ -43,6 +43,8 @@
         "devices",
         "device_roles",
         "device_types",
+        "front_ports",
+        "front_port_templates",
         "interfaces",
         "inventory_items",
         "manufacturers",
@@ -56,6 +58,8 @@
         "racks",
         "rack_groups",
         "rack_roles",
+        "rear_ports",
+        "rear_port_templates",
         "regions",
         "sites",
     ],
@@ -104,6 +108,7 @@
     rack="name",
     rack_group="slug",
     rack_role="slug",
+    rear_port="name",
     region="slug",
     rir="slug",
     slug="slug",
@@ -151,6 +156,7 @@
     rack_group="rack_groups",
     rack_role="rack_roles",
     region="regions",
+    rear_port="rear_ports",
     rir="rirs",
     services="services",
     site="sites",
@@ -182,6 +188,8 @@
     "devices": "device",
     "device_roles": "device_role",
     "device_types": "device_type",
+    "front_ports": "front_port",
+    "front_port_templates": "front_port_template",
     "interfaces": "interface",
     "inventory_items": "inventory_item",
     "ip_addresses": "ip_address",
@@ -198,6 +206,8 @@
     "racks": "rack",
     "rack_groups": "rack_group",
     "rack_roles": "rack_role",
+    "rear_ports": "rear_port",
+    "rear_port_templates": "rear_port_template",
     "regions": "region",
     "rirs": "rir",
     "roles": "role",
@@ -227,6 +237,8 @@
     "device": set(["name"]),
     "device_role": set(["slug"]),
     "device_type": set(["slug"]),
+    "front_port": set(["name", "device", "rear_port"]),
+    "front_port_template": set(["name", "device_type", "rear_port"]),
     "installed_device": set(["name"]),
     "interface": set(["name", "device", "virtual_machine"]),
     "inventory_item": set(["name", "device"]),
@@ -252,6 +264,8 @@
     "rack_group": set(["slug"]),
     "rack_role": set(["slug"]),
     "region": set(["slug"]),
+    "rear_port": set(["name", "device"]),
+    "rear_port_template": set(["name", "device_type"]),
     "rir": set(["slug"]),
     "role": set(["slug"]),
     "services": set(["device", "virtual_machine", "name", "port", "protocol"]),
@@ -290,6 +304,8 @@
     "console_server_port_templates": set(["type"]),
     "devices": set(["status", "face"]),
     "device_types": set(["subdevice_role"]),
+    "front_ports": set(["type"]),
+    "front_port_templates": set(["type"]),
     "interfaces": set(["form_factor", "mode", "type"]),
     "ip_addresses": set(["status", "role"]),
     "prefixes": set(["status"]),
@@ -299,6 +315,8 @@
     "power_ports": set(["type"]),
     "power_port_templates": set(["type"]),
     "racks": set(["status", "outer_unit", "type"]),
+    "rear_ports": set(["type"]),
+    "rear_port_templates": set(["type"]),
     "services": set(["protocol"]),
     "sites": set(["status"]),
     "virtual_machines": set(["status", "face"]),

plugins/modules/netbox_front_port.py

@@ -0,0 +1,239 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# © 2020 Nokia
+# Licensed under the GNU General Public License v3.0 only
+# SPDX-License-Identifier: GPL-3.0-only
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.1",
+    "status": ["preview"],
+    "supported_by": "community",
+}
+
+DOCUMENTATION = r"""
+---
+module: netbox_front_port
+short_description: Create, update or delete front ports within Netbox
+description:
+  - Creates, updates or removes front ports from Netbox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Tobias Groß (@toerb)
+requirements:
+  - pynetbox
+version_added: '0.2.3'
+options:
+  netbox_url:
+    description:
+      - URL of the Netbox instance resolvable by Ansible control host
+    required: true
+    type: str
+  netbox_token:
+    description:
+      - The token created within Netbox to authorize API access
+    required: true
+    type: str
+  data:
+    type: dict
+    required: true
+    description:
+      - Defines the front port configuration
+    suboptions:
+      device:
+        description:
+          - The device the front port is attached to
+        required: true
+        type: raw
+      name:
+        description:
+          - The name of the front port
+        required: true
+        type: str
+      type:
+        description:
+          - The type of the front port
+        choices:
+          - 8p8c
+          - 110-punch
+          - bnc
+          - mrj21
+          - fc
+          - lc
+          - lc-apc
+          - lsh
+          - lsh-apc
+          - mpo
+          - mtrj
+          - sc
+          - sc-apc
+          - st
+        required: true
+        type: str
+      rear_port:
+        description:
+          - The rear_port the front port is attached to
+        required: true
+        type: raw        
+      rear_port_position:
+        description:
+          - The position of the rear port this front port is connected to
+        required: false
+        type: int
+      description:
+        description:
+          - Description of the front port
+        required: false
+        type: str
+      tags:
+        description:
+          - Any tags that the front port may need to be associated with
+        required: false
+        type: list
+  state:
+    description:
+      - Use C(present) or C(absent) for adding or removing.
+    choices: [ absent, present ]
+    default: present
+    type: str
+  query_params:
+    description:
+      - This can be used to override the specified values in ALLOWED_QUERY_PARAMS that is defined
+      - in plugins/module_utils/netbox_utils.py and provides control to users on what may make
+      - an object unique in their environment.
+    required: false
+    type: list
+  validate_certs:
+    description:
+      - If C(no), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
+    default: true
+    type: raw
+"""
+
+EXAMPLES = r"""
+- name: "Test Netbox modules"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+
+  tasks:
+    - name: Create front port within Netbox with only required information
+      netbox_front_port:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Front Port
+          device: Test Device
+          type: bnc
+          rear_port: Test Rear Port
+        state: present
+
+    - name: Update front port with other fields
+      netbox_front_port:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Front Port
+          device: Test Device
+          type: bnc
+          rear_port: Test Rear Port
+          rear_port_position: 5
+          description: front port description
+        state: present
+
+    - name: Delete front port within netbox
+      netbox_front_port:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Front Port
+          device: Test Device
+          type: bnc
+          rear_port: Test Rear Port
+        state: absent
+"""
+
+RETURN = r"""
+front_port:
+  description: Serialized object as created or already existent within Netbox
+  returned: success (when I(state=present))
+  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_dcim import (
+    NetboxDcimModule,
+    NB_FRONT_PORTS,
+)
+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(
+                    device=dict(required=True, type="raw"),
+                    name=dict(required=True, type="str"),
+                    type=dict(
+                        required=True,
+                        choices=[
+                            "8p8c",
+                            "110-punch",
+                            "bnc",
+                            "mrj21",
+                            "fc",
+                            "lc",
+                            "lc-apc",
+                            "lsh",
+                            "lsh-apc",
+                            "mpo",
+                            "mtrj",
+                            "sc",
+                            "sc-apc",
+                            "st",
+                        ],
+                        type="str",
+                    ),
+                    rear_port=dict(required=True, type="raw"),
+                    rear_port_position=dict(required=False, type="int"),
+                    description=dict(required=False, type="str"),
+                    tags=dict(required=False, type="list"),
+                ),
+            ),
+        )
+    )
+
+    required_if = [
+        ("state", "present", ["device", "name", "type", "rear_port"]),
+        ("state", "absent", ["device", "name", "type", "rear_port"]),
+    ]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_front_port = NetboxDcimModule(module, NB_FRONT_PORTS)
+    netbox_front_port.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()