Add module netbox_provider_network - closes #528 (#653)

rodvand · web-flow · commit 0d5378b6fc35 · 2021-11-18T11:12:53.000+01:00
* Add module netbox_provider_network
* Add provider_network to circuit termination
diff --git a/plugins/module_utils/netbox_circuits.py b/plugins/module_utils/netbox_circuits.py
@@ -13,6 +13,7 @@
 
 
 NB_PROVIDERS = "providers"
+NB_PROVIDER_NETWORKS = "provider_networks"
 NB_CIRCUIT_TYPES = "circuit_types"
 NB_CIRCUIT_TERMINATIONS = "circuit_terminations"
 NB_CIRCUITS = "circuits"
@@ -31,6 +32,7 @@ def run(self):
         - circuit_terminations
         - circuits
         - providers
+        - provider_networks
         """
         # Used to dynamically set key when returning results
         endpoint_name = ENDPOINT_NAME_MAPPING[self.endpoint]
diff --git a/plugins/module_utils/netbox_utils.py b/plugins/module_utils/netbox_utils.py
@@ -33,7 +33,13 @@
 
 # Used to map endpoints to applications dynamically
 API_APPS_ENDPOINTS = dict(
-    circuits=["circuits", "circuit_types", "circuit_terminations", "providers"],
+    circuits=[
+        "circuits",
+        "circuit_types",
+        "circuit_terminations",
+        "providers",
+        "provider_networks",
+    ],
     dcim=[
         "cables",
         "console_ports",
@@ -120,6 +126,7 @@
     primary_ip4="address",
     primary_ip6="address",
     provider="slug",
+    provider_network="name",
     rack="name",
     rack_group="slug",
     rack_role="slug",
@@ -197,6 +204,7 @@
     "primary_ip4": "ip_addresses",
     "primary_ip6": "ip_addresses",
     "provider": "providers",
+    "provider_network": "provider_networks",
     "rack": "racks",
     "rack_group": "rack_groups",
     "rack_role": "rack_roles",
@@ -267,6 +275,7 @@
     "power_port_templates": "power_port_template",
     "prefixes": "prefix",
     "providers": "provider",
+    "provider_networks": "provider_network",
     "racks": "rack",
     "rack_groups": "rack_group",
     "rack_roles": "rack_role",
@@ -362,6 +371,7 @@
     "primary_ip4": set(["address", "vrf"]),
     "primary_ip6": set(["address", "vrf"]),
     "provider": set(["slug"]),
+    "provider_network": set(["name"]),
     "rack": set(["name", "site"]),
     "rack_group": set(["slug"]),
     "rack_role": set(["slug"]),
diff --git a/plugins/modules/netbox_circuit_termination.py b/plugins/modules/netbox_circuit_termination.py
@@ -54,6 +54,11 @@
           - The site the circuit termination will be assigned to
         required: false
         type: raw
+      provider_network:
+        description:
+          - The provider_network the circuit termination will be assigned to
+        required: false
+        type: raw
       port_speed:
         description:
           - The speed of the port (Kbps)
@@ -158,6 +163,7 @@ def main():
                     circuit=dict(required=True, type="raw"),
                     term_side=dict(required=True, choices=["A", "Z"]),
                     site=dict(required=False, type="raw"),
+                    provider_network=dict(required=False, type="raw"),
                     port_speed=dict(required=False, type="int"),
                     upstream_speed=dict(required=False, type="int"),
                     xconnect_id=dict(required=False, type="str"),
diff --git a/plugins/modules/netbox_provider_network.py b/plugins/modules/netbox_provider_network.py
@@ -0,0 +1,162 @@
+#!/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
+
+DOCUMENTATION = r"""
+---
+module: netbox_provider_network
+short_description: Create, update or delete provider networks within NetBox
+description:
+  - Creates, updates or removes provider networks from NetBox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Martin Rødvand (@rodvand)
+requirements:
+  - pynetbox
+version_added: '3.4.0'
+extends_documentation_fragment:
+  - netbox.netbox.common
+options:
+  data:
+    type: dict
+    description:
+      - Defines the provider network configuration
+    suboptions:
+      provider:
+        description:
+          - The name of the provider
+        required: true
+        type: raw
+      name:
+        description:
+          - The name of the provider network
+        required: true
+        type: str
+      description:
+        description:
+          - Description related to the provider network
+        required: false
+        type: str
+      comments:
+        description:
+          - Comments related to the provider network
+        required: false
+        type: str
+      tags:
+        description:
+          - Any tags that the provdier_network 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 modules"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+
+  tasks:
+    - name: Create provider network within NetBox with only required information
+      netbox_provider:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          provider: Test Provider
+          name: Test Provider Network
+        state: present
+
+    - name: Update provider with other fields
+      netbox_provider:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          provider: Test Provider
+          name: Test Provider Network
+          description: Describe a Provider Network
+          comments: "A Provider Network"
+        state: present
+
+    - name: Delete provider within netbox
+      netbox_provider:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          provider: test Provider
+          name: Test Provider Network
+        state: absent
+"""
+
+RETURN = r"""
+provider_network:
+  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_circuits import (
+    NetboxCircuitsModule,
+    NB_PROVIDER_NETWORKS,
+)
+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(
+                    provider=dict(required=True, type="raw"),
+                    name=dict(required=True, type="str"),
+                    description=dict(required=False, type="str"),
+                    comments=dict(required=False, type="str"),
+                    tags=dict(required=False, type="list", elements="raw"),
+                    custom_fields=dict(required=False, type="dict"),
+                ),
+            ),
+        ),
+    )
+
+    required_if = [
+        ("state", "present", ["provider", "name"]),
+        ("state", "absent", ["provider", "name"]),
+    ]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_provider_network = NetboxCircuitsModule(module, NB_PROVIDER_NETWORKS)
+    netbox_provider_network.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()
diff --git a/tests/integration/targets/v3.0/tasks/main.yml b/tests/integration/targets/v3.0/tasks/main.yml
@@ -95,6 +95,9 @@
 - name: "NETBOX_PROVIDER TESTS"
   include_tasks: "netbox_provider.yml"
 
