add docs for the nornir connection options overrides

docs/dev/arch_decision.md

@@ -4,6 +4,6 @@ The intention is to document deviations from a standard Model View Controller (M
 
 ## Handling the Nornir Inventory
 
-In order for Nornir to function, an inventory is created. There are multiple supported inventory sources that fit many needs; however there is a unique requirement that this plugin is trying to solve. The problem is specifically around the first SSoT job (Sync Devices from Network); how can we create an inventory when there is no source "yet"? Our solution to this problem is to generate a empty inventory, and then process the ip addresses from the job form to create a inventory in an on demand fashion and inject the credentials into the inventory based on the secrets group selected.
+In order for Nornir to function, an inventory is created. There are multiple supported inventory sources that fit many needs; however there is a unique requirement that this plugin is trying to solve. The problem is specifically around the first SSoT job (Sync Devices from Network); how can we create an inventory when there is no source "yet"? Our solution to this problem is to generate a empty inventory, and then process the ip addresses from the job form to create a inventory in an on demand fashion and inject the credentials into the inventory based on the secrets group selected. This inventory does support loading in Nornir connection options `extras` by using the `nautobot-app-nornir` PLUGIN_CONFIG.
 
 For the general application constraint for this ADR see the [Credentials Section](../user/app_getting_started.md#device-credentials-functionality).

docs/dev/extending.md

@@ -20,3 +20,27 @@ Extending the platform support for the SSoT specific jobs should be accomplished
 New platform support should be simplified in this framework, by providing a YAML file.
 
 The format of these YAML files are and how to extend this application is covered in [App YAML Overrides](../user/app_yaml_overrides.md).
+
+### Passing Custom Nornir Connection Options
+
+Device Onboarding 4.0 uses Netmiko as the automation engine that queries the devices for information; more specifically, nornir-netmiko. To extend the device onboarding app to pass `extras` to the connection options the following can be added to `nautobot_plugin_nornir` `PLUGIN_CONFIG`.
+
+```python
+PLUGINS_CONFIG = {
+    "nautobot_device_onboarding": {},
+    "nautobot_plugin_nornir": {
+        "nornir_settings": {
+            "... omitted ..."},
+        "connection_options": {
+            "netmiko": {
+                "extras": {  # <==== passed into the connection setup.
+                    "fast_cli": False,
+                    "read_timeout_override": 30,
+                },
+            },
+        },
+    },
+}
+```
+
+When the on-demand inventory is created for the `Sync Device from Network` job, the extras in the `netmiko` connection dictionary are added to the connection setup.

docs/user/app_detailed_design.md

@@ -21,9 +21,10 @@ To learn how to extend the app, or update its default YAML definitions visit [Ex
     - Other required fields are selected in the job inputs form.
 
 2. The SSoT framework loads the Nautobot adapter information.
-3. The SSoT frameworks network adapter `load()` method calls nornir functionality.
+3. The SSoT frameworks network adapter `load()` method calls Nornir functionality.
     - The job inputs data is passed to the InitNornir initializer, because we only have basic information a custom `EmptyInventory` Nornir inventory plugin is packaged with the App. This get initialized in the `InitNornir` function, but actually initializes a true inventory that is empty.
     - Since `Platform` information may need to be auto-detected before adding a Nornir `Host` object to the inventory, a `create_inventory` function is executed that uses the SSH-Autodetect via Netmiko to try to determine the platform so it can be injected into the `Host` object.
+    - Load in the `PLUGIN_CONFIG` to see if extra connection options need to be added to the `Host` connection_option definition.
     - Finally, all the platform specific commands to run, along with all the jpath, `post_processor` information loaded from the platform specific YAML files must be injected into the Nornir data object to be accessible later in the extract, transform functions.
 4. Within the context of a Nornir `with_processor` context manager call the `netmiko_send_commands` Nornir task.
     - Access the loaded platform specific YAML data and deduplicate commands to avoid running the same command multiple times. E.g. Multiple required data attributes come from the same show command.

docs/user/app_getting_started.md

@@ -49,6 +49,14 @@ The new SSoT based jobs each use their own Nornir inventories.
                 },
             },
         },
+        "connection_options": {
+            "netmiko": {
+                "extras": {  # <==== passed into the connection setup.
+                    "fast_cli": False,
+                    "read_timeout_override": 30,
+                },
+            },
+        },
     },
 ```
 !!! info

docs/user/faq.md

@@ -81,3 +81,25 @@ It's expected that any changes done asynchronously in Nautobot currently (within
 - Several assumptions made for Nornir inventory that would be different in all other Nornir inventory jobs.
 - An inventory created for each device.
     - Causes additional SQL connections which may benefit from the use of `serial` runner.
+
+## How do I pass in extra connection options into Netmiko for the SSoT based jobs?
+
+Device Onboarding 4.0 uses Netmiko as the automation engine that queries the devices for information; more specifically, nornir-netmiko. To extend the device onboarding app to pass `extras` to the connection options the following can be added to `nautobot_plugin_nornir` `PLUGIN_CONFIG`.
+
+```python
+PLUGINS_CONFIG = {
+    "nautobot_device_onboarding": {},
+    "nautobot_plugin_nornir": {
+        "nornir_settings": {
+            "... omitted ..."},
+        "connection_options": {
+            "netmiko": {
+                "extras": {  # <==== passed into the connection setup.
+                    "fast_cli": False,
+                    "read_timeout_override": 30,
+                },
+            },
+        },
+    },
+}
+```