new circuit modules (#37)

Author: FragmentedPacket

README.md

@@ -12,6 +12,9 @@
 ## Existing Modules
 
 - netbox_aggregate
+- netbox_circuit
+- netbox_circuit_termination
+- netbox_circuit_type
 - netbox_cluster
 - netbox_cluster_group
 - netbox_cluster_type
@@ -26,6 +29,7 @@
 - netbox_manufacturer
 - netbox_platform
 - netbox_prefix
+- netbox_provider
 - netbox_rack_group
 - netbox_rack_role
 - netbox_rack

plugins/module_utils/netbox_circuits.py

@@ -10,12 +10,19 @@
     from ansible_collections.fragmentedpacket.netbox_modules.plugins.module_utils.netbox_utils import (
         NetboxModule,
         ENDPOINT_NAME_MAPPING,
+        SLUG_REQUIRED,
     )
 except ImportError:
     import sys
 
     sys.path.append(".")
-    from netbox_utils import NetboxModule, ENDPOINT_NAME_MAPPING
+    from netbox_utils import NetboxModule, ENDPOINT_NAME_MAPPING, SLUG_REQUIRED
+
+
+NB_PROVIDERS = "providers"
+NB_CIRCUIT_TYPES = "circuit_types"
+NB_CIRCUIT_TERMINATIONS = "circuit_terminations"
+NB_CIRCUITS = "circuits"
 
 
 class NetboxCircuitsModule(NetboxModule):
@@ -27,6 +34,10 @@ def run(self):
         This function should have all necessary code for endpoints within the application
         to create/update/delete the endpoint objects
         Supported endpoints:
+        - circuit_types
+        - circuit_terminations
+        - circuits
+        - providers
         """
         # Used to dynamically set key when returning results
         endpoint_name = ENDPOINT_NAME_MAPPING[self.endpoint]
@@ -40,9 +51,21 @@ def run(self):
         data = self.data
 
         # Used for msg output
-        name = data.get("name")
-
-        data["slug"] = self._to_slug(name)
+        if data.get("name"):
+            name = data["name"]
+        elif data.get("slug"):
+            name = data["slug"]
+        elif data.get("cid"):
+            name = data["cid"]
+        elif data.get("circuit") and data.get("term_side"):
+            circuit = self.nb.circuits.circuits.get(data["circuit"]).serialize()
+            name = "{0}_{1}".format(
+                circuit["cid"].replace(" ", "_"), data["term_side"]
+            ).lower()
+
+        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)
         try:

plugins/module_utils/netbox_utils.py

@@ -26,7 +26,7 @@
 
 # Used to map endpoints to applications dynamically
 API_APPS_ENDPOINTS = dict(
-    circuits=[],
+    circuits=["circuits", "circuit_types", "circuit_terminations", "providers"],
     dcim=[
         "device_bays",
         "devices",
@@ -61,6 +61,9 @@
 
 # Used to normalize data for the respective query types used to find endpoints
 QUERY_TYPES = dict(
+    circuit="cid",
+    circuit_termination="circuit",
+    circuit_type="slug",
     cluster="name",
     cluster_group="slug",
     cluster_type="slug",
@@ -78,6 +81,7 @@
     primary_ip="address",
     primary_ip4="address",
     primary_ip6="address",
+    provider="slug",
     rack="name",
     rack_group="slug",
     rack_role="slug",
@@ -97,6 +101,9 @@
 
 # Specifies keys within data that need to be converted to ID and the endpoint to be used when queried
 CONVERT_TO_ID = dict(
+    circuit="circuits",
+    circuit_type="circuit_types",
+    circuit_termination="circuit_terminations",
     cluster="clusters",
     cluster_group="cluster_groups",
     cluster_type="cluster_types",
@@ -117,6 +124,7 @@
     primary_ip="ip_addresses",
     primary_ip4="ip_addresses",
     primary_ip6="ip_addresses",
+    provider="providers",
     rack="racks",
     rack_group="rack_groups",
     rack_role="rack_roles",
@@ -138,6 +146,9 @@
 
 ENDPOINT_NAME_MAPPING = {
     "aggregates": "aggregate",
+    "circuit_terminations": "circuit_termination",
+    "circuit_types": "circuit_type",
+    "circuits": "circuit",
     "clusters": "cluster",
     "cluster_groups": "cluster_group",
     "cluster_types": "cluster_type",
@@ -151,6 +162,7 @@
     "manufacturers": "manufacturer",
     "platforms": "platform",
     "prefixes": "prefix",
+    "providers": "provider",
     "racks": "rack",
     "rack_groups": "rack_group",
     "rack_roles": "rack_role",
@@ -267,9 +279,16 @@
 
 VIRTUAL_MACHINE_STATUS = dict(offline=0, active=1, staged=3)
 
+CIRCUIT_STATUS = dict(
+    deprovisioning=0, active=1, planned=2, provisioning=3, offline=4, decommissioned=5,
+)
+
 # This is used when attempting to search for existing endpoints
 ALLOWED_QUERY_PARAMS = {
     "aggregate": set(["prefix", "rir"]),
+    "circuit": set(["cid"]),
+    "circuit_type": set(["slug"]),
+    "circuit_termination": set(["circuit", "term_side"]),
     "cluster": set(["name", "type"]),
     "cluster_group": set(["slug"]),
     "cluster_type": set(["slug"]),
@@ -290,6 +309,7 @@
     "prefix": set(["prefix", "vrf"]),
     "primary_ip4": set(["address", "vrf"]),
     "primary_ip6": set(["address", "vrf"]),
+    "provider": set(["slug"]),
     "rack": set(["name", "site"]),
     "rack_group": set(["slug"]),
     "rack_role": set(["slug"]),
@@ -309,11 +329,23 @@
 }
 
 QUERY_PARAMS_IDS = set(
-    ["cluster", "device", "group", "rir", "vrf", "site", "vlan_group", "tenant", "type"]
+    [
+        "circuit",
+        "cluster",
+        "device",
+        "group",
+        "rir",
+        "vrf",
+        "site",
+        "vlan_group",
+        "tenant",
+        "type",
+    ]
 )
 
 # This is used when converting static choices to an ID value acceptable to Netbox API
 REQUIRED_ID_FIND = {
+    "circuits": [{"status": CIRCUIT_STATUS}],
     "devices": [{"status": DEVICE_STATUS, "face": FACE_ID}],
     "device_types": [{"subdevice_role": SUBDEVICE_ROLES}],
     "interfaces": [{"form_factor": INTF_FORM_FACTOR, "mode": INTF_MODE}],
@@ -328,6 +360,7 @@
 
 # This is used to map non-clashing keys to Netbox API compliant keys to prevent bad logic in code for similar keys but different modules
 CONVERT_KEYS = {
+    "circuit_type": "type",
     "cluster_type": "type",
     "cluster_group": "group",
     "parent_region": "parent",
@@ -342,6 +375,7 @@
 
 # This is used to dynamically conver name to slug on endpoints requiring a slug
 SLUG_REQUIRED = {
+    "circuit_types",
     "cluster_groups",
     "cluster_types",
     "device_roles",
@@ -353,6 +387,7 @@
     "roles",
     "manufacturers",
     "platforms",
+    "providers",
     "vlan_groups",
 }
 

plugins/modules/netbox_circuit.py

@@ -0,0 +1,182 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2019, Mikhail Yohman (@FragmentedPacket) <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
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.1",
+    "status": ["preview"],
+    "supported_by": "community",
+}
+
+DOCUMENTATION = r"""
+---
+module: netbox_circuit
+short_description: Create, update or delete circuits within Netbox
+description:
+  - Creates, updates or removes circuits from Netbox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Mikhail Yohman (@FragmentedPacket)
+requirements:
+  - pynetbox
+version_added: '0.1.0'
+options:
+  netbox_url:
+    description:
+      - URL of the Netbox instance resolvable by Ansible control host
+    required: true
+  netbox_token:
+    description:
+      - The token created within Netbox to authorize API access
+    required: true
+  data:
+    description:
+      - Defines the circuit configuration
+    suboptions:
+      cid:
+        description:
+          - The circuit id of the circuit
+        required: true
+      provider:
+        description:
+          - The provider of the circuit
+        required: true
+      circuit_type:
+        description:
+          - The circuit type of the circuit
+      status:
+        description:
+          - The status of the circuit
+        choices:
+          - Active
+          - Offline
+          - Planned
+          - Provisioning
+          - Deprovisioning
+          - Decommissioned
+      tenant:
+        description:
+          - The tenant assigned to the circuit
+      install_date:
+        description:
+          - The date the circuit was installed. e.g. YYYY-MM-DD
+      commit_rate:
+        description:
+          - Commit rate of the circuit (Kbps)
+      description:
+        description:
+          - Description of the circuit
+      comments:
+        description:
+          - Comments related to circuit
+      tags:
+        description:
+          - Any tags that the device may need to be associated with
+      custom_fields:
+        description:
+          - must exist in Netbox
+  state:
+    description:
+      - Use C(present) or C(absent) for adding or removing.
+    choices: [ absent, present ]
+    default: present
+  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: 'yes'
+    type: bool
+"""
+
+EXAMPLES = r"""
+- name: "Test Netbox modules"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+
+  tasks:
+    - name: Create circuit within Netbox with only required information
+      netbox_circuit:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          cid: Test Circuit
+          provider: Test Provider
+          circuit_type: Test Circuit Type
+        state: present
+
+    - name: Update circuit with other fields
+      netbox_circuit:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          cid: Test-Circuit-1000
+          provider: Test Provider
+          circuit_type: Test Circuit Type
+          status: Active
+          tenant: Test Tenant
+          install_date: "2018-12-25"
+          commit_rate: 10000
+          description: Test circuit
+          comments: "FAST CIRCUIT"
+        state: present
+
+    - name: Delete circuit within netbox
+      netbox_circuit:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          cid: Test-Circuit-1000
+        state: absent
+"""
+
+RETURN = r"""
+circuit:
+  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.fragmentedpacket.netbox_modules.plugins.module_utils.netbox_utils import (
+    NetboxAnsibleModule,
+)
+from ansible_collections.fragmentedpacket.netbox_modules.plugins.module_utils.netbox_circuits import (
+    NetboxCircuitsModule,
+    NB_CIRCUITS,
+)
+
+
+def main():
+    """
+    Main entry point for module execution
+    """
+    argument_spec = dict(
+        netbox_url=dict(type="str", required=True),
+        netbox_token=dict(type="str", required=True, no_log=True),
+        data=dict(type="dict", required=True),
+        state=dict(required=False, default="present", choices=["present", "absent"]),
+        validate_certs=dict(type="bool", default=True),
+    )
+
+    required_if = [("state", "present", ["cid"]), ("state", "absent", ["cid"])]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_circuit = NetboxCircuitsModule(module, NB_CIRCUITS)
+    netbox_circuit.run()
+
+
+if __name__ == "__main__":
+    main()