Merge pull request #118 from nautobot/develop

Sync 2.0 with main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -4,7 +4,7 @@ about: Report a reproducible bug in the current release of nautobot-plugin-norni
 ---
 
 ### Environment
-* Python version:  <!-- Example: 3.7.7 -->
+* Python version:  <!-- Example: 3.11.5 -->
 * Nautobot version:  <!-- Example: 1.0.1 -->
 * nautobot-plugin-nornir version:  <!-- Example: 1.0.0 -->
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -4,7 +4,7 @@ about: Propose a new feature or enhancement for nautobot-plugin-nornir
 ---
 
 ### Environment
-* Python version:  <!-- Example: 3.7.7 -->
+* Python version:  <!-- Example: 3.11.5 -->
 * Nautobot version:  <!-- Example: 1.0.1 -->
 * nautobot-plugin-nornir version:  <!-- Example: 1.0.0 -->
 

.github/workflows/ci.yml

@@ -82,8 +82,8 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.8"]
-        nautobot-version: ["1.4.0"]
+        python-version: ["3.11"]
+        nautobot-version: ["2.0.0"]
     env:
       INVOKE_NAUTOBOT_PLUGIN_NORNIR_PYTHON_VER: "${{ matrix.python-version }}"
       INVOKE_NAUTOBOT_PLUGIN_NORNIR_NAUTOBOT_VER: "${{ matrix.nautobot-version }}"
@@ -119,19 +119,23 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
-        db-backend: ["postgresql"]
-        nautobot-version: ["stable"]
+        python-version: ["3.8"]
+        db-backend: ["postgresql", "mysql"]
+        nautobot-version: ["2.0.0"]
+        # The include is a method to limit the amount of jobs ran. This essentially
+        # means that in addition to standard postgres and stable, also the lowest
+        # supported version and with mysql
         include:
-          - python-version: "3.10"
+          - python-version: "3.11"
             db-backend: "postgresql"
-            nautobot-version: "1.4.0"
-          - python-version: "3.7"
-            db-backend: "mysql"
-            nautobot-version: "1.4.0"
-          - python-version: "3.10"
+            nautobot-version: "2.0.0"
+          - python-version: "3.11"
+            db-backend: "postgresql"
+            nautobot-version: "stable"
+          - python-version: "3.11"
             db-backend: "mysql"
             nautobot-version: "stable"
+
     runs-on: "ubuntu-20.04"
     env:
       INVOKE_NAUTOBOT_PLUGIN_NORNIR_PYTHON_VER: "${{ matrix.python-version }}"
@@ -177,17 +181,13 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages"
         run: "pip install poetry"
       - name: "Set env"
         run: "echo RELEASE_VERSION=${GITHUB_REF:10} >> $GITHUB_ENV"
       - name: "Run Poetry Version"
         run: "poetry version $RELEASE_VERSION"
-      - name: "Install Dependencies (needed for mkdocs)"
-        run: "poetry install"
-      - name: "Build Documentation"
-        run: "poetry run mkdocs build --no-directory-urls --strict"
       - name: "Run Poetry Build"
         run: "poetry build"
       - name: "Upload binaries to release"
@@ -210,17 +210,13 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages"
         run: "pip install poetry"
       - name: "Set env"
         run: "echo RELEASE_VERSION=${GITHUB_REF:10} >> $GITHUB_ENV"
       - name: "Run Poetry Version"
         run: "poetry version $RELEASE_VERSION"
-      - name: "Install Dependencies (needed for mkdocs)"
-        run: "poetry install"
-      - name: "Build Documentation"
-        run: "poetry run mkdocs build --no-directory-urls --strict"
       - name: "Run Poetry Build"
         run: "poetry build"
       - name: "Push to PyPI"
@@ -234,7 +230,7 @@ jobs:
       - "publish_pypi"
     runs-on: "ubuntu-20.04"
     env:
-      SLACK_WEBHOOK_URL: "${{ secrets.SLACK_WEBHOOK_URL }}"
+      SLACK_WEBHOOK_URL: "${{ '{{ secrets.SLACK_WEBHOOK_URL }}' }}"
       SLACK_MESSAGE: >-
         *NOTIFICATION: NEW-RELEASE-PUBLISHED*\n
         Repository: <${{ github.server_url }}/${{ github.repository }}|${{ github.repository }}>\n
