Merge pull request #11 from nautobot/develop-docs

Documentation updates

FAQ.md

@@ -1,5 +1,14 @@
 # Frequently Asked Questions
 
+## What are the use cases for Onboarding Extensions ?
+
+> See dedicated FAQ for device onboarding: [onboarding_extensions.md](docs/onboarding-extensions/onboarding_extensions.md)
+
+## How do I onboard a device using HTTPS-API ?
+
+> You need to disable automatic platform detection, specify the device platform type (platform has to be configured with napalm driver) and port. By default, onboarding plugin uses SSH port (22) to discover platform type and loads appropriate NAPALM driver automatically. In case a HTTPS-API is to be used, you have to disable this behaviour and manually choose the platform type with a declared NAPALM driver.
+
+
 ## Is it possible to disable the automatic creation of Device Type, Device Role or Platform ?
 
 > **Yes**, Using the plugin settings, it's possible to control individually the creation of `device_role`, `device_type`, `manufacturer` & `platform`
@@ -20,25 +29,32 @@
 
 ## How can I update the default credentials used to connect to a device ?
 
-> By default, the plugin is using the credentials defined in the main `configuration.py` for Napalm (`NAPALM_USERNAME`/`NAPALM_PASSWORD`). You can update the default credentials in `configuration.py` or you can provide specific one for each onboarding task.
+> By default, the plugin uses the credentials defined in the main `nautobot_config.py` for NAPALM (`NAPALM_USERNAME`/`NAPALM_PASSWORD`). You can update the default credentials in `nautobot_config.py ` or you can provide specific one for each onboarding task.
+
+## How can I update the optional arguments for NAPALM ?
+
+> Optional arguments are often used to define a `secret` for Cisco devices and other connection parameters. By default, plugin will use a provided secret for each onboarding task. If such one is not provided, for tasks with a declared platform plugin will read optional arguments from Nautobot if they are defined at a platform level. Last resort of optional arguments is `settings.NAPALM_ARGS`
 
 ## Does this plugin support the discovery and the creation of all interfaces and IP Addresses ?
 
 > **No**, The plugin will only discover and create the management interface and the management IP address. Importing all interfaces and IP addresses is a much larger problem that requires more preparation. This is out of scope of this project.
 
