Add netbox_tenant & netbox_tenant_group

Author: FragmentedPacket

.travis.yml

@@ -9,7 +9,7 @@ env:
   global:
     - COLLECTION_NAMESPACE: fragmentedpacket
     - COLLECTION_NAME: netbox_modules
-    - COLLECTION_VERSION: 0.0.8
+    - COLLECTION_VERSION: 0.0.9
 
 matrix:
   include:

README.md

@@ -4,6 +4,7 @@
 **THIS IS A WIP DUE TO COLLECTIONS BEING IN TECH REVIEW CURRENTLY (Ansible 2.8) BUT WILL BE UPDATED AS NECESSARY AS COLLECTIONS MATURES**
 
 ## Todo
+
 - ~~initial build and changes to properly import module_utils~~
 - Add testing to Travis CI
   - ~~Initial unit tests~~
@@ -12,9 +13,10 @@
   - Local testing using Tox
   - Test currently supported versions of Ansible
 - ~~Add documentation on how to use to README~~
-- Add documentation on how to contribute to collection
+- ~~Add documentation on how to contribute to collection~~
 
 ## Requirements
+
 - Netbox 2.5+
 - pynetbox 4.0.6+
 - Python 3.6+
@@ -23,19 +25,23 @@
 
 ## Existing Modules
 
- - netbox_device
- - netbox_device_interface
- - netbox_ip_address
- - netbox_prefix
- - netbox_site
+- netbox_device
+- netbox_device_interface
+- netbox_ip_address
+- netbox_prefix
+- netbox_site
+- netbox_tenant
+- netbox_tenant_group
 
 ## How to Use