@@ -244,12 +240,11 @@ jobs:
       - name: "Send a notification to Slack"
         # ENVs cannot be used directly in job.if. This is a workaround to check
         # if SLACK_WEBHOOK_URL is present.
-        if: "env.SLACK_WEBHOOK_URL != ''"
+        if: "${{ env.SLACK_WEBHOOK_URL != '' }}"
         uses: "slackapi/slack-github-action@v1.17.0"
         with:
           payload: |
             {
-              "text": "${{ env.SLACK_MESSAGE }}",
               "blocks": [
                 {
                   "type": "section",

.gitignore

@@ -1,8 +1,10 @@
 # Specific ignores
 nautobot_backup.dump
 .creds.env
-packages/
+creds.env
+nautobot_golden_config/transposer.py
 docker-compose.override.yml
+packages/
 
 # Ansible Retry Files
 *.retry
@@ -198,6 +200,9 @@ $RECYCLE.BIN/
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
 
+# Jetbrains IDE configs
+.idea/
+
 # User-specific stuff
 .idea/**/workspace.xml
 .idea/**/tasks.xml
@@ -301,14 +306,6 @@ fabric.properties
 .vscode/*
 *.code-workspace
 
-# Rando
-creds.env
-development/*.txt
-
-# Invoke overrides
-invoke.yml
 
-# Docs
-docs/README.md
-docs/CHANGELOG.md
-public
+# MKDocs Build
+nautobot_plugin_nornir/static/nautobot_plugin_nornir/docs

development/Dockerfile

@@ -6,8 +6,8 @@
 # -------------------------------------------------------------------------------------
 # !!! USE CAUTION WHEN MODIFYING LINES BELOW
 
-# Accepts a desired Nautobot version as build argument, default to 1.4
-ARG NAUTOBOT_VER="1.4"
+# Accepts a desired Nautobot version as build argument, default to 2.0.0-rc.2
+ARG NAUTOBOT_VER="2.0.0-rc.3"
 
 # Accepts a desired Python version as build argument, default to 3.8
 ARG PYTHON_VER="3.8"

development/docker-compose.base.yml

@@ -21,8 +21,7 @@ services:
         condition: "service_started"
       db:
         condition: "service_healthy"
-    <<: *nautobot-build
-    <<: *nautobot-base
+    <<: [*nautobot-build, *nautobot-base]
   worker:
     entrypoint:
       - "sh"

development/nautobot_config.py

@@ -137,6 +137,8 @@
 # Each key in the dictionary is the name of an installed plugin and its value is a dictionary of settings.
 PLUGINS_CONFIG = {
     "nautobot_plugin_nornir": {
+        "allowed_location_types": [],
+        "denied_location_types": [],
         "use_config_context": {"use_config_context": {"secrets": False, "connection_options": True}},
         "connection_options": {
             "napalm": {

docs/admin/admin_install.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- The plugin is compatible with Nautobot 1.2.0 and higher.
+- The plugin is compatible with Nautobot 2.0.0 and higher.
 - Databases supported: PostgreSQL, MySQL
 
 !!! note
@@ -74,14 +74,15 @@ The plugin behavior can be controlled with the following list of settings.
 | Key                    | Example | Default | Description |
 | ---------------------- | ------- | ------- | ----------- |
 | nornir_settings        | {"nornir_settings": { "credentials": "cred_path"}} | N/A | The expected configuration paramters that Nornir uses, see Nornir documentation. |
-| dispatcher_mapping     | {"newos": "dispatcher.newos"} | None | A dictionary in which the key is a platform slug and the value is the import path of the dispatcher in string format |
 | username               | ntc | N/A | The username when leveraging the `CredentialsSettingsVars` credential provider. |
 | password               | password123 | N/A | The password when leveraging the `CredentialsSettingsVars` credential provider. |
 | secret                 | password123 | N/A | The secret password when leveraging the `CredentialsSettingsVars` credential provider.|
 | connection_options     | N/A | {"netmiko": {"extras": {"global_delay_factor": 1}}} | Set Nornir connection options globally to be used with **all** connections.
 | use_config_context     | {"secrets": True, "connection_options": True} | {"secrets": False, "connection_options": False} | Whether to pull Secret Access Type, and/or Connection Options from Config Context. |
 | connection_secret_path | "my_plugin.newos" |  <see note> | Dotted expression of the dictionary path where a device secret should be stored for a given Nornir Plugin. |
 | secret_access_type     | "SSH" | "GENERIC" | Type of Secret Access Type to use. Examples. "GENERIC", "CONSOLE", "GNMI", "HTTP", "NETCONF", "REST", "RESTCONF", "SNMP", "SSH"|
+| `allowed_location_types`| ["Site"] | [] | The location types you would like to be automatically grouped. |
+| `denied_location_types` | ["Region"] | [] |  The location types you would like to NOT be automatically grouped. |
 
 > Note: The default value for  `connection_secret_path` is "nautobot_plugin_nornir.plugins.credentials.env_vars.CredentialsEnvVars", left here to import rendering of the table.
 
@@ -93,4 +94,4 @@ The plugin behavior can be extended further with [config context](https://nautob
 | connection_secret_path | Dotted expression of the dictionary path where a device secret should be stored for a given Nornir Plugin. |
 | secret_access_type     | Type of Secret Access Type to use. Examples. "GENERIC", "CONSOLE", "GNMI", "HTTP", "NETCONF", "REST", "RESTCONF", "SNMP", "SSH"|
 
-For details on the [credentials](../../user/app_feature_credentials), [inventory](../../user/app_feature_inventory), and [dispatcher](../../user/app_feature_dispatcher) please see their respective documentation.
+For details on the [credentials](../../user/app_feature_credentials), and [inventory](../../user/app_feature_inventory) please see their respective documentation.

docs/admin/compatibility_matrix.md

@@ -9,3 +9,4 @@ While that last supported version will not be strictly enforced--via the max_ver
 | ------------------------------ | ------------------------------ | ----------------------------- |
 | 0.9.X                          | 1.0.0                          | 1.2.99                        |
 | 1.0.X                          | 1.2.0                          | 1.3.99                        |
+| 2.0.X                          | 2.0.0                          | 2.9999                        |

docs/admin/migrating_to_v2.md

@@ -0,0 +1,36 @@
+# Migrating to v2
+
+While not a replacement of the [Nautobot Migration guide](https://docs.nautobot.com/projects/core/en/stable/development/apps/migration/from-v1/) these migration steps specifically for Nautobot Plugin Nornir are pretty straight forward, here is a quick overview with details information below.
+
+1. Ensure `Platform.network_driver` is set on every `Platform` object you have, in most circumstances running `nautobot-server populate_platform_network_driver` will take care of it.
+2. Remove any `dispatcher_mapping` settings you have in your `nautobot_config.py` settings, see Golden Config for alternative options.
+3. Configure your Location settings, if you do not want all locations becoming grouped with the `allowed_location_types` or `denied_location_types` settings.
+
+!!! warning
+    Before you start, please note the `nautobot-server populate_platform_network_driver` command **must be ran in Nautobot 1.6.2 -> 1.6.X** as it will not work once on Nautobot 2.0.
+
+## Platform Network Driver
+
+The `Platform.slug` has been replace by Nautobot's `Platform.network_driver`. The nice thing about this feature is it provides mappings to all of the major network library (or frameworks) such as Netmiko and NAPALM to properly map between the slightly different names each library provides, such as `cisco_ios` vs `ios`. However, that means that you must now provide the network_driver on the the Platform object.
+
+While still on a Nautobot 1.6 instance, run the command `nautobot-server populate_platform_network_driver`, this will help map all of your `Platform.slug`'s to `Platform.network_driver`. If there are any Platform's missed, you must go in and update the Platforms that will be used by Nautobot Plugin Nornir.
+
+## Dispatcher Settings
+
+The `dispatcher_mapping` configuration has been removed. The use cases covered by it was:
+
+1. The default dispatcher does not support your vendor
+2. The default dispatcher uses a connectivity model (e.g. 443) that is not compatible with your environment
+3. The default dispatcher does not work for your older hardware
+4. The default dispatcher leverages a network_driver name you do not use
+
+Use cases 2 & 4 are covered natively by nornir-nautobot now and for 1 & 3 nautobot-plugin-nornir does not actually directly call the dispatcher and should be pushed off to other systems, such as Golden Config. If you are using Golden Config and fit within use cases 1 & 3, please see Golden Config's documentation.
+
+!!! warning
+    Golden Config provides the `custom_dispatcher` method, these settings should go to the `nautobot_golden_config` settings and **NOT** the `nautobot_plugin_nornir` settings.
+
+## Location Information
+
+Previously there were inventory groups automatically created out of each `Region` and `Site` object, with moving everything to `Location` there will automatically be created groups by each of those. This may lead to odd cases in which always having every Location as a group is not desirable. 
+
+Take for instance, you have multiple Locations that are on "floor04" as an example perhaps `nyc-floor04` and `sfo-floor04`, creating grouping in this case may create more confusion than help. For that reason, locations can be allowed or denied based on their `LocationType`. See the [docs](../user/app_feature_inventory.md#inventory-groupings) for more information on how to configure `allowed_location_types` or `denied_location_types`.

docs/admin/release_notes/version_2.0.md

@@ -0,0 +1,28 @@
+# v2.0 Release Notes
+
+This document describes all new features and changes in the release `2.0`. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Release Overview
+
+- Updated `nautobot` to `2.0.0` and made associated changes.
+- Added a standard way to provide error codes.
+- Removed dispatcher mapping.
+- Provided a mechanism to allow for Location Groupings to be configurable.
+
+
+## [v2.0.0] - 2023-09
+
+### Changed
+
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Updated `nautobot` to `2.0.0`.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Removed `dispatcher_mapping` a similar functionality can be found in Nautobot's Golden Config plugin, but simplified version in nornir-nautobot means this is no longer required.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Moved all references of `Platform.slug` to `Platform.network_driver`.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Removed references to `.slug` for Nautobot core models and changed to `.name`.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Moved all references of `Site` or `Region` to `Location`.
+
+### Added
+
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Plugin config `allowed_location_types` to limit what locations are **allowed** based on location types, specifically from `LocationType.name`.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Plugin config `denied_location_types` to limit what locations are turned **denied** based on location types, specifically from `LocationType.name`.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Added early failure with message when settings are in the wrong location such as `dispatcher_mapping` or `custom_dispatcher`.
+- [#117](https://github.com/nautobot/nautobot-plugin-nornir/issues/117) - Added error code framework.

docs/admin/troubleshooting/E2001.md

@@ -0,0 +1,19 @@
+# E20XX Details
+
+## Message emitted:
+
+`E20XX: Details coming soon`
+
+## Description:
+
+Description that is coming soon.
+
+## Troubleshooting:
+
+Troubleshooting that is coming soon.
+
+## Recommendation:
+
+Recommendation that is coming soon.
+
+

docs/admin/troubleshooting/E2002.md

@@ -0,0 +1,19 @@
+# E20XX Details
+
+## Message emitted:
+
+`E20XX: Details coming soon`
+
+## Description:
+
+Description that is coming soon.
+
+## Troubleshooting:
+
+Troubleshooting that is coming soon.
+
+## Recommendation:
+
+Recommendation that is coming soon.
+
+

docs/admin/troubleshooting/E2003.md

@@ -0,0 +1,19 @@
+# E20XX Details
+
+## Message emitted:
+
+`E20XX: Details coming soon`
+
+## Description:
+
+Description that is coming soon.
+
+## Troubleshooting:
+
+Troubleshooting that is coming soon.
+
+## Recommendation:
+
+Recommendation that is coming soon.
+
+

docs/admin/troubleshooting/E2004.md

@@ -0,0 +1,19 @@
+# E20XX Details
+
+## Message emitted:
+
+`E20XX: Details coming soon`
+
+## Description:
+
+Description that is coming soon.
+
+## Troubleshooting:
+
+Troubleshooting that is coming soon.
+
+## Recommendation:
+
+Recommendation that is coming soon.
+
+

docs/admin/troubleshooting/index.md

@@ -0,0 +1,13 @@
+# Troubleshooting Overview
+
+In an effort to help with troubleshooting, each expected error, will now emit an error ID, in the format of `E2XXX`, such as `E2004: Platform network_driver missing from device {device.name}, preemptively failed.`. The idea will be to define the error, the error message and some recommended troubleshooting steps or even potentially some fixes.
+
+This is an ongoing effort, but the foundation has been built.
+
+Within the Nautobot ecosystem, you may see various errors, they are distributed between 3 libraries as followed.
+
+| Error Range | Plugin Docs |
+| ----------- | ----------- |
+| E1001-E1999 | [Nornir Nautobot](https://docs.nautobot.com/projects/nornir-nautobot/en/latest/task/troubleshooting/) |
+| E2001-E2999 | [Nautobot Plugin Nornir](https://docs.nautobot.com/projects/plugin-nornir/en/latest/admin/troubleshooting/) |
+| E3001-E3999 | [Nautobot Golden Config](https://docs.nautobot.com/projects/golden-config/en/latest/admin/troubleshooting/) |