+> We recommend Network Importer tool from Network to Code for a post-onboarding network state synchronization. See [its GitHub repository](https://github.com/networktocode/network-importer) for more details
+
+
 ## Does this plugin support the discovery of device based on fqdn ? 
 
-> **No**, Current the onbarding process is based on an IP address, please open an issue to discuss your use case if you would like to see support for FQDN based devices too. 
+> **Yes**, plugin will resolve FQDN into an IP address and will use the IP address for its connections.
 
 ## Does this plugin support the discovery of Stack or Virtual Chassis devices ?
 
-> **Partially**, Multi member devices (Stack, Virtual Chassis, FW Pair) can be imported but they will be created as a single device. 
+> **Yes**, Multi member devices (Stack, Virtual Chassis, FW Pair) can be imported but by default they will be imported as a single device. As multi member devices modelling is very individual in each case, it is required to create a customized onboarding extensions to control the behaviour of creating multiple devices.
 
 ## Is this plugin able to automatically discover the type of my device ? 
 
 > **Yes**, The plugin is leveraging [Netmiko](https://github.com/ktbyers/netmiko) & [Napalm](https://napalm.readthedocs.io/en/latest/) to attempt to automatically discover the OS and the model of each device.
 
-## How many device can I import at the same time ?
+## How many devices can I import at the same time ?
 
 > **Many**, There are no strict limitations regarding the number of devices that can be imported. The speed at which devices will be imported will depend of the number of active RQ workers.
 
@@ -49,5 +65,3 @@
 ## Why don't I see a webhook generated when a new device is onboarded successfully ?
 
 > It's expected that any changes done asynchronously in Nautobot currently (within a worker) will not generate a webhook.
-
-

README.md

@@ -138,6 +138,11 @@ GET     ​   /api/plugins​/device-onboarding​/onboarding​/{id}​/  Check
 DELETE    ​ /api/plugins​/device-onboarding​/onboarding​/{id}​/  Delete a specific onboarding task
 ```
 
+## Customizing onboarding behaviour with onboarding extensions
+
+Onboarding plugin provides methods to customize onboarding behaviour. By creating onboarding extensions, it is possible to onboard switch stacks, HA pairs and perform other customizations. Please see dedicated FAQ for device onboarding: [onboarding_extensions.md](docs/onboarding-extensions/onboarding_extensions.md)
+
+
 ## Contributing
 
 Pull requests are welcomed and automatically built and tested against multiple version of Python and multiple version of Nautobot through TravisCI.

docs/examples/example_ios_set_device_role.py

@@ -72,7 +72,7 @@ class OnboardingDriverExtensions:
     def __init__(self, napalm_device):
         """Inits the class."""
         self.napalm_device = napalm_device
-        self.onboarding_class = MyOnboardingClass
+        self.onboarding_class = self.get_onboarding_class()
         self.ext_result = None
 
     def get_onboarding_class(self):
@@ -83,7 +83,7 @@ def get_onboarding_class(self):
         Result of this method is used by the OnboardingManager to
         initiate the instance of the onboarding class.
         """
-        return self.onboarding_class
+        return MyOnboardingClass
 
     def get_ext_result(self):
         """This method is used to store any object as a return value.

docs/onboarding-extensions/onboarding_extensions.md

@@ -0,0 +1,47 @@
+# Onboarding Extensions
+
+## What are onboarding extensions ?
+
+> Onboarding Extensions are Python modules that are dynamically loaded and executed as a part of device onboarding
+
+## What are common use cases for onboarding extensions ?
+
+> Onboarding extensions could be used (but not limited to) to perform following operations:
+- Stack onboarding
+- HA Pairs, VSS pairs onboarding
+- Populating device-bays and child devices, ie. Cisco UCS-Es
+- Populating device inventories during onboarding
+- Setting device roles during onboarding, ie. `Role = Access Switch`
+- Setting device tags during onboarding, ie: `onboarded_with=networktocode`
+
+## How do I enable onboarding extensions ?
+
+> You have to modify Nautobot configuration in `nautobot_config.py` to include your extension's configuration. In the example below, we map a NAPALM driver name (this one could be a custom NAPALM driver too!), into a loadable python module containing your onboarding extension. Onboarding plugin will dynamically load and execute your module as specified below:
+```
+        "onboarding_extensions_map": {
+            "cisco_ios": "onboarding_extensions.ios",
+            "cisco_nxos": "onboarding_extensions.nxos",
+            "cisco_asa": "onboarding_extensions.asa",
+        },
+```
+
+## How do I create an onboarding extension ?
+
+> You have to create two elements as a part of your extension:
+- an `OnboardingDriverExtensions` class inside your python module
+- an `OnboardingClass`
+
+> At first, plugin will initiate an instance of your `OnboardingDriverExtensions` (you have to use this name of the class). Onboarding plugin passes the NAPALM device with an opened connection to this class, allowing you to to execute any custom commands with NAPALM (ie. collect device stack information). 
+
+> `OnboardingDriverExtensions` must contain two important class attributes:
+- `onboarding_class` (mandatory) 
+- `ext_result` (optional). 
+
+> In `onboarding_class` attribute, you have to return a custom class that defines your onboarding methods. This is useful, as you might want to onboard devices in multiple different ways and `onboarding_class` acts as an distinguisher here.
+
+> `ext_result` attribute allows to collect and store any data while the device connection is active. Your custom `OnboardingClass` will be initiated with `driver_addon_result` attribute containing the value of `ext_result`
+
+
+## Where do I find an example of onboarding extension ?
+
+> Please check our example: [example_ios_set_device_role.py](../examples/example_ios_set_device_role.py)