Merge to Main for Locations Release

changelogs/changelog.yaml

@@ -354,3 +354,15 @@ releases:
       minor_changes:
         - (#171) Add provider_network to circuit_termination module
         - (#172) Add description to manufacturer
+
+  4.3.0:
+    changes:
+      minor_changes:
+        - (#185) Updated Doc Fragments
+        - (#187) Updated Tag documentation
+        - (#191) Added locations and location_type modules
+
+  4.3.1:
+    changes:
+      bugfixes:
+        - (#196) Virtual Chassis return multiple result at times

galaxy.yml

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

plugins/doc_fragments/fragments.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2023, Network to Code (@networktocode) <info@networktocode.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
+
+
+class ModuleDocFragment(object):
+    BASE = r"""
+requirements:
+  - pynautobot
+options:
+  url:
+    description:
+      - "The URL of the Nautobot instance resolvable by the Ansible host (for example: http://nautobot.example.com:8000)"
+    required: true
+    type: str
+  token:
+    description:
+      - "The token created within Nautobot to authorize API access"
+    required: true
+    type: str
+  state:
+    description:
+      - "Use C(present) or C(absent) for adding or removing."
+    choices: [ absent, present ]
+    default: present
+    type: str
+  query_params:
+    version_added: "3.0.0"
+    description:
+      - "This can be used to override the specified values in ALLOWED_QUERY_PARAMS that is defined"
+      - "in plugins/module_utils/utils.py and provides control to users on what may make"
+      - "an object unique in their environment."
+    required: false
+    type: list
+    elements: str
+  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."
+    required: false
+    default: true
+    type: raw
+  api_version:
+    version_added: "4.1.0"
+    description:
+      - "API Version Nautobot REST API"
+    required: false
+    type: str
+"""
+
+    TAGS = r"""
+options:
+  tags:
+    description:
+      - "Any tags that this item may need to be associated with"
+    required: false
+    type: list
+    elements: raw
+    version_added: "3.0.0"
+"""
+
+    CUSTOM_FIELDS = r"""
+options:
+  custom_fields:
+    description:
+      - "Must exist in Nautobot and in key/value format"
+    required: false
+    type: dict
+    version_added: "3.0.0"
+"""

plugins/lookup/lookup.py

@@ -176,6 +176,8 @@ def get_endpoint(nautobot, term):
         "interfaces": {"endpoint": nautobot.dcim.interfaces},
         "inventory-items": {"endpoint": nautobot.dcim.inventory_items},
         "ip-addresses": {"endpoint": nautobot.ipam.ip_addresses},
+        "locations": {"endpoint": nautobot.dcim.locations},
+        "location_types": {"endpoint": nautobot.dcim.location_types},
         "manufacturers": {"endpoint": nautobot.dcim.manufacturers},
         "object-changes": {"endpoint": nautobot.extras.object_changes},
         "platforms": {"endpoint": nautobot.dcim.platforms},

plugins/module_utils/dcim.py

@@ -28,6 +28,8 @@
 NB_INTERFACES = "interfaces"
 NB_INTERFACE_TEMPLATES = "interface_templates"
 NB_INVENTORY_ITEMS = "inventory_items"
+NB_LOCATIONS = "locations"
+NB_LOCATION_TYPES = "location_types"
 NB_MANUFACTURERS = "manufacturers"
 NB_PLATFORMS = "platforms"
 NB_POWER_FEEDS = "power_feeds"

plugins/module_utils/utils.py

@@ -50,6 +50,8 @@
         "interfaces",
         "interface_templates",
         "inventory_items",
+        "locations",
+        "location_types",
         "manufacturers",
         "platforms",
         "power_feeds",
@@ -90,6 +92,7 @@
     installed_device="name",
     import_targets="name",
     manufacturer="slug",
+    master="name",
     nat_inside="address",
     nat_outside="address",
     parent_rack_group="slug",
@@ -222,6 +225,8 @@
     "interface_templates": "interface_template",
     "inventory_items": "inventory_item",
     "ip_addresses": "ip_address",
+    "locations": "location",
+    "location_types": "location_type",
     "manufacturers": "manufacturer",
     "platforms": "platform",
     "power_feeds": "power_feed",
@@ -293,6 +298,8 @@
     "ip_addresses": set(["address", "vrf", "device", "interface", "vminterface"]),
     "ipaddresses": set(["address", "vrf", "device", "interface", "vminterface"]),
     "lag": set(["name"]),
+    "location": set(["name"]),
+    "location_type": set(["name"]),
     "manufacturer": set(["slug"]),
     "master": set(["name"]),
     "nat_inside": set(["vrf", "address"]),
@@ -353,6 +360,7 @@
     "interfaces": set(["form_factor", "mode", "type"]),
     "interface_templates": set(["type"]),
     "ip_addresses": set(["status", "role"]),
+    "locations": set(["status"]),
     "prefixes": set(["status"]),
     "power_feeds": set(["status", "type", "supply", "phase"]),
     "power_outlets": set(["type", "feed_leg"]),
@@ -845,6 +853,8 @@ def _find_ids(self, data, user_query_params):
                             id_list.append(list_item)
                             continue
                         else:
+                            # Reminder: this get checks the QUERY_TYPES constant above, if the item is not in the list
+                            # of approved query types, then it defaults to a q search
                             temp_dict = {QUERY_TYPES.get(k, "q"): search}
 
                         query_id = self._nb_endpoint_get(nb_endpoint, temp_dict, k)
@@ -856,6 +866,8 @@ def _find_ids(self, data, user_query_params):
                     if k in ["lag", "rear_port", "rear_port_template"]:
                         query_params = self._build_query_params(k, data, user_query_params)
                     else:
+                        # Reminder: this get checks the QUERY_TYPES constant above, if the item is not in the list
+                        # of approved query types, then it defaults to a q search
                         query_params = {QUERY_TYPES.get(k, "q"): search}
                     query_id = self._nb_endpoint_get(nb_endpoint, query_params, k)
 

plugins/modules/aggregate.py

@@ -18,26 +18,12 @@
   - This should be ran with connection C(local) and hosts C(localhost)
 author:
   - Mikhail Yohman (@FragmentedPacket)
-requirements:
-  - pynautobot
 version_added: "1.0.0"
+extends_documentation_fragment:
+  - networktocode.nautobot.fragments.base
+  - networktocode.nautobot.fragments.tags
+  - networktocode.nautobot.fragments.custom_fields
 options:
-  api_version:
-    description:
-      - API Version Nautobot REST API
-    required: false
-    type: str
-    version_added: "4.1.0"
-  url:
-    description:
-      - "URL of the Nautobot instance resolvable by Ansible control host"
-    required: true
-    type: str
-  token:
-    description:
-      - "The token created within Nautobot to authorize API access"
-    required: true
-    type: str
   prefix:
     description:
       - "The aggregate prefix"
@@ -62,39 +48,6 @@
     required: false
     type: str
     version_added: "3.0.0"
-  tags:
-    description:
-      - "Any tags that the aggregate may need to be associated with"
-    required: false
-    type: list
-    elements: raw
-    version_added: "3.0.0"
-  custom_fields:
-    description:
-      - "must exist in Nautobot"
-    required: false
-    type: dict
-    version_added: "3.0.0"
-  state:
-    description:
-      - "The state of the aggregate"
-    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/utils.py and provides control to users on what may make
-      - an object unique in their environment.
-    required: false
-    type: list
-    elements: str
-    version_added: "3.0.0"
-  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"""

plugins/modules/cable.py

@@ -19,26 +19,10 @@
   - This should be ran with connection C(local) and hosts C(localhost)
 author:
   - Tobias Groß (@toerb)
-requirements:
-  - pynautobot
 version_added: "1.0.0"
+extends_documentation_fragment:
+  - networktocode.nautobot.fragments.base
 options:
-  api_version:
-    description:
-      - API Version Nautobot REST API
-    required: false
-    type: str
-    version_added: "4.1.0"
-  url:
-    description:
-      - URL of the Nautobot instance resolvable by Ansible control host
-    required: true
-    type: str
-  token:
-    description:
-      - The token created within Nautobot to authorize API access
-    required: true
-    type: str
   termination_a_type:
     description:
       - The type of the termination a
@@ -146,26 +130,6 @@
       - in
     required: false
     type: str
-  state:
-    description:
-      - Use C(present) or C(absent) for adding or removing.
-    choices: [ absent, present ]
-    default: present
-    type: str
-  query_params:
-    version_added: "3.0.0"
-    description:
-      - This can be used to override the specified values in ALLOWED_QUERY_PARAMS that is defined
-      - in plugins/module_utils/utils.py and provides control to users on what may make
-      - an object unique in their environment.
-    required: false
-    type: list
-    elements: str
-  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"""

plugins/modules/circuit.py

@@ -19,26 +19,12 @@
   - This should be ran with connection C(local) and hosts C(localhost)
 author:
   - Mikhail Yohman (@FragmentedPacket)
-requirements:
-  - pynautobot
 version_added: "1.0.0"
+extends_documentation_fragment:
+  - networktocode.nautobot.fragments.base
+  - networktocode.nautobot.fragments.tags
+  - networktocode.nautobot.fragments.custom_fields
 options:
-  api_version:
-    description:
-      - API Version Nautobot REST API
-    required: false
-    type: str
-    version_added: "4.1.0"
-  url:
-    description:
-      - URL of the Nautobot instance resolvable by Ansible control host
-    required: true
-    type: str
-  token:
-    description:
-      - The token created within Nautobot to authorize API access
-    required: true
-    type: str
   cid:
     description:
       - The circuit id of the circuit
@@ -94,39 +80,6 @@
     required: false
     type: str
     version_added: "3.0.0"
-  tags:
-    description:
-      - Any tags that the device may need to be associated with
-    required: false
-    type: list
-    elements: raw
-    version_added: "3.0.0"
-  custom_fields:
-    description:
-      - must exist in Nautobot
-    required: false
-    type: dict
-    version_added: "3.0.0"
-  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/utils.py and provides control to users on what may make
-      - an object unique in their environment.
-    required: false
-    type: list
-    elements: str
-    version_added: "3.0.0"
-  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"""