Merge pull request #227 from nautobot/release-v1.6.0

Release v1.6.0

.github/workflows/ci.yml

@@ -83,7 +83,7 @@ jobs:
       fail-fast: true
       matrix:
         python-version: ["3.8"]
-        nautobot-version: ["1.5.13"]
+        nautobot-version: ["1.6.0"]
     env:
       INVOKE_NAUTOBOT_SSOT_PYTHON_VER: "${{ matrix.python-version }}"
       INVOKE_NAUTOBOT_SSOT_NAUTOBOT_VER: "${{ matrix.nautobot-version }}"
@@ -121,17 +121,14 @@ jobs:
       matrix:
         python-version: ["3.8", "3.9", "3.10"]
         db-backend: ["postgresql"]
-        nautobot-version: ["latest"]
+        nautobot-version: ["ltm-1.6"]
         include:
-          - python-version: "3.10"
-            db-backend: "postgresql"
-            nautobot-version: "1.5.13"
           - python-version: "3.8"
             db-backend: "mysql"
-            nautobot-version: "1.5.13"
+            nautobot-version: "ltm-1.6"
           - python-version: "3.10"
             db-backend: "mysql"
-            nautobot-version: "stable"
+            nautobot-version: "ltm-1.6"
     runs-on: "ubuntu-20.04"
     env:
       INVOKE_NAUTOBOT_SSOT_PYTHON_VER: "${{ matrix.python-version }}"

README.md

@@ -28,6 +28,7 @@ This Nautobot application framework includes the following integrations:
 
 - Cisco ACI
 - Arista CloudVision
+- Device42
 - Infoblox
 - IPFabric
 - ServiceNow

development/development.env

@@ -45,6 +45,7 @@ NAUTOBOT_CELERY_TASK_SOFT_TIME_LIMIT=3600
 NAUTOBOT_CELERY_TASK_TIME_LIMIT=3600
 
 NAUTOBOT_SSOT_HIDE_EXAMPLE_JOBS="False"
+NAUTOBOT_SSOT_ALLOW_CONFLICTING_APPS="False"
 
 NAUTOBOT_SSOT_ENABLE_ACI="True"
 NAUTOBOT_SSOT_ACI_TAG="ACI"
@@ -70,6 +71,11 @@ NAUTOBOT_ARISTACV_IMPORT_ACTIVE="False"
 NAUTOBOT_ARISTACV_IMPORT_TAG="False"
 NAUTOBOT_ARISTACV_VERIFY=True
 
+NAUTOBOT_SSOT_ENABLE_DEVICE42="True"
+NAUTOBOT_SSOT_DEVICE42_HOST=""
+NAUTOBOT_SSOT_DEVICE42_USERNAME=""
+NAUTOBOT_SSOT_DEVICE42_PASSWORD=""
+
 NAUTOBOT_SSOT_ENABLE_INFOBLOX="True"
 NAUTOBOT_SSOT_INFOBLOX_DEFAULT_STATUS="active"
 NAUTOBOT_SSOT_INFOBLOX_ENABLE_RFC1918_NETWORK_CONTAINERS="True"

development/nautobot_config.py