+
 - Install via Mazer
   - `mazer install fragmentedpacket.netbox_modules`
 - Follow Ansible instructions to use the collection
   - [https://docs.ansible.com/ansible/devel/dev_guide/collections_tech_preview.html#using-collections](https://docs.ansible.com/ansible/devel/dev_guide/collections_tech_preview.html#using-collections)
 
-#### Example playbook
+### Example playbook
+
 ```yaml
 - name: "Test Netbox modules"
   connection: local
@@ -59,12 +65,18 @@
 ```
 
 ## How to Contribute
-**Will be updated with diagram and more information needed to contribute**
 
-If looking to contribute before this is updated, please review the code and hopefully it is enough to get started on adding new modules and how the new modules should be structured.
+The structure of the Netbox modules attempts to follow the layout of the Netbox API by having a module_util for each application (`dcim, ipam, tenancy, etc`) that inherits from a base module (`NetboxModule - netbox_utils.py`) and then implements the specific endpoints within the correct application module.
+
+ex. Add logic for adding devices under netbox_dcim.py or ip addresses under netbox_ipam.py
+
+In turn when creating the actual modules, we're just calling a single function and passing in the Ansible Module and the endpoint. This means all the logic is within the specific application's module_util module and a lot of the logic should be the same for most endpoints since it is a basic operation of using the desired state of the endpoint and then either making sure it exists, updating it if it does exist, or removing it. There may be some special logic for other endpoints, but it should be minimal.
+
+(Ansible Module) netbox_{{ endpoint }} -> (Module Util) netbox_{{ application }} -> (Module Util) netbox_utils
 
-#### Testing
+### Testing
 
  1. Please update `tests/unit/module_utils/test_netbox_base_class.py` if editing anything within the base class that needs to be tested.
- 2. Run `black .` within the base directory for black formatting as it's required for tests to pass
- 3. Check necessary dependencies defined within `.travis.yml` for now if you're wanting to test locally
+ 2. Please add or update an existing play to test the new Netbox module for integration testing within `tests/integration/integration-tests.yml`
+ 3. Run `black .` within the base directory for black formatting as it's required for tests to pass
+ 4. Check necessary dependencies defined within `.travis.yml` for now if you're wanting to test locally

galaxy.yml

@@ -9,7 +9,7 @@ namespace: fragmentedpacket
 name: netbox_modules
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 0.0.8
+version: 0.0.9
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md

plugins/module_utils/netbox_tenancy.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2018, 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
+
+# This should just be temporary once 2.9 is relased and tested we can remove this
+try:
+    from ansible_collections.fragmentedpacket.netbox_modules.plugins.module_utils.netbox_utils import (
+        NetboxModule,
+        ENDPOINT_NAME_MAPPING,
+    )
+except ImportError:
+    import sys
+
+    sys.path.append(".")
+    from netbox_utils import NetboxModule, ENDPOINT_NAME_MAPPING
+
+
+NB_TENANTS = "tenants"
+NB_TENANT_GROUPS = "tenant_groups"
+
+
+class NetboxTenancyModule(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:
+        tenants
+        tenant groups
+        """
+        # 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)
+
+        data = self.data
+
+        # Used for msg output
+        name = data.get("name")
+
+        data["slug"] = self._to_slug(name)
+
+        object_query_params = self._build_query_params(endpoint_name, data)
+        try:
+            self.nb_object = nb_endpoint.get(**object_query_params)
+        except ValueError:
+            self._handle_errors(msg="More than one result returned for %s" % (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/module_utils/netbox_utils.py

@@ -44,6 +44,7 @@
     device="name",
     device_role="slug",
     device_type="slug",
+    group="slug",
     manufacturer="slug",
     nat_inside="address",
     nat_outside="address",
@@ -68,6 +69,7 @@
     device="devices",
     device_role="device_roles",
     device_type="device_types",
+    group="tenant_groups",
     interface="interfaces",
     lag="interfaces",
     nat_inside="ip_addresses",
@@ -94,6 +96,7 @@
 NO_DEFAULT_ID = set(
     [
         "device",
+        "group",
         "lag",
         "primary_ip",
         "primary_ip4",
@@ -108,6 +111,7 @@
         "untagged_vlan",
         "tagged_vlans",
         "tenant",
+        "tenant_group",
     ]
 )
 
@@ -118,6 +122,7 @@
     "prefixes": "prefix",
     "sites": "site",
     "tenants": "tenant",
+    "tenant_groups": "tenant_group",
 }
 
 DEVICE_STATUS = dict(offline=0, active=1, planned=2, staged=3, failed=4, inventory=5)
@@ -209,8 +214,10 @@
     "prefix": set(["prefix", "vrf"]),
     "site": set(["name"]),
     "vlan": set(["name", "site", "vlan_group", "tenant"]),
-    "untagged_vlan": set(["name", "site", "vlan_group", "tenant"]),
     "tagged_vlans": set(["name", "site", "vlan_group", "tenant"]),
+    "tenant": set(["name"]),
+    "tenant_group": set(["name"]),
+    "untagged_vlan": set(["name", "site", "vlan_group", "tenant"]),
 }
 
 QUERY_PARAMS_IDS = set(["device", "vrf", "site", "vlan_group", "tenant"])
@@ -343,11 +350,13 @@ def _change_choices_id(self, endpoint, data):
         :params endpoint (str): The endpoint that will be used for mapping to required _choices
         :params data (dict): User defined data passed into the module
         """
-        required_choices = REQUIRED_ID_FIND[endpoint]
-        for choice in required_choices:
-            for key, value in choice.items():
-                if data.get(key):
-                    data[key] = value[data[key].lower()]
+        if REQUIRED_ID_FIND.get(endpoint):
+            required_choices = REQUIRED_ID_FIND[endpoint]
+            for choice in required_choices:
+                for key, value in choice.items():
+                    if data.get(key):
+                        data[key] = value[data[key].lower()]
+
         return data
 
     def _find_app(self, endpoint):

plugins/modules/netbox_device.py

@@ -192,7 +192,6 @@ def main():
         validate_certs=dict(type="bool", default=True),
     )
 
-    global module
     module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True)
 
     # Fail if device name is not given