+- name: "NETBOX_PROVIDER_NETWORK TESTS"
+  include_tasks: "netbox_provider_network.yml"
+
 - name: "NETBOX_CIRCUIT_TYPE TESTS"
   include_tasks: "netbox_circuit_type.yml"
 
diff --git a/tests/integration/targets/v3.0/tasks/netbox_provider_network.yml b/tests/integration/targets/v3.0/tasks/netbox_provider_network.yml
@@ -0,0 +1,83 @@
+---
+##
+##
+### NETBOX_PROVIDER
+##
+##
+- name: "NETBOX_PROVIDER_NETWORK 1: Create provider network within NetBox with only required information"
+  netbox.netbox.netbox_provider_network:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      provider: Test Provider
+      name: Test Provider Network One
+    state: present
+  register: test_one
+
+- name: "NETBOX_PROVIDER_NETWORK 1: ASSERT - Necessary info creation"
+  assert:
+    that:
+      - test_one is changed
+      - test_one['diff']['before']['state'] == "absent"
+      - test_one['diff']['after']['state'] == "present"
+      - test_one['provider_network']['name'] == "Test Provider Network One"
+      - test_one['msg'] == "provider_network Test Provider Network One created"
+
+- name: "NETBOX_PROVIDER_NETWORK 2: Duplicate"
+  netbox.netbox.netbox_provider_network:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      provider: Test Provider
+      name: Test Provider Network One
+    state: present
+  register: test_two
+
+- name: "NETBOX_PROVIDER_NETWORK 2: ASSERT - Create duplicate"
+  assert:
+    that:
+      - not test_two['changed']
+      - test_two['provider_network']['name'] == "Test Provider Network One"
+      - test_two['msg'] == "provider_network Test Provider Network One already exists"
+
+- name: "NETBOX_PROVIDER_NETWORK 3: Update provider network with other fields"
+  netbox.netbox.netbox_provider_network:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      provider: Test Provider
+      name: Test Provider Network One
+      description: Describe a Provider Network
+      comments: "A provider network"
+    state: present
+  register: test_three
+
+- name: "NETBOX_PROVIDER_NETWORK 3: ASSERT - Updated"
+  assert:
+    that:
+      - test_three is changed
+      - test_three['diff']['after']['comments'] == "A provider network"
+      - test_three['diff']['after']['description'] == "Describe a Provider Network"
+      - test_three['provider_network']['name'] == "Test Provider Network One"
+      - test_three['provider_network']['comments'] == "A provider network"
+      - test_three['provider_network']['description'] == "Describe a Provider Network"
+      - test_three['msg'] == "provider_network Test Provider Network One updated"
+
+- name: "NETBOX_PROVIDER_NETWORK 4: Delete provider within netbox"
+  netbox.netbox.netbox_provider_network:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      provider: Test Provider
+      name: Test Provider Network One
+    state: absent
+  register: test_four
+
+- name: "NETBOX_PROVIDER_NETWORK 4 : ASSERT - Delete"
+  assert:
+    that:
+      - test_four is changed
+      - test_four['provider_network']['name'] == "Test Provider Network One"
+      - test_four['provider_network']['comments'] == "A provider network"
+      - test_four['provider_network']['description'] == "Describe a Provider Network"
+      - test_four['msg'] == "provider_network Test Provider Network One deleted"