@@ -133,24 +133,22 @@
 
 # Enable installed plugins. Add the name of each plugin to the list.
 PLUGINS = [
-    # Enable chatops after dropping Python 3.7 support
-    # "nautobot_chatops",
+    "nautobot_chatops",
     "nautobot_device_lifecycle_mgmt",
     "nautobot_ssot",
 ]
 
 # Plugins configuration settings. These settings are used by various plugins that the user may have installed.
 # Each key in the dictionary is the name of an installed plugin and its value is a dictionary of settings.
 PLUGINS_CONFIG = {
-    # Enable chatops after dropping Python 3.7 support
-    # "nautobot_chatops": {
-    #     "enable_slack": True,
-    #     "slack_api_token": os.getenv("SLACK_API_TOKEN"),
-    #     "slack_signing_secret": os.getenv("SLACK_SIGNING_SECRET"),
-    #     "session_cache_timeout": 3600,
-    #     "ipfabric_api_token": os.getenv("IPFABRIC_API_TOKEN"),
-    #     "ipfabric_host": os.getenv("IPFABRIC_HOST"),
-    # },
+    "nautobot_chatops": {
+        "enable_slack": True,
+        "slack_api_token": os.getenv("SLACK_API_TOKEN"),
+        "slack_signing_secret": os.getenv("SLACK_SIGNING_SECRET"),
+        "session_cache_timeout": 3600,
+        "ipfabric_api_token": os.getenv("IPFABRIC_API_TOKEN"),
+        "ipfabric_host": os.getenv("IPFABRIC_HOST"),
+    },
     "nautobot_ssot": {
         # URL and credentials should be configured as environment variables on the host system
         "aci_apics": {x: os.environ[x] for x in os.environ if "APIC" in x},
@@ -200,10 +198,27 @@
         "aristacv_verify": is_truthy(os.getenv("NAUTOBOT_ARISTACV_VERIFY", True)),
         "enable_aci": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_ACI")),
         "enable_aristacv": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_ARISTACV")),
+        "enable_device42": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_DEVICE42")),
         "enable_infoblox": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_INFOBLOX")),
         "enable_ipfabric": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_IPFABRIC")),
         "enable_servicenow": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_SERVICENOW")),
         "hide_example_jobs": is_truthy(os.getenv("NAUTOBOT_SSOT_HIDE_EXAMPLE_JOBS")),
+        "device42_host": os.getenv("NAUTOBOT_SSOT_DEVICE42_HOST", ""),
+        "device42_username": os.getenv("NAUTOBOT_SSOT_DEVICE42_USERNAME", ""),
+        "device42_password": os.getenv("NAUTOBOT_SSOT_DEVICE42_PASSWORD", ""),
+        "device42_verify_ssl": False,
+        "device42_defaults": {
+            "site_status": "Active",
+            "rack_status": "Active",
+            "device_role": "Unknown",
+        },
+        "device42_delete_on_sync": False,
+        "device42_use_dns": True,
+        "device42_customer_is_facility": True,
+        "device42_facility_prepend": "sitecode-",
+        "device42_role_prepend": "nautobot-",
+        "device42_ignore_tag": "",
+        "device42_hostname_mapping": [],
         "infoblox_default_status": os.getenv("NAUTOBOT_SSOT_INFOBLOX_DEFAULT_STATUS", "active"),
         "infoblox_enable_rfc1918_network_containers": is_truthy(
             os.getenv("NAUTOBOT_SSOT_INFOBLOX_ENABLE_RFC1918_NETWORK_CONTAINERS")

docs/admin/integrations/device42_setup.md

@@ -0,0 +1,84 @@
+# Device42 Integration Setup
+
+This guide will walk you through steps to set up Device42 integration with the `nautobot_ssot` app.
+
+## Prerequisites
+
+Before configuring the integration, please ensure, that `nautobot-ssot` app was [installed with Device42 integration extra dependencies](../install.md#install-guide).
+
+```shell
+pip install nautobot-ssot[device42]
+```
+
+## Configuration
+
+Integration behavior can be controlled with the following settings:
+
+| Configuration Variable | Type    | Usage                                                                                                 |
+| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| device42_host          | string  | This defines the FQDN of the Device42 instance, ie `https://device42.example.com`.                    |
+| device42_username      | string  | This defines the username of the account used to connect to the Device42 API endpoint.                |
+| device42_password      | string  | This defines the password of the account used to connect to the Device42 API endpoint.                |
+| device42_verify        | boolean | This denotes whether SSL validation of the Device42 endpoint should be enabled or not.                |
+
+When creating Sites and Racks in Nautobot it is required to define a Status for each. It is also required to define a Role for your Device when created. You may define the default for each of those objects being imported with the respective values in your `nautobot_config.py` file.
+
+| Configuration Variable                              | Type   | Usage                                                      | Default              |
+| --------------------------------------------------- | ------ | ---------------------------------------------------------- | -------------------- |
+| device42_defaults["site_status"]                    | string | Default status for Sites synced to Nautobot.               | Active               |
+| device42_defaults["rack_status"]                    | string | Default status for Racks synced to Nautobot.               | Active               |
+| device42_defaults["device_role"]                    | string | Default role for Devices synced to Nautobot.               | Unknown              |
+
+When syncing from Device42, the integration will create new Devices that do not exist in Nautobot and delete any that are not in Device42. This behavior can be controlled with the `device42_delete_on_sync` setting. This option prevents objects from being deleted from Nautobot during a synchronization. This is handy if your Device42 data fluctuates a lot and you wish to control what is removed from Nautobot. This means objects will only be added, never deleted when set to False. In addition, while syncing your Devices from Device42 you can enable the `device42_use_dns` setting to perform DNS resolution of Device hostname's when assigning management IP addresses. When True, there will be an additional process of performing DNS queries for each Device in the sync and if an A record is found, will be assigned as management IP for the Device. It will attempt to use the interface for the IP based upon data from Device42 but will create a Management interface and assign the IP to it if an interface can't be determined.
+
+| Configuration Variable                              | Type    | Usage                                                                        | Default              |
+| --------------------------------------------------- | ------- | ---------------------------------------------------------------------------- | -------------------- |
+| device42_delete_on_sync                             | boolean | Devices in Nautobot that don't exist in Device42 will be deleted.            | False                |
+| device42_use_dns                                    | boolean | Enables DNS resolution of Device name's for assigning primary IP addresses.  | False                |
+| device42_customer_is_facility                       | boolean | True when  utilizing the Customer field in Device42 to denote the site code. | False                |
+
+> When these variables are not defined in the app settings, the integration will use the default values mentioned.
+
+Due to particular data points not being available in Device42 it was decided to utilize the tagging system as a secondary method of defining information. The 'device42_facility_prepend' setting defines the string that is expected on a Tag when determining a Building's site code. If a Building has a Tag that starts with `sitecode-` it will assume the remaining Tag is the facility code. Like the `device42_facility_prepend` option, the `device42_role_prepend` setting defines the string on a Tag that defines a Device's role. If a Device has a Tag that starts with `nautobot-` it will assume the remaining string is the name of the Device's role, such as `access-switch` for example. Lastly, there is the `device42_ignore_tag` setting that enables the specification of a Tag that when found on a Device will have it skipped from import.
+
+| Configuration Variable                              | Type    | Usage                                                                        | Default              |
+| --------------------------------------------------- | ------- | ---------------------------------------------------------------------------- | -------------------- |
+| device42_facility_prepend                           | str     | Devices in Nautobot that don't exist in Device42 will be deleted.            | ""                   |
+| device42_role_prepend                               | str     | Define DeviceRole using a Tag. Will use Tag starting with this string.       | ""                   |
+| device42_ignore_tag                                 | str     | True when  utilizing the Customer field in Device42 to denote the site code. | ""                   |
+
+Finally, there is the `device42_hostname_mapping` setting that enables the parsing of Device hostname's for codes that indicate the assigned Site using the site code. This option allows you to define a mapping of a regex pattern that defines a Device's hostname and which Site the Device should be assigned. This is helpful if the location information for Devices in Device42 is inaccurate and your Device's are named with the Site name or code in it. For example, if you have Device's called `DFW-access-switch`, you could map that as `{"^DFW.+": "dallas"}` where `dallas` is the slug form for your Site name.
+
+| Configuration Variable     | Type        | Usage                                                      | Default |
+| -------------------------- | ----------- | ---------------------------------------------------------- | ------- |
+| device42_hostname_mapping  | List[dict]  | Define mapping of a hostname that indicate site.           | [{}]    |
+
+> As the Device hostname is used as the identifier for Device objects any change in hostname implies a new Device and thus should trigger a deletion and creation of a new Device in Nautobot. For this reason, the hostname parsing feature is not done during updates and only at initial creation of the Device. If you need to correct the Site or Role for a Device after initial creation you will need to manually correct it or delete it and run the import Job again.
+
+Below is an example snippet from `nautobot_config.py` that demonstrates how to enable and configure the Device42 integration:
+
+```python
+PLUGINS_CONFIG = {
+    "nautobot_ssot": {
+        "enable_device42": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_DEVICE42")),
+        "device42_host": os.getenv("NAUTOBOT_SSOT_DEVICE42_HOST", ""),
+        "device42_username": os.getenv("NAUTOBOT_SSOT_DEVICE42_USERNAME", ""),
+        "device42_password": os.getenv("NAUTOBOT_SSOT_DEVICE42_PASSWORD", ""),
+        "device42_verify_ssl": False,
+        "device42_defaults": {
+            "site_status": "Active",
+            "rack_status": "Active",
+            "device_role": "Unknown",
+        },
+        "device42_delete_on_sync": False,
+        "device42_use_dns": True,
+        "device42_customer_is_facility": True,
+        "device42_facility_prepend": "sitecode-",
+        "device42_role_prepend": "nautobot-",
+        "device42_ignore_tag": "",
+        "device42_hostname_mapping": [],
+    }
+```
+
+!!! note
+    All integration settings are defined in the block above as an example. Only some will be needed as described above.

docs/admin/release_notes/version_1.6.md

@@ -0,0 +1,19 @@
+# v1.6 Release Notes
+
+## v1.6.0 - 2023-09-29
+
+## Added
+
+- [221](https://github.com/nautobot/nautobot-plugin-ssot/pull/221) - Add Device42 integration by @jdrew82
+- [222](https://github.com/nautobot/nautobot-plugin-ssot/pull/222) - Add conflicting message link by @snaselj
+- [224](https://github.com/nautobot/nautobot-plugin-ssot/pull/224) - Allow Skipping Conflicting Apps Check by @snaselj
+
+## Changed
+
+- [219](https://github.com/nautobot/nautobot-plugin-ssot/pull/219) - Attempt fixing CI error in #214 by @Kircheneer
+- [220](https://github.com/nautobot/nautobot-plugin-ssot/pull/220) - Update ci.yml by @Kircheneer
+- [214](https://github.com/nautobot/nautobot-plugin-ssot/pull/214) - Sync Main to Develop for 1.5.0 by @jdrew82
+- [218](https://github.com/nautobot/nautobot-plugin-ssot/pull/218) - Fixes contrib.NautobotModel not returning objects on update/delete by @Kircheneer
+- [161](https://github.com/nautobot/nautobot-plugin-ssot/pull/161) - Reverts ChatOps dependency removal by @snaselj
+- [213](https://github.com/nautobot/nautobot-plugin-ssot/pull/213) - fix: :bug: Several fixes in the ACI integration by @chadell
+- [205](https://github.com/nautobot/nautobot-plugin-ssot/pull/205) - Migrate PR #164 from Arista Child Repo by @qduk

docs/admin/upgrade.md

@@ -25,5 +25,14 @@ To prevent conflicts during `nautobot-ssot` upgrade:
 
 These steps will help prevent issues during `nautobot-ssot` upgrades. Always back up your data and thoroughly test your configuration after these changes.
 
+!!! note
+    It's possible to allow conflicting apps to remain in `PLUGINS` during the upgrade process. You can specify the following environment variable to allow conflicting apps (see `development/development.env` for an example):
+
+    ```bash
+    NAUTOBOT_SSOT_ALLOW_CONFLICTING_APPS=True
+    ```
+
+    However, this is not recommended.
+
 !!! warning
     If conflicting apps remain in `PLUGINS`, the `nautobot-ssot` app will raise an exception during startup to prevent potential conflicts.

docs/user/integrations/device42.md

@@ -0,0 +1,47 @@
+# Arista CloudVision SSoT Integration
+
+The Device42 SSoT integration is built as part of the [Nautobot Single Source of Truth (SSoT)](../..tps://github.com/nautobot/nautobot-plugin-ssot) app. The SSoT app enables Nautobot to be the aggregation point for data coming from multiple systems of record (SoR).
+
+From Device42 into Nautobot, it synchronizes the following objects:
+
+| Device42                | Nautobot                     |
+| ----------------------- | ---------------------------- |
+| Buildings               | Sites                        |
+| Rooms                   | RackGroups                   |
+| Racks                   | Racks                        |
+| Vendors                 | Manufacturers                |
+| Hardware Models         | DeviceTypes                  |
+| Devices                 | Devices                      |
+| Ports                   | Interfaces                   |
+| VPC (VRF Groups)        | VRFs                         |
+| Subnets                 | Prefixes                     |
+| IP Addresses            | IP Addresses                 |
+| VLANs                   | VLANs                        |
+| Vendors                 | Providers                    |
+| Telco Circuits          | Circuits                     |
+
+`**` If the [Device Lifecycle Nautobot app](https://github.com/nautobot/nautobot-plugin-device-lifecycle-mgmt) is found to be installed, a matching Version will be created with a RelationshipAssociation connecting the Device and that Version.
+
+## Usage
+
+Once the plugin is installed and configured, you will be able to perform a data import from Device42 into Nautobot. From the Nautobot SSoT Dashboard view (`/plugins/ssot/`), Device42 will show as a Data Source.
+
+![Dashboard View](../../images/device42_dashboard.png)
+
+From the Dashboard, you can also view more information about the App by clicking on the Device42 link and see the Detail view. This view will show the mappings of Device42 objects to Nautobot objects, the sync history, and other configuration details for the App:
+
+![Detail View](../../images/device42_detail-view.png)
+
+To start the synchronization, simply click the `Sync Now` button on the Dashboard to start the Job. You should be presented with the Job form below:
+
+![Job Form](../../images/device42_job-form.png)
+
+If you wish to just test the synchronization but not have any data created in Nautobot you'll want to select the `Dry run` toggle. Clicking the `Debug` toggle will enable more verbose logging to inform you of what is occuring behind the scenes. Finally, the `Bulk import` option will enable bulk create and update operations to be used when the synchronization is complete. This can improve performance times for the App by forsaking validation of the imported data. Be aware that this could potentially cause bad data to be pushed into Nautobot.
+
+Running this Job will redirect you to a `Nautobot Job Result` view.
+
+![JobResult View](../../images/device42_jobresult.png)
+
+Once the Job has finished you can access the `SSoT Sync Details` page to see detailed information about the data that was synchronized from Device42 and the outcome of the sync Job.
+
+![SSoT Sync Details](../../images/device42_ssot-sync-details.png)

mkdocs.yml

@@ -105,6 +105,7 @@ nav:
           - "user/integrations/index.md"
           - Cisco ACI: "user/integrations/aci.md"
           - Arista CloudVision: "user/integrations/aristacv.md"
+          - Device42: "user/integrations/device42.md"
           - Infoblox: "user/integrations/infoblox.md"
           - IPFabric: "user/integrations/ipfabric.md"
           - ServiceNow: "user/integrations/servicenow.md"
@@ -118,6 +119,7 @@ nav:
           - "admin/integrations/index.md"
           - Cisco ACI: "admin/integrations/aci_setup.md"
           - Arista CloudVision: "admin/integrations/aristacv_setup.md"
+          - Device42: "admin/integrations/device42_setup.md"
           - Infoblox: "admin/integrations/infoblox_setup.md"
           - IPFabric: "admin/integrations/ipfabric_setup.md"
           - ServiceNow: "admin/integrations/servicenow_setup.md"
@@ -126,6 +128,7 @@ nav:
       - Compatibility Matrix: "admin/compatibility_matrix.md"
       - Release Notes:
           - "admin/release_notes/index.md"
+          - v1.6: "admin/release_notes/version_1.5.md"
           - v1.5: "admin/release_notes/version_1.5.md"
           - v1.4: "admin/release_notes/version_1.4.md"
           - v1.3: "admin/release_notes/version_1.3.md"