Enhancement: Added query_params to default arg_spec (#222)

Author: FragmentedPacket

plugins/module_utils/netbox_circuits.py

@@ -40,6 +40,7 @@ def run(self):
         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
 
@@ -60,7 +61,9 @@ def run(self):
             if not data.get("slug"):
                 data["slug"] = self._to_slug(name)
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        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":

plugins/module_utils/netbox_dcim.py

@@ -62,6 +62,7 @@ def run(self):
         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
 
@@ -81,7 +82,9 @@ def run(self):
         if data.get("color"):
             data["color"] = data["color"].lower()
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        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)
 
         # This is logic to handle interfaces on a VC

plugins/module_utils/netbox_extras.py

@@ -29,6 +29,7 @@ def run(self):
         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
 
@@ -37,7 +38,9 @@ def run(self):
 
         data["slug"] = self._to_slug(name)
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        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":

plugins/module_utils/netbox_ipam.py

@@ -137,6 +137,7 @@ def run(self):
         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
 
@@ -161,7 +162,9 @@ def run(self):
         else:
             first_available = False
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        object_query_params = self._build_query_params(
+            endpoint_name, data, user_query_params
+        )
         if data.get("prefix") and self.endpoint == "ip_addresses":
             object_query_params = self._build_query_params("prefix", data)
             self.nb_object = self._nb_endpoint_get(

plugins/module_utils/netbox_secrets.py

@@ -29,6 +29,7 @@ def run(self):
         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
 
@@ -37,7 +38,9 @@ def run(self):
 
         data["slug"] = self._to_slug(name)
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        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":

plugins/module_utils/netbox_tenancy.py

@@ -36,6 +36,7 @@ def run(self):
         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
 
@@ -49,7 +50,9 @@ def run(self):
             if not data.get("slug"):
                 data["slug"] = self._to_slug(name)
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        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":

plugins/module_utils/netbox_utils.py

@@ -10,16 +10,17 @@
 # Import necessary packages
 import traceback
 import re
+import json
 from itertools import chain
+
 from ansible_collections.ansible.netcommon.plugins.module_utils.compat import ipaddress
 
-# from ansible.module_utils._text import to_text
 from ansible.module_utils.common.text.converters import to_text
 
-# from ._text import to_native
 from ansible.module_utils._text import to_native
 from ansible.module_utils.common.collections import is_iterable
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
+from ansible.module_utils.urls import open_url
 
 PYNETBOX_IMP_ERR = None
 try:
@@ -303,6 +304,7 @@
     netbox_url=dict(type="str", required=True),
     netbox_token=dict(type="str", required=True, no_log=True),
     state=dict(required=False, default="present", choices=["present", "absent"]),
+    query_params=dict(required=False, type="list"),
     validate_certs=dict(type="raw", default=True),
 )
 
@@ -322,6 +324,7 @@ def __init__(self, module, endpoint, nb_client=None):
         self.check_mode = self.module.check_mode
         self.endpoint = endpoint
         self.version = None
+        query_params = self.module.params.get("query_params")
 
         if not HAS_PYNETBOX:
             self.module.fail_json(
@@ -338,11 +341,14 @@ def __init__(self, module, endpoint, nb_client=None):
         else:
             self.nb = nb_client
 
+        # if self.module.params.get("query_params"):
+        #    self._validate_query_params(self.module.params["query_params"])
+
         # These methods will normalize the regular data
         cleaned_data = self._remove_arg_spec_default(module.params["data"])
         norm_data = self._normalize_data(cleaned_data)
         choices_data = self._change_choices_id(self.endpoint, norm_data)
-        data = self._find_ids(choices_data)
+        data = self._find_ids(choices_data, query_params)
         self.data = self._convert_identical_keys(data)
 
     def _connect_netbox_api(self, url, token, ssl_verify):
@@ -372,6 +378,46 @@ def _nb_endpoint_get(self, nb_endpoint, query_params, search_item):
 
         return response
 
+    def _validate_query_params(self, query_params):
+        """
+        Validate query_params that are passed in by users to make sure
+        they're valid and return error if they're not valid.
+        """
+        invalid_query_params = []
+
+        app = self._find_app(self.endpoint)
+        nb_app = getattr(self.nb, app)
+        nb_endpoint = getattr(nb_app, self.endpoint)
+        # Fetch the OpenAPI spec to perform validation against
+        base_url = self.nb.base_url
+        junk, endpoint_url = nb_endpoint.url.split(base_url)
+        response = open_url(base_url + "/docs/?format=openapi")
+        try:
+            raw_data = to_text(response.read(), errors="surrogate_or_strict")
+        except UnicodeError:
+            self._handle_errors(
+                msg="Incorrect encoding of fetched payload from NetBox API."
+            )
+
+        try:
+            openapi = json.loads(raw_data)
+        except ValueError:
+            self._handle_errors(msg="Incorrect JSON payload returned: %s" % raw_data)
+
+        valid_query_params = openapi["paths"][endpoint_url + "/"]["get"]["parameters"]
+
+        # Loop over passed in params and add to invalid_query_params and then fail if non-empty
+        for param in query_params:
+            if param not in valid_query_params:
+                invalid_query_params.append(param)
+
+        if invalid_query_params:
+            self._handle_errors(
+                "The following query_params are invalid: {0}".format(
+                    ", ".join(invalid_query_params)
+                )
+            )
+
     def _handle_errors(self, msg):
         """
         Returns message and changed = False
@@ -438,7 +484,9 @@ def _get_query_param_id(self, match, data):
             else:
                 return data
 
-    def _build_query_params(self, parent, module_data, child=None):
+    def _build_query_params(
+        self, parent, module_data, user_query_params=None, child=None
+    ):
         """
         :returns dict(query_dict): Returns a query dictionary built using mappings to dynamically
         build available query params for Netbox endpoints
@@ -449,7 +497,10 @@ def _build_query_params(self, parent, module_data, child=None):
         to build the appropriate `query_dict` for the parent
         """
         query_dict = dict()
-        query_params = ALLOWED_QUERY_PARAMS.get(parent)
+        if user_query_params:
+            query_params = set(user_query_params)
+        else:
+            query_params = ALLOWED_QUERY_PARAMS.get(parent)
 
         if child:
             matches = query_params.intersection(set(child.keys()))
@@ -540,7 +591,7 @@ def _find_app(self, endpoint):
                 nb_app = k
         return nb_app
 
-    def _find_ids(self, data):
+    def _find_ids(self, data, user_query_params):
         """Will find the IDs of all user specified data if resolvable
         :returns data (dict): Returns the updated dict with the IDs of user specified data
         :params data (dict): User defined data passed into the module
@@ -557,22 +608,24 @@ def _find_ids(self, data):
                     if k == "interface" and v.get("virtual_machine"):
                         nb_app = getattr(self.nb, "virtualization")
                         nb_endpoint = getattr(nb_app, endpoint)
-                    query_params = self._build_query_params(k, data, v)
+                    query_params = self._build_query_params(k, data, child=v)
                     query_id = self._nb_endpoint_get(nb_endpoint, query_params, k)
 
                 elif isinstance(v, list):
                     id_list = list()
                     for list_item in v:
                         norm_data = self._normalize_data(list_item)
-                        temp_dict = self._build_query_params(k, data, norm_data)
+                        temp_dict = self._build_query_params(k, data, child=norm_data)
                         query_id = self._nb_endpoint_get(nb_endpoint, temp_dict, k)
                         if query_id:
                             id_list.append(query_id.id)
                         else:
                             self._handle_errors(msg="%s not found" % (list_item))
                 else:
                     if k in ["lag"]:
-                        query_params = self._build_query_params(k, data)
+                        query_params = self._build_query_params(
+                            k, data, user_query_params
+                        )
                     else:
                         query_params = {QUERY_TYPES.get(k, "q"): search}
                     query_id = self._nb_endpoint_get(nb_endpoint, query_params, k)

plugins/module_utils/netbox_virtualization.py

@@ -46,6 +46,7 @@ def run(self):
             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
 
@@ -59,7 +60,9 @@ def run(self):
             if not data.get("slug"):
                 data["slug"] = self._to_slug(name)
 
-        object_query_params = self._build_query_params(endpoint_name, data)
+        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":

plugins/modules/netbox_aggregate.py

@@ -80,6 +80,13 @@
     choices: [ present, absent ]
     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."

plugins/modules/netbox_circuit.py

@@ -105,6 +105,13 @@
     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.